Controles e painéis

Nesta página, você verá como combinar vários gráficos em painéis e oferecer controles aos usuários para manipular os dados exibidos.

Visão geral

Os painéis são uma maneira simples de organizar e gerenciar vários gráficos que compartilham os mesmos dados. Ao usar as APIs descritas nesta página, você fica livre do fardo de conectar e coordenar todos os gráficos que fazem parte de um painel.

Os painéis são definidos usando classes google.visualization.Dashboard. As instâncias de Dashboard recebem um DataTable contendo os dados a serem visualizados e que, portanto, devem desenhar e distribuir os dados para todos os gráficos que fazem parte do painel.

Os controles são widgets da interface do usuário (como seletores de categoria, controles deslizantes de intervalo, preenchimento automático etc.) com os quais você interage para orientar os dados gerenciados por um painel e os gráficos que fazem parte dele.

Os controles são definidos usando classes google.visualization.ControlWrapper. É possível adicionar instâncias de ControlWrapper a um painel, onde elas se comportam como canos e válvulas em um sistema de encanamento. Eles coletam a entrada do usuário e usam as informações para decidir quais dados o painel está gerenciando devem ser disponibilizados para os gráficos que fazem parte dele.

Confira o exemplo a seguir, em que um seletor de categoria e um controle deslizante de intervalo são usados para direcionar os dados visualizados por um gráfico de pizza.

Observação:o painel é interativo. Tente operar os controles e ver a mudança no gráfico em tempo real.

Como usar controles e painéis

Estas são as principais etapas para criar um painel e incorporá-lo à sua página. Você vai encontrar um snippet de código demonstrando todas as etapas abaixo, seguido de informações detalhadas sobre cada uma delas.

  1. Crie um esqueleto de HTML para seu painel. Sua página deve ter quantos elementos HTML forem necessários para conter todos os membros de um dashboard. Isso inclui o painel em si e todos os controles e gráficos que fazem parte dele. Normalmente, você usará um <div> para cada um.
  2. Carregue as bibliotecas. Um painel requer que apenas duas bibliotecas sejam incluídas ou carregadas na página: a API AJAX do Google e o pacote controls da visualização do Google.
  3. Prepare os dados. Você precisará preparar os dados para visualização. Isso significa especificar os dados por conta própria no código ou consultar um site remoto em busca de dados.
  4. Criar uma instância de painel. Instancie seu painel chamando o construtor e passando uma referência ao elemento <div> que o conterá.
  5. Crie quantas instâncias de controles e gráficos precisar. Crie instâncias de google.visualization.ChartWrapper e google.visualization.ControlWrapper para descrever cada gráfico e controle que o painel gerencia.
  6. Estabelecer dependências. Chame bind() no painel e transmita as instâncias de controle e gráfico para informar ao painel o que gerenciar. Quando um controle e um gráfico são vinculados, o painel atualiza o gráfico para corresponder às restrições que o controle impõe sobre os dados.
  7. Desenhar seu painel. Chame draw() no seu painel e transmita seus dados para desenhar o painel inteiro na página.
  8. Mudanças programáticas após o desenho. Opcionalmente, após o desenho inicial, você pode controlar programaticamente os controles que fazem parte do painel e fazer com que o painel atualize os gráficos em resposta a isso.

Este é um exemplo simples de página que cria um painel simples com um controle deslizante de intervalo que gera um gráfico de pizza. O painel resultante é mostrado abaixo do snippet. 

<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 é o dashboard criado por esse código.

1. Crie um esqueleto HTML para seu painel

Sua página precisa ter o máximo de elementos HTML (geralmente <div>s) para conter o painel e todos os controles e gráficos dele. Ao instanciar as instâncias de painel, controle e gráfico, é preciso passar uma referência ao elemento. Portanto, atribua um 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>

Você pode posicionar cada elemento HTML como quiser que o painel seja.

2. Recarregue suas bibliotecas

Um painel requer que apenas duas bibliotecas sejam incluídas ou carregadas na página: a API AJAX do Google e o pacote controls de visualização do Google. A API (em particular, google.visualization.ChartWrapper) identifica automaticamente os outros pacotes necessários (por exemplo, gauge se você estiver usando um gráfico de medidor) e os carrega em tempo real, sem que você precise intervir.

Use google.charts.load() para buscar a biblioteca de controles.

<!--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. Prepare seus dados

Quando a API de visualização for carregada, google.charts.setOnLoadCallback() chamará a função de gerenciador. Assim, você saberá que todos os métodos e classes auxiliares necessários estarão prontos para você começar a preparar os dados.

Os painéis aceitam dados em uma tabela de dados, da mesma forma que os gráficos.

4. Criar uma instância de painel

Depois de criar os dados, é possível instanciar o objeto do dashboard. Um construtor de painel usa um parâmetro: uma referência ao elemento DOM em que o painel será desenhado. 

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

Os painéis são expostos como uma classe JavaScript. Depois de instanciar seu painel, você pode executar algumas etapas opcionais, como adicionar listeners de eventos (por exemplo, para ser notificado quando o painel estiver "pronto"). Os painéis processam eventos da mesma forma que os gráficos. Portanto, consulte Como lidar com eventos de visualização ou Como exibir erros corretamente na seção de gráficos para saber mais.

5. Criar instâncias de controle e gráfico

Defina quantas instâncias forem necessárias para cada controle e gráfico que farão parte do painel. Use google.visualization.ChartWrapper e google.visualization.ControlWrapper para definir gráficos e 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'
    }
  });

Ao criar instâncias ChartWrapper e ControlWrapper, não especifique o parâmetro dataTable ou dataSourceUrl. O painel se encarrega de alimentar cada um com os dados apropriados. No entanto, especifique os parâmetros obrigatórios: chartType e containerId para gráficos e controlType e containerId para controles.

Algumas dicas sobre como configurar controles e gráficos:

  • É necessário atribuir uma filterColumnIndex (ou filterColumnLabel) a todos os controles para especificar em qual coluna do google.visualization.DataTable o controle opera (no exemplo acima, o controle opera na coluna Donuts consumidos).

  • Use a opção de configuração state nos controles para inicializá-los com um estado explícito quando forem desenhados pela primeira vez. Por exemplo, use essa configuração para corrigir as posições iniciais das miniaturas de um controle deslizante de intervalo. 

      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 os gráficos que fazem parte de um painel compartilham o mesmo dataTable subjacente que você preparou na etapa Preparar seus dados. No entanto, os gráficos geralmente exigem uma organização específica de colunas para serem exibidos corretamente: por exemplo, um gráfico de pizza exige uma coluna de string para o rótulo, seguida por uma coluna de números para o valor.

    Use a opção view ao configurar cada instância de ChartWrapper para declarar quais colunas são relevantes para o gráfico, como no exemplo a seguir. 

      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. Estabelecer dependências

Depois de instanciar o painel e todos os controles e gráficos que farão parte dele, use o método bind() para informar o painel sobre as dependências existentes entre controles e gráficos.

Quando um controle e um gráfico são vinculados, o painel atualiza o gráfico para corresponder às restrições que o controle impõe sobre os dados. No painel de exemplo que você está criando, o controle deslizante de intervalo e o gráfico de pizza são vinculados. Portanto, sempre que você interagir com o primeiro, o segundo será atualizado para exibir apenas os dados que correspondem ao intervalo selecionado. 

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

É possível vincular controles e gráficos em várias configurações diferentes: um para um, um para muitos, muitos para um e muitos para muitos. Sempre que vários controles são vinculados a um gráfico, o painel atualiza o gráfico para corresponder às restrições combinadas aplicadas por todos os controles vinculados. Ao mesmo tempo, um controle pode gerenciar vários gráficos simultaneamente. Para especificar várias vinculações ao mesmo tempo, transmita matrizes para o método bind() em vez de instâncias únicas. Também é possível encadear várias chamadas bind(). Veja alguns exemplos. 

  // 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 avançados, também é possível vincular controles a outros controles para estabelecer cadeias de dependências . 

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

7. Desenhar seu painel

Chame o método draw() na instância do painel para renderizar todo o painel. O método draw() usa apenas um parâmetro: o DataTable (ou DataView) que alimenta o painel.

Chame draw() sempre que mudar a composição do painel (por exemplo, adicionando novos controles ou gráficos) ou mudar a DataTable geral que o alimenta.

A instância do painel dispara um evento ready sempre que draw() termina de mostrar todos os controles e gráficos que fazem parte dele. Um evento error será disparado se um dos controles gerenciados ou do gráfico não for desenhado. Consulte Como processar eventos para saber mais.

Observação:detecte o evento ready antes de tentar alterar a composição do painel ou desenhá-lo novamente.

8. Mudanças programáticas após o desenho

Depois que o painel concluir o draw() inicial, ele ficará ativo e responderá automaticamente a qualquer ação realizada nele, como mudar o intervalo selecionado de um controle deslizante que faz parte do painel.

Se você precisar alterar programaticamente o estado do painel, poderá fazer isso operando diretamente nas instâncias ControlWrapper e ChartWrapper que fazem parte dele. A regra prática é realizar qualquer alteração necessária diretamente na instância específica de ControlWrapper (ou ChartWrapper). Por exemplo, altere uma opção ou estado de controle via setOption() e setState(), respectivamente, e chame o método draw() em seguida. O painel será atualizado para corresponder às alterações solicitadas.

O exemplo a seguir mostra esse caso.
Página da 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>

Referência da API

Nesta seção, listamos os objetos expostos pela API Controls and Dashboards, além dos métodos padrão expostos por todos os controles.

Painel

Representa uma coleção de controles e gráficos colaborativos que compartilham os mesmos dados.

Construtor

Dashboard(containerRef)
containerRef
Uma referência a um elemento de contêiner válido na página que vai conter o conteúdo do painel.

Métodos

O Dashboard expõe os seguintes métodos:

Método Tipo de retorno Descrição
bind(controls, charts) google.visualization.Dashboard

Vincula um ou mais controles a um ou mais participantes do painel (gráficos ou outros controles), para que todos os dois sejam redesenhados sempre que qualquer um deles colete uma interação programática ou do usuário que afete os dados gerenciados pelo painel. Retorna a própria instância do painel para encadear várias chamadas bind().

  • controls: uma única ou uma matriz de instâncias de google.visualization.ControlWrapper que definem os controles a serem vinculados.
  • charts: uma única ou uma matriz de instâncias de google.visualization.ChartWrapper que definem os gráficos que serão conduzidos pelos controles.
draw(dataTable) Nenhum

Desenha o painel.

  • dataTable - qualquer uma das seguintes opções: um objeto DataTable, um objeto DataView, uma representação JSON de um DataTable ou uma matriz seguindo a sintaxe de google.visualization.arrayToDataTable() .
getSelection() Matriz de objetos

Retorna uma matriz das entidades visuais selecionadas dos gráficos no painel. O método getSelection(), quando chamado no painel, retorna um agregado de todas as seleções feitas em todos os gráficos dentro dele, permitindo o uso de uma única referência ao trabalhar com seleções de gráficos.

Observação:os listeners do evento select ainda precisam ser anexados a cada gráfico que você quer detectar.

Descrição estendida

Eventos

O objeto do painel de controle gera os seguintes eventos. É necessário chamar Dashboard.draw() antes que qualquer evento seja gerado.

Nome Descrição Propriedades
error Disparado quando ocorre um erro ao tentar renderizar o painel. Um ou mais controles e gráficos que fazem parte do painel podem ter falhado na renderização. ID, mensagem
ready

O desenho do painel foi concluído, e ele está pronto para aceitar alterações. Todos os controles e gráficos que fazem parte do painel estão prontos para chamada de método externo e interação com o usuário. Se você quiser alterar o painel (ou os dados que ele exibe) depois de desenhá-lo, configure um listener para esse evento antes de chamar o método draw e aplique as alterações somente depois que o evento for disparado.

O evento ready também será disparado:

  • após a conclusão de uma atualização do painel acionada por um usuário ou interação programática com um dos controles;
  • depois de uma chamada programática para o método draw() de qualquer parte do gráfico no painel.
Nenhum

ControlWrapper

Um objeto ControlWrapper é um wrapper em torno de uma representação JSON de uma instância de controle configurada. A classe expõe métodos de conveniência para definir um controle de painel, desenhá-lo e alterar programaticamente o estado dele.

Construtor

ControlWrapper(opt_spec)
opt_spec
[Opcional]: um objeto JSON que define o controle ou uma versão de string serializada desse objeto. As propriedades compatíveis do objeto JSON são mostradas na tabela a seguir. Se não for especificado, você precisará definir todas as propriedades adequadas usando os métodos set... expostos por ControlWrapper.
Propriedade Tipo Obrigatório Padrão Descrição
controlType String Obrigatório nenhum O nome da classe do controle. O nome do pacote google.visualization pode ser omitido nos controles do Google. Exemplos:CategoryFilter, NumberRangeFilter.
containerId String Obrigatório nenhum O ID do elemento DOM da página que hospedará o controle.
do modelo. Objeto Opcional nenhum Um objeto que descreve as opções do controle. É possível usar a notação literal JavaScript ou fornecer um identificador para o objeto. Exemplo: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state Objeto Opcional nenhum Um objeto que descreve o estado do controle. O estado coleta todas as variáveis que o usuário que opera o controle pode afetar. Por exemplo, um estado de controle deslizante de intervalo pode ser descrito considerando as posições que os dedos baixo e alto dele ocupam. Você pode usar a notação literal JavaScript ou fornecer um handle para o objeto.Exemplo:"state": {"lowValue": 20, "highValue": 50}

Métodos

ControlWrapper expõe os seguintes métodos adicionais:

Método Tipo de retorno Descrição
draw() Nenhum

Desenha o controle. Normalmente, o painel que detém o controle cuida de desenhá-lo. Chame draw() para forçar reexibição programática do controle depois de alterar outras configurações, como opções ou estado.

toJSON() String Retorna uma versão em string da representação JSON do controle.
clone() ControlWrapper Retorna uma cópia detalhada do wrapper de controle.
getControlType() String O nome da classe do controle. Se for um controle do Google, o nome não será qualificado com google.visualization. Por exemplo, se fosse um controle CategoryFilter, ele retornaria "CategoryFilter" em vez de "google.visualization.CategoryFilter".
getControlName() String Retorna o nome de controle atribuído por setControlName().
getControl() Referência de objeto de controle Retorna uma referência ao controle criado por este ControlWrapper. Isso retornará um valor nulo até que você chame draw() no objeto ControlWrapper (ou no painel que o contém) e gere um evento "ready". O objeto retornado expõe apenas um método: resetControl(), que redefine o estado de controle para o que foi inicializado (como redefinir um elemento de formulário HTML).
getContainerId() String O ID do elemento de contêiner DOM do controle.
getOption(key, opt_default_val) Qualquer tipo

Retorna o valor da opção de controle especificado

  • key: o nome da opção a ser recuperada. Pode ser um nome qualificado, como 'vAxis.title'.
  • opt_default_value [opcional]: se o valor especificado for indefinido ou nulo, esse valor será retornado.
getOptions() Objeto Retorna o objeto de opções deste controle.
getState() Objeto Retorna o estado de controle.
setControlType(type) Nenhum Define o tipo de controle. Transmita o nome da classe do controle a ser instanciado. Se for um controle do Google, não o qualifique com google.visualization. Por exemplo, para um controle deslizante de intervalo sobre uma coluna numérica, transmita "NumberRangeFilter".
setControlName(name) Nenhum Define um nome arbitrário para o controle. Isso não é exibido em nenhum lugar no controle, mas serve apenas para sua referência.
setContainerId(id) Nenhum Define o ID do elemento DOM que o contém para o controle.
setOption(key, value) Nenhum Define um único valor de opção de controle, em que key é o nome da opção e value é o valor. Para cancelar a definição de uma opção, transmita o valor nulo. key pode ser um nome qualificado, como 'vAxis.title'.
setOptions(options_obj) Nenhum Define um objeto de opções completo para um controle.
setState(state_obj) Nenhum Define o estado do controle. O estado coleta todas as variáveis que o usuário que opera o controle pode afetar. Por exemplo, um estado de controle deslizante de intervalo pode ser descrito considerando as posições que os dedos inferior e alto dele ocupam.

Eventos

O objeto ControlWrapper lança os seguintes eventos. Chame ControlWrapper.draw() (ou desenhe o painel que contém o controle) antes que qualquer evento seja gerado.

Nome Descrição Propriedades
error Disparado quando ocorre um erro ao tentar renderizar o controle. ID, mensagem
ready O controle está pronto para aceitar a interação do usuário e para chamadas de métodos externos. Se você quiser interagir com o controle e chamar métodos depois de desenhá-lo, configure um listener para esse evento antes de chamar o método draw e chame-o somente depois que o evento for disparado. Como alternativa, você pode detectar um evento ready no painel que contém os métodos de controle e chamada de controle somente depois que o evento foi disparado. Nenhum
statechange Disparado quando o usuário interage com o controle, afetando o estado dele. Por exemplo, um evento statechange será disparado sempre que você mover as miniaturas de um controle deslizante de intervalo. Para recuperar um estado de controle atualizado após o disparo do evento, chame ControlWrapper.getState(). Nenhum

ChartWrapper

Consulte a documentação de google.visualization.ChartWrapper na seção de referência da API das visualizações.

As observações a seguir se aplicam ao uso de um ChartWrapper como parte de um painel:

  • Não defina os atributos dataTable, query, dataSourceUrl e refreshInterval explicitamente. O painel que contém o gráfico é responsável por alimentá-lo com os dados necessários.
  • Defina o atributo view para declarar quais colunas, dentre todas as presentes no dataTable fornecidas ao painel, são relevantes para o gráfico, conforme mostrado em Criar instâncias de controle e gráfico.

Filtros são elementos gráficos que as pessoas podem usar para selecionar interativamente quais dados são exibidos no seu gráfico. Esta seção descreve os filtros de gráfico do Google: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter e StringFilter.

É possível usar qualquer um deles como parâmetro para ControlWrapper.setControlType().

Observação:ao descrever opções, a notação de ponto é usada para descrever atributos de objetos aninhados. Por exemplo, uma opção chamada 'ui.label' precisa ser declarada em um objeto de opções como var options = {"ui": {"label": "someLabelValue"} };.

CategoryFilter

Um seletor para escolher um ou mais valores entre um conjunto de valores definidos.

Estado

Nome Tipo Padrão Descrição
selectedValues matriz de objetos ou tipos primitivos nenhum O conjunto de valores selecionado no momento. Os valores selecionados precisam ser um conjunto dos valores selecionáveis gerais definidos pela opção values (qualquer valor irrelevante será ignorado). Se o CategoryFilter não permitir a múltipla escolha, somente o primeiro valor da matriz será mantido.

Opções

Nome Tipo Padrão Descrição
filterColumnIndex number nenhum A coluna da tabela de dados na qual o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência.
filterColumnLabel string nenhum O rótulo da coluna em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnIndex. Se ambos estiverem presentes, filterColumnIndex terá precedência.
valores Matriz automático Lista de valores para escolher. Se uma matriz de objetos for usada, eles precisarão ter uma representação de toString() adequada para exibição ao usuário. Se for nulo ou indefinido, a lista de valores será calculada automaticamente com base nos valores presentes na coluna "DataTable" em que esse controle opera.
useFormattedValue boolean false Ao preencher automaticamente a lista de valores selecionáveis na coluna DataTable em que esse filtro opera, seja usando os valores de células reais ou seus valores formatados.
ui Objeto null Um objeto com membros para configurar vários aspectos da interface do controle. Para especificar as propriedades desse objeto, use a notação literal de objeto, como mostrado aqui: 
{label: 'Metric', labelSeparator: ':'}
ui.caption string "Escolher um valor..." A legenda a ser exibida dentro do widget do seletor de valor quando nenhum item é selecionado.
ui.sortValues boolean verdadeiro Indica se os valores para escolher devem ser classificados.
ui.selectedValuesLayout string 'de lado' Como mostrar valores selecionados quando a seleção múltipla é permitida. Os valores possíveis são:
  • 'aside': os valores selecionados serão exibidos em uma única linha de texto ao lado do widget do seletor de valor.
  • 'below': os valores selecionados serão exibidos em uma única linha de texto abaixo do widget.
  • 'belowWrapping': semelhante a below, mas as entradas que não couberem no seletor serão agrupadas em uma nova linha;
  • 'belowStacked': os valores selecionados serão exibidos em uma coluna abaixo do widget.
ui.allowNone boolean verdadeiro Define se o usuário tem permissão para não escolher nenhum valor. Se for false, o usuário precisará escolher pelo menos um dos valores disponíveis. Durante a inicialização do controle, se a opção for definida como false e nenhum estado selectedValues for fornecido, o primeiro valor disponível será selecionado automaticamente.
ui.allowMultiple boolean verdadeiro Indica se vários valores podem ser selecionados, em vez de apenas um.
ui.allowTyping boolean verdadeiro Se o usuário tem permissão para digitar em um campo de texto para restringir a lista de opções possíveis (por meio de um preenchimento automático) ou não.
ui.label string automático O rótulo a ser exibido ao lado do seletor de categoria. Se não for especificado, será usado o rótulo da coluna em que o controle opera.
ui.labelSeparator string nenhum Uma string de separador anexada ao rótulo para separar visualmente o rótulo do seletor de categoria.
ui.labelStacking string "horizontal" Indica se o rótulo deve ser exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) do seletor de categoria. Use 'vertical' ou 'horizontal'.
ui.cssClass string 'google-visualization-controls-categoryfilter' A classe CSS a ser atribuída ao controle para estilização personalizada.

ChartRangeFilter

Um controle deslizante com dois ícones sobrepostos em um gráfico para selecionar um intervalo de valores a partir do eixo contínuo (em inglês).

Estado

Nome Tipo Padrão Descrição
range.start número, data, data e hora ou timeofday Valor inicial do intervalo O início do intervalo selecionado.
range.end número, data, data e hora ou timeofday Valor final do intervalo O fim do intervalo selecionado (valor inclusivo).

Opções

Nome Tipo Padrão Descrição
filterColumnIndex number nenhum O índice da coluna na tabela de dados em que o filtro opera. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência.

Observe que só faz sentido especificar um índice de uma coluna domain que está incorporada no eixo contínuo do gráfico desenhado dentro do controle.

filterColumnLabel string nenhum O rótulo da coluna da tabela de dados em que o filtro opera. É obrigatório fornecer essa opção ou filterColumnIndex. Se ambos estiverem presentes, filterColumnIndex terá precedência.

Observe que só faz sentido especificar um rótulo de uma coluna domain que está incorporada no eixo contínuo do gráfico desenhado dentro do controle.

ui Objeto null Um objeto com membros para configurar vários aspectos da interface do controle. Para especificar as propriedades desse objeto, use a notação literal de objeto, como mostrado aqui: 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType string "ComboChart" O tipo do gráfico dentro do controle.
Pode ser um destes: "Gráfico de área", "Gráfico de linhas", "Gráfico de combinação" ou "Gráfico de dispersão".
ui.chartOptions Objeto 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
As opções de configuração do gráfico dentro do controle. Permite o mesmo nível de configuração de qualquer gráfico no painel e segue o mesmo formato aceito por ChartWrapper.setOptions().

É possível especificar opções adicionais ou substituir as opções padrão. No entanto, observe que os padrões foram cuidadosamente escolhidos para melhorar a aparência.

ui.chartView Objeto ou string (objeto serializado) null Especificação da visualização a ser aplicada à tabela de dados usada para desenhar o gráfico dentro do controle. Permite o mesmo nível de configuração que qualquer gráfico no painel e segue o mesmo formato aceito por ChartWrapper.setView(). Se não for especificado, a própria tabela de dados será usada para desenhar o gráfico.

O eixo horizontal do gráfico desenhado precisa ser contínuo. Portanto, especifique ui.chartView corretamente.

ui.minRangeSize number Diferença no valor de dados interpretada como 1 pixel O tamanho mínimo do intervalo selecionável (range.end - range.start), especificado em unidades de valor de dados. No eixo numérico, é um número (não necessariamente um número inteiro). Para um eixo de data, datetime ou timeofday, é um número inteiro que especifica a diferença em milissegundos.
ui.snapToData boolean false Se verdadeira, as miniaturas do intervalo são ajustadas aos pontos de dados mais próximos. Nesse caso, os endpoints do intervalo retornado por getState() são necessariamente valores na tabela de dados.

Eventos

Adições aos eventos ControlWrapper:

Nome Descrição Propriedades
statechange Igual à documentação para cada ControlWrapper, tem apenas uma propriedade booleana extra, inProgress, que especifica se o estado está sendo modificado (uma das miniaturas ou o próprio intervalo está sendo arrastado). inProgress

DateRangeFilter

Um controle deslizante de valor duplo para selecionar períodos de datas.

Mova o controle deslizante para mudar as linhas mostradas na tabela abaixo.

Estado

Nome Tipo Padrão Descrição
lowValue number nenhum A menor extensão do intervalo selecionado.
highValue number nenhum A maior extensão do intervalo selecionado.
lowThumbAtMinimum boolean nenhum Indica se o círculo inferior do controle deslizante está bloqueado no intervalo mínimo permitido. Se definido, substitui lowValue.
highThumbAtMaximum boolean nenhum Indica se a extremidade mais alta do controle deslizante está bloqueada no intervalo máximo permitido. Se definido, substitui highValue.

Opções

Nome Tipo Padrão Descrição
filterColumnIndex number nenhum A coluna da tabela de dados na qual o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência. Precisa apontar para uma coluna com o tipo number.
filterColumnLabel string nenhum O rótulo da coluna em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnIndex. Se ambos estiverem presentes, filterColumnIndex terá precedência. Precisa apontar para uma coluna com tipo number.
minValue Data automático Valor mínimo permitido para a extensão menor do intervalo. Se não definido, o valor será inferido do conteúdo do DataTable gerenciado pelo controle.
maxValue Data automático Valor máximo permitido para a extensão maior do intervalo. Se não definido, o valor será inferido do conteúdo do DataTable gerenciado pelo controle.
ui Objeto null Um objeto com membros para configurar vários aspectos da interface do controle. Para especificar as propriedades desse objeto, use a notação literal de objeto, como mostrado aqui: 
{label: 'Age', labelSeparator: ':'}
ui.format Objeto nenhum Como representar a data como uma string. Aceita qualquer formato de data válido.
ui.step string dia A mudança mínima possível ao arrastar as marcações "Gostei" no controle deslizante: pode ser qualquer unidade de tempo até "dia". ("mês" e "ano" ainda não são compatíveis.)
ui.ticks number automático O número de marcações (posições fixas na barra de intervalo) que os ícones do controle deslizante podem ocupar.
ui.unitIncrement string "1" O valor a ser incrementado para incrementos de unidades das extensões do intervalo. Um incremento de unidade é equivalente a usar as teclas de seta para mover um indicador de movimento.
ui.blockIncrement number 10 O valor a ser incrementado para incrementos de blocos das extensões do intervalo. Um incremento de bloco é equivalente a usar as teclas pgUp e pgDown para mover o controle deslizante "Gostei".
ui.showRangeValues boolean verdadeiro Indica se rótulos ao lado do controle deslizante vão exibir as extensões do intervalo selecionado.
ui.orientation string "horizontal" A orientação do controle deslizante. 'horizontal' ou 'vertical'.
ui.label string automático O rótulo que será exibido ao lado do controle deslizante. Se não for especificado, será usado o rótulo da coluna em que o controle opera.
ui.labelSeparator string nenhum Uma string de separador anexada ao rótulo para separar visualmente o rótulo do controle deslizante.
ui.labelStacking string "horizontal" Indica se o rótulo será exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) do controle deslizante. Use 'vertical' ou 'horizontal'.
ui.cssClass string 'google-visualization-controls-rangefilter' A classe CSS a ser atribuída ao controle para estilização personalizada.

NumberRangeFilter

Um controle deslizante de valor duplo para selecionar intervalos de valores numéricos.

Estado

Nome Tipo Padrão Descrição
lowValue number nenhum A menor extensão do intervalo selecionado.
highValue number nenhum A maior extensão do intervalo selecionado.
lowThumbAtMinimum boolean nenhum Indica se o círculo inferior do controle deslizante está bloqueado no intervalo mínimo permitido. Se definido, substitui lowValue.
highThumbAtMaximum boolean nenhum Indica se a extremidade mais alta do controle deslizante está bloqueada no intervalo máximo permitido. Se definido, substitui highValue.

Opções

Nome Tipo Padrão Descrição
filterColumnIndex number nenhum A coluna da tabela de dados na qual o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência. Precisa apontar para uma coluna com o tipo number.
filterColumnLabel string nenhum O rótulo da coluna em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnIndex. Se ambos estiverem presentes, filterColumnIndex terá precedência. Precisa apontar para uma coluna com tipo number.
minValue number automático Valor mínimo permitido para a extensão menor do intervalo. Se não definido, o valor será inferido do conteúdo do DataTable gerenciado pelo controle.
maxValue number automático Valor máximo permitido para a extensão maior do intervalo. Se não definido, o valor será inferido do conteúdo do DataTable gerenciado pelo controle.
ui Objeto null Um objeto com membros para configurar vários aspectos da interface do controle. Para especificar as propriedades desse objeto, use a notação literal de objeto, como mostrado aqui: 
{label: 'Age', labelSeparator: ':'}
ui.format Objeto nenhum Como representar o número como uma string. Aceita qualquer formato de número válido.
ui.step number 1 ou calculado com base em ticks, se definido A mudança mínima possível ao arrastar os dedos do controle deslizante.
ui.ticks number automático O número de marcações (posições fixas na barra de intervalo) que os ícones do controle deslizante podem ocupar.
ui.unitIncrement number 1 O valor a ser incrementado para incrementos de unidades das extensões do intervalo. Um incremento de unidade é equivalente a usar as teclas de seta para mover um indicador de movimento.
ui.blockIncrement number 10 O valor a ser incrementado para incrementos de blocos das extensões do intervalo. Um incremento de bloco é equivalente a usar as teclas pgUp e pgDown para mover o controle deslizante "Gostei".
ui.showRangeValues boolean verdadeiro Indica se rótulos ao lado do controle deslizante vão exibir as extensões do intervalo selecionado.
ui.orientation string "horizontal" A orientação do controle deslizante. 'horizontal' ou 'vertical'.
ui.label string automático O rótulo que será exibido ao lado do controle deslizante. Se não for especificado, será usado o rótulo da coluna em que o controle opera.
ui.labelSeparator string nenhum Uma string de separador anexada ao rótulo para separar visualmente o rótulo do controle deslizante.
ui.labelStacking string "horizontal" Indica se o rótulo será exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) do controle deslizante. Use 'vertical' ou 'horizontal'.
ui.cssClass string 'google-visualization-controls-rangefilter' A classe CSS a ser atribuída ao controle para estilização personalizada.

StringFilter

Um campo de entrada de texto simples que permite filtrar dados usando correspondência de string. Ela é atualizada após cada tecla pressionada. Tente digitar j para restringir a tabela abaixo a João e Jessica.

Estado

Nome Tipo Padrão Descrição
valor string ou objeto nenhum O texto inserido no campo de entrada de controle.

Opções

Nome Tipo Padrão Descrição
filterColumnIndex number nenhum A coluna da tabela de dados na qual o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência.
filterColumnLabel string nenhum O rótulo da coluna em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnIndex. Se ambos estiverem presentes, filterColumnIndex terá precedência.
matchType string "prefixo" Define se o controle deve corresponder apenas a valores exatos ('exact'), a prefixos que comecem no início do valor ('prefix') ou a qualquer substring ('any').
caseSensitive boolean false Indica se a correspondência deve diferenciar maiúsculas de minúsculas ou não.
useFormattedValue boolean false Define se o controle deve corresponder a valores formatados de célula ou novamente a valores reais.
ui Objeto null Um objeto com membros para configurar vários aspectos da interface do controle. Para especificar as propriedades desse objeto, use a notação literal de objeto, como mostrado aqui: 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean verdadeiro Define se o controle deve corresponder sempre que uma tecla for pressionada ou somente quando o campo de entrada "mudar" (perda de foco ou pressionar a tecla Enter).
ui.label string automático O rótulo a ser exibido ao lado do campo de entrada. Se não for especificado, será usado o rótulo da coluna em que o controle opera.
ui.labelSeparator string nenhum Uma string de separador anexada ao rótulo para separar visualmente o rótulo do campo de entrada.
ui.labelStacking string "horizontal" Se o rótulo deve ser exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) do campo de entrada. Use 'vertical' ou 'horizontal'.
ui.cssClass string 'google-visualization-controls-stringfilter' A classe CSS a ser atribuída ao controle para estilização personalizada.