Controles y paneles de control

En esta página, verás cómo combinar varios gráficos en paneles y dar a los usuarios controles para manipular los datos que muestran.

Descripción general

Los paneles son una forma sencilla de organizar y administrar varios gráficos que comparten los mismos datos subyacentes. Si usas las API que se describen en esta página, puedes liberarte de la carga de conectar y coordinar todos los gráficos que forman parte de un panel.

Los paneles se definen usando clases google.visualization.Dashboard. Las instancias de Dashboard reciben un DataTable que contiene los datos para visualizar y encargarse de dibujar y distribuir los datos a todos los gráficos que forman parte del panel.

Los controles son widgets de interfaz de usuario (como selectores de categoría, controles deslizantes de rango, autocompletados, etc.) con los que interactúas para controlar los datos que administra un panel y los gráficos que forman parte de él.

Los controles se definen con las clases google.visualization.ControlWrapper. Puedes agregar instancias de ControlWrapper a un panel, en el que se comportan como canalizaciones y válvulas en un sistema de plomería. Recopilan las entradas del usuario y usan la información para decidir qué datos administra el panel que deben estar disponibles para los gráficos que forman parte de él.

Observa el siguiente ejemplo, en el que se usan un selector de categoría y un control deslizante de rango para controlar los datos visualizados en un gráfico circular.

Nota: El panel es interactivo. Prueba operar los controles y observa el gráfico en tiempo real.

Uso de los controles y paneles

Estos son los pasos clave para crear un panel y, luego, incorporarlo en tu página. A continuación, encontrarás un fragmento de código que muestra todos estos pasos, seguido de información detallada sobre cada uno.

  1. Crea un esquema HTML para tu panel. Tu página debe tener tantos elementos HTML como sea necesario para incluir a todos los miembros de un panel. Esto incluye el panel en sí y todos los controles y gráficos que forman parte de él. Por lo general, usarás una <div> para cada uno.
  2. Carga tus bibliotecas. Un panel requiere que solo se incluyan o carguen dos bibliotecas en la página: la API de AJAX de Google y el paquete controls de visualización de Google.
  3. Prepara tus datos. Deberás preparar los datos que quieras visualizar, lo que implica especificar los datos tú mismo en el código o consultarlos en un sitio remoto.
  4. Crea una instancia de panel. Para crear una instancia de tu panel, llama a su constructor y pasa una referencia al elemento <div> que lo contendrá.
  5. Crea todas las instancias de controles y gráficos que necesites. Crea instancias de google.visualization.ChartWrapper y google.visualization.ControlWrapper para describir cada gráfico y controlar que el panel administre.
  6. Establece dependencias. Llama a bind() en tu panel y pasa las instancias de control y gráfico para permitir que el panel sepa qué administrar. Una vez que un control y un gráfico están vinculados, el panel actualiza el gráfico para que coincida con las restricciones que el control aplica a los datos.
  7. Dibuja tu panel. Llama a draw() en el panel y pasa los datos para dibujar el panel completo en la página.
  8. Cambios programáticos después del dibujo. De manera opcional, después del dibujo inicial, puedes controlar de manera programática los controles que forman parte del panel y hacer que este actualice los gráficos en respuesta a eso.

Este es un ejemplo simple de una página que crea un panel simple con un control deslizante de rango que impulsa un gráfico circular. El panel resultante se muestra debajo del fragmento. 

<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">

      // Load the Visualization API and the controls package.
      google.charts.load('current', {'packages':['corechart', 'controls']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(drawDashboard);

      // Callback that creates and populates a data table,
      // instantiates a dashboard, a range slider and a pie chart,
      // passes in the data and draws it.
      function drawDashboard() {

        // Create our data table.
        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        // Create a dashboard.
        var dashboard = new google.visualization.Dashboard(
            document.getElementById('dashboard_div'));

        // Create a range slider, passing some options
        var donutRangeSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'filter_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten'
          }
        });

        // Create a pie chart, passing some options
        var pieChart = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'pieSliceText': 'value',
            'legend': 'right'
          }
        });

        // Establish dependencies, declaring that 'filter' drives 'pieChart',
        // so that the pie chart will only display entries that are let through
        // given the chosen slider range.
        dashboard.bind(donutRangeSlider, pieChart);

        // Draw the dashboard.
        dashboard.draw(data);
      }
    </script>
  </head>

  <body>
    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>
  </body>
</html>

Este es el panel que crea este código.

1. Crea un esqueleto HTML para tu panel

Tu página debe tener tantos elementos HTML (por lo general, <div>s) para contener el panel en sí y todos los controles y gráficos que forman parte de él. Cuando creas instancias de paneles, controles y gráficos, debes pasar una referencia a su elemento, por lo que debes asignar un ID a cada elemento HTML. 

    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>

Puedes colocar cada elemento HTML como quieras que se vea tu panel.

2. Carga tus bibliotecas

Un panel requiere que solo se incluyan o carguen dos bibliotecas en la página: la API de AJAX de Google y el paquete controls de visualización de Google. La API (en particular, google.visualization.ChartWrapper) identifica automáticamente los otros paquetes necesarios (por ejemplo, gauge si usas un gráfico de indicadores) y los carga sobre la marcha sin que tengas que intervenir.

Debes usar google.charts.load() para recuperar la biblioteca de control.

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">

  // Load the Visualization API and the controls package.
  // Packages for all the other charts you need will be loaded
  // automatically by the system.
  google.charts.load('current', {'packages':['corechart', 'controls']});

  // Set a callback to run when the Google Visualization API is loaded.
  google.charts.setOnLoadCallback(drawDashboard);

  function drawDashboard() {
    // Everything is loaded. Assemble your dashboard...
  }
</script>

3. Prepara tus datos

Cuando se haya cargado la API de visualización, google.charts.setOnLoadCallback() llamará a la función de controlador para que sepas que todas las clases y los métodos auxiliares necesarios estarán listos para que comiences a preparar los datos.

Los paneles aceptan datos en una DataTable, al igual que los gráficos.

4. Crea una instancia de panel

Después de crear tus datos, puedes crear una instancia de tu objeto de panel. Un constructor de panel toma un parámetro: una referencia al elemento del DOM en el cual debe dibujarse el panel. 

  var dashboard = new google.visualization.Dashboard(document.getElementById('dashboard_div'));

Los paneles se exponen como una clase de JavaScript. Después de crear una instancia del panel, puedes realizar algunos pasos opcionales, como agregar objetos de escucha de eventos (por ejemplo, recibir una notificación cuando el panel esté "listo"). Los paneles manejan los eventos de la misma manera que los gráficos, por lo que debes consultar Cómo administrar los eventos de visualización o Cómo mostrar errores de forma correcta en la sección del gráfico para obtener más información.

5. Crear instancias de control y gráfico

Define todas las instancias que necesites para cada control y gráfico que formarán parte del panel. Usa google.visualization.ChartWrapper y google.visualization.ControlWrapper para definir gráficos y controles, respectivamente. 

  // Create a range slider, passing some options
  var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten'
    }
  });

  // Create a pie chart, passing some options
  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'pieSliceText': 'label'
    }
  });

Cuando crees instancias de ChartWrapper y ControlWrapper, no especifiques los parámetros dataTable ni dataSourceUrl. El panel se encarga de alimentar a cada uno con los datos adecuados. Sin embargo, asegúrate de especificar los parámetros obligatorios: chartType y containerId para los gráficos, controlType y containerId para los controles.

Algunos consejos sobre la configuración de controles y gráficos:

  • Debes otorgar a todos los controles un filterColumnIndex (o filterColumnLabel) para especificar en qué columna de google.visualization.DataTable opera el control (en el ejemplo anterior, el control opera en la columna etiquetada Donas ingeridas).

  • Usa la opción de configuración state en los controles para inicializarlos con un estado explícito cuando se dibujen por primera vez. Por ejemplo, usa este parámetro de configuración para fijar las posiciones iniciales de los círculos de un control deslizante de rango. 

      var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten',
      'minValue': 1,
      'maxValue': 10
    },
    // Explicitly positions the thumbs at position 3 and 8,
    // out of the possible range of 1 to 10.
    'state': {'lowValue': 3, 'highValue': 8}
  });

  • Todos los gráficos que forman parte de un panel comparten la misma dataTable subyacente que preparaste en el paso Prepara tus datos. Sin embargo, los gráficos a menudo requieren una disposición específica de columnas para mostrarse de forma correcta. Por ejemplo, un gráfico circular requiere una columna de string para la etiqueta, seguida de una columna de números para el valor.

    Usa la opción view mientras configuras cada instancia de ChartWrapper a fin de declarar qué columnas son relevantes para el gráfico, como en el siguiente ejemplo. 

      var data = google.visualization.arrayToDataTable([
    ['Name', 'Gender', 'Age', 'Donuts eaten'],
    ['Michael' , 'Male', 12, 5],
    ['Elisa', 'Female', 20, 7],
    ['Robert', 'Male', 7, 3],
    ['John', 'Male', 54, 2],
    ['Jessica', 'Female', 22, 6],
    ['Aaron', 'Male', 3, 1],
    ['Margareth', 'Female', 42, 8]
  ]);

  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'title': 'Donuts eaten per person'
    },
    // The pie chart will use the columns 'Name' and 'Donuts eaten'
    // out of all the available ones.
    'view': {'columns': [0, 3]}
  });

  // The rest of dashboard configuration follows
  // ...

6. Establecer dependencias

Una vez que hayas creado una instancia para el panel y todos los controles y gráficos que formarán parte de él, usa el método bind() para indicarle al panel las dependencias que existen entre los controles y los gráficos.

Una vez que un control y un gráfico están vinculados, el panel actualiza el gráfico para que coincida con las restricciones que el control aplica sobre los datos. En el panel de ejemplo que estás compilando, el control deslizante de rango y el gráfico circular están vinculados, por lo que cada vez que interactúas con el primero, el último se actualiza para mostrar solo los datos que coinciden con el rango seleccionado. 

  // 'pieChart' will update whenever you interact with 'donutRangeSlider'
  // to match the selected range.
  dashboard.bind(donutRangeSlider, pieChart);

Puedes vincular controles y gráficos en muchas configuraciones diferentes: uno a uno, uno a varios, de varios a uno y de varios a varios. Cuando se vinculan varios controles a un gráfico, el panel actualiza el gráfico para que coincida con las restricciones combinadas que aplican todos los controles vinculados. Al mismo tiempo, un control puede generar varios gráficos de forma simultánea. Para especificar varias vinculaciones al mismo tiempo, pasa los arrays al método bind() en lugar de instancias individuales. También puedes encadenar varias llamadas bind(). Aquí tiene algunos ejemplos. 

  // Many-to-one binding where 'ageSelector' and 'salarySelector' concurrently
  // participate in selecting which data 'ageVsSalaryScatterPlot' visualizes.
  dashboard.bind([agePicker, salaryPicker], ageVsSalaryScatterPlot);

  // One-to-many binding where 'ageSelector' drives two charts.
  dashboard.bind(agePicker, [ageVsSalaryScatterPlot, ageBarChart]);

  // bind() chaining where each control drives its own chart.
  dashboard.bind(agePicker, ageBarChart).bind(salaryRangePicker, salaryPieChart);

Para usos avanzados, también puedes vincular controles a otros controles para establecer cadenas de dependencias . 

  dashboard.bind(countryPicker, regionPicker).bind(regionPicker, cityPicker);

7. Dibuja tu panel

Llama al método draw() en la instancia del panel para renderizar el panel completo. El método draw() toma solo un parámetro: el DataTable (o DataView) que potencia el panel.

Debes llamar a draw() cada vez que cambies la composición del panel (por ejemplo, si le agregas controles o gráficos nuevos) o cambias el DataTable general que lo impulsa.

La instancia de panel activa un evento ready cada vez que draw() termina de dibujar todos los controles y gráficos que forman parte de él. Se activa un evento error si alguno de los controles o gráficos administrados no se puede generar. Para obtener más información sobre cómo controlar eventos, consulta Cómo controlar eventos.

Nota: Debes escuchar el evento ready antes de intentar cambiar la composición del panel o dibujarla nuevamente.

8. Cambios programáticos después del dibujo

Una vez que el panel complete la draw() inicial, estará publicado y responderá automáticamente a cualquier acción que realices en él (como cambiar el rango seleccionado de un control deslizante que forma parte del panel).

Si necesitas modificar de manera programática el estado del panel, puedes operar directamente en las instancias ControlWrapper y ChartWrapper que forman parte de él. La regla general es realizar cualquier cambio que necesites directamente en la instancia ControlWrapper (o ChartWrapper) específica; por ejemplo, cambiar una opción o un estado de control con setOption() y setState(), respectivamente, y luego llamar a su método draw(). El panel se actualizará para que coincida con los cambios solicitados.

En el siguiente ejemplo, se muestra este caso.
Página web completa
<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">
      google.charts.load('current', {'packages':['corechart', 'controls']});
      google.charts.setOnLoadCallback(drawStuff);

      function drawStuff() {

        var dashboard = new google.visualization.Dashboard(
          document.getElementById('programmatic_dashboard_div'));

        // We omit "var" so that programmaticSlider is visible to changeRange.
        var programmaticSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'programmatic_control_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten',
            'ui': {'labelStacking': 'vertical'}
          }
        });

        var programmaticChart  = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'programmatic_chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'legend': 'none',
            'chartArea': {'left': 15, 'top': 15, 'right': 0, 'bottom': 0},
            'pieSliceText': 'value'
          }
        });

        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        dashboard.bind(programmaticSlider, programmaticChart);
        dashboard.draw(data);

        changeRange = function() {
          programmaticSlider.setState({'lowValue': 2, 'highValue': 5});
          programmaticSlider.draw();
        };

        changeOptions = function() {
          programmaticChart.setOption('is3D', true);
          programmaticChart.draw();
        };
      }

    </script>
  </head>
  <body>
    <div id="programmatic_dashboard_div" style="border: 1px solid #ccc">
      <table class="columns">
        <tr>
          <td>
            <div id="programmatic_control_div" style="padding-left: 2em; min-width: 250px"></div>
            <div>
              <button style="margin: 1em 1em 1em 2em" onclick="changeRange();">
                Select range [2, 5]
              </button><br />
              <button style="margin: 1em 1em 1em 2em" onclick="changeOptions();">
                Make the pie chart 3D
              </button>
            </div>
          </td>
          <td>
            <div id="programmatic_chart_div"></div>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>

Referencia de la API

En esta sección, se enumeran los objetos que expone la API de controles y paneles, y los métodos estándar que exponen todos los controles.

Panel

Representa una colección de gráficos y controles colaborativos que comparten los mismos datos subyacentes.

Constructor

Dashboard(containerRef)
containerRef
Es una referencia a un elemento de contenedor válido en la página que contendrá el contenido del panel.

Métodos

El panel expone los siguientes métodos:

Método Tipo de datos que se muestra Descripción
bind(controls, charts) google.visualization.Dashboard

Vincula uno o más controles a uno o más participantes del panel (ya sean gráficos o algún otro control), de modo que todos estos últimos se vuelvan a dibujar cada vez que alguno de ellos recopile una interacción programática o del usuario que afecte los datos administrados por el panel. Muestra la instancia de panel para encadenar varias llamadas a bind().

  • controles: Una instancia o un array de instancias de google.visualization.ControlWrapper que definen los controles que se vincularán.
  • charts: Una sola instancia o un array de google.visualization.ChartWrapper que define los gráficos que controlarán los controles.
draw(dataTable) Ninguno

Dibuja el panel.

  • dataTable: Cualquiera de las siguientes opciones: un objeto DataTable, un objeto DataView, una representación JSON de una DataTable o un array que siga la sintaxis de google.visualization.arrayToDataTable() .
getSelection() Array de objetos

Muestra un array de las entidades visuales seleccionadas de los gráficos del panel. Cuando se llama al método getSelection() en el panel, se muestra un agregado de todas las selecciones realizadas en todos los gráficos que contiene, lo que permite usar una única referencia cuando se trabaja con selecciones de gráficos.

Nota: Los objetos de escucha de eventos para el evento de selección aún deben adjuntarse a cada gráfico que deseas escuchar.

Descripción extendida

Eventos

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

Nombre Descripción Propiedades
error Se activa cuando se produce un error cuando se intenta renderizar el panel. Es posible que se haya producido un error en la renderización de uno o más de los controles y gráficos del panel. ID, mensaje
ready

Se completó el dibujo del panel y está listo para aceptar cambios. Todos los controles y gráficos que forman parte del panel están listos para llamadas de método externas y la interacción del usuario. Si deseas cambiar el panel (o los datos que muestra) después de dibujarlo, debes configurar un objeto de escucha para este evento antes de llamar al método draw y, luego, aplicar los cambios solo después de que se haya activado el evento.

También se activará el evento ready:

  • después de la finalización de una actualización del panel activada por un usuario o una interacción programática con uno de
  • después de una llamada programática al método draw() de cualquier parte del gráfico del panel.
Ninguno

ControlWrapper

Un objeto ControlWrapper es un wrapper alrededor de una representación JSON de una instancia de control configurada. La clase expone métodos convenientes para definir un control de panel, dibujarlo y cambiar su estado de manera programática.

Constructor

ControlWrapper(opt_spec)
opt_spec
[Opcional]: Es un objeto JSON que define el control o una versión de cadena serializada de ese objeto. Las propiedades admitidas del objeto JSON se muestran en la siguiente tabla. Si no se especifica, debes configurar todas las propiedades apropiadas con los métodos set... expuestos por ControlWrapper.
Propiedad Tipo Obligatorio Predeterminado Descripción
controlType String Obligatorio ninguno Es el nombre de clase del control. Se puede omitir el nombre del paquete google.visualization para los controles de Google. Ejemplos: CategoryFilter, NumberRangeFilter.
containerId String Obligatorio ninguno Es el ID del elemento DOM de tu página que alojará el control.
Opciones Objeto Opcional ninguno Un objeto que describe las opciones del control. Puedes usar la notación literal de JavaScript o proporcionar un controlador para el objeto. Ejemplo: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state Objeto Opcional ninguno Un objeto que describe el estado del control. El estado recopila todas las variables que puede afectar el usuario que opera el control. Por ejemplo, el estado de un control deslizante de rango se puede describir en términos de las posiciones que ocupa el dedo pulgar inferior y alto del control deslizante. Puedes usar la notación literal de JavaScript o proporcionar un controlador para el objeto.Ejemplo: "state": {"lowValue": 20, "highValue": 50}

Métodos

ControlWrapper expone los siguientes métodos adicionales:

Método Tipo de datos que se muestra Descripción
draw() Ninguno

Dibuja el control. Normalmente, el panel que contiene el control se encarga de dibujarlo. Debes llamar a draw() para forzar los rediseños programáticos del control después de cambiar cualquiera de sus otros parámetros de configuración, como las opciones o el estado.

toJSON() String Muestra una versión de cadena de la representación JSON del control.
clone() ControlWrapper Muestra una copia profunda del wrapper de control.
getControlType() String Es el nombre de clase del control. Si es un control de Google, el nombre no se calificará con google.visualization. Por ejemplo, si este fuera un control de CategoryFilter, mostraría "CategoryFilter" en lugar de "google.visualization.CategoryFilter".
getControlName() String Muestra el nombre de control que asignó setControlName().
getControl() Referencia de objetos de control Muestra una referencia al control creado por este ControlWrapper. Se mostrará un valor nulo hasta que hayas llamado a draw() en el objeto ControlWrapper (o en el panel que lo contiene) y se arroje un evento listo. El objeto que se muestra solo expone un método: resetControl(), que restablece el estado de control al que se inicializó (como restablecer un elemento de formulario HTML).
getContainerId() String El ID del elemento del contenedor DOM del control.
getOption(key, opt_default_val) Cualquier tipo

Devuelve el valor de opción de control especificado.

  • clave: El nombre de la opción que se debe recuperar. Puede ser un nombre calificado, como 'vAxis.title'.
  • opt_default_value [opcional]: si el valor especificado es indefinido o nulo, se mostrará este valor.
getOptions() Objeto Muestra el objeto de opciones para este control.
getState() Objeto Muestra el estado de control.
setControlType(type) Ninguno Establece el tipo de control. Pasa el nombre de clase del control para crear una instancia. Si se trata de un control de Google, no lo califiques con google.visualization. Por ejemplo, para un control deslizante de rango sobre una columna numérica, pasa "NumberRangeFilter".
setControlName(name) Ninguno Establece un nombre arbitrario para el control. Esto no se muestra en ninguna parte del control, pero es solo para tu referencia.
setContainerId(id) Ninguno Establece el ID del elemento DOM que lo contiene para el control.
setOption(key, value) Ninguno Establece un solo valor de opción de control, en el que key es el nombre de la opción y value es el valor. Para anular una opción, pasa null para el valor. Ten en cuenta que key puede ser un nombre calificado, como 'vAxis.title'.
setOptions(options_obj) Ninguno Configura un objeto de opciones completo para un control.
setState(state_obj) Ninguno Establece el estado de control. El estado recopila todas las variables que puede afectar el usuario que opera el control. Por ejemplo, el estado de un control deslizante de rango puede describirse en términos de las posiciones que ocupa el dedo pulgar inferior y alto del control deslizante.

Eventos

El objeto ControlWrapper genera los siguientes eventos. Ten en cuenta que debes llamar a ControlWrapper.draw() (o dibujar el panel que contiene el control) antes de que se arroje cualquier evento.

Nombre Descripción Propiedades
error Se activa cuando se produce un error cuando se intenta procesar el control. ID, mensaje
ready El control está listo para aceptar la interacción del usuario y las llamadas a métodos externas. Si deseas interactuar con el control y llamar a los métodos después de dibujarlo, debes configurar un objeto de escucha para este evento antes de llamar al método draw e llamarlos solo después de que se haya activado el evento. De manera alternativa, puedes escuchar un evento ready en el panel manteniendo los métodos de control y de control de llamadas solo después de que se haya activado el evento. Ninguno
statechange Se activa cuando el usuario interactúa con el control, lo que afecta su estado. Por ejemplo, se activará un evento statechange cada vez que muevas el pulgar de un control deslizante de rango. Para recuperar un estado de control actualizado después de que se activó el evento, llama a ControlWrapper.getState(). Ninguno

ChartWrapper

Consulta la documentación de google.visualization.ChartWrapper en la sección de referencia de la API de visualizaciones.

Las siguientes notas se aplican cuando se usa un ChartWrapper como parte de un panel:

  • No configures los atributos dataTable, query, dataSourceUrl ni refreshInterval de forma explícita. El panel que contiene el gráfico se encarga de proporcionarle los datos que necesita.
  • Establece su atributo view a fin de declarar qué columnas, de todas las presentes en el dataTable proporcionado al panel, son relevantes para el gráfico, como se muestra en Crea instancias de control y gráficos.

Los filtros son elementos gráficos que las personas pueden usar para seleccionar de forma interactiva qué datos se muestran en tu gráfico. En esta sección, se describen los filtros del gráfico de Google: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter y StringFilter.

Puedes usar cualquiera de ellas como parámetro para ControlWrapper.setControlType().

Nota: Al describir opciones, la notación de puntos se usa para describir los atributos de objetos anidados. Por ejemplo, se debe declarar una opción llamada 'ui.label' en un objeto de opciones como var options = {"ui": {"label": "someLabelValue"} };

CategoryFilter

Un selector para elegir uno o más valores de un conjunto de valores definidos.

Estado

Nombre Tipo Predeterminado Descripción
selectedValues Array de objetos o tipos primitivos ninguno Es el conjunto de valores seleccionado actualmente. Los valores seleccionados deben ser un conjunto de todos los valores seleccionables definidos por la opción values (se ignorará cualquier ajeno). Si CategoryFilter no permite la opción múltiple, solo se conserva el primer valor del array.

Opciones

Nombre Tipo Predeterminado Descripción
filterColumnIndex número ninguno Es la columna de la tabla de datos sobre la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnLabel. Si ambas están presentes, esta opción tiene prioridad.
filterColumnLabel cadena ninguno Es la etiqueta de la columna en la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnIndex. Si ambas están presentes, filterColumnIndex tiene prioridad.
valores Array automático Lista de valores para elegir. Si se usa un array de objetos, estos deben tener una representación de toString() adecuada para mostrarse al usuario. Si es nulo o indefinido, la lista de valores se calculará automáticamente a partir de los valores presentes en la columna DataTable en la que opera este control.
useFormattedValue boolean false Cuando se propaga automáticamente la lista de valores seleccionables desde la columna DataTable, este filtro funciona, ya sea para usar los valores reales de las celdas o sus valores con formato.
ui Objeto null Un objeto con miembros para configurar varios aspectos de la IU del control. Para especificar propiedades de este objeto, puedes usar la notación literal de objeto, como se muestra aquí: 
{label: 'Metric', labelSeparator: ':'}
ui.caption cadena "Elige un valor..." Es la leyenda que se mostrará dentro del widget del selector de valores cuando no se seleccione ningún elemento.
ui.sortValues boolean verdadero Indica si deben ordenarse los valores que se deben elegir.
ui.selectedValuesLayout cadena "apartado" Cómo mostrar los valores seleccionados cuando se permite la selección múltiple Los valores posibles son los siguientes:
  • 'aside': Los valores seleccionados se mostrarán en una sola línea de texto junto al widget del selector de valores.
  • 'below': Los valores seleccionados se mostrarán en una sola línea de texto debajo del widget.
  • 'belowWrapping': Es similar a below, pero las entradas que no pueden caber en el selector se unirán a una línea nueva.
  • 'belowStacked': Los valores seleccionados se mostrarán en una columna debajo del widget.
ui.allowNone boolean verdadero Indica si el usuario no puede elegir ningún valor. Si es false, el usuario debe elegir al menos un valor de los disponibles. Durante la inicialización del control, si la opción se establece en false y no se proporciona un estado selectedValues, el primer valor de los disponibles se selecciona automáticamente.
ui.allowMultiple boolean verdadero Indica si se pueden seleccionar varios valores, en lugar de solo uno.
ui.allowTyping boolean verdadero Indica si se le permite al usuario escribir en un campo de texto para reducir la lista de opciones posibles (mediante un autocompletado) o no.
ui.label cadena automático La etiqueta que se mostrará junto al selector de categoría. Si no se especifica, se usará la etiqueta de la columna en la que opera el control.
ui.labelSeparator cadena ninguno Es una cadena de separador anexada a la etiqueta para separar visualmente la etiqueta del selector de categoría.
ui.labelStacking cadena 'horizontal' [horizontal] Indica si la etiqueta debe mostrarse arriba (apilado vertical) o al lado (apilado horizontal) del selector de categorías. Usa 'vertical' o 'horizontal'.
ui.cssClass cadena 'google-visualization-controls-categoryfilter' La clase de CSS que se asignará al control para un estilo personalizado.

ChartRangeFilter

Un control deslizante con dos puntos de control superpuestos en un gráfico para seleccionar un rango de valores del eje continuo del gráfico.

Estado

Nombre Tipo Predeterminado Descripción
range.start número, fecha, fecha y hora o hora del día Valor inicial del rango El inicio del rango seleccionado, inclusive.
range.end número, fecha, fecha y hora o hora del día Valor final de intervalo El final del rango seleccionado inclusive.

Opciones

Nombre Tipo Predeterminado Descripción
filterColumnIndex número ninguno El índice de la columna en la tabla de datos en la que opera el filtro. Es obligatorio proporcionar esta opción o filterColumnLabel. Si los dos están presentes, esta opción tiene prioridad.

Ten en cuenta que solo tiene sentido especificar un índice de una columna de domain que esté incorporada en el eje continuo del gráfico dibujado dentro del control.

filterColumnLabel cadena ninguno Es la etiqueta de la columna de la tabla de datos en la que opera el filtro. Es obligatorio proporcionar esta opción o filterColumnIndex. Si ambos están presentes, filterColumnIndex tiene prioridad.

Ten en cuenta que solo tiene sentido especificar una etiqueta para una columna de dominio que esté incorporada en el eje continuo del gráfico dibujado dentro del control.

ui Objeto null Un objeto con miembros para configurar varios aspectos de la IU del control. Para especificar propiedades de este objeto, puedes usar la notación literal de objeto, como se muestra aquí: 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType cadena Gráfico combinado El tipo de gráfico dibujado dentro del control.
Puede ser una de las siguientes opciones: “AreaChart”, “LineChart”, “ComboChart” o “ScatterChart”.
ui.chartOptions Objeto 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
Las opciones de configuración del gráfico dibujado dentro del control. Permite el mismo nivel de configuración que cualquier gráfico del panel y cumple con el mismo formato que acepta ChartWrapper.setOptions().

Puedes especificar opciones adicionales o anular las predeterminadas (aunque los valores predeterminados se eligieron cuidadosamente para lograr un aspecto óptimo).

ui.chartView Objeto o cadena (objeto serializado) null Es la especificación de la vista que se aplicará a la tabla de datos utilizada para dibujar el gráfico dentro del control. Permite el mismo nivel de configuración que cualquier gráfico del panel y cumple con el mismo formato que acepta ChartWrapper.setView(). Si no se especifica, se usa la tabla de datos para dibujar el gráfico.

Ten en cuenta que el eje horizontal del gráfico dibujado debe ser continuo, por lo que debes especificar ui.chartView según corresponda.

ui.minRangeSize número Diferencia de valores de datos interpretada como 1 píxel El tamaño mínimo del rango seleccionable (range.end - range.start), especificado en unidades de valores de datos. En el caso de un eje numérico, es un número (no necesariamente un número entero). Para un eje de fecha, fecha y hora o timeofday, es un número entero que especifica la diferencia en milisegundos.
ui.snapToData boolean false Si es verdadero, los pulgares de rango se ajustan a los datos más cercanos. En este caso, los extremos del rango que muestra getState() son siempre valores de la tabla de datos.

Eventos

Incorporaciones a eventos ControlWrapper:

Nombre Descripción Propiedades
statechange Tal como se documenta para cada ControlWrapper, solo tiene una propiedad booleana adicional, inProgress, que especifica si el estado se está modificando en ese momento (se está arrastrando uno de los pulgares o el rango en sí). inProgress

DateRangeFilter

Un control deslizante con doble valor para seleccionar períodos de fechas.

Prueba mover el control deslizante para cambiar las filas que se muestran en la tabla de abajo.

Estado

Nombre Tipo Predeterminado Descripción
lowValue número ninguno Es la extensión más baja del rango seleccionado.
highValue número ninguno El alcance mayor del rango seleccionado, inclusive.
lowThumbAtMinimum boolean ninguno Indica si el círculo inferior del control deslizante está bloqueado en el rango mínimo permitido. Si se configura, anula lowValue.
highThumbAtMaximum boolean ninguno Indica si el círculo superior del control deslizante está bloqueado en el rango máximo permitido. Si se configura, anula highValue.

Opciones

Nombre Tipo Predeterminado Descripción
filterColumnIndex número ninguno Es la columna de la tabla de datos sobre la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnLabel. Si ambas están presentes, esta opción tiene prioridad. Debe apuntar a una columna con el tipo number.
filterColumnLabel cadena ninguno Es la etiqueta de la columna en la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnIndex. Si ambas están presentes, filterColumnIndex tiene prioridad. Debe apuntar a una columna con el tipo number.
minValue Fecha automático Valor mínimo permitido para el rango inferior. Si no está definido, el valor se inferirá del contenido de DataTable administrado por el control.
maxValue Fecha automático Valor máximo permitido para el rango superior. Si no está definido, el valor se inferirá del contenido de DataTable administrado por el control.
ui Objeto null Un objeto con miembros para configurar varios aspectos de la IU del control. Para especificar propiedades de este objeto, puedes usar la notación literal de objeto, como se muestra aquí: 
{label: 'Age', labelSeparator: ':'}
ui.format Objeto ninguno Cómo representar la fecha como una cadena Acepta cualquier formato de fecha válido.
ui.step cadena día El cambio mínimo posible al arrastrar el control deslizante puede ser cualquier unidad de tiempo hasta "día". ("mes" y "año" aún no son compatibles).
ui.ticks número automático La cantidad de marcas (posiciones fijas en la barra de rango) que puede ocupar el control deslizante.
ui.unitIncrement cadena '1' La cantidad que se debe incrementar para incrementos unitarios de la extensión del rango. Un incremento de unidad equivale a usar las teclas de flecha para mover el control deslizante.
ui.blockIncrement número 10 La cantidad que se debe incrementar para incrementos de bloque de la extensión del rango. Un incremento de bloque equivale a usar las teclas pgUp y pgDown para mover los controles deslizantes.
ui.showRangeValues boolean verdadero Establece si hay etiquetas junto al control deslizante que muestran las extensiones del rango seleccionado.
ui.orientation cadena 'horizontal' [horizontal] Es la orientación del control deslizante. 'horizontal' o 'vertical'
ui.label cadena automático La etiqueta que se mostrará junto al control deslizante. Si no se especifica, se usará la etiqueta de la columna en la que opera el control.
ui.labelSeparator cadena ninguno Una cadena de separador agregada a la etiqueta para separar visualmente la etiqueta del control deslizante
ui.labelStacking cadena 'horizontal' [horizontal] Indica si la etiqueta debe mostrarse arriba (apilado vertical) o al lado (apilamiento horizontal) del control deslizante. Usa 'vertical' o 'horizontal'.
ui.cssClass cadena 'google-visualization-controls-rangefilter' La clase de CSS que se asignará al control para un estilo personalizado.

NumberRangeFilter

Un control deslizante con doble valor para seleccionar rangos de valores numéricos.

Estado

Nombre Tipo Predeterminado Descripción
lowValue número ninguno Es la extensión más baja del rango seleccionado.
highValue número ninguno El alcance mayor del rango seleccionado, inclusive.
lowThumbAtMinimum boolean ninguno Indica si el círculo inferior del control deslizante está bloqueado en el rango mínimo permitido. Si se configura, anula lowValue.
highThumbAtMaximum boolean ninguno Indica si el círculo superior del control deslizante está bloqueado en el rango máximo permitido. Si se configura, anula highValue.

Opciones

Nombre Tipo Predeterminado Descripción
filterColumnIndex número ninguno Es la columna de la tabla de datos sobre la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnLabel. Si ambas están presentes, esta opción tiene prioridad. Debe apuntar a una columna con el tipo number.
filterColumnLabel cadena ninguno Es la etiqueta de la columna en la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnIndex. Si ambas están presentes, filterColumnIndex tiene prioridad. Debe apuntar a una columna con el tipo number.
minValue número automático Valor mínimo permitido para el rango inferior. Si no está definido, el valor se inferirá del contenido de DataTable administrado por el control.
maxValue número automático Valor máximo permitido para el rango superior. Si no está definido, el valor se inferirá del contenido de DataTable administrado por el control.
ui Objeto null Un objeto con miembros para configurar varios aspectos de la IU del control. Para especificar propiedades de este objeto, puedes usar la notación literal de objeto, como se muestra aquí: 
{label: 'Age', labelSeparator: ':'}
ui.format Objeto ninguno Cómo representar el número como una cadena Acepta cualquier formato de número válido.
ui.step número 1 o se calcula a partir de ticks si está definido El cambio mínimo posible cuando se arrastra el control deslizante.
ui.ticks número automático La cantidad de marcas (posiciones fijas en la barra de rango) que puede ocupar el control deslizante.
ui.unitIncrement número 1 La cantidad que se debe incrementar para incrementos unitarios de la extensión del rango. Un incremento de unidad equivale a usar las teclas de flecha para mover el control deslizante.
ui.blockIncrement número 10 La cantidad que se debe incrementar para incrementos de bloque de la extensión del rango. Un incremento de bloque equivale a usar las teclas pgUp y pgDown para mover los controles deslizantes.
ui.showRangeValues boolean verdadero Establece si hay etiquetas junto al control deslizante que muestran las extensiones del rango seleccionado.
ui.orientation cadena 'horizontal' [horizontal] Es la orientación del control deslizante. 'horizontal' o 'vertical'
ui.label cadena automático La etiqueta que se mostrará junto al control deslizante. Si no se especifica, se usará la etiqueta de la columna en la que opera el control.
ui.labelSeparator cadena ninguno Una cadena de separador agregada a la etiqueta para separar visualmente la etiqueta del control deslizante
ui.labelStacking cadena 'horizontal' [horizontal] Indica si la etiqueta debe mostrarse arriba (apilado vertical) o al lado (apilamiento horizontal) del control deslizante. Usa 'vertical' o 'horizontal'.
ui.cssClass cadena 'google-visualization-controls-rangefilter' La clase de CSS que se asignará al control para un estilo personalizado.

StringFilter

Es un campo de entrada de texto simple que te permite filtrar datos mediante la coincidencia de cadenas. Se actualiza después de cada pulsación de teclas: intenta escribir j para reducir la tabla a John y Jessica.

Estado

Nombre Tipo Predeterminado Descripción
value objeto o cadena ninguno Es el texto ingresado actualmente en el campo de entrada de control.

Opciones

Nombre Tipo Predeterminado Descripción
filterColumnIndex número ninguno Es la columna de la tabla de datos sobre la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnLabel. Si ambas están presentes, esta opción tiene prioridad.
filterColumnLabel cadena ninguno Es la etiqueta de la columna en la que debe operar el filtro. Es obligatorio proporcionar esta opción o filterColumnIndex. Si ambas están presentes, filterColumnIndex tiene prioridad.
matchType cadena "prefijo" Indica si el control solo debe coincidir con valores exactos ('exact'), prefijos que comiencen desde el principio del valor ('prefix') o cualquier subcadena ('any').
caseSensitive boolean false Si las coincidencias deben distinguir entre mayúsculas y minúsculas o no.
useFormattedValue boolean false Indica si el control debe coincidir con los valores con formato de celda o con los valores reales.
ui Objeto null Un objeto con miembros para configurar varios aspectos de la IU del control. Para especificar propiedades de este objeto, puedes usar la notación literal de objeto, como se muestra aquí: 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean verdadero Indica si el control debe coincidir cada vez que se presiona una tecla o solo cuando el campo de entrada "cambia" (pérdida de enfoque o presión de la tecla Intro).
ui.label cadena automático La etiqueta que se mostrará junto al campo de entrada. Si no se especifica, se usará la etiqueta de la columna en la que opera el control.
ui.labelSeparator cadena ninguno Una cadena de separador agregada a la etiqueta para separar visualmente la etiqueta del campo de entrada
ui.labelStacking cadena 'horizontal' [horizontal] Indica si la etiqueta debe mostrarse arriba (apilado vertical) o junto a (apilamiento horizontal) el campo de entrada. Usa 'vertical' o 'horizontal'.
ui.cssClass cadena 'google-visualization-controls-stringfilter' La clase de CSS que se asignará al control para un estilo personalizado.