Controlli e dashboard

In questa pagina puoi vedere come combinare più grafici nelle dashboard e offrire agli utenti i controlli per manipolare i dati che mostrano.

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 del carico di cablaggio insieme e coordinare tutti i grafici che fanno parte di una dashboard.

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

I controlli sono widget dell'interfaccia utente (come selettori di categorie, dispositivi di scorrimento degli intervalli, completamenti automatici...) con cui interagisci per gestire i dati gestiti da una dashboard e i grafici che ne fanno parte.

I controlli sono definiti utilizzando le classi google.visualization.ControlWrapper. Puoi aggiungere istanze ControlWrapper a una dashboard, in modo che si comportino come tubi e valvole in un sistema idraulico. Raccoglie l'input dell'utente e usa le informazioni per decidere quali dati devono essere resi disponibili dalla dashboard per i grafici che ne fanno parte.

Osserva l'esempio seguente in cui vengono utilizzati un selettore di categoria e un dispositivo di scorrimento dell'intervallo per generare i dati visualizzati da un grafico a torta.

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

Utilizzare i controlli e le dashboard

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

  1. Crea uno scheletro HTML per la tua dashboard. La pagina deve avere tutti gli elementi HTML necessari per contenere tutti i membri di una dashboard. tra cui la dashboard stessa e tutti i controlli e i grafici inclusi. In genere, devi utilizzare un elemento <div> per ciascuno di essi.
  2. Carica le tue librerie. Una dashboard richiede solo due librerie per essere incluse o caricate nella pagina: l'API Google AJAX e il pacchetto controls di visualizzazione Google.
  3. Prepara i tuoi dati. Dovrai preparare i dati da visualizzare; ciò significa specificare i dati autonomamente nel codice o interrogare un sito remoto per ottenere dati.
  4. Crea un'istanza della dashboard. Crea un'istanza della tua dashboard chiamando il costruttore e trasmettendo un riferimento all'elemento <div> che la conterrà.
  5. Crea tutti i controlli e le istanze di grafici di cui hai bisogno. Crea istanze google.visualization.ChartWrapper e google.visualization.ControlWrapper per descrivere ogni grafico e controllo gestiti dalla dashboard.
  6. Stabilisci le dipendenze. Chiama il numero bind() sulla tua dashboard e passa le istanze di controllo e grafico per comunicare alla dashboard cosa gestire. Quando un controllo e un grafico vengono associati, la dashboard aggiorna il grafico in modo che corrisponda ai vincoli applicati dal controllo sui dati.
  7. Traccia la dashboard. Chiama draw() nella dashboard e trasmetti i tuoi dati per disegnare l'intera dashboard nella pagina.
  8. Modifiche programmatiche dopo l'estrazione. Facoltativamente, dopo l'estrazione iniziale, puoi impostare in modo programmatico i controlli che fanno parte della dashboard e fare in modo che la dashboard aggiorni i grafici in risposta a questo.

Ecco un semplice esempio di una pagina che crea una dashboard semplice con un dispositivo di scorrimento degli intervalli che guida un grafico a torta. La dashboard risultante è mostrata 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>

Ecco la dashboard creata da questo codice.

1. Crea uno scheletro HTML per la tua dashboard

La pagina deve contenere il maggior numero possibile di elementi HTML (in genere <div>) per contenere sia la dashboard stessa sia tutti i controlli e i grafici al suo interno. Quando crei un'istanza di dashboard, controllo e istanze di grafico, devi passare un riferimento al relativo elemento, quindi assegna 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>

Sei libero di posizionare ciascun elemento HTML come preferisci per la tua 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 ulteriori interventi da parte tua.

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

<!--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 funzione del gestore, quindi sai che tutti i metodi e le classi necessari saranno pronti per iniziare la preparazione dei dati.

Le dashboard accettano i dati in una DataTable, come i grafici.

4. Crea un'istanza di dashboard

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

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

Le dashboard vengono esposte come classe JavaScript. Dopo aver creato un'istanza della dashboard, puoi eseguire alcuni passaggi facoltativi, ad esempio l'aggiunta di listener di eventi, ad esempio per ricevere una notifica quando la dashboard è pronta. Le dashboard gestiscono gli eventi come fanno i grafici, quindi per ulteriori informazioni consulta Gestire gli eventi di visualizzazione o Visualizzare correttamente gli errori nella sezione del grafico.

5. Crea istanze di controllo e grafico

Definisci tutte le istanze necessarie per ogni controllo e grafico che faranno parte della dashboard. Utilizza google.visualization.ChartWrapper e google.visualization.ControlWrapper rispettivamente per definire grafici e 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 le istanze ChartWrapper e ControlWrapper, non specificare il parametro dataTable o dataSourceUrl. La dashboard si occupa di fornire a ognuno i dati necessari. 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 del tuo google.visualization.DataTable opera il controllo (nell'esempio precedente, il controllo opera nella colonna Ciambelle 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 di scorrimento 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 dati sottostante che hai preparato nel passaggio Prepara i tuoi dati. Tuttavia, i grafici spesso richiedono una disposizione specifica di colonne per essere visualizzate correttamente: ad esempio, un grafico a torta richiede una colonna stringa per l'etichetta, seguita da una colonna numerica per il valore.

    Usa 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 le dipendenze

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

Quando un controllo e un grafico vengono associati, la dashboard aggiorna il grafico in modo che corrisponda ai vincoli applicati dal controllo sui dati. Nella dashboard di esempio che stai creando, il dispositivo di scorrimento dell'intervallo e il grafico a torta vengono uniti, quindi ogni volta che interagisci con la prima, il secondo viene aggiornato in modo da visualizzare solo i dati che corrispondono 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. Quando più controlli sono associati a un grafico, la dashboard aggiorna il grafico in modo che corrisponda ai vincoli combinati applicati da tutti i controlli associati. Allo stesso tempo, un controllo può gestire più grafici contemporaneamente. Per specificare più associazioni contemporaneamente, trasmetti gli array al metodo bind() anziché a 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 gli 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. Per il metodo draw() è necessario un solo parametro: DataTable (o DataView) su cui si basa la dashboard.

Devi chiamare draw() ogni volta che modifichi la composizione della dashboard (ad esempio con l'aggiunta di nuovi controlli o grafici) oppure modifichi il valore DataTable complessivo di cui si basa.

L'istanza della dashboard attiva un evento ready ogni volta che draw() termina il disegno di tutti i controlli e i grafici che fanno parte di questo evento. Viene attivato un evento error se non è possibile tracciare alcun grafico o controlli gestiti. 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 a tracciarla di nuovo.

8: Modifiche programmatiche dopo l'estrazione

Una volta completata la dashboard, l'draw() iniziale verrà pubblicata e risponderà automaticamente a qualsiasi azione eseguita dalla dashboard, ad esempio la modifica dell'intervallo selezionato di un dispositivo di scorrimento che fa parte della dashboard.

Se devi modificare in modo programmatico lo stato della dashboard, puoi farlo direttamente sulle istanze ControlWrapper e ChartWrapper che fanno parte dello strumento. La regola empirica consiste nell'eseguire qualsiasi modifica necessaria direttamente nell'istanza ControlWrapper (o ChartWrapper) specifica: ad esempio, modificare un'opzione o uno stato di controllo rispettivamente tramite setOption() e setState() e richiamare il metodo draw() in seguito. La dashboard verrà aggiornata per corrispondere alle modifiche richieste.

L'esempio che segue 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

In questa sezione sono elencati gli oggetti esposti dall'API Controls and Dashboards, e i metodi standard esposti da tutti i controlli.

Dashboard

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

Costruttore

Dashboard(containerRef)
containerRef
Un riferimento a un elemento contenitore valido nella pagina in cui saranno inseriti i contenuti della dashboard.

Metodi

La 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 alla dashboard (grafici o altri controlli), in modo che il secondo venga riprogettato ogni volta che uno dei primi raccoglie un'interazione programmatica o utente che influisce sui dati gestiti dalla dashboard. Restituisce l'istanza della dashboard stessa per concatenare più chiamate bind().

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

Disegna la dashboard.

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

Restituisce una matrice delle entità visive selezionate dei grafici nella dashboard. Il metodo getSelection(), quando viene richiamato sulla dashboard, restituisce un insieme aggregato di tutte le selezioni effettuate in tutti i grafici al suo interno, consentendo l'utilizzo di un singolo riferimento durante la selezione delle opzioni.

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

Descrizione estesa

Eventi

L'oggetto Dashboard genera i seguenti eventi. Tieni presente che devi chiamare Dashboard.draw() prima che vengano organizzati 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 creazione della dashboard è stata completata ed è pronta per accettare modifiche. Tutti i controlli e i grafici inclusi nella dashboard sono pronti per l'interazione di utenti esterni e chiamate ai metodi. Se vuoi modificare la dashboard (o i dati visualizzati) dopo averla tracciata, devi configurare 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 tramite un'interazione programmatica con uno dei controlli,
  • dopo una chiamata programmatica al metodo draw() di qualsiasi parte del grafico della dashboard.
Nessuno

wrapper wrapper

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

Costruttore

ControlWrapper(opt_spec)
spec_opt
[Facoltativo] - Un oggetto JSON che definisce il controllo o una versione della stringa serializzata di tale oggetto. Le proprietà supportate dell'oggetto JSON sono mostrate nella tabella seguente. Se non specificato, devi impostare tutte le proprietà appropriate utilizzando i metodi set... esposti da ControlWrapper.
Proprietà Tipo Obbligatorio Predefinito Descrizione
Tipo di controllo Stringa 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 Stringa Obbligatorio Nessuno L'ID dell'elemento DOM sulla tua pagina che ospita il controllo.
opzioni Oggetto Facoltativo Nessuno Un oggetto che descrive le opzioni per il controllo. Puoi utilizzare la notazione letterale JavaScript o 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 l'utente che utilizza il controllo può influire. Ad esempio, uno stato del dispositivo di scorrimento dell'intervallo può essere descritto in termini delle posizioni occupate dal pollice basso e alto. Puoi utilizzare la 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() Nessuno

Disegna il controllo. Solitamente, la dashboard che contiene il controllo si occupa di tracciarlo. Devi chiamare draw() per forzare il ritiro programmatico del controllo dopo aver modificato una qualsiasi altra impostazione, ad esempio le opzioni o lo stato.

toJSON() Stringa Restituisce una versione stringa della rappresentazione JSON del controllo.
clone() Wrapper wrapper Restituisce una copia approfondita del wrapper di controllo.
getControlType() Stringa Il nome della classe del controllo. Se si tratta di un controllo di Google, il nome non sarà idoneo per google.visualization. Ad esempio, se questo fosse un controllo CategoryFilter, verrebbe restituito "CategoryFilter" anziché "google.visualization.CategoryFilter".
getControlName() Stringa 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 null fino a quando non avrai chiamato draw() nell'oggetto ControlWrapper (o nella dashboard che lo contiene) e verrà generato un evento pronto. L'oggetto restituito espone solo un metodo: resetControl(), che reimposta lo stato del controllo rispetto a quello con cui è stato inizializzato (ad esempio, la reimpostazione di un elemento del modulo HTML).
getContainerId() Stringa L'ID dell'elemento container DOM del controllo.
getOption(key, opt_default_val) Qualsiasi tipo

Restituisce il valore specificato per l'opzione di controllo

  • chiave - Il nome dell'opzione di recupero. Potrebbe essere un nome qualificato, ad esempio 'vAxis.title'.
  • opt_default_value [Facoltativo] - Se il valore specificato non è definito o è nullo, verrà restituito questo valore.
getOptions() Oggetto Restituisce l'oggetto options per questo controllo.
getState() Oggetto Restituisce lo stato del controllo.
setControlType(type) Nessuno Imposta il tipo di controllo. Passa il nome della classe del controllo per creare un'istanza. Se questo è un controllo Google, non idoneo per google.visualization. Quindi, ad esempio, per un dispositivo di scorrimento di un intervallo sopra una colonna numerica, inserisci "NumberRangeFilter".
setControlName(name) Nessuno Imposta un nome arbitrario per il controllo. Non viene mostrato in nessun punto del controllo, ma viene fornito solo come riferimento.
setContainerId(id) Nessuno Imposta l'ID dell'elemento DOM contenitore per il controllo.
setOption(key, value) Nessuno Imposta un unico valore per l'opzione di controllo, dove chiave è il nome dell'opzione e valore è il valore. Per annullare l'impostazione di un'opzione, inserisci null per il valore. Tieni presente che key potrebbe essere un nome qualificato, ad esempio 'vAxis.title'.
setOptions(options_obj) Nessuno Imposta un oggetto con opzioni complete per un controllo.
setState(state_obj) Nessuno Imposta lo stato del controllo. Lo stato raccoglie tutte le variabili che l'utente che utilizza il controllo può influire. Ad esempio, uno stato del dispositivo di scorrimento dell'intervallo può essere descritto in termini di posizioni occupate dal pollice basso e alto.

Eventi

L'oggetto ControlWrapper genera i seguenti eventi. Tieni presente che devi chiamare ControlWrapper.draw() (o tracciare la dashboard che contiene il controllo) prima che vengano avviati eventuali 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 per le chiamate ai metodi esterni. Se vuoi interagire con il controllo e chiamare i metodi dopo averlo disegnato, devi configurare un listener per questo evento prima di chiamare il metodo draw e chiamarlo solo dopo che l'evento è stato attivato. In alternativa, puoi ascoltare un evento ready nella dashboard contenente i metodi di controllo e di controllo delle chiamate solo dopo che l'evento è stato attivato. Nessuno
statechange Attivato quando l'utente interagisce con il controllo, ne influenza lo stato. Ad esempio, un evento statechange viene attivato ogni volta che sposti i pollici di un controllo di scorrimento dell'intervallo. Per recuperare uno stato di controllo aggiornato dopo l'attivazione dell'evento, chiama ControlWrapper.getState(). Nessuno

ChartWrapper

Fai riferimento alla documentazione google.visualization.ChartWrapper nella sezione di riferimento dell'API delle visualizzazioni.

Le seguenti note si applicano quando utilizzi ChartWrapper come parte di una dashboard:

  • Non impostare esplicitamente gli attributi dataTable, query, dataSourceUrl e refreshInterval. La dashboard che contiene il grafico si occupa di fornire i dati necessari.
  • Imposta l'attributo view per dichiarare quali colonne, tra tutte quelle presenti in dataTable fornite nella 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 interattivamente i dati da visualizzare nel grafico. Questa sezione descrive i filtri di Google Chart: CategoryFilter, ChartRangeFilter, DateRangeFilter, NumberRangeFilter e StringFilter.

Puoi utilizzarli come parametro per ControlWrapper.setControlType().

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

Filtro categoria

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

Stato

Nome Tipo Predefinito Descrizione
selectedValues (Valori selezionati) Array di oggetti o tipi primitivi Nessuno L'insieme di valori attualmente selezionato. I valori selezionati devono essere un insieme dei valori selezionabili complessivamente definiti dall'opzione values (qualsiasi valore non pertinente verrà ignorato). Se CategoryFilter non consente la scelta multipla, viene conservato solo il primo valore dell'array.

Opzioni

Nome Tipo Predefinito Descrizione
Filtraindiceindice number Nessuno La colonna della tabella dati su cui dovrebbe funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza.
FiltroEtichettaEtichetta string Nessuno L'etichetta della colonna su cui deve agire il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.
values Array Automatica Elenco di valori tra cui scegliere. Se viene utilizzato un array di oggetti, questi devono avere una rappresentazione toString() appropriata per la visualizzazione all'utente. Se null o non definito, l'elenco dei valori viene calcolato automaticamente dai valori presenti nella colonna DataTable su cui opera questo controllo.
usoValoreFormato boolean false Durante l'inserimento automatico dell'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 i vari aspetti della UI del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale dell'oggetto, come mostrato di seguito:
{label: 'Metric', labelSeparator: ':'}
ui.sottotitolo string "Scegli un valore..." La didascalia da visualizzare nel widget del selettore valori quando non è selezionato alcun elemento.
ui.sortValues boolean true Indica se i valori tra cui scegliere devono essere ordinati.
ui.selectedValuesLayout string "a parte" Come visualizzare i valori selezionati quando sono consentite più selezioni. I valori possibili sono:
  • 'aside': i valori selezionati vengono visualizzati in una singola riga di testo accanto al widget del selettore dei valori
  • 'below': i valori selezionati vengono visualizzati in un'unica riga di testo sotto il widget
  • 'belowWrapping': simile a below, ma le voci che non possono essere inserite nel selettore vengono aggregate a 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 assegnato alcuno stato selectedValues, il primo valore tra quelli disponibili viene selezionato automaticamente.
ui.allowMulti boolean true 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 opzioni (tramite un completamento automatico) o meno.
etichetta.UI string Automatica L'etichetta da visualizzare accanto al selettore categoria. Se non è specificato, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparatore string Nessuno Una stringa di separazione aggiunta all'etichetta per separare visivamente l'etichetta dal selettore di categorie.
ui.labelStacking string "orizzontale" Indica se l'etichetta deve essere visualizzata sopra (Stacking verticale) o accanto (Stacking orizzontale) nel selettore di categorie. Utilizza 'vertical' o 'horizontal'.
ui.cssclass string "google-visualization-controls-categoryfilter" La classe CSS da assegnare al controllo, per lo stile personalizzato.

ChartRangeFilter

Un dispositivo di scorrimento con due pollici sovrapposti su un grafico per selezionare un intervallo di valori dall'asse continuo del grafico.

Stato

Nome Tipo Predefinito Descrizione
intervallo.inizio numero, data, data/ora o ora del giorno Valore iniziale intervallo L'inizio dell'intervallo selezionato incluso.
intervallo.end numero, data, data/ora o ora del giorno Valore fine intervallo La fine dell'intervallo selezionato incluso.

Opzioni

Nome Tipo Predefinito Descrizione
Filtraindiceindice number Nessuno L'indice della colonna nella tabella 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 un indice di una colonna dominio incorporata nell'asse continuo del grafico disegnato all'interno del controllo.

FiltroEtichettaEtichetta string Nessuno Etichetta della colonna della tabella dati su cui opera il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.

Tieni presente che è opportuno 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 i vari aspetti della UI del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale dell'oggetto, come mostrato di seguito:
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.graficoTipo string "ComboChart" Il tipo di grafico disegnato all'interno del controllo.
Può essere uno dei seguenti: "AreaChart", "LineChart", "ComboChart" o "ScatterChart".
ui.graficiOpzioni 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 ed è conforme allo stesso formato accettato da ChartWrapper.setOptions().

Tuttavia, puoi specificare opzioni aggiuntive o sostituire quelle predefinite (tieni presente che sono state scelte con cura per un aspetto ottimale).

interfaccia utente Oggetto o stringa (oggetto serializzato) null Specifica della vista da applicare alla tabella dati utilizzata per disegnare il grafico all'interno del controllo. Consente lo stesso livello di configurazione di qualsiasi grafico nella dashboard ed è conforme allo stesso formato accettato da ChartWrapper.setView(). Se non specificato, viene utilizzata la tabella di dati 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 number Differenza del valore dei dati interpretata come 1 pixel La dimensione minima selezionabile per l'intervallo (range.end - range.start), specificata in unità di valore dei dati. Per gli assi numerici, è un numero (non necessariamente un numero intero). Per l'asse data, data/ora o ora del giorno, è un numero intero che specifica la differenza in millisecondi.
UI.snapToData boolean false Se true, i pollici dell'intervallo vengono agganciati ai punti dati più vicini. In questo caso, i punti finali dell'intervallo restituito da getState() sono necessariamente valori nella tabella dati.

Eventi

Aggiunte a eventi ControlWrapper:

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

Filtro intervallo di date

Un dispositivo di scorrimento a due valori 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 Predefinito Descrizione
Valore basso number Nessuno L'intervallo più basso dell'intervallo selezionato, inclusi.
Valore elevato number Nessuno L'intervallo più alto dell'intervallo selezionato, inclusi.
ThumbMinMinimo boolean Nessuno Indica se il pollice inferiore del dispositivo di scorrimento è bloccato al limite minimo consentito. Se impostato, sostituisce lowValue.
Numero massimoPolliceAtMassimo boolean Nessuno Indica se il pollice più alto del dispositivo di scorrimento è bloccato al massimo consentito. Se impostato, sostituisce highValue.

Opzioni

Nome Tipo Predefinito Descrizione
Filtraindiceindice number Nessuno La colonna della tabella dati su cui dovrebbe 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.
FiltroEtichettaEtichetta string Nessuno L'etichetta della colonna su cui deve agire il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza. Deve puntare a una colonna di tipo number.
Valore min Data Automatica Valore minimo consentito per l'intervallo inferiore. Se il valore non è definito, il valore viene dedotto dai contenuti della DataTable gestita dal controllo.
Valore max Data Automatica Valore massimo consentito per l'intervallo superiore. Se il valore non è definito, il valore viene dedotto dai contenuti della DataTable gestita dal controllo.
ui Oggetto null Un oggetto con membri per configurare i vari aspetti della UI del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale dell'oggetto, come mostrato di seguito:
{label: 'Age', labelSeparator: ':'}
UI.format Oggetto Nessuno Come rappresentare la data come stringa. Accetta tutti i formati di data validi.
ui.passaggio string giorno La modifica minima possibile quando trascini il dispositivo di scorrimento del pollice: può essere qualsiasi unità di tempo fino a "giorno". ("mese" e "anno" non sono ancora supportati).
UI.ticks number Automatica Il numero di segni di graduazione (posizioni fisse nella barra dell'intervallo) che possono essere occupate dal dispositivo di scorrimento.
ui.unitIncrement string "1" L'importo da aumentare per incrementi di unità dell'intervallo. Un incremento di unità equivale a utilizzare i tasti freccia per spostare il dispositivo di scorrimento.
ui.blockIncrement number 10 La quantità da aumentare per gli incrementi a blocchi delle estensioni di intervallo. Un incremento di blocco equivale a utilizzare i tasti pgSu e pgDown per spostare il dispositivo di scorrimento con i pollici.
ui.showRangeValues boolean true Indica se accanto al dispositivo di scorrimento sono presenti etichette che mostrano le estensioni dell'intervallo selezionato.
UI.orientation string "orizzontale" L'orientamento del dispositivo di scorrimento. 'horizontal' o 'vertical'.
etichetta.UI string Automatica L'etichetta da visualizzare accanto al dispositivo di scorrimento. Se non è specificato, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparatore string Nessuno Una stringa di separazione aggiunta all'etichetta, per separare visivamente l'etichetta dal dispositivo di scorrimento.
ui.labelStacking string "orizzontale" Indica se l'etichetta deve essere visualizzata sopra (Stacking verticale) o accanto (Stacking orizzontale) nel dispositivo di scorrimento. Utilizza 'vertical' o 'horizontal'.
ui.cssclass string "google-visualization-controls-rangefilter" La classe CSS da assegnare al controllo, per lo stile personalizzato.

Filtro intervallo numeri

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

Stato

Nome Tipo Predefinito Descrizione
Valore basso number Nessuno L'intervallo più basso dell'intervallo selezionato, inclusi.
Valore elevato number Nessuno L'intervallo più alto dell'intervallo selezionato, inclusi.
ThumbMinMinimo boolean Nessuno Indica se il pollice inferiore del dispositivo di scorrimento è bloccato al limite minimo consentito. Se impostato, sostituisce lowValue.
Numero massimoPolliceAtMassimo boolean Nessuno Indica se il pollice più alto del dispositivo di scorrimento è bloccato al massimo consentito. Se impostato, sostituisce highValue.

Opzioni

Nome Tipo Predefinito Descrizione
Filtraindiceindice number Nessuno La colonna della tabella dati su cui dovrebbe 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.
FiltroEtichettaEtichetta string Nessuno L'etichetta della colonna su cui deve agire il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza. Deve puntare a una colonna di tipo number.
Valore min number Automatica Valore minimo consentito per l'intervallo inferiore. Se il valore non è definito, il valore viene dedotto dai contenuti della DataTable gestita dal controllo.
Valore max number Automatica Valore massimo consentito per l'intervallo superiore. Se il valore non è definito, il valore viene dedotto dai contenuti della DataTable gestita dal controllo.
ui Oggetto null Un oggetto con membri per configurare i vari aspetti della UI del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale dell'oggetto, come mostrato di seguito:
{label: 'Age', labelSeparator: ':'}
UI.format Oggetto Nessuno Come rappresentare il numero come stringa. Accetta tutti i formati di numeri validi.
ui.passaggio number 1 o calcolato da ticks se definito La modifica minima possibile quando trascini il dispositivo di scorrimento del dispositivo di scorrimento.
UI.ticks number Automatica Il numero di segni di graduazione (posizioni fisse nella barra dell'intervallo) che possono essere occupate dal dispositivo di scorrimento.
ui.unitIncrement number 1 L'importo da aumentare per incrementi di unità dell'intervallo. Un incremento di unità equivale a utilizzare i tasti freccia per spostare il dispositivo di scorrimento.
ui.blockIncrement number 10 La quantità da aumentare per gli incrementi a blocchi delle estensioni di intervallo. Un incremento di blocco equivale a utilizzare i tasti pgSu e pgDown per spostare il dispositivo di scorrimento con i pollici.
ui.showRangeValues boolean true Indica se accanto al dispositivo di scorrimento sono presenti etichette che mostrano le estensioni dell'intervallo selezionato.
UI.orientation string "orizzontale" L'orientamento del dispositivo di scorrimento. 'horizontal' o 'vertical'.
etichetta.UI string Automatica L'etichetta da visualizzare accanto al dispositivo di scorrimento. Se non è specificato, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparatore string Nessuno Una stringa di separazione aggiunta all'etichetta, per separare visivamente l'etichetta dal dispositivo di scorrimento.
ui.labelStacking string "orizzontale" Indica se l'etichetta deve essere visualizzata sopra (Stacking verticale) o accanto (Stacking orizzontale) nel dispositivo di scorrimento. Utilizza 'vertical' o 'horizontal'.
ui.cssclass string "google-visualization-controls-rangefilter" La classe CSS da assegnare al controllo, per lo stile personalizzato.

Filtro stringa

Un campo di immissione di testo semplice che consente di filtrare i dati tramite la corrispondenza delle stringhe. Si aggiorna dopo ogni pressione di un tasto: prova a digitare j per restringere la tabella seguente a Mario e Jessica.

Stato

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

Opzioni

Nome Tipo Predefinito Descrizione
Filtraindiceindice number Nessuno La colonna della tabella dati su cui dovrebbe funzionare il filtro. È obbligatorio fornire questa opzione o filterColumnLabel. Se sono presenti entrambi, questa opzione ha la precedenza.
FiltroEtichettaEtichetta string Nessuno L'etichetta della colonna su cui deve agire il filtro. È obbligatorio fornire questa opzione o filterColumnIndex. Se sono presenti entrambi, filterColumnIndex ha la precedenza.
tipo di corrispondenza string "prefisso" Indica se il controllo deve corrispondere solo ai valori esatti ('exact'), ai prefissi che iniziano dall'inizio del valore ('prefix') o a qualsiasi sottostringa ('any').
sensibile alle maiuscole boolean false Indica se la corrispondenza deve essere sensibile o meno alle maiuscole.
usoValoreFormato boolean false Indica se il controllo deve corrispondere ai valori formattati cella o ai valori effettivi.
ui Oggetto null Un oggetto con membri per configurare i vari aspetti della UI del controllo. Per specificare le proprietà di questo oggetto, puoi utilizzare la notazione letterale dell'oggetto, come mostrato di seguito:
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true Consente di specificare se il controllo deve corrispondere ogni volta che un tasto viene premuto o solo quando il campo di immissione "cambia" (perdita di valore o viene premuto il tasto Invio).
etichetta.UI string Automatica L'etichetta da visualizzare accanto al campo di immissione. Se non è specificato, verrà utilizzata l'etichetta della colonna su cui opera il controllo.
ui.labelSeparatore string Nessuno Una stringa di separazione aggiunta all'etichetta per separare visivamente l'etichetta dal campo di immissione.
ui.labelStacking string "orizzontale" Indica se l'etichetta deve essere visualizzata sopra (Stacking verticale) o accanto (Stacking orizzontale) nel campo di input. Utilizza 'vertical' o 'horizontal'.
ui.cssclass string "google-visualization-controls-stringfilter" La classe CSS da assegnare al controllo, per lo stile personalizzato.