Referencia de la API de visualización de Google

En esta página, se enumeran los objetos que expone la API de visualización de Google, así como los métodos estándar que exponen todas las visualizaciones.

Nota: El espacio de nombres de la API de visualización de Google es google.visualization.*.

Clase DataTable

Representa una tabla de valores mutable y bidimensional. Para hacer una copia de solo lectura de una DataTable (con un filtro opcional para mostrar valores, filas o columnas específicos), crea una DataView.

A cada columna se le asigna un tipo de datos, además de varias propiedades opcionales, que incluyen un ID, una etiqueta y una cadena de patrón.

Además, puedes asignar propiedades personalizadas (pares nombre/valor) a cualquier celda, fila, columna o a toda la tabla. Algunas visualizaciones admiten propiedades personalizadas específicas; por ejemplo, la Visualización de la tabla admite una propiedad de celda denominada "style", que te permite asignar una cadena de estilo CSS intercalada a la celda de la tabla renderizada. Una visualización debe describir en su documentación todas las propiedades personalizadas que admite.

Consulta también: QueryResponse.getDataTable

Constructor

Sintaxis

DataTable(opt_data, opt_version)

opt_data

[Opcional] Datos que se usan para inicializar la tabla. Puede ser el archivo JSON que se muestra cuando se llama a DataTable.toJSON() en una tabla completada o un objeto JavaScript que contiene los datos que se usaron para inicializar la tabla. La estructura del objeto literal de JavaScript se describe aquí. Si no se proporciona este parámetro, se mostrará una tabla de datos nueva y vacía.

opt_version

[Opcional] Es un valor numérico que especifica la versión del protocolo de cable que se usa. Solo lo usan los implementadores de fuentes de datos de herramientas de gráficos. La versión actual es 0.6.

Detalles

El objeto DataTable se usa para contener los datos que se pasaron a una visualización. Un objeto DataTable es una tabla bidimensional básica. Todos los datos de cada columna deben tener el mismo tipo de datos. Cada columna tiene un descriptor que incluye su tipo de datos, una etiqueta para esa columna (que podría mostrarse en una visualización) y un ID, que se puede usar para hacer referencia a una columna específica (como alternativa al uso de índices de columna). El objeto DataTable también admite un mapa de propiedades arbitrarias asignadas a un valor específico, una fila, una columna o todo el DataTable. Las visualizaciones pueden usarlas para admitir características adicionales; por ejemplo, la Visualización de tabla usa propiedades personalizadas para permitirte asignar nombres o estilos de clase arbitrarios a celdas individuales.

Cada celda de la tabla contiene un valor. Las celdas pueden tener un valor nulo o un valor del tipo especificado por su columna. De manera opcional, las celdas pueden tomar una versión “con formato” de los datos; esta es una versión de cadena de los datos, con formato para que se muestre a través de una visualización. Una visualización puede usar la versión con formato para su visualización (aunque no está obligado a hacerlo), pero siempre usará los datos en sí para cualquier orden o cálculo que realice (por ejemplo, determinar en qué parte de un gráfico colocar un punto). Un ejemplo podría ser asignar los valores “bajo”, “medio” y “alto” como valores con formato a valores de celdas numéricas de 1, 2 y 3.

Para agregar filas de datos después de llamar al constructor, puedes llamar a addRow() para una sola fila o a addRows() para varias. También puedes agregar columnas llamando a los métodos addColumn(). También existen métodos de eliminación para filas y columnas, pero en lugar de quitar filas o columnas, considera crear una DataView que sea una vista selectiva de DataTable.

Si cambias los valores de una DataTable después de que se pasan al método draw() de una visualización, los cambios no cambiarán el gráfico de inmediato. Debes volver a llamar a draw() para reflejar los cambios.

Nota: Google Charts no realiza ninguna validación en las tablas de datos. (Si así fuera, los gráficos se renderizarían más lento). Si proporcionas un número en el que tu columna espera una cadena, o viceversa, Gráficos de Google hará todo lo posible para interpretar el valor de manera lógica, pero no marcará errores.

En el siguiente ejemplo, se muestra cómo crear una instancia de DataTable y propagarla con una string literal con los mismos datos que se muestran en el ejemplo de JavaScript anterior:

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

En el siguiente ejemplo, se crea un DataTable nuevo y vacío y, luego, se propaga manualmente con los mismos datos anteriores:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

Métodos

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

Formato del parámetro data literal de JavaScript del constructor

Puedes inicializar un DataTable si pasas un objeto literal de cadena de JavaScript al parámetro data. Llamaremos a este objeto el objeto data. Puedes programar este objeto de forma manual, de acuerdo con la descripción a continuación, o puedes usar una biblioteca auxiliar de Python si sabes cómo usar Python y tu sitio puede hacerlo. Sin embargo, si deseas construir el objeto a mano, en esta sección, se describirá la sintaxis.

Primero, mostremos un ejemplo de un objeto JavaScript simple que describe una tabla con tres filas y tres columnas (tipos de cadena, número y fecha):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

Ahora, describamos la sintaxis:

El objeto data consta de dos propiedades de nivel superior obligatorias, cols y rows, y una propiedad p opcional que es un mapa de valores arbitrarios.

Nota: Todos los nombres de propiedades y constantes de string que se muestran distinguen mayúsculas de minúsculas. Además, las propiedades descritas como tomar un valor de cadena deben tener su valor entre comillas. Por ejemplo, si deseas especificar la propiedad de tipo como un número, se expresaría de la siguiente manera: type: 'number', pero el valor en sí, como numérico, se expresaría de la siguiente manera: v: 42

Propiedad cols

cols es un array de objetos que describe el ID y el tipo de cada columna. Cada propiedad es un objeto con las siguientes propiedades (distingue mayúsculas de minúsculas):

• type (obligatorio): Es el tipo de datos de la columna. Admite los siguientes valores de string (los ejemplos incluyen la propiedad v:, que se describe más adelante):
  • "boolean": valor booleano de JavaScript ("verdadero" o "falso"). Valor de ejemplo: v:'true'
  • "number": el valor numérico de JavaScript. Valores de ejemplo: v:7, v:3.14, v:-55
  • "string": Valor de la string de JavaScript. Valor de ejemplo: v:'hello'
  • "date": objeto de fecha de JavaScript (mes basado en cero), con la hora truncada. Valor de ejemplo: v:new Date(2008, 0, 15)
  • "datetime": el objeto Date de JavaScript que incluye la hora. Valor de ejemplo: v:new Date(2008, 0, 15, 14, 30, 45)
  • "timeofday": array de tres números y un cuarto opcional que representa la hora (0 indica la medianoche), el minuto, el segundo y el milisegundo opcional. Valores de ejemplo: v:[8, 15, 0], v: [6, 12, 1, 144]
• id (opcional): Es el ID de cadena de la columna. Debe ser único en la tabla. Usa caracteres alfanuméricos básicos, de modo que la página de host no requiera escapes sofisticados para acceder a la columna en JavaScript. Tenga cuidado de no elegir una palabra clave de JavaScript. Ejemplo: id:'col_1'
• label (opcional): Es el valor de string que muestran algunas visualizaciones para esta columna. Ejemplo: label:'Height'
• pattern (opcional): Patrón de string que una fuente de datos usó para dar formato a los valores de columna numéricos, de fecha o de hora. Esto es solo de referencia; es probable que no necesites leer el patrón y que no sea necesario que exista. El cliente de visualización de Google no usa este valor (lee el valor con formato de la celda). Si DataTable proviene de una fuente de datos en respuesta a una consulta con una cláusula format, es probable que el patrón que especificaste en esa cláusula se muestre en este valor. Los estándares de patrón recomendados son DecimalFormat y SimpleDateFormat de ICU.
• p [Opcional] Es un objeto que es un mapa de valores personalizados aplicados a la celda. Estos valores pueden ser de cualquier tipo de JavaScript. Si tu visualización admite propiedades a nivel de celda, las describirá; de lo contrario, se ignorará esta propiedad. Ejemplo: p:{style: 'border: 1px solid green;'}.

Ejemplo de cols

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

rows Propiedad

La propiedad rows incluye un array de objetos de fila.

Cada objeto de fila tiene una propiedad obligatoria llamada c, que es un array de celdas en esa fila. También tiene una propiedad p opcional que define un mapa de valores personalizados arbitrarios para asignar a toda la fila. Si tu visualización admite propiedades a nivel de fila, las describirá; de lo contrario, esta propiedad se ignorará.

Objetos de celda

Cada celda de la tabla es descrita por un objeto con las siguientes propiedades:

• v (opcional): Es el valor de la celda. El tipo de datos debe coincidir con el tipo de datos de la columna. Si la celda es nula, la propiedad v debe ser nula, aunque puede tener propiedades f y p.
• f (opcional): Es una versión de cadena del valor v, con formato para visualización. Por lo general, los valores coincidirán, aunque no es necesario, por lo que si especificas Date(2008, 0, 1) para v, debes especificar "1 de enero de 2008" o alguna cadena similar para esta propiedad. Este valor no se compara con el valor v. La visualización no usará este valor para el cálculo, solo como una etiqueta para mostrar. Si se omite, se generará automáticamente una versión de cadena de v con el formateador predeterminado. Los valores f se pueden modificar con tu propio formateador, establecerse con setFormattedValue() o setCell(), o recuperarse con getFormattedValue().
• p [Opcional] Es un objeto que es un mapa de valores personalizados aplicados a la celda. Estos valores pueden ser de cualquier tipo de JavaScript. Si tu visualización admite propiedades a nivel de celda, las describirá. Estas propiedades se pueden recuperar con los métodos getProperty() y getProperties(). Ejemplo: p:{style: 'border: 1px solid green;'}.

Las celdas del array de filas deben estar en el mismo orden que las descripciones de sus columnas en cols. Para indicar una celda nula, puedes especificar null, omitir los miembros finales del array o dejar un espacio en blanco para una celda de un array. Por lo tanto, si deseas indicar una fila con un valor nulo para las primeras dos celdas, puedes especificar [ , , {cell_val}] o [null, null, {cell_val}].

Este es un objeto de tabla de muestra con tres columnas, rellenadas con tres filas de datos:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

Propiedad p

La propiedad p a nivel de la tabla es un mapa de valores personalizados aplicados a todo DataTable. Estos valores pueden ser de cualquier tipo de JavaScript. Si tu visualización admite propiedades a nivel de tabla de datos, las describirá. De lo contrario, esta propiedad estará disponible para que la use la aplicación. Ejemplo: p:{className: 'myDataTable'}.

Clase DataView

Una vista de solo lectura de una DataTable subyacente. Un objeto DataView permite seleccionar solo un subconjunto de las columnas o filas. También permite reordenar columnas y filas, y duplicar columnas y filas.

Una vista es una ventana en vivo en el DataTable subyacente, no una instantánea estática de los datos. Sin embargo, de todas formas, debes tener cuidado cuando cambies la estructura de la tabla, como se describe a continuación:

• Agregar o quitar columnas de la tabla subyacente no se verá reflejada en la vista y podría provocar un comportamiento inesperado en la vista. Deberás crear una DataView nueva desde el DataTable para registrar estos cambios.
• Agregar o quitar filas de la tabla subyacente es seguro y los cambios se propagarán a la vista de inmediato (pero debes llamar a draw() en cualquier visualización después de este cambio para que se renderice el nuevo conjunto de filas). Ten en cuenta que, si tu vista filtró filas mediante una llamada a uno de los métodos setRows() or hideRows(), y agregas o quitas filas de la tabla subyacente, el comportamiento es inesperado; debes crear una DataView nueva para reflejar la tabla nueva.
• Cambiar los valores de celda en las celdas existentes es seguro, y los cambios se propagan de inmediato a DataView (pero debes llamar a draw() en cualquier visualización después de este cambio para que se procesen los valores nuevos de las celdas).

También es posible crear un DataView a partir de otro DataView. Ten en cuenta que cada vez que se menciona una tabla o vista subyacente, se refiere al nivel que está inmediatamente debajo de este. En otras palabras, se refiere al objeto de datos que se usó para construir este DataView.

DataView también admite columnas calculadas; es decir, aquellas cuyo valor se calcula sobre la marcha mediante una función que proporciones. Por ejemplo, puedes incluir una columna que sea la suma de las dos columnas anteriores o una columna que calcule y muestre el trimestre calendario de una fecha de otra columna. Consulta setColumns() para obtener más información.

Si ocultas o muestras filas o columnas para modificar una DataView, la visualización no se verá afectada hasta que vuelvas a llamar a draw() en ella.

Puedes combinar DataView.getFilteredRows() con DataView.setRows() para crear un DataView con un subconjunto interesante de datos, como se muestra a continuación:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

Constructores

Existen dos maneras de crear una instancia nueva de DataView:

Constructor 1

var myView = new google.visualization.DataView(data)

data

Es una DataTable o DataView que se usa para inicializar la vista. De forma predeterminada, la vista contiene todas las columnas y filas de la tabla o vista de datos subyacentes, en el orden original. Para ocultar o mostrar filas o columnas en esta vista, llama a los métodos set...() o hide...() correspondientes.

También:

setColumns(), hideColumns(), setRows() y hideRows().

Constructor 2

Este constructor crea un DataView nuevo mediante la asignación de un DataView serializado a un DataTable. Te ayuda a recrear el DataView que serializaste con DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

datos

Es el objeto DataTable que usaste para crear el DataView, en el que llamaste a DataView.toJSON(). Si esta tabla es diferente de la original, obtendrás resultados impredecibles.

viewAsJson

Es la cadena JSON que muestra DataView.toJSON(). Esta es una descripción de qué filas se deben ocultar o mostrar en DataTable de data.

Métodos

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

Clase ChartWrapper

Se usa una clase ChartWrapper para ajustar el gráfico y controlar todas las cargas, los dibujos y las consultas de fuente de datos del gráfico. La clase expone métodos convenientes para configurar valores en el gráfico y dibujarlo. Esta clase simplifica la lectura de una fuente de datos, ya que no tienes que crear un controlador de devolución de llamada de consulta. También puedes usarlo para guardar un gráfico fácilmente y volver a usarlo.

Otra ventaja de usar ChartWrapper es que puedes reducir la cantidad de cargas de la biblioteca con la carga dinámica. Además, no necesitas cargar los paquetes de forma explícita, ya que ChartWrapper se encargará de buscar y cargar los paquetes de gráficos por ti. Consulta los siguientes ejemplos para obtener más detalles.

Sin embargo, en la actualidad, ChartWrapper solo propaga un subconjunto de eventos arrojados por gráficos: select, ready y error. Otros eventos no se transmiten a través de la instancia ChartWrapper. Para obtener otros eventos, debes llamar a getChart() y suscribirte a los eventos directamente desde el controlador del gráfico, como se muestra a continuación:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

Constructor

ChartWrapper(opt_spec)

opt_spec

[Opcional]: Es un objeto JSON que define el gráfico o una versión de cadena serializada de ese objeto. El formato de este objeto se muestra en la documentación de drawChart(). Si no se especifica, debes configurar todas las propiedades adecuadas con los métodos set... que expone este objeto.

Métodos

ChartWrapper expone los siguientes métodos adicionales:

Eventos

El objeto ChartWrapper arroja los siguientes eventos. Ten en cuenta que debes llamar a ChartWrapper.draw() antes de que se arroje cualquier evento.

Ejemplo

Los dos fragmentos que aparecen a continuación crean un gráfico de líneas equivalente. En el primer ejemplo, se usa la notación literal JSON para definir el gráfico; en el segundo, se usan métodos ChartWrapper para configurar estos valores.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

El mismo gráfico, ahora con métodos set:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

Clase de ChartEditor

La clase ChartEditor se usa para abrir un cuadro de diálogo in-page que le permite al usuario personalizar una visualización sobre la marcha.

Sigue estos pasos para usar ChartEditor:

1. Carga el paquete charteditor. En google.charts.load(), carga el paquete "charteditor". No es necesario que cargues los paquetes para el tipo de gráfico que renderizas en el editor; este cargará cualquier paquete por ti según sea necesario.
2. Crea un objeto ChartWrapper que defina el gráfico para que el usuario personalice. Este gráfico se mostrará en el diálogo y el usuario utiliza el editor para rediseñar el gráfico, cambiar su tipo o incluso cambiar los datos de origen.
3. Crea una instancia nueva de ChartEditor y regístrate para escuchar el evento "ok". Este evento se genera cuando el usuario hace clic en el botón "OK" del diálogo. Cuando se recibe, debes llamar a ChartEditor.getChartWrapper() para recuperar el gráfico modificado por el usuario.
4. Llama a ChartEditor.openDialog() y pasa el ChartWrapper. Se abrirá el diálogo. Los botones de diálogo permiten que el usuario cierre el editor. La instancia ChartEditor estará disponible siempre y cuando esté dentro del alcance; no se destruye automáticamente después de que el usuario cierra el diálogo.
5. Para actualizar el gráfico en el código, llama a setChartWrapper().

Métodos

Opciones

El editor de gráficos admite las siguientes opciones:

Eventos

El editor de gráficos muestra los siguientes eventos:

Ejemplo

El siguiente código de ejemplo abre un diálogo del editor de gráficos con un gráfico de líneas propagado. Si el usuario hace clic en "Aceptar", el gráfico editado se guardará en el <div> especificado en la página.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

Métodos de manipulación de datos

El espacio de nombres google.visualization.data contiene métodos estáticos para realizar operaciones similares a las de SQL en objetos DataTable, por ejemplo, unirlos o agruparlos por valor de columna.

El espacio de nombres google.visualization.data expone los siguientes métodos:

group()

Toma un objeto DataTable propagado, realiza una operación GROUP BY similar a SQL y muestra una tabla con filas agrupadas por los valores de columna especificados. Ten en cuenta que esto no modifica el objeto DataTable de entrada.

La tabla que se muestra incluye una fila para cada combinación de valores en las columnas de claves especificadas. Cada fila incluye las columnas de clave, más una columna con un valor de columna agregado en todas las filas que coinciden con la combinación de claves (por ejemplo, una suma o un recuento de todos los valores de la columna especificada).

El espacio de nombres google.visualization.data incluye varios valores de agregación útiles (por ejemplo, sum y count), pero puedes definir los tuyos (por ejemplo, standardDeviation osecondHighest). Las instrucciones para definir tu propio agregador se proporcionan después de la descripción del método.

Sintaxis

google.visualization.data.group(data_table, keys, columns)

data_table

Es el DataTable de entrada. Esto no se modificará llamando a group().

keys

Es un array de objetos o números que especifica por qué columnas se deben agrupar. La tabla de resultados incluye todas las columnas de este array, así como todas las columnas de columns. Si es un número, es un índice de columna de la DataTable de entrada para agrupar. Si es un objeto, incluirá una función que puede modificar la columna especificada (por ejemplo, agregar 1 al valor de esa columna). El objeto debe tener las siguientes propiedades:

• columna: Un número que es un índice de columna de dt al que se aplicará la transformación.
• modifier: una función que acepta un valor (el valor de celda en esa columna para cada fila) y muestra el valor modificado. Esta función se usa para modificar el valor de la columna a fin de ayudar con la agrupación, por ejemplo, mediante una llamada a la función whatQuarter que calcula un trimestre a partir de una columna de fecha, de modo que la API pueda agrupar filas por trimestre. El valor calculado se muestra en las columnas de claves de la tabla que se muestra. Esta función se puede declarar intercalada dentro de este objeto, o puede ser una función que defines en otra parte del código (debe estar dentro del alcance de la llamada). La API proporciona una función de modificador simple. Aquí encontrarás instrucciones para crear tus propias funciones más útiles. Debes conocer el tipo de datos que esta función puede aceptar y llamarlo solo en columnas de ese tipo. También debes conocer el tipo de datos que se muestra de esta función y declararlo en la propiedad type que se describe a continuación.
• tipo: Tipo que muestra el modificador de la función. Debe ser un nombre de tipo de cadena de JavaScript, por ejemplo: "número" o "booleano".
• label: [opcional] es una etiqueta de cadena para asignar esta columna en el DataTable que se muestra.
• id: [opcional] Es un ID de string para asignar esta columna en el DataTable que se muestra.

Ejemplos: [0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

columnas

[Opcional] Te permite especificar qué columnas, además de las columnas de clave, incluir en la tabla de resultados. Debido a que todas las filas del grupo de filas se comprimen en una sola fila de salida, debes determinar qué valor mostrar para ese grupo de filas. Por ejemplo, puedes elegir mostrar el valor de la columna de la primera fila del conjunto o un promedio de todas las filas de ese grupo. columns es un array de objetos, que tiene las siguientes propiedades:

• columna: Es un número que especifica el índice de la columna que se mostrará.
• agregación: función que acepta un arreglo de todos los valores de la columna en este grupo de filas y muestra un solo valor para mostrar en la fila de resultados. El valor que se muestra debe ser del tipo especificado por la propiedad type del objeto. A continuación, encontrarás los detalles para crear tu propia función de agregación. Debes saber qué tipos de datos acepta este método y solo llamarlo en columnas del tipo adecuado. La API proporciona varias funciones de agregación útiles. Consulta Funciones de agregación proporcionadas a continuación para obtener una lista o Crea una función de agregación para aprender a escribir tu propia función de agregación.
• tipo: el tipo de datos que se muestra de la función de agregación. Debe ser un nombre de tipo de cadena de JavaScript, por ejemplo: "número" o "booleano".
• label: [Opcional] Es una etiqueta de cadena que se aplica a esta columna en la tabla que se muestra.
• id: [opcional] ID de string que se aplica a esta columna en la tabla que se muestra.

Valor que se muestra

Un DataTable con una columna para cada columna que aparece en keys y una columna para cada columna que aparece en columns La tabla está ordenada por filas clave, de izquierda a derecha.

Ejemplo

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

Funciones de modificación proporcionadas

La API proporciona las siguientes funciones de modificador que puedes pasar a las claves. modifier para personalizar el comportamiento de agrupación.

Funciones de agregación proporcionadas

La API proporciona las siguientes funciones de agregación que puedes pasar a las columnas. aggregation.

Crear una función modificadora

Puedes crear una función de modificador para realizar una transformación simple en valores clave antes de que la función group() agrupe las filas. Esta función toma un valor de una sola celda, realiza una acción sobre él (por ejemplo, agrega 1 al valor) y lo muestra. No es necesario que los tipos de entrada y de resultado sean del mismo tipo, pero el llamador debe conocerlos. Aquí tienes un ejemplo de una función que acepta una fecha y muestra el trimestre:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

Crear una función de agregación

Puedes crear una función de agregación que acepte un conjunto de valores de columna en un grupo de filas y muestre un solo número; por ejemplo, que muestre un recuento o un promedio de valores. A continuación, se muestra una implementación de la función de agregación de recuento proporcionada, que muestra un recuento de cuántas filas hay en el grupo de filas:

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

Este método une dos tablas de datos (objetos DataTable o DataView) en una sola tabla de resultados, similar a una instrucción JOIN de SQL. Especifica uno o más pares de columnas (columnas key) entre las dos tablas y la tabla de salida incluirá las filas según un método de unión que especifiques: solo las filas en las que coinciden ambas claves; todas las filas de una tabla; o todas las filas de ambas tablas, sin importar si las claves coinciden o no. La tabla de resultados incluye solo las columnas de clave, además de las columnas adicionales que especifiques. Ten en cuenta que dt2 no puede tener claves duplicadas, pero dt1 sí. El término “clave” se refiere a la combinación de todos los valores de las columnas de clave, no a un valor de columna de clave específico; por lo tanto, si una fila tiene valores de celda A | B | C y las columnas 0 y 1 son columnas clave, la clave para esa fila es AB.

Sintaxis

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

Es un DataTable propagado para unir con dt2.

dt2

Es un DataTable propagado para unir con dt1. Esta tabla no puede tener varias claves idénticas (cuando una clave es una combinación de valores de columnas de claves).

joinMethod

Es una cadena que especifica el tipo de unión. Si dt1 tiene varias filas que coinciden con una fila dt2, la tabla de salida incluirá todas las filas dt1 coincidentes. Elige uno de los siguientes valores:

• “completo”: La tabla de resultados incluye todas las filas de ambas tablas, sin importar si las claves coinciden. Las filas no coincidentes tendrán entradas de celda nulas; las filas coincidentes se unirán.
• “inner”: la unión completa filtrada para incluir solo las filas en las que coinciden las claves.
• "left": la tabla de resultados incluye todas las filas de dt1, sin importar si hay filas coincidentes de dt2 o no.
• "right": la tabla de resultados incluye todas las filas de dt2, sin importar si hay o no filas que coincidan de dt1.

keys

Es un array de columnas clave para comparar de ambas tablas. Cada par es un arreglo de dos elementos: el primero es una clave en dt1 y el segundo es una clave en dt2. Este array puede especificar columnas por su índice, ID o etiqueta; consulta getColumnIndex.
Las columnas deben ser del mismo tipo en ambas tablas. Todas las claves especificadas deben coincidir de acuerdo con la regla que proporciona joinMethod para incluir una fila de la tabla. Las columnas de clave siempre se incluyen en la tabla de resultados. Solo dt1, la tabla de la izquierda, puede incluir claves duplicadas; las claves en dt2 deben ser únicas. En este caso, el término “clave” se refiere a un conjunto único de columnas de clave, no a valores de columnas individuales. Por ejemplo, si las columnas de clave fueran A y B, la siguiente tabla solo tendría valores clave únicos (por lo tanto, podría usarse como dt2):

A	B
Julia	Rojo
Julia	Azul
Fred	Rojo

Ejemplo: [[0,0], [2,1]] compara valores de la primera columna en ambas tablas y en la tercera columna de dt1 con la segunda columna de dt1.

dt1Columns

Es un array de columnas de dt1 para incluir en la tabla de resultados, además de las columnas de clave de dt1. Este array puede especificar columnas por su índice, ID o etiqueta; consulta getColumnIndex.

dt2Columns

Es un array de columnas de dt2 para incluir en la tabla de resultados, además de las columnas de clave de dt2. Este array puede especificar columnas por su índice, ID o etiqueta; consulta getColumnIndex.

Valor que se muestra

Un DataTable con las columnas clave, dt1Columns y dt2Columns. Esta tabla está ordenada por las columnas clave, de izquierda a derecha. Cuando joinMethod es “inner”, todas las celdas clave deben completarse. Para otros métodos de unión, si no se encuentra una clave coincidente, la tabla tendrá un valor nulo para las celdas clave que no coincidan.

Ejemplos

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

Formateadores

La API de visualización de Google proporciona formateadores que se pueden usar para cambiar el formato de los datos en una visualización. Estos formateadores cambian el valor con formato de la columna especificada en todas las filas. Ten en cuenta lo siguiente:

• Los formateadores solo modifican los valores con formato, no los valores subyacentes. Por ejemplo, el valor que se muestra sería "$1,000.00", pero el valor subyacente seguiría siendo "1,000".
• Los formateadores solo afectan a una columna a la vez; para cambiar el formato de varias columnas, aplica un formateador a cada columna que desees cambiar.
• Si también utilizas formateadores definidos por el usuario, algunos formateadores de Visualización de Google anularán todos los formateadores definidos por el usuario.

El formato real que se aplica a los datos se deriva de la configuración regional con la que se cargó la API. Para obtener más detalles, consulta cómo cargar gráficos con una configuración regional específica .

Importante: Los formateadores solo se pueden usar con un DataTable. No se pueden usar con un DataView (los objetos DataView son de solo lectura).

Estos son los pasos generales para usar un formateador:

1. Obtén tu objeto DataTable propagado.
2. Para cada columna a la que quieras cambiar el formato, haz lo siguiente:
   1. Crea un objeto que especifique todas las opciones para tu formateador. Este es un objeto básico de JavaScript con un conjunto de propiedades y valores. Consulta la documentación del formateador para ver qué propiedades son compatibles. De forma opcional, puedes pasar un objeto de notación literal de objeto en el que se especifiquen las opciones.
   2. Crea el formateador y pasa el objeto options.
   3. Llama a formatter.format(table, colIndex) y pasa DataTable y el número de columna (basada en cero) de los datos a los que se les debe cambiar el formato. Ten en cuenta que solo puedes aplicar un formateador único a cada columna. Si aplicas un segundo formateador, solo se reemplazarán los efectos de la primera.
      Importante: Muchos formateadores requieren etiquetas HTML para mostrar un formato especial. Si tu visualización admite una opción allowHtml, debes establecerla como verdadera.

A continuación, se muestra un ejemplo de cómo cambiar los valores de fecha con formato de una columna de fecha para que usen un formato de fecha largo ("1 de enero de 2009"):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

La mayoría de los formateadores exponen los dos métodos siguientes:

Método	Descripción
google.visualization.formatter_name(options)	Constructor, en el que formatter_name es un nombre de formatterclass específico. options: Es un objeto JavaScript genérico que especifica las opciones para ese formateador. Este objeto es un objeto genérico con pares propiedad/valor con propiedades específicas para ese formateador. Consulta la documentación de tu formateador específico para conocer las opciones compatibles. A continuación, se muestran dos ejemplos de maneras de llamar al constructor para el objeto DateFormat y pasar dos propiedades: // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	Cambia el formato de los datos en la columna especificada. data: Un DataTable que contiene los datos a los que se les debe cambiar el formato. No puedes usar un DataView aquí. colIndex: índice basado en cero de la columna a la que se va a formatear. Para dar formato a varias columnas, debes llamar a este método varias veces, con diferentes valores de colIndex.

 

La API de visualización de Google proporciona los siguientes formateadores:

Nombre del formateador	Descripción
ArrowFormat	Agrega una flecha hacia arriba o hacia abajo que indica si el valor de la celda está arriba o abajo de un valor especificado.
BarFormat	Agrega una barra de color, cuya dirección y color indican si el valor de la celda es superior o inferior a un valor especificado.
ColorFormat	Colorea una celda según si los valores se encuentran dentro de un rango especificado.
DateFormat	Da formato a un valor de fecha o de fecha y hora de varias maneras diferentes, incluidas "1 de enero de 2009", "1/1/09" y "1 de enero de 2009".
NumberFormat	Da formato a varios aspectos de los valores numéricos.
PatternFormat	Concatena los valores de celda de la misma fila en una celda especificada, junto con texto arbitrario.

ArrowFormat

Agrega una flecha hacia arriba o hacia abajo a una celda numérica en función de si el valor está por encima o por debajo de un valor base especificado. Si es igual al valor base, no se muestra ninguna flecha.

Opciones

ArrowFormat admite las siguientes opciones, que se pasan al constructor:

Opción	Descripción
base	Es un número que indica el valor base que se usa para compararlo con el valor de la celda. Si el valor de la celda es mayor, la celda incluirá una flecha verde hacia arriba; si el valor de la celda es inferior, incluirá una flecha roja hacia abajo; si es igual, ninguna flecha.

Código de muestra

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

Agrega una barra de color a una celda numérica que indica si el valor de la celda es superior o inferior a un valor base especificado.

Opciones

BarFormat admite las siguientes opciones, que se pasan al constructor:

Opción	Ejemplo Descripción
base	Número que es el valor base con el que se va a comparar el valor de la celda. Si el valor de la celda es mayor, se dibujará a la derecha de la base; si es inferior, se dibujará a la izquierda. El valor predeterminado es 0.
colorNegative	Es una cadena que indica la sección de valor negativo de las barras. Los valores posibles son “rojo”, “verde” y “azul”. El valor predeterminado es “rojo”.
colorPositive	Es una cadena que indica el color de la sección de valor positivo de las barras. Los valores posibles son “rojo”, “verde” y “azul”. El valor predeterminado es "azul".
drawZeroLine	Un valor booleano que indica si se debe dibujar una línea base oscura de 1 píxel cuando hay valores negativos. La línea oscura está ahí para mejorar el escaneo visual de las barras. El valor predeterminado es "false".
max	El valor de número máximo para el rango de barras. El valor predeterminado es el valor más alto de la tabla.
min	El valor numérico mínimo para el rango de barras. El valor predeterminado es el valor más bajo de la tabla.
showValue	Si es verdadero, muestra valores y barras; si es falso, solo muestra barras. El valor predeterminado es verdadero.
width	Espesor de cada barra, en píxeles. El valor predeterminado es 100.

Código de muestra

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

Asigna colores al primer o segundo plano de una celda numérica según el valor de la celda. Este formateador es inusual, ya que no toma sus opciones en el constructor. En su lugar, debes llamar a addRange() o addGradientRange() todas las veces que desees para agregar rangos de color antes de llamar a format(). Los colores se pueden especificar en cualquier formato HTML aceptable, por ejemplo, "negro", "#000000" o "#000".

Métodos

ColorFormat admite los siguientes métodos:

Método	Descripción
google.visualization.ColorFormat()	Constructor. No toma argumentos.
addRange(from, to, color, bgcolor)	Especifica un color de primer plano o de fondo para una celda, según su valor. A cualquier celda con un valor en el rango from-to se le asignarán color y bgcolor. Es importante tener en cuenta que el rango no es inclusivo, ya que crear un rango de 1 a 1,000 y un segundo de 1,000 a 2,000 no cubrirá el valor 1,000. from: [String, Number, Date, DateTime o TimeOfDay] El límite inferior (incluido) del rango o nulo. Si es nulo, coincidirá con -∞. Los límites de las cadenas se comparan alfabéticamente con los valores de las cadenas. to: [String, Number, Date, DateTime o TimeOfDay] El límite alto (no inclusivo) del rango, o nulo. Si es nulo, coincidirá con +∞. Los límites de las cadenas se comparan alfabéticamente con los valores de las cadenas. color: Es el color que se aplica al texto en las celdas coincidentes. Los valores pueden ser valores "#RRGGBB" o constantes de color definidas (por ejemplo, "#FF0000" o "rojo"). bgcolor: Es el color que se aplica al fondo de las celdas coincidentes. Los valores pueden ser valores "#RRGGBB" o constantes de color definidas (por ejemplo, "#FF0000" o "rojo").
addGradientRange(from, to, color, fromBgColor, toBgColor)	Asigna un color de fondo de un rango, según el valor de la celda. El color se ajusta para coincidir con el valor de la celda dentro de un rango que va de un color de límite inferior a un color de límite superior. Ten en cuenta que este método no puede comparar valores de cadenas, como sí puede hacerlo addRange(). Sugerencia: A menudo, los rangos de color son difíciles de medir con precisión. El rango más simple y fácil de leer es de un color completamente saturado a blanco (p. ej., #FF0000—FFFFFF). from: [Number, Date, DateTime, or TimeOfDay] Es el límite inferior (incluido) del rango, o nulo. Si es nulo, coincidirá con -∞. to: [Number, Date, DateTime, or TimeOfDay] El límite más alto (no inclusivo) del rango, o nulo. Si es nulo, coincidirá con +∞. color: Es el color que se aplica al texto en las celdas coincidentes. Este color es el mismo para todas las celdas, independientemente de su valor. fromBgColor: El color de fondo de las celdas que contienen valores en el extremo inferior del gradiente. Los valores pueden ser valores "#RRGGBB" o constantes de color definidas (por ejemplo, "#FF0000" o "rojo"). toBgColor: Es el color de fondo de las celdas que contienen valores en el extremo superior del gradiente. Los valores pueden ser valores "#RRGGBB" o constantes de color definidas (por ejemplo, "#FF0000" o "rojo").
format(dataTable, columnIndex)	Es el método format() estándar para aplicar formato a la columna especificada.

Código de muestra

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

Da formato a un valor Date de JavaScript de varias maneras, incluidas "1 de enero de 2016", "1/1/16" y "1 de enero de 2016".

Opciones

DateFormat admite las siguientes opciones, que se pasan al constructor:

Opción	Descripción
formatType	Una opción de formato rápido para la fecha. Se admiten los siguientes valores de cadena, con el cambio de formato de la fecha 28 de febrero de 2016, como se muestra a continuación: "short": formato corto, p.ej., "28/2/16" "medium": formato medio, p.ej., "28 de febrero de 2016" "long": formato largo, p.ej., "28 de febrero de 2016" No puedes especificar formatType y pattern a la vez.
pattern	Un patrón de formato personalizado para aplicar al valor, similar al formato de fecha y hora de ICU. Por ejemplo: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"});. No puedes especificar formatType y pattern a la vez. Puedes leer más detalles sobre los patrones en la siguiente sección.
timeZone	Zona horaria en la que se muestra el valor de la fecha. Este es un valor numérico que indica GMT + esta cantidad de zonas horarias (puede ser negativo). Los objetos de fecha se crean de forma predeterminada con la zona horaria supuesta de la computadora en la que se crean. Esta opción se usa para mostrar ese valor en una zona horaria diferente. Por ejemplo, si creaste un objeto Date de las 5 p.m. del mediodía en una computadora ubicada en Greenwich, Inglaterra, y especificaste la zona horaria en -5 (options['timeZone'] = -5, o la hora del este del Pacífico en EE.UU.), el valor que se muestra sería 12:00 p.m.

Métodos

DateFormat admite los siguientes métodos:

Método	Descripción
google.visualization.DateFormat(options)	Constructor. Consulta la sección de opciones anterior para obtener más información.
format(dataTable, columnIndex)	Es el método format() estándar para aplicar formato a la columna especificada.
formatValue(value)	Muestra el valor con formato de un valor determinado. Este método no requiere un DataTable.

Código de muestra

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

Más información sobre los patrones de fecha

A continuación, se presentan algunos detalles adicionales sobre los patrones compatibles:

Los patrones son similares al formato de fecha y hora de ICU, pero aún no se admiten los siguientes: A e D F g Y u w W. Para evitar la colisión con los patrones, cualquier texto literal que desees que aparezca en el resultado debe estar entre comillas simples, a excepción de las comillas simples, que deben duplicarse, p.ej., "K 'o''clock.'".

Patrón	Descripción	Resultado de ejemplo
GG	Designador de era.	“ANUNCIO”
yy o aaaa	año.	1996
M	Mes en año. En enero: M produce 1 MM produce 01 El MMM produce enero El MMMM produce enero	“julio” “07”
d	Día en mes. Los valores "d" adicionales sumarán ceros a la izquierda.	10
h	Hora en una escala de 12 horas. Los valores "h" adicionales sumarán ceros a la izquierda.	12
H	Hora en una escala de 24 horas. Los valores Extra Hk' sumarán ceros a la izquierda.	0
m	Minuto en hora. Los valores "M" adicionales sumarán ceros a la izquierda.	30
s	Segundo en minuto. Los valores "s" adicionales agregarán ceros a la izquierda.	55
S	Fracción de segundo. Los valores “S” adicionales se rellenarán a la derecha con ceros.	978
E	Día de la semana. Próximos resultados de “martes”: E produce T EE o EEE Produce Tu o Mar El EEEE produce los martes	"Mar" “martes”
aa	a.m./p.m.	“PM”
k	Hora en día (1~24). Los valores "k" adicionales sumarán ceros a la izquierda.	24
K	Hora en a.m./p.m. (0~11). Los valores "k" adicionales sumarán ceros a la izquierda.	0
z	Zona horaria. Para la zona horaria 5, produce "UTC+5".	"UTC+5"
Z	Zona horaria en formato RFC 822. Para la zona horaria -5: Z, ZZ, ZZZ producen -0500 ZZZZ y otros productos producen "GMT -05:00"	“-0800” "GMT -05:00"
v	Zona horaria (genérica).	"Etc/GMT-5"
'	escape para texto	'Date='
.	comilla simple	''yy

NumberFormat

Describe cómo se debe dar formato a las columnas numéricas. Las opciones de formato incluyen la especificación de un símbolo de prefijo (como un signo de dólar) o la puntuación que se usará como marcador de miles.

Opciones

NumberFormat admite las siguientes opciones, que se pasan al constructor:

Opción	Descripción
decimalSymbol	Es un carácter que se usará como marcador decimal. El valor predeterminado es un punto (.).
fractionDigits	Es un número que especifica cuántos dígitos se deben mostrar después del decimal. El valor predeterminado es 2. Si especificas más dígitos de los que contiene el número, se mostrarán ceros para los valores más pequeños. Los valores truncados se redondearán (5 se redondearán hacia arriba).
groupingSymbol	Carácter que se utiliza para agrupar los dígitos que se encuentran a la izquierda del decimal en conjuntos de tres. El valor predeterminado es una coma (,).
negativeColor	El color del texto para los valores negativos. Sin valor predeterminado. Los valores pueden ser cualquier valor de color HTML aceptable, como "rojo" o "#FF0000".
negativeParens	Un valor booleano, donde "verdadero" indica que los valores negativos deben estar entre paréntesis. La opción predeterminada es true.
pattern	Es una cadena de formato. Cuando se proporciona, se ignoran todas las demás opciones, excepto negativeColor. La string de formato es un subconjunto del conjunto de patrones de ICU . Por ejemplo, {pattern:'#,###%'} dará como resultado valores de salida “1,000%”, “750%” y “50%” para los valores 10, 7.5 y 0.5.
prefix	Un prefijo de cadena para el valor, por ejemplo, "$".
suffix	Un sufijo de string para el valor, por ejemplo, "%".

Métodos

NumberFormat admite los siguientes métodos:

Método	Descripción
google.visualization.NumberFormat(options)	Constructor. Consulta la sección de opciones anterior para obtener más información.
format(dataTable, columnIndex)	Es el método format() estándar para aplicar formato a la columna especificada.
formatValue(value)	Muestra el valor con formato de un valor determinado. Este método no requiere un DataTable.

Código de muestra

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

Te permite combinar los valores de las columnas designadas en una sola columna, junto con texto arbitrario. Entonces, por ejemplo, si tuvieras una columna para el nombre y una para el apellido, podrías propagar una tercera columna con {last name}, {first name}. Este formateador no sigue las convenciones para el constructor y el método format(). Consulta la sección Métodos a continuación para obtener instrucciones.

Métodos

PatternFormat admite los siguientes métodos:

Método	Descripción
google.visualization.PatternFormat(pattern)	Constructor. No toma un objeto de opciones. En su lugar, toma un parámetro pattern de la cadena. Esta es una cadena que describe qué valores de columna deben incluirse en la columna de destino, junto con cualquier texto arbitrario. Incorpora marcadores de posición en tu cadena a fin de indicar un valor de otra columna para incorporar. Los marcadores de posición son {#}, en el que # es el índice de una columna de origen que se usará. El índice es un índice del array srcColumnIndices del método format() que aparece a continuación. Para incluir un carácter { or } literal, escápate de la siguiente manera: \{ or \}. Para incluir una marca \ literal, escáptala como \\. Código de muestra En el siguiente ejemplo, se muestra un constructor para un patrón que crea un elemento de anclaje, con el primer y segundo elemento tomado del método format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	La llamada de formato estándar, con algunos parámetros adicionales: dataTable: La DataTable en la que se opera. srcColumnIndices: Es un array de uno o más índices de columna (basados en cero) para extraer como fuentes de la DataTable subyacente. Se usará como fuente de datos para el parámetro pattern en el constructor. No es necesario que los números de columna estén en orden. opt_dstColumnIndex - [opcional] Es la columna de destino en la que se coloca el resultado de la manipulación de pattern. Si no se especifica, se usará el primer elemento en srcColumIndices como destino. Consulta los ejemplos de formato después de la tabla.

Estos son algunos ejemplos de entradas y salidas para una tabla de cuatro columnas.

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

Código de muestra

En el siguiente ejemplo, se muestra cómo combinar datos de dos columnas para crear una dirección de correo electrónico. Utiliza un objeto DataView para ocultar las columnas de origen originales:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

Clase de ayuda para simplificar la escritura de widgets que utilizan la API de visualización de Google.

Constructor

google.visualization.GadgetHelper()

Métodos

Método	Valor de retorno	Descripción
createQueryFromPrefs(prefs)	google.visualization.Query	Estático. Crea una nueva instancia de google.visualization.Query y configura sus propiedades de acuerdo con los valores de las preferencias del gadget. El tipo de parámetro prefs es _IG_Prefs. La preferencia _table_query_url se usa para establecer la URL de la fuente de datos de consulta. La preferencia _table_query_refresh_interval se usa para establecer el intervalo de actualización de la consulta (en segundos).
validateResponse(response)	Booleano	Estático. El parámetro response es del tipo google.visualization.QueryResponse. Muestra true si la respuesta contiene datos. Muestra false si la ejecución de la consulta falló y la respuesta no contiene datos. Si se produjo un error, este método muestra un mensaje de error.

Clases de consulta

Los siguientes objetos están disponibles para enviar consultas de datos a una fuente de datos externa, como Hojas de cálculo de Google.

• Consulta: Une la solicitud de datos saliente.
• QueryResponse: Maneja la respuesta de la fuente de datos.

Consulta

Representa una consulta que se envía a una fuente de datos.

Constructor

google.visualization.Query(dataSourceUrl, opt_options)

Parámetros

dataSourceUrl

[Obligatorio, Cadena] URL a la que se enviará la consulta. Consulta la documentación sobre gráficos y hojas de cálculo para Hojas de cálculo de Google.

opt_options

[Opcional, objeto] Un mapa de opciones para la solicitud. Nota: Si accedes a una fuente de datos restringida , no debes usar este parámetro. Estas son las propiedades admitidas:

• sendMethod: [opcional, string] especifica el método que se usará para enviar la consulta. Elige uno de los siguientes valores de cadena:
  • 'xhr': Envía la consulta con XmlHttpRequest.
  • 'scriptInjection': envía la consulta con la inyección de secuencia de comandos.
  • 'makeRequest': [Disponible solo para los gadgets, que están obsoletos] Envía la consulta con el método makeRequest() de la API de gadgets. Si se especifica, también debes especificar makeRequestParams.
  • 'auto': Usa el método especificado por el parámetro de URL tqrt de la URL de la fuente de datos. tqrt puede tener los siguientes valores: "xhr", "scriptInjection" o "makeRequest". Si falta tqrt o tiene un valor no válido, el valor predeterminado es "xhr" para solicitudes del mismo dominio y "scriptInjection" para las solicitudes entre dominios.
• makeRequestParams: [Objeto] Es un mapa de parámetros para una consulta makeRequest(). Se usa y solo es obligatorio si sendMethod es "makeRequest".

Métodos

Método	Valor de retorno	Descripción
abort()	Ninguno	Detiene el envío automático de consultas que se inició con setRefreshInterval().
setRefreshInterval(seconds)	Ninguno	Configura la consulta para que llame automáticamente al método send cada duración especificada (cantidad de segundos), a partir de la primera llamada explícita a send. seconds es un número mayor o igual que cero. Si usas este método, debes llamarlo antes de llamar al método send. Para cancelar este método, llámalo de nuevo con cero (el valor predeterminado) o llama a abort().
setTimeout(seconds)	Ninguno	Establece la cantidad de segundos que se debe esperar para que responda la fuente de datos antes de generar un error de tiempo de espera. seconds es un número mayor que cero. El tiempo de espera predeterminado es de 30 segundos. Si se usa, se debe llamar a este método antes de llamar al método send.
setQuery(string)	Ninguno	Establece la cadena de consulta. El valor del parámetro string debe ser una consulta válida. Si se usa, se debe llamar a este método antes de llamar al método send. Obtén más información sobre el lenguaje de consulta.
send(callback)	Ninguno	Envía la consulta a la fuente de datos. callback debe ser una función a la que se llamará cuando responda la fuente de datos. La función de devolución de llamada recibirá un solo parámetro de tipo google.visualization.QueryResponse.

QueryResponse

Representa una respuesta de la ejecución de una consulta tal como se recibió desde la fuente de datos. Se pasa una instancia de esta clase como un argumento a la función de devolución de llamada establecida cuando se llamó a Query.send.

Métodos

Método	Valor de retorno	Descripción
getDataTable()	DataTable	Muestra la tabla de datos como lo muestra la fuente de datos. Muestra null si la ejecución de la consulta falló y no se mostraron datos.
getDetailedMessage()	String	Muestra un mensaje de error detallado para las consultas que fallaron. Si la ejecución de la consulta fue exitosa, este método muestra una string vacía. El mensaje que se muestra es un mensaje dirigido a desarrolladores y puede contener información técnica, por ejemplo, "La columna {salario} no existe".
getMessage()	String	Muestra un mensaje de error corto para las consultas que fallaron. Si la ejecución de la consulta se realizó de forma correcta, este método muestra una string vacía. El mensaje que se muestra es un mensaje corto destinado a los usuarios finales, como “Consulta no válida” o “Acceso denegado”.
getReasons()	Arreglo de strings	Muestra un array de cero entradas adicionales. Cada entrada es una string corta con un código de error o advertencia que se generó mientras se ejecutaba la consulta. Códigos posibles: access_denied El usuario no tiene permisos para acceder a la fuente de datos. invalid_query La consulta especificada tiene un error de sintaxis. data_truncated Una o más filas de datos que coinciden con la selección de la consulta no se mostraron debido a los límites de tamaño de los resultados. (advertencia). timeout La consulta no respondió en el tiempo esperado.
hasWarning()	Booleano	Muestra true si la ejecución de la consulta tiene algún mensaje de advertencia.
isError()	Booleano	Muestra true si la ejecución de la consulta falló y la respuesta no contiene ninguna tabla de datos. Muestra <false> si la ejecución de la consulta fue exitosa y la respuesta contiene una tabla de datos.

Pantalla de errores

La API proporciona varias funciones para ayudarte a mostrar mensajes de error personalizados a tus usuarios. Para usar estas funciones, proporciona un elemento contenedor en la página (por lo general, un <div>), en el que la API mostrará un mensaje de error con formato. Este contenedor puede ser el elemento de contenedor de la visualización o un contenedor solo para errores. Si especificas el elemento contenedor de la visualización, se mostrará el mensaje de error sobre la visualización. Luego, llama a la función correspondiente de abajo para mostrar o quitar el mensaje de error.

Todas las funciones son estáticas en el espacio de nombres google.visualization.errors.

Muchas visualizaciones pueden arrojar un evento de error; consulta eventos de error a continuación para obtener más información al respecto.

Puedes ver un error personalizado de ejemplo en el ejemplo de wrapper de consultas.

Función	Valor de retorno	Descripción
addError(container, message, opt_detailedMessage, opt_options)	Valor de ID de cadena que identifica el objeto de error creado. Este es un valor único en la página y se puede usar para quitar el error o encontrar el elemento que lo contiene.	Agrega un bloque de visualización de error al elemento de página especificado, con texto y formato especificados. container: Es el elemento DOM en el que se debe insertar el mensaje de error. Si no se puede encontrar el contenedor, la función arrojará un error de JavaScript. message: Es un mensaje de cadena para mostrar. opt_detailedMessage: Es una string opcional de mensaje detallado. De forma predeterminada, este es texto que se muestra cuando se desplaza el mouse sobre un anuncio, pero esto se puede cambiar en la propiedad opt_options.showInToolTip que se describe a continuación. opt_options: Es un objeto opcional con propiedades que configuran varias opciones de visualización para el mensaje. Se admiten las siguientes opciones: showInTooltip: Un valor booleano donde "true" muestra el mensaje detallado solo como texto de información y "false" muestra el mensaje detallado en el cuerpo del contenedor después del mensaje corto. El valor predeterminado es verdadero. type: Es una cadena que describe el tipo de error y determina qué estilos CSS se deben aplicar a este mensaje. Los valores admitidos son "error" y "warning". El valor predeterminado es "error". style: Es una string de estilo para el mensaje de error. Este diseño anulará cualquier diseño aplicado al tipo de advertencia (opt_options.type). Ejemplo: 'background-color: #33ff99; padding: 2px;' El valor predeterminado es una string vacía. removable: Un valor booleano, donde "true" significa que el usuario puede cerrar el mensaje con un clic del mouse. El valor predeterminado es falso.
addErrorFromQueryResponse(container, response)	Valor de ID de string que identifica el objeto de error creado o nulo si la respuesta no indicó un error. Este es un valor único en la página y se puede usar para quitar el error o encontrar el elemento que lo contiene.	Pasa una respuesta de consulta y un contenedor de mensajes de error a este método: si la respuesta de la consulta indica un error de consulta, muestra un mensaje de error en el elemento de página especificado. Si la respuesta a la consulta es nula, el método arrojará un error de JavaScript. Pasa la QueryResponse que recibiste en tu controlador de consultas a este mensaje para mostrar un error. También configurará el estilo de la pantalla adecuado para el tipo (error o advertencia, similar a addError(opt_options.type)). container: Es el elemento DOM en el que se debe insertar el mensaje de error. Si no se puede encontrar el contenedor, la función arrojará un error de JavaScript. response: Un objeto QueryResponse que recibe el controlador de consultas en respuesta a una consulta. Si es nulo, el método arrojará un error de JavaScript.
removeError(id)	Booleano: Es verdadero si se quitó el error; de lo contrario, es falso.	Quita de la página el error especificado por ID. id: El ID de cadena de un error creado con addError() o addErrorFromQueryResponse().
removeAll(container)	Ninguno	Quita todos los bloques de errores de un contenedor especificado. Si el contenedor especificado no existe, se mostrará un error. contenedor: el elemento DOM que contiene las strings de error que se deben quitar. Si no se puede encontrar el contenedor, la función arrojará un error de JavaScript.
getContainer(errorId)	Maneja un elemento del DOM que contiene el error especificado o nulo si no se encuentra.	Recupera un controlador para el elemento contenedor que contiene el error especificado por errorID. errorId: ID de cadena de un error creado con addError() o addErrorFromQueryResponse().

Eventos

La mayoría de las visualizaciones activan eventos para indicar que algo ocurrió. Como usuario del gráfico, es posible que quieras escuchar estos eventos. Si codificas tu propia visualización, es posible que también desees activar esos eventos por tu cuenta.

Los siguientes métodos permiten a los desarrolladores escuchar eventos, quitar controladores de eventos existentes o activar eventos desde una visualización.

• google.visualization.events.addListener() y google.visualization.events.addOneTimeListener() detectan eventos.
• google.visualization.events.removeListener() quita un objeto de escucha existente
• google.visualization.events.removeAllListeners() quita todos los objetos de escucha de un gráfico específico.
• google.visualization.events.trigger() activa un evento.

addListener()

Llama a este método para registrarte y recibir eventos activados por una visualización alojada en tu página. Debes documentar qué argumentos de evento, si los hay, se pasarán a la función de control.

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

Es un controlador para la instancia de visualización de origen.

event_name

Es el nombre de la cadena del evento que se debe escuchar. Una visualización debe documentar qué eventos arroja.

handling_function

Es el nombre de la función local de JavaScript a la que se llamará cuando source_visualization active el evento event_name. La función de manejo recibirá cualquier argumento de evento como parámetro.

Qué muestra

Un controlador de objeto de escucha para el objeto de escucha nuevo. El controlador se puede usar para quitar este objeto de escucha más tarde, si es necesario, llamando a google.visualization.events.removeListener().

Ejemplo

Este es un ejemplo de cómo registrarse para recibir el evento de selección

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

Es idéntico a addListener(), pero está diseñado para eventos que solo se deben escuchar una vez. Los lanzamientos posteriores del evento no invocarán la función de control.

Un ejemplo de cuándo es útil esto: cada dibujo provoca un evento ready. Si quieres que solo los primeros ready ejecuten tu código, querrás addOneTimeListener en lugar de addListener.

removeListener()

Llama a este método para cancelar el registro de un objeto de escucha de eventos existente.

google.visualization.events.removeListener(listener_handler)

listener_handler

El controlador del objeto de escucha que se quitará, como lo muestra google.visualization.events.addListener().

removeAllListeners()

Llama a este método para cancelar el registro de todos los objetos de escucha de eventos de una instancia de visualización específica.

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

Es un controlador para la instancia de visualización de origen de la que se deben quitar todos los objetos de escucha de eventos.

trigger()

Llamados por implementadores de visualización. Llama a este método desde tu visualización para activar un evento con un nombre arbitrario y un conjunto de valores.

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

Es un controlador para la instancia de visualización de origen. Si llamas a esta función desde un método definido por la visualización de envío, simplemente puedes pasar la palabra clave this.

event_name

Es un nombre de cadena para llamar al evento. Puedes elegir cualquier valor de cadena que desees.

event_args

[opcional] Es un mapa de pares de nombre/valor para pasar al método receptor. Por ejemplo: {message: "Hello there!", score: 10, name: "Fred"}. Puedes pasar un valor nulo si no se necesitan eventos; el receptor debe estar preparado para aceptar un valor nulo en este parámetro.

Ejemplo

A continuación, se incluye un ejemplo de una visualización que muestra un método llamado "select" cuando se llama a su método "onclick". No devuelve ningún valor.

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
}

Métodos y propiedades de visualización estándar

Cada visualización debe exponer el siguiente conjunto de métodos y propiedades obligatorios y opcionales. Sin embargo, ten en cuenta que no existe verificación de tipo para aplicar estos estándares, por lo que debes leer la documentación de cada visualización.

• Constructor
• draw().
• getAction() [opcional]
• getSelection() (opcional)
• removeAction() [opcional]
• setAction() (opcional)
• setSelection() (opcional)

Nota: Estos métodos se encuentran en el espacio de nombres de la visualización, no en el espacio de nombres google.visualization.

Constructor

El constructor debe tener el nombre de tu clase de visualización y mostrar una instancia de esa clase.

visualization_class_name(dom_element)

dom_element

Un puntero para un elemento del DOM en el que se debe incorporar la visualización.

Ejemplo

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

Dibuja la visualización en la página. En segundo plano, se puede obtener un gráfico de un servidor o crearlo en la página con el código de visualización vinculado. Debes llamar a este método cada vez que cambien los datos o las opciones. El objeto debe dibujarse dentro del elemento del DOM que se pasa al constructor.

draw(data[, options])

datos

Es un objeto DataTable o DataView que contiene los datos que se usarán para dibujar el gráfico. No hay un método estándar para extraer un DataTable de un gráfico.

options

[Opcional] Es un mapa de pares nombre-valor de opciones personalizadas. Entre los ejemplos, se incluyen la altura y el ancho, los colores de fondo y las leyendas. La documentación de visualización debe enumerar las opciones disponibles y debe admitir las opciones predeterminadas si no especificas este parámetro. Puedes usar la sintaxis del literal de objeto de JavaScript para pasar un mapa de opciones: p.ej., {x:100, y:200, title:'An Example'}

Ejemplo

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

De manera opcional, se puede exponer mediante visualizaciones que tienen información sobre la herramienta y permiten acciones sobre herramientas.

Muestra el objeto de acción de información sobre la herramienta con el actionID solicitado.

Ejemplo:

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

De manera opcional, se puede exponer mediante visualizaciones que te permiten acceder a los datos seleccionados en el gráfico.

selection_array getSelection()

Qué muestra

selection_array: Es un array de objetos seleccionados, cada uno de los cuales describe un elemento de datos en la tabla subyacente que se usa para crear la visualización (una DataView o una DataTable). Cada objeto tiene propiedades row o column, con el índice de la fila o columna del elemento seleccionado en el DataTable subyacente. Si la propiedad row es nula, la selección es una columna. Si la propiedad column es nula, la selección es una fila. Si ambas no son nulas, es un elemento de datos específico. Puedes llamar al método DataTable.getValue() para obtener el valor del elemento seleccionado. El array recuperado se puede pasar a setSelection().

Ejemplo

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

De manera opcional, se puede exponer mediante visualizaciones que tienen información sobre la herramienta y permiten acciones sobre herramientas.

Quita el objeto de acción de información sobre la herramienta con el actionID solicitado de tu gráfico.

Ejemplo:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

De manera opcional, se puede exponer mediante visualizaciones que tienen información sobre la herramienta y permiten acciones sobre herramientas. Solo funciona para los gráficos principales (barra, columna, línea, área, dispersión, combinado, burbuja, circular, dona, vela, histograma, área escalonada).

Establece una acción de información sobre la herramienta que se ejecutará cuando el usuario haga clic en el texto de acción.

setAction(action object)

El método setAction toma un objeto como su parámetro de acción. Este objeto debe especificar 3 propiedades: id (el ID de la acción que se establece, text, el texto que debe aparecer en la información sobre la acción) y action (la función que se debe ejecutar cuando un usuario hace clic en el texto de acción).

Todas las acciones de información sobre la herramienta se deben configurar antes de llamar al método draw() del gráfico.

Ejemplo:

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

El método setAction también puede definir dos propiedades adicionales: visible y enabled. Estas propiedades deben ser funciones que muestren valores boolean que indiquen si la acción de información sobre la herramienta será visible o habilitada.

Ejemplo:

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

De manera opcional, selecciona una entrada de datos en la visualización (por ejemplo, un punto en un gráfico de áreas o una barra en un gráfico de barras). Cuando se llama a este método, la visualización debe indicar visualmente cuál es la nueva selección. La implementación de setSelection() no debe activar un evento "select". Las visualizaciones pueden ignorar parte de la selección. Por ejemplo, una tabla que solo puede mostrar las filas seleccionadas puede ignorar elementos de celda o columna en su implementación de setSelection(), o bien puede seleccionar toda la fila.

Cada vez que se llama a este método, se anula la selección de todos los elementos seleccionados y se debe aplicar la nueva lista de selección que se pasó. No hay una forma explícita de anular la selección de elementos individuales. Para anular la selección de elementos individuales, llama a setSelection() con los elementos para que permanezcan seleccionados. Para anular la selección de todos los elementos, llama a setSelection(), setSelection(null) o setSelection([]).

setSelection(selection_array)

selection_array

Es un array de objetos, cada uno con una propiedad numérica de fila o columna. row y column son el número de fila o columna basado en cero de un elemento de la tabla de datos que deseas seleccionar. Para seleccionar una columna completa, establece row como nulo; para seleccionar una fila completa, establece column como nulo. Ejemplo: setSelection([{row:0,column:1},{row:1, column:null}]) selecciona la celda ubicada en (0,1) y toda la fila 1.

Métodos estáticos variados

En esta sección, se incluyen varios métodos útiles expuestos en el espacio de nombres google.visualization.

arrayToDataTable()

Este método toma un array bidimensional y lo convierte en un objeto DataTable.

Los tipos de datos de la columna se determinan automáticamente con los datos proporcionados. Los tipos de datos de la columna también se pueden especificar con la notación de literal de objeto en la primera fila (la fila de encabezado de la columna) del array (es decir, {label: 'Start Date', type: 'date'}). También se pueden usar funciones de datos opcionales, pero deben definirse de manera explícita con la notación literal de objeto. La notación literal de objeto también se puede usar para cualquier celda, lo que te permite definir Objetos de celda.

Sintaxis

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

Es un array bidimensional, en el que cada fila representa una fila de la tabla de datos. Si opt_firstRowIsData es falso (el valor predeterminado), la primera fila se interpretará como etiquetas de encabezado. Los tipos de datos de cada columna se interpretan automáticamente a partir de los datos proporcionados. Si una celda no tiene valor, especifica un valor nulo o vacío según corresponda.

opt_firstRowIsData

Indica si la primera fila define una fila de encabezado o no. Si es verdadero, se supone que todas las filas son datos. Si es falso, se supone que la primera fila es una fila de encabezado y los valores se asignan como etiquetas de columna. El valor predeterminado es falso.

Qué muestra

Un nuevo objeto DataTable

Ejemplos

En el siguiente código, se muestran tres formas de crear el mismo objeto DataTable:

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

Este método crea un gráfico en una sola llamada. La ventaja de usar este método es que requiere un poco menos de código, y puedes serializar y guardar visualizaciones como strings de texto para reutilizarlas. Este método no muestra un controlador para el gráfico creado, por lo que no puedes asignar objetos de escucha de métodos para captar eventos del gráfico.

Sintaxis

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

Una string literal JSON o un objeto JavaScript, con las siguientes propiedades (distingue mayúsculas de minúsculas):

Propiedad	Tipo	Obligatorio	Predeterminado	Descripción
chartType	String	Obligatorio	ninguno	Es el nombre de clase de la visualización. El nombre del paquete google.visualization se puede omitir para los gráficos de Google. Si todavía no se cargó la biblioteca de visualización adecuada, este método cargará la biblioteca por ti si se trata de una visualización de Google. Debes cargar las visualizaciones de terceros de manera explícita. Ejemplos: Table, PieChart y example.com.CrazyChart.
containerId	String	Obligatorio	ninguno	El ID del elemento DOM en tu página que alojará la visualización.
Opciones	Objeto	Opcional	ninguno	Es un objeto que describe las opciones para la visualización. Puedes usar la notación literal de JavaScript o proporcionar un controlador para el objeto. Ejemplo: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	Objeto	Opcional	Ninguno	Un DataTable que se usa para propagar la visualización Puede ser una representación de string JSON literal de una DataTable, como se describió anteriormente, un controlador para un objeto google.visualization.DataTable propagado o un array bidimensional como el que acepta arrayToDataTable(opt_firstRowIsData=false) . Debes especificar esta propiedad o la propiedad dataSourceUrl.
dataSourceUrl	String	Opcional	Ninguno	Una consulta de fuente de datos para propagar los datos del gráfico (por ejemplo, una hoja de cálculo de Google). Debes especificar esta propiedad o la propiedad dataTable.
búsqueda	String	Opcional	Ninguno	Si especificas dataSourceUrl, tienes la opción de especificar una cadena de consulta similar a SQL con el lenguaje de consulta de visualización para filtrar o manipular los datos.
refreshInterval	Número	Opcional	Ninguno	Es la frecuencia con la que la visualización, en segundos, debe actualizar su fuente de consulta. Úsalo solo cuando especifiques dataSourceUrl.
vista	Objeto OR array	Opcional	Ninguno	Establece un objeto de inicializador DataView, que actúa como un filtro sobre los datos subyacentes, según lo definido por el parámetro dataTable o dataSourceUrl. Puedes pasar una cadena o un objeto inicializador DataView, como el que muestra dataview.toJSON(). Ejemplo: "view": {"columns": [1, 2]} También puedes pasar un array de objetos inicializadores de DataView, en cuyo caso el primer DataView del array se aplica a los datos subyacentes para crear una nueva tabla de datos, y el segundo DataView se aplica a la tabla de datos resultante de la aplicación de la primera DataView, y así sucesivamente.

Ejemplos

Crea un gráfico de tabla basado en una fuente de datos de hoja de cálculo e incluye la consulta SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

En el siguiente ejemplo, se crea la misma tabla, pero se crea un DataTable de forma local:

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

En este ejemplo, se pasa una representación de cadena JSON del gráfico, que puedes haber cargado desde un archivo:

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

Este es el constructor del elemento de la barra de herramientas que se puede adjuntar a muchas visualizaciones. Esta barra de herramientas permite al usuario exportar los datos de visualización en diferentes formatos o proporcionar una versión incorporable de la visualización para usarla en diferentes lugares. Consulta la página de la barra de herramientas para obtener más información y un ejemplo de código.