Riferimento all'API di visualizzazione di Google

Questa pagina elenca gli oggetti esposti dall'API Google Visualization e i metodi standard esposti da tutte le visualizzazioni.

Nota: lo spazio dei nomi dell'API Google Visualization è google.visualization.*

Classe DataTable

Rappresenta una tabella di valori bidimensionale e modificabile. Per creare una copia di sola lettura di un DataTable (facoltativamente filtrato per mostrare valori, righe o colonne specifici), crea un DataView.

A ogni colonna viene assegnato un tipo di dati, oltre a diverse proprietà facoltative tra cui un ID, un'etichetta e una stringa con pattern.

Inoltre, puoi assegnare proprietà personalizzate (coppie nome/valore) a qualsiasi cella, riga, colonna o all'intera tabella. Alcune visualizzazioni supportano specifiche proprietà personalizzate; ad esempio, la visualizzazione tabella supporta una proprietà della cella denominata "style", che consente di assegnare una stringa di stile CSS incorporata alla cella della tabella visualizzata. Una visualizzazione deve descrivere nella documentazione le proprietà personalizzate supportate.

Vedi anche: QueryResponse.getDataTable

Costruttore

Sintassi

DataTable(opt_data, opt_version)

opt_data

[Facoltativo] Dati utilizzati per inizializzare la tabella. Può trattarsi del JSON restituito chiamando DataTable.toJSON() su una tabella compilata oppure di un oggetto JavaScript contenente i dati utilizzati per inizializzare la tabella. La struttura dell'oggetto letterale JavaScript è descritta qui. Se questo parametro non viene fornito, verrà restituita una nuova tabella di dati vuota.

opt_version

[Facoltativo] Un valore numerico che specifica la versione del protocollo di trasferimento utilizzato. Viene utilizzato solo dagli implementatori dell'origine dati di Strumenti per i grafici. La versione attuale è la 0.6.

Dettagli

L'oggetto DataTable viene utilizzato per contenere i dati trasmessi in una visualizzazione. Un DataTable è una tabella bidimensionale di base. Tutti i dati di ogni colonna devono avere lo stesso tipo di dati. Ogni colonna ha un descrittore che include il tipo di dati, un'etichetta per quella colonna (che potrebbe essere visualizzata da una visualizzazione) e un ID, che può essere utilizzato per fare riferimento a una colonna specifica (in alternativa all'utilizzo degli indici di colonna). L'oggetto DataTable supporta anche una mappa di proprietà arbitrarie assegnate a un valore specifico, a una riga, a una colonna o all'intero DataTable. Le visualizzazioni possono utilizzarli per supportare funzionalità aggiuntive. Ad esempio, la visualizzazione tabella utilizza le proprietà personalizzate per consentirti di assegnare nomi o stili arbitrari alle singole celle.

Ogni cella della tabella contiene un valore. Le celle possono avere un valore nullo o del tipo specificato dalla relativa colonna. Le celle facoltativamente possono assumere una versione "formattata" dei dati, ovvero una versione stringa dei dati, formattata per la visualizzazione da parte di una visualizzazione. Una visualizzazione può utilizzare (ma non è obbligatoria) la versione formattata per la visualizzazione, ma utilizzerà sempre i dati stessi per qualsiasi ordinamento o calcolo che effettua (ad esempio per determinare dove posizionare un punto su un grafico). Un esempio potrebbe essere l'assegnazione dei valori "low", "medium" e "high" come valori formattati ai valori numerici delle celle 1, 2 e 3.

Per aggiungere righe di dati dopo aver chiamato il costruttore, puoi chiamare addRow() per una singola riga o addRows() per più righe. Puoi anche aggiungere colonne chiamando i metodi addColumn(). Esistono metodi di rimozione anche per righe e colonne; tuttavia, anziché rimuovere righe o colonne, valuta la possibilità di creare una DataView che sia una visualizzazione selettiva di DataTable.

Se modifichi i valori in un elemento DataTable dopo che è stato passato al metodo draw() di una visualizzazione, le modifiche non modificheranno immediatamente il grafico. Devi richiamare draw() di nuovo per riflettere eventuali modifiche.

Nota: i grafici Google non eseguono alcuna convalida sulle tabelle dati. Se lo fosse, la visualizzazione dei grafici sarebbe più lenta. Se fornisci un numero in cui la colonna prevede una stringa o viceversa, Google Chart farà del proprio meglio per interpretare il valore in modo che abbia senso, ma non segnalerà eventuali errori.

L'esempio seguente mostra la creazione di un'istanza e il completamento di DataTable con una stringa letterale, con gli stessi dati mostrati nell'esempio JavaScript riportato sopra:

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

L'esempio seguente crea un nuovo DataTable vuoto e lo compila manualmente con gli stessi dati indicati sopra:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

Metodi

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

Formato del parametro data letterale JavaScript del costruttore

Puoi inizializzare DataTable passando un oggetto letterale stringa JavaScript nel parametro data. Questo oggetto viene chiamato oggetto data. Puoi codificare questo oggetto a mano, secondo la descrizione riportata di seguito, oppure puoi utilizzare una libreria Python helper se sai come utilizzare Python e il tuo sito può utilizzarlo. Tuttavia, se vuoi costruire l'oggetto a mano, questa sezione descrive la sintassi.

Innanzitutto, mostriamo un esempio di un semplice oggetto JavaScript che descrive una tabella con tre righe e tre colonne (tipi Stringa, Numero e Data):

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

Adesso descriviamo la sintassi:

L'oggetto data è composto da due proprietà di primo livello obbligatorie, cols e rows, e da una proprietà p facoltativa, ovvero una mappa di valori arbitrari.

Nota: tutti i nomi delle proprietà e le costanti delle stringhe mostrati sono sensibili alle maiuscole. Inoltre, le proprietà descritte come valori di stringa devono avere il relativo valore racchiuso tra virgolette. Ad esempio, se vuoi specificare la proprietà type come numero, questa viene espressa nel seguente modo: type: 'number', ma il valore stesso, come numerico, viene espresso nel seguente modo: v: 42

Proprietà cols

cols è un array di oggetti che descrive l'ID e il tipo di ogni colonna. Ogni proprietà è un oggetto con le seguenti proprietà (sensibili alle maiuscole):

• type [Obbligatorio] Tipo di dati dei dati nella colonna. Supporta i seguenti valori stringa (gli esempi includono la proprietà v: descritta più avanti):
  • "boolean" - Valore booleano JavaScript ("true" o "false"). Valore di esempio: v:'true'
  • 'number' - Valore numerico JavaScript. Valori di esempio: v:7, v:3.14, v:-55
  • 'string' - Valore della stringa JavaScript. Valore di esempio: v:'hello'
  • "date": oggetto Date JavaScript (mese in base zero), con l'ora troncata. Valore di esempio: v:new Date(2008, 0, 15)
  • 'datetime' - Oggetto Date JavaScript inclusa l'ora. Valore di esempio: v:new Date(2008, 0, 15, 14, 30, 45)
  • "timeofday": array di tre numeri e un quarto facoltativo, che rappresenta l'ora (0 indica mezzanotte), i minuti, i secondi e i millisecondi facoltativi. Valori di esempio: v:[8, 15, 0], v: [6, 12, 1, 144]
• id [Facoltativo] ID stringa della colonna. Deve essere univoco nella tabella. Utilizza caratteri alfanumerici di base, in modo che la pagina host non richieda caratteri di escape elaborati per accedere alla colonna in JavaScript. Fai attenzione a non scegliere una parola chiave JavaScript. Esempio: id:'col_1'
• label [Facoltativo] Valore della stringa mostrato per questa colonna da alcune visualizzazioni. Esempio: label:'Height'
• pattern [Facoltativo] Pattern stringa utilizzato da un'origine dati per formattare i valori numerici, di date o di ore delle colonne. Questo è solo un riferimento; probabilmente non avrai bisogno di leggere il pattern e non è necessario che esista. Il client di visualizzazione di Google non utilizza questo valore, che legge il valore formattato della cella. Se DataTable proviene da un'origine dati in risposta a una query con una clausola format, il pattern specificato in quella clausola probabilmente verrà restituito in questo valore. Gli standard di pattern consigliati sono DecimalFormat e SimpleDateFormat di ICU.
• p [Facoltativo] Un oggetto che è una mappa di valori personalizzati applicati alla cella. Questi valori possono essere di qualsiasi tipo JavaScript. Se la visualizzazione supporta proprietà a livello di cella, queste verranno descritte; in caso contrario, questa proprietà verrà ignorata. Esempio: p:{style: 'border: 1px solid green;'}.

Esempio di cols

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

Proprietà rows

La proprietà rows contiene un array di oggetti riga.

Ogni oggetto riga ha una proprietà obbligatoria denominata c, che è un array di celle in quella riga. Ha anche una proprietà facoltativa p che definisce una mappa di valori personalizzati arbitrari da assegnare all'intera riga. Se la visualizzazione supporta proprietà a livello di riga, queste verranno descritte; in caso contrario, questa proprietà verrà ignorata.

Oggetti cellulari

Ogni cella della tabella è descritta da un oggetto con le seguenti proprietà:

• v [Facoltativo] Il valore della cella. Il tipo di dati deve corrispondere al tipo di dati della colonna. Se la cella è nulla, la proprietà v deve essere nulla, anche se può comunque avere proprietà f e p.
• f [Facoltativo] Una versione stringa del valore v, formattata per la visualizzazione. In genere i valori corrisponderanno, sebbene non sia necessario, quindi se specifichi Date(2008, 0, 1) per v, devi specificare "1 gennaio 2008" o una stringa di questo tipo per questa proprietà. Questo valore non viene verificato rispetto al valore v. La visualizzazione non utilizzerà questo valore per il calcolo, ma solo come etichetta per la visualizzazione. Se omesso, verrà generata automaticamente una versione stringa di v utilizzando il formattatore predefinito. I valori f possono essere modificati utilizzando il tuo formattatore, impostati con setFormattedValue() o setCell() oppure recuperati con getFormattedValue().
• p [Facoltativo] Un oggetto che è una mappa di valori personalizzati applicati alla cella. Questi valori possono essere di qualsiasi tipo JavaScript. Se la visualizzazione supporta proprietà a livello di cella, queste verranno descritte. Queste proprietà possono essere recuperate con i metodi getProperty() e getProperties(). Esempio: p:{style: 'border: 1px solid green;'}.

Le celle nell'array di righe devono essere nello stesso ordine delle descrizioni delle colonne in cols. Per indicare una cella null, puoi specificare null, lasciare uno spazio vuoto per una cella in un array oppure omettere i membri finali dell'array. Pertanto, per indicare una riga con un valore nullo per le prime due celle, puoi specificare [ , , {cell_val}] o [null, null, {cell_val}].

Ecco un esempio di oggetto tabella con tre colonne riempite con tre righe di dati:

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

Proprietà

La proprietà p a livello di tabella è una mappa dei valori personalizzati applicati all'intero DataTable. Questi valori possono essere di qualsiasi tipo JavaScript. Se la visualizzazione supporta proprietà a livello di tabella di dati, queste saranno descritte; in caso contrario, questa proprietà sarà disponibile per l'uso da parte dell'applicazione. Esempio: p:{className: 'myDataTable'}.

Classe DataView

Una visualizzazione di sola lettura di una DataTable sottostante. Un DataView consente di selezionare solo un sottoinsieme di colonne e/o righe. Consente inoltre di riordinare colonne/righe e duplicare colonne/righe.

Una visualizzazione è una finestra in tempo reale sull'elemento DataTable sottostante, non un'istantanea statica dei dati. Tuttavia, devi comunque prestare attenzione quando modifichi la struttura della tabella stessa, come descritto qui:

• L'aggiunta o la rimozione di colonne dalla tabella sottostante non verrà applicata dalla vista e potrebbe causare un comportamento imprevisto nella vista. Per accettare queste modifiche, devi creare un nuovo DataView da DataTable.
• L'aggiunta o la rimozione di righe dalla tabella sottostante è sicura e le modifiche verranno propagate immediatamente alla vista (ma devi chiamare draw() su qualsiasi visualizzazione dopo questa modifica per eseguire il rendering del nuovo set di righe). Tieni presente che se la vista ha filtrato le righe richiamando uno dei metodi setRows() or hideRows() e aggiungi o rimuovi righe dalla tabella sottostante, il comportamento è imprevisto; devi creare un nuovo DataView per riflettere la nuova tabella.
• La modifica dei valori delle celle nelle celle esistenti è sicura e le modifiche vengono immediatamente propagate in DataView (ma devi chiamare draw() su qualsiasi visualizzazione dopo questa modifica per eseguire il rendering dei nuovi valori delle celle).

È anche possibile creare un DataView da un altro DataView. Tieni presente che ogni volta che viene menzionata una tabella o una vista sottostante, si fa riferimento al livello immediatamente inferiore a questo livello. In altre parole, si riferisce all'oggetto dati utilizzato per creare questo DataView.

DataView supporta anche le colonne calcolate, ovvero il cui valore viene calcolato in tempo reale utilizzando una funzione da te specificata. Quindi, ad esempio, puoi includere una colonna che corrisponda alla somma di due colonne precedenti o una colonna che calcola e mostra il trimestre di calendario di una data di un'altra colonna. Per ulteriori dettagli, consulta la pagina setColumns().

Quando modifichi un DataView nascondendo o mostrando righe o colonne, la visualizzazione rimarrà invariata finché non richiamerai draw() sulla visualizzazione.

Puoi combinare DataView.getFilteredRows() con DataView.setRows() per creare un DataView con un sottoinsieme di dati interessante, come mostrato qui:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

Costruttori

Esistono due modi per creare una nuova istanza DataView:

Costruttore 1

var myView = new google.visualization.DataView(data)

data

Un DataTable o DataView utilizzato per inizializzare la vista. Per impostazione predefinita, la visualizzazione contiene tutte le colonne e le righe nella tabella o nella vista sottostante, nell'ordine originale. Per nascondere o mostrare righe o colonne in questa visualizzazione, chiama i metodi set...() o hide...() appropriati.

Vedi anche:

setColumns(), hideColumns(), setRows(), hideRows().

Costruttore 2

Questo costruttore crea un nuovo DataView assegnando un oggetto DataView serializzato a un DataTable. Ti aiuta a ricreare il DataView che hai serializzato utilizzando DataView.toJSON().

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

dati

L'oggetto DataTable che hai utilizzato per creare DataView, su cui hai chiamato DataView.toJSON(). Se questa tabella è diversa da quella originale, i risultati non sono prevedibili.

viewAsJson

La stringa JSON restituita da DataView.toJSON(). Questa è una descrizione delle righe da mostrare o nascondere nella tabella di dati data.

Metodi

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

Classe ChartWrapper

Una classe ChartWrapper viene utilizzata per aggregare il grafico e gestire tutte le query di caricamento, disegno e origine dati per il grafico. La classe espone metodi pratici per impostare i valori nel grafico e disegnarlo. Questa classe semplifica la lettura da un'origine dati, perché non è necessario creare un gestore di callback delle query. Puoi utilizzarlo anche per salvare facilmente un grafico per riutilizzarlo.

Un altro vantaggio dell'utilizzo di ChartWrapper è che puoi ridurre il numero di caricamenti della libreria grazie al caricamento dinamico. Inoltre, non devi caricare i pacchetti in modo esplicito, poiché ChartWrapper si occuperà della ricerca e del caricamento dei pacchetti di grafici. Per informazioni dettagliate, consulta gli esempi riportati di seguito.

Tuttavia, al momento ChartWrapper propaga solo un sottoinsieme di eventi generati dai grafici: select, ready ed error. Gli altri eventi non vengono trasmessi tramite l'istanza ChartWrapper. Per riceverne altri, devi chiamare getChart() e sottoscrivere gli eventi direttamente nell'handle del grafico, come mostrato qui:

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

Costruttore

ChartWrapper(opt_spec)

opt_spec

[Facoltativo] - Un oggetto JSON che definisce il grafico o una versione stringa serializzata dell'oggetto. Il formato di questo oggetto è mostrato nella documentazione didrawChart(). Se non specificato, devi impostare tutte le proprietà appropriate utilizzando i metodi set... esposti da questo oggetto.

Metodi

ChartWrapper espone i seguenti metodi aggiuntivi:

Eventi

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

Esempio

I due snippet seguenti creano un grafico a linee equivalente. Il primo esempio utilizza la notazione letterale JSON per definire il grafico, il secondo utilizza i metodi ChartWrapper per impostare questi valori.

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

Stesso grafico, ora con metodi setter:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

ClasseChartEditor

La classe ChartEditor viene utilizzata per aprire una finestra di dialogo in-page che consente a un utente di personalizzare una visualizzazione all'istante.

Per utilizzare ChartEditor:

1. Carica il pacchetto charteditor. In google.charts.load(), carica il pacchetto "charteditor". Non è necessario caricare i pacchetti per il tipo di grafico visualizzato nell'editor; qualsiasi pacchetto verrà caricato automaticamente dall'editor di grafici, se necessario.
2. Crea un oggetto ChartWrapper che definisca il grafico che l'utente può personalizzare. Questo grafico verrà mostrato nella finestra di dialogo e l'utente utilizza l'editor per riprogettarlo, cambiare i tipi di grafico o persino modificare i dati di origine.
3. Crea una nuova istanza di ChartEditor e registrati per rimanere in ascolto dell'evento "ok". Questo evento viene generato quando l'utente fa clic sul pulsante "OK" nella finestra di dialogo. Una volta ricevuto, devi chiamare ChartEditor.getChartWrapper() per recuperare il grafico modificato dall'utente.
4. Chiama ChartEditor.openDialog(), passando per ChartWrapper. Viene visualizzata la finestra di dialogo. I pulsanti della finestra di dialogo consentono all'utente di chiudere l'editor. L'istanza ChartEditor è disponibile purché rientri nell'ambito; non viene eliminata automaticamente dopo la chiusura della finestra di dialogo da parte dell'utente.
5. Per aggiornare il grafico nel codice, chiama setChartWrapper().

Metodi

Opzioni

L'editor di grafici supporta le seguenti opzioni:

Eventi

L'editor del grafico genera i seguenti eventi:

Esempio

Il codice di esempio che segue apre una finestra di dialogo dell'editor di grafici con un grafico a linee compilato. Se l'utente fa clic su "Ok", il grafico modificato verrà salvato nell'elemento <div> specificato nella pagina.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

Metodi di manipolazione dei dati

Lo spazio dei nomi google.visualization.data contiene metodi statici per eseguire operazioni di tipo SQL sugli oggetti DataTable, ad esempio unirli o un raggruppamento in base al valore di colonna.

Lo spazio dei nomi google.visualization.data espone i seguenti metodi:

group()

Prende un oggetto DataTable compilato ed esegue un'operazione GROUP BY di tipo SQL, restituendo una tabella con righe raggruppate in base ai valori di colonna specificati. Tieni presente che questa operazione non modifica l'input DataTable.

La tabella restituita include una riga per ogni combinazione di valori nelle colonne chiave specificate. Ogni riga include le colonne chiave, oltre a una colonna con un valore di colonna aggregato su tutte le righe che corrispondono alla combinazione di chiavi (ad esempio, una somma o un conteggio di tutti i valori nella colonna specificata).

Lo spazio dei nomi google.visualization.data include diversi valori di aggregazione utili (ad esempio sum e count), ma puoi definirne uno personalizzato (ad esempio, standardDeviation o secondHighest). Le istruzioni su come definire il tuo aggregatore sono fornite dopo la descrizione del metodo.

Sintassi

google.visualization.data.group(data_table, keys, columns)

data_table

L'input DataTable. Non verrà modificato chiamando group().

tasti

Un array di numeri e/o oggetti che specifica le colonne in base a cui raggruppare. La tabella dei risultati include tutte le colonne di questo array e tutte le colonne di columns. Se è un numero, si tratta di un indice di colonna dell'input DataTable in base al quale raggruppare. Se si tratta di un oggetto, includerà una funzione in grado di modificare la colonna specificata (ad esempio, aggiungi 1 al valore nella colonna). L'oggetto deve avere le seguenti proprietà:

• colonna: un numero che rappresenta un indice di colonna da dt a cui applicare la trasformazione.
• modifier - Una funzione che accetta un valore (il valore della cella in quella colonna per ogni riga) e restituisce il valore modificato. Questa funzione viene utilizzata per modificare il valore della colonna al fine di agevolare il raggruppamento: ad esempio, richiamando una funzione WhatQuarter che calcola un trimestre da una colonna di date, in modo che l'API possa raggruppare le righe per trimestre. Il valore calcolato viene visualizzato nelle colonne chiave della tabella restituita. Questa funzione può essere dichiarata in linea all'interno di questo oggetto oppure può essere una funzione definita altrove nel codice (deve rientrare nell'ambito della chiamata). L'API fornisce una semplice funzione di modifica; qui sono riportate le istruzioni su come creare le tue funzioni più utili. Devi conoscere il tipo di dati che questa funzione può accettare e chiamarlo solo su colonne di quel tipo. Devi anche conoscere il tipo restituito di questa funzione e dichiararlo nella proprietà type descritta di seguito.
• type - Il tipo restituito dalla funzione modifier. Dovrebbe essere un nome di tipo di stringa JavaScript, ad esempio "number" o "boolean".
• label - [Facoltativo] Un'etichetta di stringa per assegnare questa colonna nel valore DataTable restituito.
• id - [Facoltativo] Un ID stringa per assegnare questa colonna nel valore DataTable restituito.

Esempi: [0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

colonne

[Facoltativo] Consente di specificare quali colonne, oltre alle colonne chiave, includere nella tabella di output. Poiché tutte le righe nel gruppo di righe sono compresse in una singola riga di output, devi determinare quale valore visualizzare per quel gruppo di righe. Ad esempio, puoi scegliere di mostrare il valore della colonna della prima riga dell'insieme o una media di tutte le righe del gruppo. colonne è un array di oggetti con le seguenti proprietà:

• colonna - Un numero che specifica l'indice della colonna da visualizzare.
• aggregazione - Una funzione che accetta un array di tutti i valori di questa colonna nel gruppo di righe e restituisce un singolo valore da visualizzare nella riga dei risultati. Il valore restituito deve essere del tipo specificato dalla proprietà type dell'oggetto. I dettagli sulla creazione di una funzione di aggregazione sono riportati di seguito. Devi sapere quali tipi di dati sono accettati da questo metodo e chiamarli solo nelle colonne del tipo appropriato. L'API offre diverse utili funzioni di aggregazione. Consulta Funzioni di aggregazione fornite di seguito per un elenco oppure Creazione di una funzione di aggregazione per scoprire come scrivere una funzione di aggregazione personalizzata.
• type - Il tipo restituito della funzione di aggregazione. Deve essere un nome di tipo di stringa JavaScript, ad esempio "number" o "boolean".
• label - [Facoltativo] Un'etichetta di stringa da applicare a questa colonna nella tabella restituita.
• id - [Facoltativo] Un ID stringa da applicare a questa colonna nella tabella restituita.

Valore restituito

Un elemento DataTable con una colonna per ogni colonna elencata in chiavi e una colonna per ogni colonna elencata in colonne. La tabella è ordinata in base a righe chiave, da sinistra a destra.

Esempio

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

Funzioni di modifica disponibili

L'API fornisce le seguenti funzioni di modifica che puoi passare nelle chiavi. modifier per personalizzare il comportamento di raggruppamento.

Funzioni di aggregazione fornite

L'API fornisce le seguenti funzioni di aggregazione che puoi passare nelle colonne. dell'array di parametri di aggregazione.

Creazione di una funzione di modifica

Puoi creare una funzione di modifica per eseguire una semplice trasformazione su valori chiave prima che la funzione group() gruppi le righe. Questa funzione prende un singolo valore di cella, esegue un'azione su di esso (ad esempio, aggiunge 1 al valore) e lo restituisce. I tipi di input e restituiti non devono essere dello stesso tipo, ma il chiamante deve conoscere i tipi di input e output. Di seguito è riportato un esempio di funzione che accetta una data e restituisce il trimestre:

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

Creazione di una funzione di aggregazione

Puoi creare una funzione di aggregazione che accetta un insieme di valori di colonna in un gruppo di righe e restituisca un singolo numero, ad esempio restituendo un conteggio o una media di valori. Di seguito è riportata un'implementazione della funzione di aggregazione del conteggio fornita, che restituisce un conteggio del numero di righe presenti nel gruppo di righe:

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

Questo metodo unisce due tabelle di dati (DataTable o DataView oggetti) in un'unica tabella dei risultati, simile a un'istruzione SQL JOIN. Puoi specificare una o più coppie di colonne (colonne chiave) tra le due tabelle e la tabella di output include le righe in base a un metodo di join specificato: solo le righe in cui entrambe le chiavi corrispondono, tutte le righe di una tabella o tutte le righe di entrambe le tabelle, indipendentemente dalla corrispondenza delle chiavi. La tabella dei risultati include solo le colonne chiave ed eventuali colonne aggiuntive specificate. Tieni presente che dt2 non può avere chiavi duplicate, al contrario di dt1. Il termine "chiave" indica la combinazione di tutti i valori delle colonne chiave, non di uno specifico valore della colonna chiave. Di conseguenza, se una riga contiene valori di celle A | B | C e le colonne 0 e 1 sono colonne chiave, la chiave per quella riga è AB.

Sintassi

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

Un DataTable compilato da unire con dt2.

dt2

Un elemento DataTable compilato da unire a dt1. Questa tabella non può avere più chiavi identiche (in cui una chiave è una combinazione di valori di colonne chiave).

joinMethod

Una stringa che specifica il tipo di join. Se dt1 ha più righe che corrispondono a una riga dt2, la tabella di output includerà tutte le righe dt1 corrispondenti. Scegli tra i seguenti valori:

• "full": la tabella di output include tutte le righe di entrambe le tabelle, indipendentemente dalla corrispondenza delle chiavi. Le righe senza corrispondenza avranno voci di cella null; le righe corrispondenti vengono unite.
• "inner" - Il join completo filtrato in modo da includere solo le righe in cui le chiavi corrispondono.
• "left": la tabella di output include tutte le righe da dt1, indipendentemente dal fatto che esistano o meno righe corrispondenti da dt2.
• "right" - La tabella di output include tutte le righe da dt2, indipendentemente dal fatto che esistano o meno righe corrispondenti da dt1.

tasti

Un array di colonne chiave da confrontare da entrambe le tabelle. Ogni coppia è un array di due elementi: la prima è una chiave in dt1, la seconda una chiave in dt2. Questo array può specificare le colonne in base all'indice, all'ID o all'etichetta. Consulta getColumnIndex.
Le colonne devono essere dello stesso tipo in entrambe le tabelle. Tutte le chiavi specificate devono corrispondere in base alla regola specificata da joinMethod per poter includere una riga della tabella. Le colonne chiave sono sempre incluse nella tabella di output. Solo dt1, la tabella a sinistra, può includere chiavi duplicate; le chiavi in dt2 devono essere univoche. In questo caso, il termine "chiave" indica un insieme univoco di colonne chiave, non singoli valori di colonna. Ad esempio, se le colonne chiave fossero A e B, la seguente tabella avrebbe solo coppie chiave-valore univoche (e potrebbe quindi essere utilizzata come dt2):

A	B
Gianni	Rosso
Gianni	di colore blu
Fred	Rosso

Esempio: [[0,0], [2,1]] confronta i valori della prima colonna in entrambe le tabelle e della terza colonna di dt1 con la seconda colonna di dt1.

dt1Columns

Un array di colonne dt1 da includere nella tabella di output, oltre alle colonne chiave di dt1. Questo array può specificare le colonne in base all'indice, all'ID o all'etichetta. Consulta getColumnIndex.

dt2Columns

Un array di colonne dt2 da includere nella tabella di output, oltre alle colonne chiave di dt2. Questo array può specificare le colonne in base all'indice, all'ID o all'etichetta. Consulta getColumnIndex.

Valore restituito

Un elemento DataTable con le colonne chiave dt1Columns e dt2Columns. Questa tabella è ordinata in base alle colonne chiave, da sinistra a destra. Quando joinMethod è "inner", tutte le celle chiave devono essere compilate. Per altri metodi di join, se non viene trovata alcuna chiave corrispondente, la tabella avrà un valore null per tutte le celle chiave senza corrispondenza.

Esempi

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

Formattatori

L'API Google Visualization fornisce formatter che possono essere utilizzati per riformattare i dati in una visualizzazione. Questi formattatori modificano il valore formattato della colonna specificata in tutte le righe. Ricorda:

• I formattatori modificano solo i valori formattati, non i valori sottostanti. Ad esempio, il valore visualizzato è "1000,00 $", ma il valore sottostante è comunque "1000".
• I formattatori hanno effetto su una sola colonna alla volta; per riformattare più colonne, applica un formattatore a ogni colonna che vuoi modificare.
• Se utilizzi anche i formattatori definiti dall'utente, alcuni formattatori di visualizzazione di Google sostituiranno tutti i formattatori definiti dall'utente.

La formattazione effettiva applicata ai dati deriva dalle impostazioni internazionali con cui è stata caricata l'API. Per maggiori dettagli, consulta la sezione sul caricamento dei grafici con impostazioni internazionali specifiche .

Importante: i formattatori possono essere utilizzati solo con un elemento DataTable; non con un elemento DataView (gli oggetti DataView sono di sola lettura).

Di seguito sono riportati i passaggi generali per utilizzare un formattatore:

1. Ottieni l'oggetto DataTable compilato.
2. Per ogni colonna che vuoi riformattare:
   1. Crea un oggetto che specifichi tutte le opzioni per il tuo formattatore. Si tratta di un oggetto JavaScript di base con un insieme di proprietà e valori. Consulta la documentazione del formattatore per verificare quali proprietà sono supportate. (Facoltativamente, puoi passare un oggetto di notazione letterale oggetto specificando le opzioni.)
   2. Crea il formattatore, passando l'oggetto opzioni.
   3. Richiama formatter.format(table, colIndex), trasmettendo il valore di DataTable e il numero di colonna (in base zero) dei dati da riformattare. Tieni presente che puoi applicare un solo formattatore a ogni colonna; l'applicazione di un secondo formattatore semplicemente sovrascriverà gli effetti del primo.
      Importante:molti formattatori richiedono ai tag HTML di visualizzare una formattazione speciale; se la visualizzazione supporta un'opzione allowHtml, dovresti impostarla su true.

Ecco un esempio di come modificare i valori di data formattati di una colonna di date per utilizzare un formato di data esteso ("1 gennaio 2009"):

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

La maggior parte dei formattatori espone i seguenti due metodi:

Metodo	Descrizione
google.visualization.formatter_name(options)	Costruttore, dove formatter_name è un nome formatterclass specifico. options - Un oggetto JavaScript generico che specifica le opzioni per quel formattatore. Si tratta di un oggetto generico con coppie di proprietà/valore e proprietà specifiche per il formattatore. Consulta la documentazione del tuo formattatore specifico per scoprire quali opzioni sono supportate. Ecco due esempi di modi per chiamare il costruttore per l'oggetto DateFormat, passando in due proprietà: // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	Riformatta i dati nella colonna specificata. data: un DataTable contenente i dati da riformattare. Non puoi utilizzare un DataView qui. colIndex - L'indice in base zero della colonna da formattare. Per formattare più colonne, devi chiamare questo metodo più volte, con valori colIndex diversi.

 

L'API di visualizzazione di Google fornisce i seguenti formattatori:

Nome formattatore	Descrizione
ArrowFormat	Aggiunge una Freccia su o una Freccia giù, che indica se il valore della cella è superiore o inferiore a un valore specificato.
BarFormat	Aggiunge una barra colorata, la cui direzione e il cui colore indicano se il valore della cella è superiore o inferiore a un valore specificato.
ColorFormat	Colora una cella a seconda che i valori rientrino in un intervallo specificato.
DateFormat	Formatta un valore Date o DateTime in diversi modi, ad esempio "1 gennaio 2009", "1/1/09" e "1 gen 2009".
NumberFormat	Formatta vari aspetti dei valori numerici.
PatternFormat	Concatena i valori delle celle sulla stessa riga in una cella specificata, insieme a testo arbitrario.

ArrowFormat

Aggiunge una Freccia su o una Freccia giù a una cella numerica, a seconda che il valore sia superiore o inferiore a un valore di base specificato. Se è uguale al valore base, non viene mostrata alcuna freccia.

Opzioni

ArrowFormat supporta le seguenti opzioni, trasmesse al costruttore:

Opzione	Descrizione
base	Un numero che indica il valore di base, utilizzato per il confronto con il valore della cella. Se il valore della cella è più alto, verrà inclusa una freccia verde su

Codice campione

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

Aggiunge una barra colorata a una cella numerica che indica se il valore della cella è superiore o inferiore a un valore di base specificato.

Opzioni

BarFormat supporta le seguenti opzioni, trasmesse al costruttore:

Opzione	Esempio Descrizione
base	Un numero che rappresenta il valore di base con cui confrontare il valore della cella. Se il valore della cella è più alto, verrà disegnata a destra della base; se più bassa, a sinistra. Il valore predefinito è 0.
colorNegative	Una stringa che indica la sezione del valore negativo delle barre. I valori possibili sono "red", "green" e "blue"; il valore predefinito è "red".
colorPositive	Una stringa che indica il colore della sezione del valore positivo delle barre. I valori possibili sono "red", "green" e "blue". Il valore predefinito è "blu".
drawZeroLine	Un valore booleano che indica se tracciare una linea di base scura da 1 pixel in presenza di valori negativi. La linea scura serve a migliorare la scansione visiva delle barre. Il valore predefinito è "false".
max	Il valore numerico massimo per l'intervallo di barre. Il valore predefinito è il valore più alto della tabella.
min	Il valore numerico minimo per l'intervallo di barre. Il valore predefinito è il valore più basso della tabella.
showValue	Se il valore è true, mostra valori e barre; se è falso, mostra solo barre. Il valore predefinito è true.
width	Spessore di ogni barra, in pixel. Il valore predefinito è 100.

Codice campione

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

Assegna i colori al primo piano o allo sfondo di una cella numerica, a seconda del valore della cella. Questo formattatore è insolito, in quanto non prende le sue opzioni nel costruttore. Devi invece chiamare addRange() o addGradientRange() tutte le volte che vuoi per aggiungere intervalli di colori prima di chiamare format(). I colori possono essere specificati in qualsiasi formato HTML accettabile, ad esempio "nero", "#000000" o "#000".

Metodi

ColorFormat supporta i seguenti metodi:

Metodo	Descrizione
google.visualization.ColorFormat()	Costruttore. Non accetta argomenti.
addRange(from, to, color, bgcolor)	Specifica il colore di primo piano e/o il colore di sfondo di una cella, a seconda del valore della cella. A ogni cella con un valore nell'intervallo specificato da da a a verranno assegnati i valori color e bgcolor. È importante capire che l'intervallo non è inclusivo, perché la creazione di un intervallo compreso tra 1 e 1000 e un secondo compreso tra 1000 e 2000 non copre il valore di 1000. from: [String, Number, Date, DateTime o TimeOfDay] limite inferiore (incluso) dell'intervallo, oppure null. Se nullo, corrisponde a -∞. I limiti delle stringhe vengono confrontati in ordine alfabetico con i valori delle stringhe. to: [String, Number, Date, DateTime o TimeOfDay] Il limite superiore (non incluso) dell'intervallo oppure null. Se nullo, corrisponde a +∞. I limiti delle stringhe vengono confrontati in ordine alfabetico con i valori delle stringhe. colore - Il colore da applicare al testo nelle celle corrispondenti. I valori possono essere "#RRGGBB" o costanti di colore definite (esempio: "#FF0000" o "red"). bgcolor - Il colore da applicare allo sfondo delle celle corrispondenti. I valori possono essere "#RRGGBB" o costanti di colore definite (esempio: "#FF0000" o "red").
addGradientRange(from, to, color, fromBgColor, toBgColor)	Assegna un colore di sfondo da un intervallo, in base al valore della cella. Il colore viene scalato in modo da corrispondere al valore della cella all'interno di un intervallo che va dal colore del limite inferiore al colore del limite superiore. Tieni presente che questo metodo non può confrontare i valori di stringa, a differenza di addRange(). Suggerimento: le serie di colori sono spesso difficili da valutare con precisione.L'intervallo più semplice e più facile da leggere va da un colore completamente saturo al bianco (ad es. #FF0000 - FFFFFF). from - [Number, Date, DateTime o TimeOfDay] Il limite inferiore (incluso) dell'intervallo, oppure null. Se nullo, corrisponderà a -∞. to - [Numero, Data, DataOra o Ora del giorno] Il limite più alto (non incluso) dell'intervallo, oppure il valore nullo. Se nullo, corrisponderà a +∞. colore - Il colore da applicare al testo nelle celle corrispondenti. Questo colore è lo stesso per tutte le celle, indipendentemente dal loro valore. fromBgColor: il colore di sfondo per le celle che contengono valori all'estremità inferiore del gradiente. I valori possono essere "#RRGGBB" o costanti di colore definite, ad esempio "#FF0000" o "red". toBgColor: il colore di sfondo per le celle che contengono valori all'estremità superiore della sfumatura. I valori possono essere "#RRGGBB" o costanti di colore definite, ad esempio "#FF0000" o "red".
format(dataTable, columnIndex)	Il metodo format() standard per applicare la formattazione alla colonna specificata.

Codice campione

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

Formatta un valore Date JavaScript in diversi modi, ad esempio "1 gennaio 2016", "1/1/16" e "1 gen 2016".

Opzioni

DateFormat supporta le seguenti opzioni, trasmesse al costruttore:

Opzione	Descrizione
formatType	Un'opzione di formattazione rapida per la data. Sono supportati i seguenti valori di stringa, che riformattano la data 28 febbraio 2016 come mostrato di seguito: "short" (formato breve): ad es. "28/2/16" "medium" - formato medio: ad es. "28 feb 2016" "long" - Formato lungo: ad es. "28 febbraio 2016" Non puoi specificare sia formatType sia pattern.
pattern	Un pattern di formato personalizzato da applicare al valore, simile al formato di data e ora di ICU. Ad esempio: var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); Non puoi specificare sia formatType sia pattern. Puoi leggere ulteriori dettagli sui pattern nella prossima sezione.
timeZone	Il fuso orario in cui visualizzare il valore della data. Questo è un valore numerico che indica GMT + questo numero di fusi orari (può essere negativo). Per impostazione predefinita, gli oggetti Date vengono creati con il fuso orario presunto del computer su cui vengono creati; questa opzione viene utilizzata per visualizzare il valore in un fuso orario diverso. Ad esempio, se hai creato un oggetto Date delle 17:00 su un computer che si trova a Greenwich, in Inghilterra, e hai specificato il fuso orario -5 (options['timeZone'] = -5 o fuso orario del Pacifico orientale negli Stati Uniti), il valore visualizzato sarà 12 mezzogiorno.

Metodi

DateFormat supporta i seguenti metodi:

Metodo	Descrizione
google.visualization.DateFormat(options)	Costruttore. Per saperne di più, consulta la sezione delle opzioni in alto.
format(dataTable, columnIndex)	Il metodo format() standard per applicare la formattazione alla colonna specificata.
formatValue(value)	Restituisce il valore formattato di un determinato valore. Questo metodo non richiede un DataTable.

Codice campione

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

Scopri di più sui pattern di date

Di seguito sono riportati alcuni dettagli aggiuntivi sui pattern supportati:

I pattern sono simili al formato di data e ora di ICU, ma quelli che seguono non sono ancora supportati: A e D F g Y u w W. Per evitare conflitti con pattern, il testo letterale che vuoi visualizzare nell'output deve essere racchiuso tra virgolette singole, ad eccezione delle virgolette singole, che devono essere raddoppiate: ad esempio, "K 'o''clock.'".

Sequenza	Descrizione	Output di esempio
GG	Indicatore dell'era.	"ANNUNCIO"
yy o yyyy	anno.	1996
L	Mese dell'anno. Per gennaio: M produce 1 MM produce 01 il Marketing Mix Modeling produce Jan MMMM produce gennaio	"Luglio" "07"
d	Giorno del mese. I valori "d" aggiuntivi aggiungeranno zeri iniziali.	10
h	Ora nella scala di 12 ore. I valori "h" aggiuntivi aggiungeranno zeri iniziali.	12
V	Ora nella scala di 24 ore. Ai valori Hk extra verranno aggiunti zeri iniziali.	0
M	Minuto in un'ora. I valori "M" aggiuntivi aggiungeranno zeri iniziali.	30
s	Secondo nel minuto. I valori di "" aggiuntivi" aggiungeranno zeri iniziali.	55
S	Frazione di secondo. I valori "S" aggiuntivi verranno riempiti a destra con zeri.	978
E	Giorno della settimana. Output seguenti per "Martedì": E produce T Prodotti EE o EEE mar o mar EEEE produce martedì	"Mar" "Martedì"
aa	AM/PM	"PM"
k	Ora del giorno (1~24). I valori "k" aggiuntivi aggiungeranno zeri iniziali.	24
K	Ora in AM/PM (0~11). I valori "k" aggiuntivi aggiungeranno zeri iniziali.	0
z	Fuso orario. Per il fuso orario 5, produce "UTC+5"	"UTC+5"
Z	Fuso orario nel formato RFC 822. Per il fuso orario -5: Z, ZZ, ZZZ prodotti -0500 ZZZZ e altri prodotti "GMT -05:00"	"-0800" "GMT -05:00"
v	Fuso orario (generico).	"Etc/GMT-5"
'	escape per il testo	'Date="
"	virgoletta singola	''yy

NumberFormat

Descrive come formattare le colonne numeriche. Le opzioni di formattazione includono la specifica di un prefisso (ad esempio il simbolo del dollaro) o della punteggiatura da utilizzare come indicatore delle migliaia.

Opzioni

NumberFormat supporta le seguenti opzioni, trasmesse al costruttore:

Opzione	Descrizione
decimalSymbol	Un carattere da utilizzare come indicatore decimale. L'impostazione predefinita è un punto (.).
fractionDigits	Un numero che specifica quante cifre visualizzare dopo il separatore decimale. Il valore predefinito è 2. Se specifichi più cifre di quelle contenute nel numero, per i valori più piccoli verranno visualizzati zeri. I valori troncati verranno arrotondati (5 arrotondati per eccesso).
groupingSymbol	Un carattere da utilizzare per raggruppare le cifre a sinistra del decimale in serie di tre. Il valore predefinito è una virgola (,).
negativeColor	Il colore del testo per i valori negativi. Nessun valore predefinito. I valori possono essere qualsiasi valore di colore HTML accettabile, ad esempio "red" o "#FF0000".
negativeParens	Un valore booleano, dove true indica che i valori negativi devono essere racchiusi tra parentesi. Il valore predefinito è true.
pattern	Una stringa di formato. Se fornite, tutte le altre opzioni vengono ignorate, ad eccezione di negativeColor. La stringa di formato è un sottoinsieme del set di pattern di ICU . Ad esempio, {pattern:'#,###%'} restituirà i valori di output "1000%", "750%" e "50%" per i valori 10, 7,5 e 0,5.
prefix	Un prefisso di stringa per il valore, ad esempio "$".
suffix	Un suffisso della stringa per il valore, ad esempio "%".

Metodi

NumberFormat supporta i seguenti metodi:

Metodo	Descrizione
google.visualization.NumberFormat(options)	Costruttore. Per saperne di più, consulta la sezione delle opzioni in alto.
format(dataTable, columnIndex)	Il metodo format() standard per applicare la formattazione alla colonna specificata.
formatValue(value)	Restituisce il valore formattato di un determinato valore. Questo metodo non richiede un valore DataTable.

Codice campione

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

Consente di unire i valori delle colonne designate in un'unica colonna, insieme a testo arbitrario. Quindi, ad esempio, se avessi una colonna per il nome e una per il cognome, potresti completare una terza colonna con {last name}, {first name}. Questo formattatore non segue le convenzioni per il costruttore e il metodo format(). Per istruzioni, consulta la sezione Metodi di seguito.

Metodi

PatternFormat supporta i seguenti metodi:

Metodo	Descrizione
google.visualization.PatternFormat(pattern)	Costruttore. Non accetta un oggetto options. Richiede invece un parametro pattern di stringa. Questa è una stringa che descrive quali valori di colonna inserire nella colonna di destinazione, insieme a qualsiasi testo arbitrario. Incorpora segnaposto nella stringa per indicare un valore di un'altra colonna da incorporare. I segnaposto sono {#}, dove # è l'indice di una colonna di origine da utilizzare. L'indice è un indice nell'array srcColumnIndices del metodo format() riportato di seguito. Per includere un carattere letterale { o }, utilizza il carattere di escape in questo modo: \{ o \}. Per includere un carattere \, utilizza il carattere di escape \\. Codice campione L'esempio seguente mostra un costruttore per un pattern che crea un elemento anchor, con il primo e il secondo elemento presi dal metodo format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	La chiamata alla formattazione standard, con alcuni parametri aggiuntivi: dataTable - La tabella di dati su cui operare. srcColumnIndices: un array di uno o più indici di colonna (in base zero) da estrarre come origini dalla tabella di dati sottostante. Verrà utilizzato come origine dati per il parametro pattern nel costruttore. I numeri delle colonne non devono essere ordinati in ordine. opt_dstColumnIndex: la colonna di destinazione in cui inserire l'output della manipolazione del pattern. [facoltativo] Se non specificato, il primo elemento in srcColumIndices verrà utilizzato come destinazione. Consulta gli esempi di formattazione dopo la tabella.

Ecco alcuni esempi di input e output per una tabella a quattro colonne.

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

Codice campione

L'esempio seguente mostra come combinare i dati di due colonne per creare un indirizzo email. Utilizza un oggetto DataView per nascondere le colonne di origine originali:

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

Una classe helper per semplificare la scrittura di Gadget che utilizzano l'API di visualizzazione di Google.

Costruttore

google.visualization.GadgetHelper()

Metodi

Metodo	Valore restituito	Descrizione
createQueryFromPrefs(prefs)	google.visualization.Query	Statica. Crea una nuova istanza di google.visualization.Query e impostane le proprietà in base ai valori delle preferenze per i gadget. Il tipo di parametro prefs è _IG_Prefs La preferenza _table_query_url viene utilizzata per impostare l'URL dell'origine dati Query. La preferenza _table_query_refresh_interval viene utilizzata per impostare l'intervallo di aggiornamento delle query (in secondi).
validateResponse(response)	Booleano	Statica. Il parametro response è di tipo google.visualization.QueryResponse. Restituisce true se la risposta contiene dati. Restituisce false se l'esecuzione della query non è riuscita e la risposta non contiene dati. Se si è verificato un errore, questo metodo mostra un messaggio di errore.

Classi delle query

I seguenti oggetti sono disponibili per inviare query sui dati a un'origine dati esterna, come Fogli Google.

• Query: esegue il wrapping della richiesta di dati in uscita.
• QueryResponse: gestisce la risposta dall'origine dati.

Query

Rappresenta una query inviata a un'origine dati.

Costruttore

google.visualization.Query(dataSourceUrl, opt_options)

Parametri

dataSourceUrl

URL [obbligatorio, stringa] a cui inviare la query. Consulta la documentazione relativa a grafici e fogli di lavoro per Fogli di lavoro Google.

opt_options

[Facoltativo, oggetto] Una mappa delle opzioni per la richiesta. Nota : se accedi a un' origine dati limitata , non devi utilizzare questo parametro. Di seguito sono riportate le proprietà supportate:

• sendMethod - [Facoltativo, stringa] Specifica il metodo da utilizzare per inviare la query. Scegli uno dei seguenti valori di stringa:
  • 'xhr' - Invia la query utilizzando XmlHttpRequest.
  • 'scriptInjection' - Invia la query utilizzando script injection.
  • 'makeRequest' - [Disponibile solo per i gadget, che sono deprecati] Invia la query utilizzando il metodo makeRequest() dell'API Gadget. Se specificato, devi specificare anche makeRequestParams.
  • 'auto' - Utilizza il metodo specificato dal parametro URL tqrt dell'URL dell'origine dati. tqrt può avere i seguenti valori: "xhr", "scriptInjection" o "makeRequest". Se tqrt non è presente o presenta un valore non valido, il valore predefinito è "xhr" per le richieste dello stesso dominio e "scriptInjection" per le richieste interdominio.
• makeRequestParams - [Object] Una mappa dei parametri per una query makeRequest(). Utilizzato e obbligatorio solo se sendMethod è 'makeRequest'.

Metodi

Metodo	Valore restituito	Descrizione
abort()	Nessun valore	Interrompi l'invio della query automatica avviato con setRefreshInterval().
setRefreshInterval(seconds)	Nessun valore	Imposta la query in modo che chiami automaticamente il metodo send ogni durata specificata (numero di secondi), a partire dalla prima chiamata esplicita a send. seconds è un numero maggiore o uguale a zero. Se utilizzi questo metodo, devi chiamarlo prima di chiamare il metodo send. Annulla questo metodo chiamandolo di nuovo con zero (valore predefinito) o richiamando abort().
setTimeout(seconds)	Nessun valore	Imposta il numero di secondi di attesa prima che l'origine dati risponda prima di generare un errore di timeout. seconds è un numero maggiore di zero. Il timeout predefinito è 30 secondi. Questo metodo, se utilizzato, deve essere chiamato prima di chiamare il metodo send.
setQuery(string)	Nessun valore	Imposta la stringa di query. Il valore del parametro string deve essere una query valida. Questo metodo, se utilizzato, deve essere chiamato prima di chiamare il metodo send. Scopri di più sul linguaggio di query.
send(callback)	Nessun valore	Invia la query all'origine dati. callback dovrebbe essere una funzione che verrà chiamata quando l'origine dati risponde. La funzione di callback riceverà un singolo parametro di tipo google.visualization.QueryResponse.

QueryResponse

Rappresenta la risposta dell'esecuzione di una query come ricevuta dall'origine dati. Un'istanza di questa classe viene passata come argomento alla funzione di callback impostata durante la chiamata di Query.send.

Metodi

Metodo	Valore restituito	Descrizione
getDataTable()	DataTable	Restituisce la tabella di dati restituita dall'origine dati. Restituisce null se l'esecuzione della query non è riuscita e non sono stati restituiti dati.
getDetailedMessage()	String	Restituisce un messaggio di errore dettagliato per le query non riuscite. Se l'esecuzione della query è riuscita, questo metodo restituisce una stringa vuota. Il messaggio restituito è destinato agli sviluppatori e può contenere informazioni tecniche, ad esempio "La colonna {salary} non esiste".
getMessage()	String	Restituisce un breve messaggio di errore per le query non riuscite. Se l'esecuzione della query è riuscita, questo metodo restituisce una stringa vuota. Il messaggio restituito è un breve messaggio destinato agli utenti finali, ad esempio "Query non valida" o "Accesso negato".
getReasons()	Array di stringhe	Restituisce un array di zero di più voci. Ogni voce è una breve stringa con un codice di errore o di avviso generato durante l'esecuzione della query. Codici possibili: access_denied L'utente non dispone delle autorizzazioni per accedere all'origine dati. invalid_query La query specificata contiene un errore di sintassi. data_truncated Una o più righe di dati che corrispondono alla selezione della query non sono state restituite a causa dei limiti delle dimensioni dell'output. (avviso). timeout La query non ha risposto entro il tempo previsto.
hasWarning()	Booleano	Restituisce true se l'esecuzione della query contiene messaggi di avviso.
isError()	Booleano	Restituisce true se l'esecuzione della query non è riuscita e la risposta non contiene alcuna tabella di dati. Restituisce <false> se l'esecuzione della query è riuscita e la risposta contiene una tabella di dati.

Visualizzazione degli errori

L'API fornisce diverse funzioni per aiutarti a mostrare messaggi di errore personalizzati agli utenti. Per utilizzare queste funzioni, fornisci nella pagina un elemento container (in genere un <div>), in cui l'API estrarrà un messaggio di errore formattato. Questo contenitore può essere l'elemento del contenitore di visualizzazione o un contenitore solo per gli errori. Se specifichi l'elemento contenente la visualizzazione, il messaggio di errore verrà mostrato sopra la visualizzazione. Quindi chiama la funzione appropriata tra quelle riportate di seguito per mostrare o rimuovere il messaggio di errore.

Tutte le funzioni sono funzioni statiche nello spazio dei nomi google.visualization.errors.

Molte visualizzazioni possono generare un evento di errore. Per saperne di più, consulta l'evento di errore di seguito.

Puoi vedere un esempio di errore personalizzato in Esempio di wrapper query.

Funzione	Valore restituito	Descrizione
addError(container, message, opt_detailedMessage, opt_options)	Valore dell'ID stringa che identifica l'oggetto di errore creato. Si tratta di un valore univoco nella pagina e può essere utilizzato per rimuovere l'errore o trovare l'elemento che la contiene.	Aggiunge un blocco di visualizzazione degli errori all'elemento della pagina specificato, con il testo e la formattazione specificati. container - L'elemento DOM in cui inserire il messaggio di errore. Se non è possibile trovare il container, la funzione genera un errore JavaScript. message - Una stringa messaggio da visualizzare. opt_detailedMessage - Una stringa di messaggio dettagliata facoltativa. Per impostazione predefinita, si tratta di testo mouseover, ma può essere modificato nella proprietà opt_options.showInToolTip descritta di seguito. opt_options - Un oggetto facoltativo con proprietà che impostano varie opzioni di visualizzazione per il messaggio. Sono supportate le seguenti opzioni: showInTooltip - Un valore booleano in cui true mostra il messaggio dettagliato solo come testo della descrizione comando e false il messaggio dettagliato nel corpo del container dopo il breve messaggio. Il valore predefinito è true. type - Una stringa che descrive il tipo di errore, che determina quali stili CSS devono essere applicati al messaggio. I valori supportati sono "error" e "warning". Il valore predefinito è "error". style - Una stringa di stile per il messaggio di errore. Questo stile sostituirà qualsiasi stile applicato al tipo di avviso (opt_options.type). Esempio: 'background-color: #33ff99; padding: 2px;' Il valore predefinito è una stringa vuota. removable - Un valore booleano, dove true significa che il messaggio può essere chiuso con un clic del mouse da parte dell'utente. Il valore predefinito è false.
addErrorFromQueryResponse(container, response)	Valore dell'ID stringa che identifica l'oggetto di errore creato oppure nullo se la risposta non indicava un errore. Si tratta di un valore univoco nella pagina che può essere utilizzato per rimuovere l'errore o trovare l'elemento che la contiene.	Passa una risposta alla query e un contenitore di messaggi di errore a questo metodo: se la risposta alla query indica un errore di query, viene visualizzato un messaggio di errore nell'elemento della pagina specificato. Se la risposta alla query è nulla, il metodo genera un errore JavaScript. Per visualizzare un errore, passa la QueryResponse ricevuta nel gestore di query a questo messaggio. Verrà inoltre impostato lo stile di visualizzazione appropriato al tipo (errore o avviso, simile a addError(opt_options.type)) container - L'elemento DOM in cui inserire il messaggio di errore. Se non è possibile trovare il container, la funzione genera un errore JavaScript. response: un oggetto QueryResponse ricevuto dal tuo gestore di query in risposta a una query. Se nullo, il metodo genera un errore JavaScript.
removeError(id)	Booleano: true se l'errore è stato rimosso; false negli altri casi.	Rimuove l'errore specificato dall'ID dalla pagina. id - L'ID stringa di un errore creato utilizzando addError() o addErrorFromQueryResponse().
removeAll(container)	Nessun valore	Rimuove tutti i blocchi di errori da un container specificato. Se il container specificato non esiste, verrà visualizzato un errore. container - L'elemento DOM che contiene le stringhe di errore da rimuovere. Se non è possibile trovare il container, la funzione genera un errore JavaScript.
getContainer(errorId)	Handle a un elemento DOM che contiene l'errore specificato o nullo se non è stato possibile trovarlo.	Recupera un handle dell'elemento container che contiene l'errore specificato da errorID. errorId - ID stringa di un errore creato utilizzando addError() o addErrorFromQueryResponse().

Eventi

La maggior parte delle visualizzazioni attiva gli eventi per indicare che si è verificato qualcosa. In qualità di utente del grafico, spesso vorrai ascoltare questi eventi. Se codifichi la tua visualizzazione, ti consigliamo anche di attivare questi eventi autonomamente.

I seguenti metodi consentono agli sviluppatori di ascoltare gli eventi, rimuovere i gestori di eventi esistenti o attivare eventi dall'interno di una visualizzazione.

• google.visualization.events.addListener() e google.visualization.events.addOneTimeListener() restano in ascolto degli eventi.
• google.visualization.events.removeListener() rimuove un listener esistente
• google.visualization.events.removeAllListeners() rimuove tutti i listener di un grafico specifico
• google.visualization.events.trigger() attiva un evento.

addListener()

Chiama questo metodo per registrarti e ricevere eventi attivati da una visualizzazione ospitata sulla tua pagina. Devi documentare quali argomenti dell'evento, se presenti, verranno passati alla funzione di gestione.

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

Un handle all'istanza di visualizzazione di origine.

event_name

Il nome della stringa dell'evento da ascoltare. Una visualizzazione deve documentare gli eventi che genera.

handling_function

Il nome della funzione JavaScript locale da chiamare quando source_visualization attiva l'evento event_name. Alla funzione di gestione verranno passati tutti gli argomenti evento come parametri.

Restituisce

Un gestore listener per il nuovo listener. Il gestore può essere utilizzato per rimuovere in seguito questo listener, se necessario, chiamando google.visualization.events.removeListener().

Esempio

Ecco un esempio di registrazione per ricevere l'evento di selezione

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

È identico a addListener(), ma è destinato agli eventi che devono essere ascoltati una sola volta. I lanci successivi dell'evento non richiamano la funzione di gestione.

Ecco un esempio dei casi in cui è utile: ogni estrazione genera un evento ready. Se vuoi che solo il primo ready esegua il codice, ti consigliamo di addOneTimeListener anziché addListener.

removeListener()

Chiama questo metodo per annullare la registrazione di un listener di eventi esistente.

google.visualization.events.removeListener(listener_handler)

listener_handler

Il gestore listener da rimuovere, come restituito da google.visualization.events.addListener().

removeAllListeners()

Chiama questo metodo per annullare la registrazione di tutti i listener di eventi di una specifica istanza di visualizzazione.

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

Un handle all'istanza di visualizzazione di origine da cui devono essere rimossi tutti i listener di eventi.

trigger()

Chiamata dagli implementatori della visualizzazione. Chiama questo metodo dalla tua visualizzazione per attivare un evento con un nome e un insieme di valori arbitrari.

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

Un handle all'istanza di visualizzazione di origine. Se chiami questa funzione da un metodo definito dalla visualizzazione di invio, puoi semplicemente trasmettere la parola chiave this.

event_name

Un nome di stringa per chiamare l'evento. Puoi scegliere qualsiasi valore di stringa che desideri.

event_args

[Facoltativo] Una mappa di coppie nome/valore da passare al metodo di ricezione. Ad esempio: {message: "Ciao!", score: 10, name: "Fred"}. Puoi passare un valore nullo se non sono necessari eventi. Il destinatario deve essere pronto ad accettare un valore nullo per questo parametro.

Esempio

Di seguito è riportato un esempio di visualizzazione che genera un metodo denominato "select" quando viene chiamato il suo metodo Stackdriver. Non restituisce alcun valore.

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
}

Metodi e proprietà di visualizzazione standard

Ogni visualizzazione deve esporre il seguente insieme di metodi e proprietà obbligatori e facoltativi. Tuttavia, tieni presente che non è previsto alcun controllo di tipo per applicare questi standard, quindi ti consigliamo di leggere la documentazione per ogni visualizzazione.

• Costruttore
• disegno()
• getAction() [facoltativo]
• getSelection() [facoltativo]
• removeAction() [facoltativo]
• setAction() [facoltativo]
• setSelection() [facoltativo]

Nota : questi metodi si trovano nello spazio dei nomi della visualizzazione, non nello spazio dei nomi google.visualization.

Costruttore

Il costruttore deve avere il nome della classe di visualizzazione e restituire un'istanza di quella classe.

visualization_class_name(dom_element)

dom_element

Un puntatore a un elemento DOM in cui deve essere incorporata la visualizzazione.

Esempio

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

Traccia la visualizzazione sulla pagina. Dietro le quinte, può essere il recupero di un'immagine da un server o la creazione dell'immagine sulla pagina utilizzando il codice di visualizzazione collegato. Devi chiamare questo metodo ogni volta che i dati o le opzioni cambiano. L'oggetto deve essere disegnato all'interno dell'elemento DOM passato nel costruttore.

draw(data[, options])

dati

Un elemento DataTable o DataView che contiene i dati da utilizzare per disegnare il grafico. Non esiste un metodo standard per estrarre un valore DataTable da un grafico.

opzioni

[Facoltativo] Una mappa di coppie nome/valore di opzioni personalizzate. Alcuni esempi sono altezza e larghezza, colori di sfondo e didascalie. La documentazione relativa alla visualizzazione deve elencare le opzioni disponibili e deve supportare quelle predefinite se non specifichi questo parametro. Puoi utilizzare la sintassi letterale dell'oggetto JavaScript per inserire una mappa delle opzioni: ad es. {x:100, y:200, title:'An Example'}

Esempio

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

È facoltativamente esposto dalle visualizzazioni che hanno descrizioni comando e consentono le azioni delle descrizioni comando.

Restituisce l'oggetto azione descrizione comando con l'oggetto actionID richiesto.

Esempio:

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

Facoltativamente, viene mostrata dalle visualizzazioni che vogliono consentirti di accedere ai dati attualmente selezionati nel grafico.

selection_array getSelection()

Restituisce

selection_array Un array di oggetti selezionati, ognuno dei quali descrive un elemento di dati nella tabella sottostante, utilizzato per creare la visualizzazione (un DataView o un DataTable). Ogni oggetto ha le proprietà row e/o column, con l'indice della riga e/o della colonna dell'elemento selezionato nella DataTable sottostante. Se la proprietà row è null, la selezione è una colonna; se la proprietà column è nulla, la selezione è una riga; se entrambe sono diverse, si tratta di un elemento di dati specifico. Puoi chiamare il metodo DataTable.getValue() per ottenere il valore dell'elemento selezionato. L'array recuperato può essere passato a setSelection().

Esempio

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

È facoltativamente esposto dalle visualizzazioni che hanno descrizioni comando e consentono le azioni delle descrizioni comando.

Rimuove l'oggetto azione descrizione comando con l'oggetto actionID richiesto dal grafico.

Esempio:

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

È facoltativamente esposto dalle visualizzazioni che hanno descrizioni comando e consentono le azioni delle descrizioni comando. Funziona solo per i grafici principali (a barre, a colonne, a linee, ad area, a dispersione, combinato, a bolle, a torta, ad anello, a candele, a istogramma, con area con rientri).

Imposta un'azione della descrizione comando da eseguire quando l'utente fa clic sul testo dell'azione.

setAction(action object)

Il metodo setAction prende un oggetto come parametro di azione. Questo oggetto deve specificare tre proprietà: id: l'ID dell'azione da impostare, text, il testo da visualizzare nella descrizione comando dell'azione, e action, la funzione da eseguire quando un utente fa clic sul testo dell'azione.

Qualsiasi azione della descrizione comando deve essere impostata prima di chiamare il metodo draw() del grafico.

Esempio:

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

Il metodo setAction può anche definire due proprietà aggiuntive: visible e enabled. Queste proprietà devono essere funzioni che restituiscono valori boolean che indicano se l'azione della descrizione comando sarà visibile e/o abilitata.

Esempio:

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

Facoltativamente, seleziona una voce di dati nella visualizzazione, ad esempio un punto in un grafico ad area o una barra in un grafico a barre. Quando questo metodo viene chiamato, la visualizzazione deve indicare visivamente la nuova selezione. L'implementazione di setSelection() non deve attivare un evento "select". Le visualizzazioni potrebbero ignorare parte della selezione. Ad esempio, una tabella che può mostrare solo righe selezionate potrebbe ignorare gli elementi di cella o colonna nell'implementazione di setSelection() oppure può selezionare l'intera riga.

Ogni volta che questo metodo viene chiamato, tutti gli elementi selezionati vengono deselezionati e il nuovo elenco di selezione inviato deve essere applicato. Non esiste un modo esplicito per deselezionare singoli elementi. Per deselezionare singoli elementi, chiama setSelection() con gli elementi per rimanere selezionati; per deselezionare tutti gli elementi, chiama setSelection(), setSelection(null) o setSelection([]).

setSelection(selection_array)

selection_array

Un array di oggetti, ciascuno con una proprietà numerica di riga e/o colonna. row e column sono il numero di riga o colonna in base zero di un elemento nella tabella di dati da selezionare. Per selezionare un'intera colonna, imposta row su null; per selezionare un'intera riga, imposta column su null. Esempio: setSelection([{row:0,column:1},{row:1, column:null}]) seleziona la cella in corrispondenza di (0,1) e l'intera riga 1.

Metodi statici assortiti

Questa sezione contiene vari metodi utili esposti nello spazio dei nomi google.visualization.

arrayToDataTable()

Questo metodo prende una matrice bidimensionale e la converte in una tabella di dati.

I tipi di dati delle colonne vengono determinati automaticamente in base ai dati forniti. I tipi di dati delle colonne possono essere specificati anche utilizzando la notazione letterale oggetto nella prima riga (la riga di intestazione della colonna) dell'array (ad es. {label: 'Start Date', type: 'date'}). È possibile utilizzare anche ruoli dati facoltativi, ma devono essere definiti esplicitamente utilizzando la notazione letterale oggetto. Per qualsiasi cella puoi anche utilizzare la notazione letterale oggetto, in modo da definire oggetti cella.

Sintassi

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

Un array bidimensionale, in cui ogni riga rappresenta una riga nella tabella di dati. Se opt_firstRowIsData è false (valore predefinito), la prima riga verrà interpretata come etichette di intestazione. I tipi di dati di ogni colonna vengono interpretati automaticamente a partire dai dati forniti. Se una cella non ha valori, specifica un valore nullo o vuoto a seconda dei casi.

opt_firstRowIsData

Indica se la prima riga definisce o meno una riga di intestazione. Se true, si presume che tutte le righe siano dati. Se il valore è false, si presume che la prima riga sia una riga di intestazione e i valori vengono assegnati come etichette di colonna. Il valore predefinito è false.

Restituisce

Un nuovo DataTable.

Esempi

Il codice seguente illustra tre modi per creare lo stesso oggetto DataTable:

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

Questo metodo crea un grafico in una singola chiamata. Il vantaggio di utilizzare questo metodo è che richiede leggermente meno codice e consente di serializzare e salvare le visualizzazioni come stringhe di testo da riutilizzare. Questo metodo non restituisce un handle al grafico creato, quindi non puoi assegnare listener del metodo per rilevare gli eventi del grafico.

Sintassi

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

Una stringa letterale JSON o un oggetto JavaScript, con le seguenti proprietà (sensibili alle maiuscole):

Proprietà	Tipo	Obbligatorio	Predefinita	Descrizione
chartType	String	Obbligatorio	Nessuno	Il nome della classe della visualizzazione. Il nome del pacchetto google.visualization può essere omesso per i grafici Google. Se la libreria di visualizzazioni appropriata non è già stata caricata, questo metodo caricherà automaticamente la libreria se si tratta di una visualizzazione Google; devi caricare esplicitamente le visualizzazioni di terze parti. Esempi: Table, PieChart, example.com.CrazyChart.
containerId	String	Obbligatorio	Nessuno	L'ID dell'elemento DOM sulla pagina che ospita la visualizzazione.
opzioni del modello.	Oggetto	Facoltativo	Nessuno	Un oggetto che descrive le opzioni per la visualizzazione. Puoi utilizzare la notazione letterale JavaScript oppure fornire un handle all'oggetto. Esempio: "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	Oggetto	Facoltativo	Nessun valore	Un elemento DataTable utilizzato per popolare la visualizzazione. Può essere una rappresentazione stringa JSON letterale di una tabella di dati, come descritto sopra, un handle per un oggetto google.visualization.DataTable compilato o un array bidimensionale come quello accettato da arrayToDataTable(opt_firstRowIsData=false) . Devi specificare questa proprietà o la proprietà dataSourceUrl.
dataSourceUrl	String	Facoltativo	Nessun valore	Una query sull'origine dati per completare i dati del grafico, ad esempio un foglio di lavoro Google. Devi specificare questa proprietà o la proprietà dataTable.
query	String	Facoltativo	Nessun valore	Se specifichi dataSourceUrl, puoi facoltativamente specificare una stringa di query di tipo SQL utilizzando il Linguaggio di query di visualizzazione per filtrare o manipolare i dati.
refreshInterval	Numero	Facoltativo	Nessun valore	La frequenza, in secondi, che la visualizzazione deve aggiornare l'origine della query. Utilizza questo valore solo quando specifichi dataSourceUrl.
vista	Oggetto OR array	Facoltativo	Nessun valore	Imposta un oggetto inizializzatore DataView, che funge da filtro sui dati sottostanti, come definito dal parametro dataTable o dataSourceUrl. Puoi passare in una stringa o in un oggetto inizializzatore DataView, come quello restituito da dataview.toJSON(). Esempio: "view": {"columns": [1, 2]} puoi anche passare un array di oggetti inizializzatori DataView, nel qual caso il primo DataView dell'array viene applicato ai dati sottostanti per creare una nuova tabella di dati, mentre il secondo DataView viene applicato alla tabella di dati risultante dall'applicazione del primo DataView e così via.

Esempi

Crea un grafico a tabella basato su un'origine dati del foglio di lavoro e include la query SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

L'esempio successivo crea la stessa tabella, ma crea un elemento DataTable localmente:

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

Questo esempio passa in una rappresentazione stringa JSON del grafico, che potresti aver caricato da un file:

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

È il costruttore dell'elemento della barra degli strumenti che può essere collegato a molte visualizzazioni. Questa barra degli strumenti consente all'utente di esportare i dati di visualizzazione in diversi formati o di fornire una versione incorporabile della visualizzazione da utilizzare in luoghi diversi. Consulta la pagina della barra degli strumenti per ulteriori informazioni e un esempio di codice.