Controles e painéis

Nesta página, você verá como combinar vários gráficos em painéis e dar aos usuários controles para manipular os dados que eles mostrarão.

Visão geral

Painéis são uma maneira simples de organizar e gerenciar vários gráficos que compartilham os mesmos dados subjacentes. Ao usar as APIs descritas nesta página, você não precisa sobrecarregar a fiação e a coordenação de 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 para visualizar e cuidar da exibição e distribuição dos dados para todos os gráficos que fazem parte do painel.

Controles são widgets da interface do usuário (como seletores de categoria, controles deslizantes de intervalo, preenchimentos automáticos) com que você interage para direcionar 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, em que elas se comportam como tubos e válvulas em um sistema de encanamento. Elas coletam informações do usuário e usam as informações para decidir quais dados o painel deve gerenciar e disponibilizar os gráficos que fazem parte deles.

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

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

Como usar controles e painéis

Veja as principais etapas para criar e incorporar um painel na sua página. Veja abaixo um snippet de código que demonstra todas as etapas e informações detalhadas sobre cada uma delas.

  1. Crie um esqueleto de HTML para o painel. Sua página deve ter tantos elementos HTML quanto necessário para conter cada membro de um painel. Isso inclui o próprio painel e todos os controles e gráficos que fazem parte dele. Normalmente, você vai usar uma <div> para cada um.
  2. Carregue suas bibliotecas. Um painel requer apenas duas bibliotecas para serem incluídas ou carregadas na página: a API AJAX do Google e o pacote controls de visualização do Google.
  3. Prepare seus dados. É necessário preparar os dados para visualização. Isso significa especificar os dados no código ou consultar um site remoto para encontrar dados.
  4. Crie uma instância de painel. Instancie o painel chamando o construtor e transmitindo uma referência ao elemento <div> que o manterá.
  5. Crie quantos controles e instâncias de gráficos forem necessários. Crie instâncias google.visualization.ChartWrapper e google.visualization.ControlWrapper para descrever cada gráfico e controlar que o painel gerencia.
  6. Estabeleça dependências. Chame bind() no seu painel e transmita as instâncias de controle e gráfico para que o painel saiba 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. Desenhe seu painel. Chame draw() no painel e transmita seus dados para desenhar o painel inteiro na página.
  8. Mudanças programáticas após o desenho. Após o desenho inicial, você poderá conduzir os controles que fazem parte do painel de forma programática e fazer com que o painel atualize os gráficos em resposta a isso.

Veja um exemplo simples de uma página que cria um painel simples com um controle deslizante de intervalo para gerar 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 painel que o código cria.

1. Criar um esqueleto HTML para seu painel

Sua página precisa ter o máximo de elementos HTML (normalmente <div>s) para armazenar o painel e todos os controles e gráficos que fazem parte dele. Ao instanciar as instâncias de painel, controle e gráfico, é necessário transmitir 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.

2. Carregar 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 (especialmente, 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 qualquer intervenção do usuário.

É necessário usar google.charts.load() para buscar a biblioteca de controle.

<!--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á sua função de gerenciador para que todos os métodos e classes auxiliares necessários estejam prontos para você começar a preparar seus dados.

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

4. Criar uma instância de painel

Depois de criar os dados, é possível instanciar o objeto do painel. 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, é possível realizar algumas etapas opcionais, como adicionar listeners de eventos (por exemplo, ser notificado quando o painel estiver "pronto"). Os painéis manipulam os eventos da mesma forma que os gráficos. Portanto, consulte Como processar eventos de visualização ou Como exibir erros na seção de gráfico para mais informações.

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

Defina quantas instâncias forem necessárias para cada controle e gráfico que fará 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 cuida do envio de dados adequados a cada um deles. No entanto, especifique os parâmetros obrigatórios: chartType e containerId para gráficos, controlType e containerId para controles.

Veja algumas dicas sobre como configurar controles e gráficos:

  • Você precisa dar a todos os controles uma filterColumnIndex (ou filterColumnLabel) para especificar em qual coluna do google.visualization.DataTable o controle opera. No exemplo acima, o controle opera na coluna Donuts ingerido.

  • 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 dos polegares 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 a mesma tabela de dados subjacente que você preparou na etapa Preparar seus dados. No entanto, os gráficos geralmente exigem uma disposição específica de colunas para serem exibidos corretamente. Por exemplo, um gráfico de pizza requer uma coluna de string para o rótulo, seguida por uma coluna de número 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 vão fazer parte, use o método bind() para informar ao painel sobre as dependências entre os controles e gráficos.

Quando um controle e um gráfico são vinculados, o painel o atualiza para corresponder às restrições aplicadas pelo controle aos 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 último vai ser atualizado para mostrar 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: um para um, um para muitos, muitos para um e muitos para muitos. Sempre que vários controles estiverem vinculados a um gráfico, o painel atualizará o gráfico para corresponder às restrições combinadas aplicadas por todos os controles vinculados. Ao mesmo tempo, um controle pode gerar 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 de bind() ao mesmo tempo. 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 o painel inteiro. O método draw() usa apenas um parâmetro: o DataTable (ou DataView) que alimenta o painel.

Chame draw() sempre que você 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() encerra a desenho de todos os controles e gráficos que fazem parte dele. Um evento error será disparado se algum dos gráficos ou controles gerenciados não for desenhado. Para saber mais, consulte Gerenciar eventos.

Observação: você precisa detectar o evento ready antes de tentar mudar a composição do painel ou desenhá-lo novamente.

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

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

Se você precisar mudar o estado do painel de forma programática, faça isso diretamente nas instâncias ControlWrapper e ChartWrapper que fazem parte dele. A regra de ouro é executar qualquer mudança necessária diretamente na instância ControlWrapper (ou ChartWrapper) específica. Por exemplo, mudar uma opção ou estado de controle usando setOption() e setState(), respectivamente, e chamar o método draw() depois. 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

Esta seção lista os objetos expostos pela API de controles e painéis e os métodos padrão expostos por todos os controles.

Painel

Representa um conjunto de gráficos e controles colaborativos que compartilham os mesmos dados.

Construtor

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

Métodos

O painel 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 últimos sejam redesenhados sempre que um dos primeiros coletar 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() juntas.

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

Desenha o painel.
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 uma agregação 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áfico.

Observação:os listeners de eventos para o evento selecionado ainda precisam ser anexados a cada gráfico que você quer detectar.

Descrição estendida

Eventos

O objeto Dashboard gera os eventos a seguir. É preciso 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 falhar na renderização. ID, mensagem
ready

O painel concluiu o desenho e está pronto para aceitar alterações. Todos os controles e gráficos que fazem parte do painel estão prontos para a chamada de método externo e a interação do usuário. Se você quiser mudar o painel (ou os dados exibidos) 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 acionado.

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,
  • após uma chamada programática para o método draw() de qualquer parte do gráfico do 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 do painel, desenhando-o e alterando o estado dele de forma programática.

Construtor

ControlWrapper(opt_spec)
opt_spec (link em inglês)
[Opcional] - Um objeto JSON que define o controle ou uma versão em 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 apropriadas usando os métodos set... expostos pelo ControlWrapper.
Propriedade Tipo Obrigatório Padrão Descrição
tipo de controle String Obrigatório nenhum Nome da classe do controle. O nome do pacote google.visualization pode ser omitido para os controles do Google. Exemplos:CategoryFilter, NumberRangeFilter.
containerId String Obrigatório nenhum O ID do elemento DOM na sua página que hospedará o controle.
opções Objeto Opcional nenhum Um objeto que descreve as opções para o controle. Você pode usar a notação literal do JavaScript ou fornecer um identificador para o objeto. Exemplo: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
estado Objeto Opcional nenhum Um objeto que descreve o estado do controle. O estado coleta todas as variáveis que o usuário que controla o controle podem afetar. Por exemplo, um estado de controle deslizante de intervalo pode ser descrito em termos de posições ocupadas pelos polegares altos e baixos. Você pode usar a notação literal do JavaScript ou fornecer um identificador 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 contém o controle cuida do desenho. Chame draw() para forçar novos desenho programáticos do controle depois de alterar qualquer outra configuração, como opções ou estado.

toJSON() String Retorna uma versão de string da representação JSON do controle.
clone() ControlWrapper Retorna uma cópia detalhada do wrapper de controle.
getControlType() String 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 do controle atribuído pelo setControlName().
getControl() Referência do objeto de controle Retorna uma referência ao controle criado por essa ControlWrapper. Isso retornará um valor nulo até que você tenha chamado draw() no objeto ControlWrapper (ou no painel que o contém) e lance um evento pronto. 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 ID do elemento do 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 desse controle.
getState() Objeto Retorna o estado do controle.
setControlType(type) Nenhum Define o tipo de controle. Transmita o nome da classe do controle para instanciar. Se este for um controle do Google, não o qualifique com google.visualization. Por exemplo, para um controle deslizante de intervalo de uma coluna numérica, transmita "NumberRangeFilter".
setControlName(name) Nenhum Define um nome arbitrário para o controle. Ela não é exibida no controle, mas é apenas para sua referência.
setContainerId(id) Nenhum Define o ID do elemento DOM que contém 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 desativar uma opção, transmita o valor nulo para 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 de controle. O estado coleta todas as variáveis que o usuário pode controlar. Por exemplo, um estado de controle deslizante de intervalo pode ser descrito com base nas posições ocupadas pelos polegares altos e baixos do controle deslizante.

Eventos

O objeto ControlWrapper gera os eventos a seguir. É necessário chamar ControlWrapper.draw() (ou desenhar o painel mantendo 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 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 acionado. Como alternativa, é possível detectar um evento ready no painel que contém os métodos de controle e chamada de controle somente após o evento ser acionado. Nenhum
statechange Disparado quando o usuário interage com o controle, afetando o estado. Por exemplo, um evento statechange será disparado sempre que você mover os polegares de um controle de controle deslizante de intervalo. Para recuperar um estado de controle atualizado após o evento ser acionado, chame ControlWrapper.getState(). Nenhum

ChartWrapper

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

As seguintes observações se aplicam ao usar 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 cuida da alimentação dos dados necessários.
  • Defina o atributo view para declarar quais colunas, entre todas as presentes no dataTable fornecidas ao painel, são relevantes para o gráfico, como mostrado em Criar instâncias de controle e gráfico.

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

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

Observação:na descrição das 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"} };.

FilterFilter

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

Estado

Nome Tipo Padrão Descrição
Valores selecionados Matriz de objetos ou tipos primitivos nenhum O conjunto de valores selecionados 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 várias opções, apenas o primeiro valor da matriz será mantido.

Opções

Nome Tipo Padrão Descrição
IndexFilterColumn number nenhum A coluna da tabela de dados em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência.
ColumnFilterFilter 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.
values Matriz auto Lista de valores para escolher. Se uma matriz de objetos for usada, ela precisará ter uma representação 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 a lista de valores selecionáveis automaticamente da coluna DataTable em que o filtro opera, use os valores reais da célula ou os valores formatados.
iu Objeto null Um objeto com membros para configurar vários aspectos da IU do controle. Para especificar propriedades desse objeto, use a notação literal do objeto, conforme mostrado aqui: 
{label: 'Metric', labelSeparator: ':'}
ui.caption string "Escolha um valor..." Legenda a ser exibida no widget do seletor de valor quando nenhum item estiver selecionado.
Valores de IU boolean verdadeiro Indica se os valores a serem escolhidos devem ser classificados.
ui.selectValuesLayout string "side" Como exibir valores selecionados, quando várias seleções são permitidas. 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 cabem no seletor serão encapsuladas em uma nova linha.
  • 'belowStacked': os valores selecionados serão exibidos em uma coluna abaixo do widget.
ui.allowNone boolean verdadeiro Indica se o usuário tem permissão para não escolher nenhum valor. Se false, o usuário precisa 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 dos disponíveis ficará selecionado automaticamente.
ui.allowMultiple boolean verdadeiro Indica se é possível selecionar vários valores em vez de apenas um.
ui.allowTyping boolean verdadeiro Indica se o usuário tem permissão para digitar um campo de texto para restringir a lista de opções possíveis (usando um preenchimento automático) ou não.
rótulo.ui string auto O rótulo que será exibido ao lado do seletor de categoria. Se não for especificado, o rótulo da coluna em que o controle opera será usado.
ui.labelSeparator string nenhum Uma string separadora anexada ao rótulo para separar visualmente o rótulo do seletor de categorias.
ui.labelStacking string "horizontal" Indica se o rótulo vai ser exibido acima (empilhamento vertical) ou ao lado (pilha horizontal) no seletor de categoria. Use 'vertical' ou 'horizontal'.
classe.ui.css string "google-visualization-controls-categoryfilter" A classe CSS a ser atribuída ao controle para definir o estilo personalizado.

ChartRangeFilter

Um controle deslizante com dois polegares sobrepostos em um gráfico para selecionar um intervalo de valores do eixo contínuo do gráfico.

Estado

Nome Tipo Padrão Descrição
intervalo.início número, data, data e hora ou hora do dia Valor inicial do intervalo O início do intervalo selecionado.
intervalo.fim número, data, data e hora ou hora do dia Valor final do intervalo Fim do intervalo selecionado.

Opções

Nome Tipo Padrão Descrição
IndexFilterColumn 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, essa opção vai ter precedência.

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

ColumnFilterFilter 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 é incorporada no eixo contínuo do gráfico desenhado dentro do controle.

iu Objeto null Um objeto com membros para configurar vários aspectos da IU do controle. Para especificar propriedades desse objeto, use a notação literal do objeto, conforme mostrado aqui: 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
Tipo de IU string "ComboChart" O tipo de gráfico desenhado dentro do controle.
Ele pode ser "AreaChart", "LineChart", "ComboChart" ou "ScatterChart".
Opções do gráfico do ui. 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 desenhado dentro do controle. Permite o mesmo nível de configuração de qualquer gráfico no painel e está em conformidade com o mesmo formato aceito por ChartWrapper.setOptions().

Você pode especificar outras opções ou substituir as opções padrão. No entanto, os padrões foram escolhidos com cuidado para a aparência ideal.

Visualização da IU 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 de qualquer gráfico no painel e segue o mesmo formato aceito por ChartWrapper.setView(). Se não for especificado, a tabela de dados será usada para desenhar o gráfico.

O eixo horizontal do gráfico desenhado precisa ser contínuo. Portanto, tenha cuidado para especificar ui.chartView.

ui.minRangeSize number Diferença no valor dos dados interpretada como 1 pixel O tamanho mínimo do intervalo selecionável (range.end - range.start), especificado em unidades de valor de dados. Para um eixo numérico, é um número (não necessariamente um número inteiro). Para um eixo de data, data/hora ou hora do dia, é um número inteiro que especifica a diferença em milissegundos.
Dados do arquivo ui.snapToData boolean false Se verdadeiro, os polegares de intervalo são ajustados nos pontos de dados mais próximos. Nesse caso, os endpoints do intervalo retornados por getState() são necessariamente valores na tabela de dados.

Eventos

Adições a eventos ControlWrapper:

Nome Descrição Propriedades
statechange O mesmo que é documentado para cada ControlWrapper, tem apenas uma propriedade booleana extra, inProgress, que especifica se o estado está sendo modificado (seja uma das miniaturas ou o próprio intervalo sendo arrastado). em andamento

DateRangeFilter

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

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

Estado

Nome Tipo Padrão Descrição
Valor baixo number nenhum A menor extensão do intervalo selecionado, inclusive.
Alto valor number nenhum A maior extensão do intervalo selecionado, inclusive.
lowThumbAtMinimum boolean nenhum Indica se o polegar inferior do controle deslizante está bloqueado no intervalo mínimo permitido. Se definido, modifica lowValue.
HighThumbAtMáximo boolean nenhum Indica se o polegar superior do controle deslizante está bloqueado no intervalo máximo permitido. Se definido, modifica highValue.

Opções

Nome Tipo Padrão Descrição
IndexFilterColumn number nenhum A coluna da tabela de dados em que 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.
ColumnFilterFilter 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 o tipo number.
minValue Data auto Valor mínimo permitido para o intervalo menor. Se for indefinido, o valor será inferido do conteúdo da tabela de dados gerenciada pelo controle.
maxValue Data auto Valor máximo permitido para o intervalo maior. Se for indefinido, o valor será inferido do conteúdo da tabela de dados gerenciada pelo controle.
iu Objeto null Um objeto com membros para configurar vários aspectos da IU do controle. Para especificar propriedades desse objeto, use a notação literal do objeto, conforme mostrado aqui: 
{label: 'Age', labelSeparator: ':'}
formato 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 os dedos do controle deslizante: pode ser qualquer unidade de tempo até "dia". "mês" e "ano" ainda não são compatíveis.
marcações da IU number auto O número de marcações (fixas na barra de intervalo) que os botões do controle deslizante podem ocupar.
inc.unidade string "1" A quantidade a ser incrementada para incrementos de unidades nas extensões. Um incremento de unidade é equivalente a usar as teclas de seta para mover um polegar no controle deslizante.
IU.blockIncrement number 10 O valor a ser incrementado para incrementos de blocos nas extensões. Um incremento de bloco é equivalente ao uso das teclas pgUp e pgDown para mover os polegares do controle deslizante.
ui.showRangeValues boolean verdadeiro Indica se os rótulos serão exibidos ao lado do controle deslizante exibindo as extensões do intervalo selecionado.
orientação da IU string "horizontal" A orientação do controle deslizante. 'horizontal' ou 'vertical'.
rótulo.ui string auto O rótulo que será exibido ao lado do controle deslizante. Se não for especificado, o rótulo da coluna em que o controle opera é usado.
ui.labelSeparator string nenhum Uma string separadora anexada ao rótulo para separar visualmente o rótulo do controle deslizante.
ui.labelStacking string "horizontal" Indica se o rótulo precisa ser exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) no controle deslizante. Use 'vertical' ou 'horizontal'.
classe.ui.css string "google-visualization-controls-rangefilter" A classe CSS a ser atribuída ao controle para definir o estilo personalizado.

NumberRangeFilter

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

Estado

Nome Tipo Padrão Descrição
Valor baixo number nenhum A menor extensão do intervalo selecionado, inclusive.
Alto valor number nenhum A maior extensão do intervalo selecionado, inclusive.
lowThumbAtMinimum boolean nenhum Indica se o polegar inferior do controle deslizante está bloqueado no intervalo mínimo permitido. Se definido, modifica lowValue.
HighThumbAtMáximo boolean nenhum Indica se o polegar superior do controle deslizante está bloqueado no intervalo máximo permitido. Se definido, modifica highValue.

Opções

Nome Tipo Padrão Descrição
IndexFilterColumn number nenhum A coluna da tabela de dados em que 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.
ColumnFilterFilter 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 o tipo number.
minValue number auto Valor mínimo permitido para o intervalo menor. Se for indefinido, o valor será inferido do conteúdo da tabela de dados gerenciada pelo controle.
maxValue number auto Valor máximo permitido para o intervalo maior. Se for indefinido, o valor será inferido do conteúdo da tabela de dados gerenciada pelo controle.
iu Objeto null Um objeto com membros para configurar vários aspectos da IU do controle. Para especificar propriedades desse objeto, use a notação literal do objeto, conforme mostrado aqui: 
{label: 'Age', labelSeparator: ':'}
formato 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 calculada a partir de ticks, se definido A mudança mínima possível ao arrastar os polegares do controle deslizante.
marcações da IU number auto O número de marcações (fixas na barra de intervalo) que os botões do controle deslizante podem ocupar.
inc.unidade number 1 A quantidade a ser incrementada para incrementos de unidades nas extensões. Um incremento de unidade é equivalente a usar as teclas de seta para mover um polegar no controle deslizante.
IU.blockIncrement number 10 O valor a ser incrementado para incrementos de blocos nas extensões. Um incremento de bloco é equivalente ao uso das teclas pgUp e pgDown para mover os polegares do controle deslizante.
ui.showRangeValues boolean verdadeiro Indica se os rótulos serão exibidos ao lado do controle deslizante exibindo as extensões do intervalo selecionado.
orientação da IU string "horizontal" A orientação do controle deslizante. 'horizontal' ou 'vertical'.
rótulo.ui string auto O rótulo que será exibido ao lado do controle deslizante. Se não for especificado, o rótulo da coluna em que o controle opera é usado.
ui.labelSeparator string nenhum Uma string separadora anexada ao rótulo para separar visualmente o rótulo do controle deslizante.
ui.labelStacking string "horizontal" Indica se o rótulo precisa ser exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) no controle deslizante. Use 'vertical' ou 'horizontal'.
classe.ui.css string "google-visualization-controls-rangefilter" A classe CSS a ser atribuída ao controle para definir o estilo personalizado.

StringFilter

Um campo de entrada de texto simples que permite filtrar os dados por correspondência de strings. Ele é atualizado após cada pressionamento de tecla: tente digitar j para restringir a tabela abaixo para João e Jéssica.

Estado

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

Opções

Nome Tipo Padrão Descrição
IndexFilterColumn number nenhum A coluna da tabela de dados em que o filtro deve operar. É obrigatório fornecer essa opção ou filterColumnLabel. Se ambos estiverem presentes, esta opção terá precedência.
ColumnFilterFilter 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" Indica se o controle deve corresponder apenas a valores exatos ('exact'), prefixos a partir do início do valor ('prefix') ou qualquer substring ('any').
caseSensitive boolean false Se a correspondência precisa diferenciar letras maiúsculas e minúsculas.
UseFormattedValue boolean false Indica se o controle deve corresponder aos valores formatados em células ou aos valores reais.
iu Objeto null Um objeto com membros para configurar vários aspectos da IU do controle. Para especificar propriedades desse objeto, use a notação literal do objeto, conforme mostrado aqui: 
{label: 'Name', labelSeparator: ':'}
Acionador de ui.realtime boolean verdadeiro Indica se o controle precisa corresponder sempre que uma tecla é pressionada ou apenas quando o campo de entrada "muda", como perda de foco ou a tecla Enter.
rótulo.ui string auto O rótulo que será exibido ao lado do campo de entrada. Se não for especificado, o rótulo da coluna em que o controle opera será usado.
ui.labelSeparator string nenhum Uma string separadora anexada ao marcador para separar visualmente o marcador do campo de entrada.
ui.labelStacking string "horizontal" Se o rótulo é exibido acima (empilhamento vertical) ou ao lado (empilhamento horizontal) no campo de entrada. Use 'vertical' ou 'horizontal'.
classe.ui.css string "google-visualization-controls-stringfilter" A classe CSS a ser atribuída ao controle para definir o estilo personalizado.