Controlli e dashboard

In questa pagina scoprirai come combinare più grafici in dashboard e come offrire agli utenti i controlli per manipolare i dati visualizzati.

Panoramica

Le dashboard sono un modo semplice per organizzare e gestire più grafici che condividono gli stessi dati sottostanti. Utilizzando le API descritte in questa pagina, puoi liberarti dal carico di dover collegare i cavi e coordinare tutti i grafici che fanno parte di una dashboard.

Le dashboard vengono definite utilizzando classi google.visualization.Dashboard. Le istanze Dashboard ricevono un DataTable contenente i dati da visualizzare e che si occupano di disegnare e distribuire i dati in tutti i grafici che fanno parte della dashboard.

I controlli sono widget dell'interfaccia utente (ad esempio selettori di categorie, cursori di intervallo, strumenti di completamento automatico e così via) con cui interagisci per gestire i dati gestiti da una dashboard e i grafici che ne fanno parte.

I controlli vengono definiti utilizzando le classi google.visualization.ControlWrapper. Puoi aggiungere istanze ControlWrapper a una dashboard in cui si comportano come tubi e valvole in un impianto idraulico. Raccolgono input degli utenti e utilizzano le informazioni per decidere quali dati gestiti dalla dashboard devono essere resi disponibili nei grafici che ne fanno parte.

Dai un'occhiata all'esempio seguente, in cui vengono utilizzati un selettore di categorie e un dispositivo di scorrimento dell'intervallo per orientare i dati visualizzati da un grafico a torta.

Nota:la dashboard è interattiva. Prova a utilizzare i controlli e guarda come cambia il grafico in tempo reale.

Utilizzare i controlli e le dashboard

Di seguito sono riportati i passaggi chiave per creare una dashboard e incorporarla nella tua pagina. Troverai uno snippet di codice che mostra tutti i passaggi riportati di seguito, seguito da informazioni dettagliate su ogni passaggio.

  1. Crea uno scheletro HTML per la dashboard. La pagina deve contenere tutti gli elementi HTML necessari per contenere tutti i membri di una dashboard. Ciò include la dashboard stessa e tutti i controlli e i grafici che ne fanno parte. In genere, viene utilizzato un tag <div> per ciascuno.
  2. Carica le raccolte. Una dashboard richiede solo due librerie per essere incluse o caricate nella pagina: l'API Google AJAX e il pacchetto controls di visualizzazione di Google.
  3. Prepara i dati. Dovrai preparare i dati da visualizzare, il che significa che devi specificare i dati personalmente nel codice o eseguire una query sui dati a un sito remoto.
  4. Crea un'istanza della dashboard. Crea un'istanza per la tua dashboard chiamando il relativo costruttore e passando un riferimento all'elemento <div> che la conterrà.
  5. Crea tutte le istanze di controlli e grafici che ti servono. Crea istanze google.visualization.ChartWrapper e google.visualization.ControlWrapper per descrivere ogni grafico e controllo gestito dalla dashboard.
  6. Stabilisci le dipendenze. Richiama bind() sulla tua dashboard e passa le istanze di controllo e grafico per consentire alla dashboard di sapere cosa gestire. Dopo aver associato un controllo e un grafico, la dashboard aggiorna il grafico in modo che corrisponda ai vincoli che il controllo applica ai dati.
  7. Disegna la dashboard. Richiama draw() sulla tua dashboard e passa i dati per disegnare l'intera dashboard sulla pagina.
  8. Modifiche programmatiche dopo l'estrazione. Facoltativamente, dopo l'estrazione iniziale puoi gestire in modo programmatico i controlli che fanno parte della dashboard e fare in modo che la dashboard aggiorni i grafici di conseguenza.

Ecco un semplice esempio di una pagina che crea una dashboard semplice con un dispositivo di scorrimento dell'intervallo che guida un grafico a torta. La dashboard risultante è visualizzata sotto lo 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>

Questa è la dashboard creata da questo codice.

1. Crea uno scheletro HTML per la dashboard

La pagina deve contenere tutti gli elementi HTML (in genere <div>) per poter contenere sia la dashboard stessa sia tutti i controlli e i grafici che ne fanno parte. Quando crei un'istanza di istanze di dashboard, controllo e grafici, devi passare un riferimento al relativo elemento, quindi assegnare un ID a ogni 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>

Puoi posizionare ogni elemento HTML nel modo che preferisci nella dashboard.

2. Carica le tue biblioteche

Una dashboard richiede solo due librerie per essere incluse o caricate nella pagina: l'API Google AJAX e il pacchetto controls di visualizzazione Google. L'API (in particolare google.visualization.ChartWrapper) identifica automaticamente gli altri pacchetti necessari (ad esempio, gauge se utilizzi un grafico a contatore) e li carica all'istante senza il tuo ulteriore intervento.

Devi utilizzare google.charts.load() per recuperare la libreria di controlli.

<!--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 i tuoi dati

Una volta caricata l'API di visualizzazione, google.charts.setOnLoadCallback() chiamerà la tua funzione di gestore, in modo che tu sappia che tutti i metodi e le classi helper richiesti saranno pronti per iniziare a preparare i tuoi dati.

Le dashboard accettano i dati in una tabella di dati, come accade per i grafici.

4. Crea un'istanza dashboard

Dopo aver creato i dati, puoi creare un'istanza dell'oggetto dashboard. Un costruttore di dashboard utilizza un solo parametro: un riferimento all'elemento DOM in cui tracciare la dashboard. 

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

Le dashboard sono esposte come classe JavaScript. Dopo aver creato un'istanza per la dashboard, puoi eseguire alcuni passaggi facoltativi, ad esempio aggiungere listener di eventi (ad esempio, ricevere una notifica quando la dashboard è pronta). Le dashboard gestiscono gli eventi allo stesso modo dei grafici, quindi per ulteriori informazioni fai riferimento a Gestione degli eventi di visualizzazione o Visualizzazione degli errori nella sezione del grafico.

5. Crea istanze di controllo e grafico

Definisci il numero di istanze necessario per ogni controllo e grafico che farà parte della dashboard. Utilizza google.visualization.ChartWrapper e google.visualization.ControlWrapper per definire rispettivamente i grafici e i controlli. 

  // 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'
    }
  });

Quando crei istanze ChartWrapper e ControlWrapper, non specificare il parametro dataTable o dataSourceUrl. La dashboard si occupa di fornire a ciascuno i dati appropriati. Tuttavia, assicurati di specificare i parametri obbligatori: chartType e containerId per i grafici, controlType e containerId per i controlli.

Alcuni suggerimenti sulla configurazione di controlli e grafici:

  • Devi assegnare a tutti i controlli un filterColumnIndex (o filterColumnLabel) per specificare su quale colonna di google.visualization.DataTable opera il controllo (nell'esempio precedente, il controllo opera sulla colonna con l'etichetta Donut mangiate),

  • Utilizza l'opzione di configurazione state sui controlli per inizializzarli con uno stato esplicito quando vengono disegnati per la prima volta. Ad esempio, utilizza questa impostazione per correggere le posizioni iniziali dei pollici di un controllo del cursore dell'intervallo. 

      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}
  });

  • Tutti i grafici che fanno parte di una dashboard condividono la stessa tabella di dati sottostante che hai preparato nel passaggio Prepara i dati. Tuttavia, i grafici spesso richiedono una disposizione specifica delle colonne per essere visualizzati correttamente: ad esempio, un grafico a torta richiede una colonna stringa per l'etichetta, seguita da una colonna di numeri per il valore.

    Utilizza l'opzione view durante la configurazione di ogni istanza ChartWrapper per dichiarare quali colonne sono pertinenti per il grafico, come nell'esempio seguente. 

      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. Stabilisci dipendenze

Dopo aver creato un'istanza sia per la dashboard sia per tutti i controlli e i grafici che ne fanno parte, utilizza il metodo bind() per indicare alla dashboard le dipendenze esistenti tra controlli e grafici.

Dopo aver associato un controllo e un grafico, la dashboard aggiorna il grafico in modo che corrisponda ai vincoli che il controllo applica ai dati. Nella dashboard di esempio che stai creando, il dispositivo di scorrimento dell'intervallo e il grafico a torta sono associati; pertanto, ogni volta che interagisci con la prima, la seconda si aggiorna mostrando solo i dati corrispondenti all'intervallo selezionato. 

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

Puoi associare controlli e grafici in molte configurazioni diverse: one-to-one, one-to-many, many-to-one e many-to-many. Ogni volta che più controlli sono associati a un grafico, la dashboard lo aggiorna in modo che corrisponda ai vincoli combinati applicati da tutti i controlli associati. Contemporaneamente, un controllo può guidare più grafici contemporaneamente. Per specificare più associazioni contemporaneamente, passa gli array al metodo bind() anziché alle singole istanze. Puoi anche concatenare più chiamate bind(). Ecco alcuni esempi. 

  // 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);

Per utilizzi avanzati, puoi anche associare i controlli ad altri controlli per stabilire catene di dipendenze. . 

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

7. Disegna la tua dashboard

Chiama il metodo draw() sull'istanza della dashboard per eseguire il rendering dell'intera dashboard. Il metodo draw() richiede un solo parametro: DataTable (o DataView) alla base della dashboard.

Devi chiamare draw() ogni volta che modifichi la composizione della dashboard (ad esempio aggiungendo nuovi controlli o grafici) o modifichi il valore generale DataTable alla base della dashboard.

L'istanza della dashboard attiva un evento ready ogni volta che draw() termina disegnando tutti i controlli e i grafici che ne fanno parte. Se non riesce a disegnare uno dei controlli gestiti o del grafico, viene attivato un evento error. Per scoprire di più sulla gestione degli eventi, consulta Gestione degli eventi.

Nota: devi ascoltare l'evento ready prima di provare a modificare la composizione della dashboard o disegnarla di nuovo.

8. Modifiche programmatiche dopo il disegno

Una volta completata l'istruzione draw() iniziale, la dashboard sarà pubblica e risponderà automaticamente a qualsiasi azione eseguita su di essa (come la modifica dell'intervallo selezionato di un dispositivo di scorrimento di controllo che fa parte della dashboard).

Se devi modificare in modo programmatico lo stato della dashboard, puoi farlo operando direttamente sulle istanze ControlWrapper e ChartWrapper che ne fanno parte. La regola generale è eseguire qualsiasi modifica di cui hai bisogno direttamente sull'istanza ControlWrapper (o ChartWrapper) specifica: ad esempio, modificare un'opzione o uno stato di controllo rispettivamente tramite setOption() e setState() e chiamare il relativo metodo draw() in seguito. La dashboard verrà quindi aggiornata in modo da corrispondere alle modifiche richieste.

L'esempio seguente mostra questo caso.
Pagina 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>

Riferimento API

Questa sezione elenca gli oggetti esposti dall'API Controls and Dashboards e i metodi standard esposti da tutti i controlli.

Dashboard

Rappresenta una raccolta di controlli e grafici collaborativi che condividono gli stessi dati sottostanti.

Costruttore

Dashboard(containerRef)
containerRef
Un riferimento a un elemento contenitore valido nella pagina che conterrà i contenuti della dashboard.

Metodi

Dashboard espone i seguenti metodi:

Metodo Tipo restituito Descrizione
bind(controls, charts) google.visualization.Dashboard

Associa uno o più Controlli a uno o più altri partecipanti della dashboard (grafici o altri controlli), in modo che tutti i secondi vengano ridisegnati ogni volta che i primi raccolgono un'interazione programmatica o utente che influisce sui dati gestiti dalla dashboard. Restituisce l'istanza della dashboard stessa per concatenare più chiamate bind().

  • controls: una singola istanza o un array di istanze google.visualization.ControlWrapper che definisce i controlli da associare.
  • grafici: una singola istanza o un array di istanze google.visualization.ChartWrapper che definiscono i grafici che saranno guidati dai controlli.
draw(dataTable) Nessun valore

Disegna la dashboard.

  • dataTable: uno qualsiasi dei seguenti oggetti: un oggetto DataTable; un oggetto DataView; una rappresentazione JSON di una tabella di dati oppure un array che segue la sintassi di google.visualization.arrayToDataTable() .
getSelection() array di oggetti

Restituisce un array delle entità visive selezionate dei grafici nella dashboard. Il metodo getSelection(), quando chiamato nella dashboard, restituisce un insieme di tutte le selezioni effettuate su tutti i grafici al suo interno, consentendo l'utilizzo di un singolo riferimento quando si lavora con le selezioni dei grafici.

Nota:i listener di eventi per l'evento selezionato devono comunque essere collegati a ogni grafico che vuoi ascoltare.

Descrizione estesa

Eventi

L'oggetto Dashboard genera i seguenti eventi. Tieni presente che devi chiamare Dashboard.draw() prima che vengano generati eventi.

Nome Descrizione Proprietà
error Attivato quando si verifica un errore durante il tentativo di rendering della dashboard. Il rendering di uno o più controlli e grafici che fanno parte della dashboard potrebbe non essere riuscito. id, messaggio
ready

La dashboard ha completato il disegno ed è pronta per accettare le modifiche. Tutti i controlli e i grafici che fanno parte della dashboard sono pronti per la chiamata di metodo esterna e l'interazione dell'utente. Per modificare la dashboard (o i dati visualizzati) dopo averla disegnata, devi impostare un listener per questo evento prima di chiamare il metodo draw, quindi applicare le modifiche solo dopo che l'evento è stato attivato.

L'evento ready verrà attivato anche:

  • Dopo il completamento di un aggiornamento della dashboard attivato da un utente o da un'interazione programmatica con uno dei controlli,
  • dopo una chiamata programmatica al metodo draw() di qualsiasi parte del grafico della dashboard.
Nessun valore

ControlWrapper

Un oggetto ControlWrapper è un wrapper attorno a una rappresentazione JSON di un'istanza di controllo configurata. La classe espone metodi pratici per definire un controllo della dashboard, disegnarlo e modificarne lo stato in modo programmatico.

Costruttore

ControlWrapper(opt_spec)
opt_spec
[Facoltativo] - Un oggetto JSON che definisce il controllo o una versione stringa serializzata dell'oggetto. Le proprietà supportate dell'oggetto JSON sono mostrate nella seguente tabella. Se non specificato, è necessario impostare tutte le proprietà appropriate utilizzando i metodi set... esposti da ControlWrapper.
Proprietà Tipo Obbligatorio Predefinita Descrizione
controlType String Obbligatorio Nessuno Il nome della classe del controllo. Il nome del pacchetto google.visualization può essere omesso per i controlli Google. Esempi: CategoryFilter, NumberRangeFilter.
containerId String Obbligatorio Nessuno L'ID dell'elemento DOM nella pagina che ospita il controllo.
opzioni del modello. Oggetto Facoltativo Nessuno Un oggetto che descrive le opzioni per il controllo. Puoi utilizzare la notazione letterale JavaScript oppure fornire un handle all'oggetto. Esempio: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state Oggetto Facoltativo Nessuno Un oggetto che descrive lo stato del controllo. Lo stato raccoglie tutte le variabili che possono interessare l'utente che utilizza il controllo. Ad esempio, uno stato del cursore dell'intervallo può essere descritto in termini di posizioni occupate dalle posizioni basse e alte del cursore del cursore. Puoi utilizzare una notazione letterale JavaScript o fornire un handle all'oggetto.Esempio: "state": {"lowValue": 20, "highValue": 50}

Metodi

ControlWrapper espone i seguenti metodi aggiuntivi:

Metodo Tipo restituito Descrizione
draw() Nessun valore

Disegna il controllo. Normalmente la dashboard con il controllo si occupa di disegnarla. Devi chiamare draw() per forzare le riprogettazioni programmatiche del controllo dopo aver modificato altre impostazioni, come opzioni o stato.

toJSON() String Restituisce una versione stringa della rappresentazione JSON del controllo.
clone() ControlWrapper Restituisce una copia diretta del wrapper di controllo.
getControlType() String Il nome della classe del controllo. Se si tratta di un controllo Google, il nome non sarà qualificato con google.visualization. Quindi, ad esempio, se questo fosse un controllo CategoryFilter, verrebbe restituito "CategoryFilter" anziché "google.visualization.CategoryFilter".
getControlName() String Restituisce il nome del controllo assegnato da setControlName().
getControl() Riferimento oggetto di controllo Restituisce un riferimento al controllo creato da questo ControlWrapper. Verrà restituito un valore nullo finché non avrai chiamato draw() sull'oggetto ControlWrapper (o sulla dashboard che lo contiene) e verrà generato un evento pronto. L'oggetto restituito espone solo un metodo: resetControl(), che reimposta lo stato di controllo su quello con cui è stato inizializzato (ad esempio, la reimpostazione di un elemento modulo HTML).
getContainerId() String L'ID dell'elemento container DOM del controllo.
getOption(key, opt_default_val) Tutti i tipi

Restituisce il valore dell'opzione di controllo specificato

  • chiave - Il nome dell'opzione da recuperare. Può essere un nome qualificato, ad esempio 'vAxis.title'.
  • opt_default_value [facoltativo] - Se il valore specificato non è definito o nullo, questo valore verrà restituito.
getOptions() Oggetto Restituisce l'oggetto opzioni per questo controllo.
getState() Oggetto Restituisce lo stato del controllo.
setControlType(type) Nessun valore Imposta il tipo di controllo. Passa il nome della classe del controllo per creare un'istanza. Se si tratta di un controllo di Google, non qualificarlo con google.visualization. Quindi, ad esempio, per un dispositivo di scorrimento di un intervallo su una colonna numerica, inserisci "NumberRangeFilter".
setControlName(name) Nessun valore Consente di impostare un nome arbitrario per il controllo. Questa informazione non viene mostrata in nessuna parte del controllo, ma è solo per riferimento.
setContainerId(id) Nessun valore Imposta l'ID dell'elemento DOM contenitore per il controllo.
setOption(key, value) Nessun valore Imposta un singolo valore dell'opzione di controllo, dove key è il nome dell'opzione e value è il valore. Per annullare l'impostazione di un'opzione, passa un valore nullo per il valore. Tieni presente che key può essere un nome qualificato, ad esempio 'vAxis.title'.
setOptions(options_obj) Nessun valore Imposta un oggetto opzioni completo per un controllo.
setState(state_obj) Nessun valore Imposta lo stato del controllo. Lo stato raccoglie tutte le variabili che possono interessare l'utente che utilizza il controllo. Ad esempio, uno stato del cursore dell'intervallo può essere descritto in termini di posizioni occupate dalle posizioni basse e alte del cursore del cursore.

Eventi

L'oggetto ControlWrapper genera i seguenti eventi. Tieni presente che devi chiamare ControlWrapper.draw() (o disegnare la dashboard che contiene il controllo) prima che vengano generati eventi.

Nome Descrizione Proprietà
error Attivato quando si verifica un errore durante il tentativo di rendering del controllo. id, messaggio
ready Il controllo è pronto per accettare l'interazione dell'utente e le chiamate di metodi esterne. Se vuoi interagire con il controllo e richiamare i metodi dopo averlo tracciato, devi impostare un listener per questo evento prima di chiamare il metodo draw e richiamarli solo dopo che l'evento è stato attivato. In alternativa, puoi rimanere in ascolto per un evento ready sulla dashboard che contiene i metodi di controllo e chiamata solo dopo che l'evento è stato attivato. Nessun valore
statechange Attivato quando l'utente interagisce con il controllo, influenzando il suo stato. Ad esempio, un evento statechange verrà attivato ogni volta che muovi i pollici del controllo di un cursore di intervallo. Per recuperare uno stato di controllo aggiornato dopo l'attivazione dell'evento, chiama ControlWrapper.getState(). Nessun valore

ChartWrapper

Consulta la documentazione google.visualization.ChartWrapper nella sezione di riferimento dell'API delle visualizzazioni.

Le seguenti note si applicano quando utilizzi un ChartWrapper in una dashboard:

  • Non impostare gli attributi dataTable, query, dataSourceUrl e refreshInterval in modo esplicito. La dashboard contenente il grafico si occupa di inserirvi i dati di cui ha bisogno.
  • Imposta il suo attributo view per dichiarare quali colonne, tra tutte quelle presenti nel dataTable assegnato alla dashboard, sono pertinenti per il grafico, come mostrato in Creare istanze di controllo e grafico.

I filtri sono elementi grafici che le persone possono utilizzare per selezionare in modo interattivo i dati visualizzati sul grafico. Questa sezione descrive i filtri di Google Chart: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter e StringFilter.

Puoi utilizzare uno qualsiasi di questi parametri come parametro per ControlWrapper.setControlType().

Nota: nella descrizione delle opzioni, viene utilizzata la notazione del punto per descrivere gli attributi degli oggetti nidificati. Ad esempio, un'opzione denominata 'ui.label' dovrebbe essere dichiarata in un oggetto options come var options = {"ui": {"label": "someLabelValue"} };

CategoryFilter

Un selettore per scegliere uno o più valori tra un insieme di valori definiti.

Stato

Nome Tipo Predefinita Descrizione
selectedValues array di oggetti o tipi primitivi Nessuno L'insieme di valori attualmente selezionati. I valori selezionati devono essere un insieme di valori complessivamente selezionabili definiti dall'opzione values (quelli non pertinenti verranno ignorati). Se CategoryFilter non consente la scelta multipla, viene conservato solo il primo valore dell'array.

Opzioni

Nome Tipo Predefinita Descrizione
filterColumnIndex numero Nessuno La colonna della tabella dati su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza.
filterColumnLabel stringa Nessuno L'etichetta della colonna su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.
valori Array Automatica Elenco di valori tra cui scegliere. Se viene utilizzato un array di oggetti, questi dovrebbero avere una rappresentazione toString() adatta da mostrare all'utente. Se nullo o non definito, l'elenco di valori verrà calcolato automaticamente dai valori presenti nella colonna DataTable su cui opera il controllo.
useFormattedValue boolean false Quando compili automaticamente l'elenco di valori selezionabili dalla colonna DataTable, su cui opera il filtro, scegli se utilizzare i valori effettivi delle celle o i relativi valori formattati.
ui Oggetto null Un oggetto con membri per configurare vari aspetti dell'interfaccia utente del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale oggetto, come mostrato qui: 
{label: 'Metric', labelSeparator: ':'}
ui.caption stringa "Scegli un valore..." La didascalia da visualizzare all'interno del widget del selettore dei valori quando non è selezionato alcun elemento.
ui.sortValues boolean true Indica se i valori tra cui scegliere devono essere ordinati.
ui.selectedValuesLayout stringa "aside" Come visualizzare i valori selezionati quando è consentita la selezione multipla. I valori possibili sono:
  • 'aside': i valori selezionati verranno visualizzati in un'unica riga di testo accanto al widget del selettore dei valori,
  • 'below': i valori selezionati verranno visualizzati in un'unica riga di testo sotto il widget,
  • 'belowWrapping': simile a below, ma le voci che non possono essere inserite nel selettore verranno racchiuse in una nuova riga.
  • 'belowStacked': i valori selezionati verranno visualizzati in una colonna sotto il widget.
ui.allowNone boolean true Indica se all'utente è consentito non scegliere alcun valore. Se false l'utente deve scegliere almeno un valore tra quelli disponibili. Durante l'inizializzazione del controllo, se l'opzione è impostata su false e non viene fornito alcuno stato selectedValues, il primo valore tra quelli disponibili viene selezionato automaticamente.
ui.allowMultiple boolean true Indica se è possibile selezionare più valori anziché uno solo.
ui.allowTyping boolean true Indica se all'utente è consentito digitare in un campo di testo per restringere l'elenco delle possibili scelte (tramite un completamento automatico) o meno.
ui.label stringa Automatica L'etichetta da visualizzare accanto al selettore di categorie. Se non specificata, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparator stringa Nessuno Una stringa separatore aggiunta all'etichetta, per separare visivamente l'etichetta dal selettore di categorie.
ui.labelStacking stringa 'orizzontale' Indica se l'etichetta deve essere visualizzata sopra (sovrapposizione verticale) o accanto (sovrapposizione orizzontale) al selettore di categorie. Usa 'vertical' o 'horizontal'.
ui.cssClass stringa 'google-visualization-controls-categoryfilter' La classe CSS da assegnare al controllo, per gli stili personalizzati.

ChartRangeFilter

Un cursore con due pollici sovrapposti a un grafico per selezionare un intervallo di valori dall'asse continuo del grafico.

Stato

Nome Tipo Predefinita Descrizione
range.start numero, data, ora o ora del giorno Valore iniziale intervallo L'inizio dell'intervallo selezionato, incluso.
range.end numero, data, ora o ora del giorno Valore di fine intervallo La fine dell'intervallo selezionato (incluso).

Opzioni

Nome Tipo Predefinita Descrizione
filterColumnIndex numero Nessuno L'indice della colonna nella tabella di dati su cui opera il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza.

Tieni presente che ha senso specificare solo l'indice di una colonna dominio incorporata nell'asse continuo del grafico disegnato all'interno del controllo.

filterColumnLabel stringa Nessuno L'etichetta della colonna della tabella di dati su cui opera il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.

Tieni presente che ha senso specificare solo un'etichetta di una colonna dominio incorporata nell'asse continuo del grafico disegnato all'interno del controllo.

ui Oggetto null Un oggetto con membri per configurare vari aspetti dell'interfaccia utente del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale oggetto, come mostrato qui: 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType stringa "ComboChart" Il tipo di grafico disegnato all'interno del controllo.
Può essere "AreaChart", "LineChart", "ComboChart" o "ScatterChart".
ui.chartOptions Oggetto 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
Le opzioni di configurazione del grafico disegnato all'interno del controllo. Consente lo stesso livello di configurazione di qualsiasi grafico nella dashboard e rispetta lo stesso formato accettato da ChartWrapper.setOptions().

Puoi specificare opzioni aggiuntive o sostituire quelle predefinite (tieni presente che, tuttavia, i valori predefiniti sono stati scelti con cura per un aspetto ottimale).

ui.chartView Oggetto o stringa (oggetto serializzato) null Specifica della vista da applicare alla tabella di dati utilizzata per disegnare il grafico all'interno del controllo. Consente lo stesso livello di configurazione di qualsiasi grafico nella dashboard e rispetta lo stesso formato accettato da ChartWrapper.setView(). Se non specificato, la tabella dati viene utilizzata per disegnare il grafico.

Tieni presente che l'asse orizzontale del grafico disegnato deve essere continua, quindi assicurati di specificare ui.chartView di conseguenza.

ui.minRangeSize numero Differenza del valore dei dati interpretata come 1 pixel La dimensione minima dell'intervallo selezionabile (range.end - range.start), specificata in unità del valore dei dati. Per un asse numerico, è un numero (non necessariamente un numero intero). Per un asse data, ora o data/ora, è un numero intero che specifica la differenza in millisecondi.
ui.snapToData boolean false Se il valore è true, i pollici dell'intervallo sono agganciati ai punti dati più vicini. In questo caso, i punti finali dell'intervallo restituito da getState() sono necessariamente valori nella tabella di dati.

Eventi

Aggiunte agli eventi ControlWrapper:

Nome Descrizione Proprietà
statechange Come documentato per ogni ControlWrapper, ha solo una proprietà booleana aggiuntiva, inProgress, che specifica se lo stato è attualmente in fase di modifica (è in corso il trascinamento di uno dei pollici o dell'intervallo stesso). inProgress

DateRangeFilter

Un dispositivo di scorrimento a doppio valore per la selezione di intervalli di date.

Prova a spostare il dispositivo di scorrimento per modificare le righe visualizzate nella tabella seguente.

Stato

Nome Tipo Predefinita Descrizione
lowValue numero Nessuno Il valore più basso dell'intervallo selezionato (incluso).
highValue numero Nessuno Il valore più alto dell'intervallo selezionato (incluso).
lowThumbAtMinimum boolean Nessuno Indica se il pollice inferiore del cursore è bloccato all'intervallo minimo consentito. Se impostato, sostituisce lowValue.
highThumbAtMaximum boolean Nessuno Indica se il pollice più alto del dispositivo di scorrimento è bloccato all'intervallo massimo consentito. Se impostato, sostituisce highValue.

Opzioni

Nome Tipo Predefinita Descrizione
filterColumnIndex numero Nessuno La colonna della tabella dati su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza. Deve puntare a una colonna di tipo number.
filterColumnLabel stringa Nessuno L'etichetta della colonna su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza. Deve puntare a una colonna di tipo number.
minValue Data Automatica Valore minimo consentito per l'estensione inferiore dell'intervallo. Se non definito, il valore verrà dedotto dai contenuti della tabella dati gestita dal controllo.
maxValue Data Automatica Valore massimo consentito per l'estensione superiore dell'intervallo. Se non definito, il valore verrà dedotto dai contenuti della tabella dati gestita dal controllo.
ui Oggetto null Un oggetto con membri per configurare vari aspetti dell'interfaccia utente del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale oggetto, come mostrato qui: 
{label: 'Age', labelSeparator: ':'}
ui.format Oggetto Nessuno Come rappresentare la data come stringa. Accetta qualsiasi formato di data valido.
ui.step stringa giorno La variazione minima possibile quando trascini il cursore del cursore: può essere qualsiasi unità di tempo fino a "giorno". "mese" e "anno" non sono ancora supportati.)
ui.ticks numero Automatica Il numero di segni di graduazione (posizioni fisse nella barra dell'intervallo) che possono essere occupati dai pollici del cursore.
ui.unitIncrement stringa "1" La quantità da incrementare per gli incrementi di unità delle estensioni dell'intervallo. Un incremento dell'unità equivale all'uso dei tasti freccia per spostare il pollice del cursore.
ui.blockIncrement numero 10 La quantità da incrementare per gli incrementi di blocchi nell'estensione dell'intervallo. Un incremento del blocco equivale all'utilizzo dei tasti pag su e pg giù per spostare i tasti di scorrimento del cursore.
ui.showRangeValues boolean true Indica se avere etichette accanto al dispositivo di scorrimento che mostrano le estensioni dell'intervallo selezionato.
ui.orientation stringa 'orizzontale' L'orientamento del cursore. 'horizontal' o 'vertical'.
ui.label stringa Automatica L'etichetta da visualizzare accanto al dispositivo di scorrimento. Se non specificata, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparator stringa Nessuno Una stringa separatore aggiunta all'etichetta, per separare visivamente l'etichetta dal dispositivo di scorrimento.
ui.labelStacking stringa 'orizzontale' Indica se l'etichetta deve essere visualizzata sopra (sovrapposizione verticale) o accanto (sovrapposizione orizzontale) al dispositivo di scorrimento. Usa 'vertical' o 'horizontal'.
ui.cssClass stringa 'google-visualization-controls-rangefilter' La classe CSS da assegnare al controllo, per gli stili personalizzati.

NumberRangeFilter

Un dispositivo di scorrimento a doppio valore per la selezione di intervalli di valori numerici.

Stato

Nome Tipo Predefinita Descrizione
lowValue numero Nessuno Il valore più basso dell'intervallo selezionato (incluso).
highValue numero Nessuno Il valore più alto dell'intervallo selezionato (incluso).
lowThumbAtMinimum boolean Nessuno Indica se il pollice inferiore del cursore è bloccato all'intervallo minimo consentito. Se impostato, sostituisce lowValue.
highThumbAtMaximum boolean Nessuno Indica se il pollice più alto del dispositivo di scorrimento è bloccato all'intervallo massimo consentito. Se impostato, sostituisce highValue.

Opzioni

Nome Tipo Predefinita Descrizione
filterColumnIndex numero Nessuno La colonna della tabella dati su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza. Deve puntare a una colonna di tipo number.
filterColumnLabel stringa Nessuno L'etichetta della colonna su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza. Deve puntare a una colonna di tipo number.
minValue numero Automatica Valore minimo consentito per l'estensione inferiore dell'intervallo. Se non definito, il valore verrà dedotto dai contenuti della tabella dati gestita dal controllo.
maxValue numero Automatica Valore massimo consentito per l'estensione superiore dell'intervallo. Se non definito, il valore verrà dedotto dai contenuti della tabella dati gestita dal controllo.
ui Oggetto null Un oggetto con membri per configurare vari aspetti dell'interfaccia utente del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale oggetto, come mostrato qui: 
{label: 'Age', labelSeparator: ':'}
ui.format Oggetto Nessuno Come rappresentare il numero come stringa. Accetta qualsiasi formato numerico valido.
ui.step numero 1 oppure calcolato da ticks, se definito La variazione minima possibile quando trascini il cursore del cursore.
ui.ticks numero Automatica Il numero di segni di graduazione (posizioni fisse nella barra dell'intervallo) che possono essere occupati dai pollici del cursore.
ui.unitIncrement numero 1 La quantità da incrementare per gli incrementi di unità delle estensioni dell'intervallo. Un incremento dell'unità equivale all'uso dei tasti freccia per spostare il pollice del cursore.
ui.blockIncrement numero 10 La quantità da incrementare per gli incrementi di blocchi nell'estensione dell'intervallo. Un incremento del blocco equivale all'utilizzo dei tasti pag su e pg giù per spostare i tasti di scorrimento del cursore.
ui.showRangeValues boolean true Indica se avere etichette accanto al dispositivo di scorrimento che mostrano le estensioni dell'intervallo selezionato.
ui.orientation stringa 'orizzontale' L'orientamento del cursore. 'horizontal' o 'vertical'.
ui.label stringa Automatica L'etichetta da visualizzare accanto al dispositivo di scorrimento. Se non specificata, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparator stringa Nessuno Una stringa separatore aggiunta all'etichetta, per separare visivamente l'etichetta dal dispositivo di scorrimento.
ui.labelStacking stringa 'orizzontale' Indica se l'etichetta deve essere visualizzata sopra (sovrapposizione verticale) o accanto (sovrapposizione orizzontale) al dispositivo di scorrimento. Usa 'vertical' o 'horizontal'.
ui.cssClass stringa 'google-visualization-controls-rangefilter' La classe CSS da assegnare al controllo, per gli stili personalizzati.

StringFilter

Un semplice campo di immissione di testo che consente di filtrare i dati tramite la corrispondenza delle stringhe. L'aggiornamento viene eseguito dopo ogni pressione di un tasto: prova a digitare j per restringere la tabella seguente a John e Jessica.

Stato

Nome Tipo Predefinita Descrizione
valore stringa o oggetto Nessuno Il testo attualmente inserito nel campo di immissione del controllo.

Opzioni

Nome Tipo Predefinita Descrizione
filterColumnIndex numero Nessuno La colonna della tabella dati su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza.
filterColumnLabel stringa Nessuno L'etichetta della colonna su cui deve funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.
matchType stringa 'prefisso' Indica se il controllo deve corrispondere solo a valori esatti ('exact'), prefissi che iniziano dall'inizio del valore ('prefix') o qualsiasi sottostringa ('any').
caseSensitive boolean false Indica se la corrispondenza deve fare distinzione tra maiuscole e minuscole.
useFormattedValue boolean false Indica se il controllo deve corrispondere a valori formattati in cella o a valori effettivi.
ui Oggetto null Un oggetto con membri per configurare vari aspetti dell'interfaccia utente del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale oggetto, come mostrato qui: 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true Indica se il controllo deve corrispondere ogni volta che viene premuto un tasto o solo quando il campo di immissione "cambia" (perdita di messa a fuoco o pressione del tasto Invio).
ui.label stringa Automatica L'etichetta da visualizzare accanto al campo di immissione. Se non specificata, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparator stringa Nessuno Una stringa separatore aggiunta all'etichetta, per separare visivamente l'etichetta dal campo di immissione.
ui.labelStacking stringa 'orizzontale' Indica se l'etichetta deve essere visualizzata sopra (sovrapposizione verticale) o accanto (sovrapposizione orizzontale) al campo di immissione. Usa 'vertical' o 'horizontal'.
ui.cssClass stringa 'google-visualization-controls-stringfilter' La classe CSS da assegnare al controllo, per gli stili personalizzati.