Documentation de référence sur l'API Google Visualization

Cette page répertorie les objets exposés par l'API Google Visualization, ainsi que les méthodes standards proposées par toutes les visualisations.

Remarque:L'espace de noms de l'API Google Visualization est google.visualization.*.

Classe DataTable

Représente un tableau de valeurs modifiable et bidimensionnel. Pour créer une copie en lecture seule d'une DataTable (éventuellement filtrée pour afficher des valeurs, des lignes ou des colonnes spécifiques), créez une DataView.

Chaque colonne se voit attribuer un type de données et plusieurs propriétés facultatives, y compris un ID, un libellé et une chaîne de modèle.

De plus, vous pouvez attribuer des propriétés personnalisées (paires nom/valeur) à n'importe quelle cellule, ligne, colonne ou à la table entière. Certaines visualisations prennent en charge des propriétés personnalisées spécifiques. Par exemple, la visualisation du tableau accepte une propriété de cellule appelée "style", qui vous permet d'attribuer une chaîne de style CSS intégrée à la cellule du tableau affiché. Une visualisation doit décrire dans sa documentation toutes les propriétés personnalisées qu'elle prend en charge.

Voir aussi:QueryResponse.getDataTable

Constructeur

Syntaxe

DataTable(opt_data, opt_version)

opt_data

[Facultatif] Données utilisées pour initialiser la table. Il peut s'agir du fichier JSON renvoyé en appelant DataTable.toJSON() sur une table renseignée ou d'un objet JavaScript contenant des données utilisées pour initialiser la table. La structure de l'objet littéral JavaScript est décrite ici. Si ce paramètre n'est pas fourni, une nouvelle table de données vide est renvoyée.

opt_version

[Facultatif] Valeur numérique indiquant la version du protocole filaire utilisé Il n'est utilisé que par les intégrateurs de sources de données des outils de graphique. La version actuelle est 0.6.

Détails

L'objet DataTable permet de stocker les données transmises dans une visualisation. Un élément DataTable est un tableau bidimensionnel de base. Toutes les données de chaque colonne doivent avoir le même type de données. Chaque colonne comporte un descripteur qui inclut son type de données, un libellé pour cette colonne (qui peut être affiché par une visualisation) et un ID qui peut être utilisé pour faire référence à une colonne spécifique (au lieu d'utiliser des index de colonne). L'objet DataTable accepte également un mappage de propriétés arbitraires attribuées à une valeur spécifique, à une ligne, à une colonne ou à l'ensemble de la DataTable. Les visualisations peuvent les utiliser pour prendre en charge des fonctionnalités supplémentaires. Par exemple, la visualisation de table utilise des propriétés personnalisées pour vous permettre d'attribuer des noms de classe ou des styles arbitraires à des cellules individuelles.

Chaque cellule du tableau contient une valeur. Les cellules peuvent avoir une valeur nulle ou une valeur du type spécifié par leur colonne. Les cellules peuvent éventuellement avoir une version "formatée" des données. Il s'agit d'une version de chaîne des données, formatée pour être affichée par une visualisation. Une visualisation peut (mais n'est pas obligatoire) utiliser la version mise en forme pour l'affichage, mais elle utilisera toujours les données elles-mêmes pour tous les tris ou calculs qu'elle effectue (par exemple, pour déterminer où placer un point sur un graphique). Par exemple, vous pouvez attribuer les valeurs "bas", "moyen" et "élevé" aux valeurs numériques des cellules 1, 2 et 3.

Pour ajouter des lignes de données après avoir appelé le constructeur, vous pouvez appeler addRow() pour une seule ligne ou addRows() pour plusieurs lignes. Vous pouvez également ajouter des colonnes en appelant les méthodes addColumn(). Il existe également des méthodes de suppression des lignes et des colonnes, mais au lieu de supprimer des lignes ou des colonnes, envisagez de créer un DataView qui est une vue sélective de DataTable.

Si vous modifiez les valeurs d'un DataTable après l'avoir transmis à la méthode draw() d'une visualisation, les modifications ne modifieront pas immédiatement le graphique. Vous devez rappeler draw() pour refléter les modifications.

Remarque:Google Charts n'effectue aucune validation sur les tables de données. (Si c'était le cas, le rendu des graphiques serait plus lent.) Si vous fournissez un nombre alors que votre colonne attend une chaîne, ou inversement, Google Charts interprétera au mieux la valeur de manière logique, mais ne signalera pas d'erreurs.

L'exemple suivant montre comment instancier et renseigner un DataTable avec une chaîne littérale, avec les mêmes données que dans l'exemple JavaScript ci-dessus:

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'exemple suivant crée un DataTable vide, puis le remplit manuellement avec les mêmes données que ci-dessus:

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

Méthodes

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)"}]}
 ]
}

Format du paramètre de données du littéral JavaScript du constructeur

Vous pouvez initialiser un DataTable en transmettant un objet littéral de chaîne JavaScript au paramètre data. Nous appellerons cet objet l'objet data. Vous pouvez coder cet objet à la main, conformément à la description ci-dessous, ou utiliser une bibliothèque d'aide Python si vous savez utiliser Python et que votre site peut l'utiliser. Toutefois, si vous souhaitez construire l'objet manuellement, vous allez décrire la syntaxe dans cette section.

Voyons d'abord un exemple d'objet JavaScript simple décrivant une table comportant trois lignes et trois colonnes (types "Chaîne", "Nombre" et "Date"):

{
  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!'}
}

Décrivons maintenant la syntaxe:

L'objet data se compose de deux propriétés de niveau supérieur obligatoires, cols et rows, et d'une propriété p facultative qui est un mappage de valeurs arbitraires.

Remarque:Tous les noms de propriétés et les constantes de chaîne affichés sont sensibles à la casse. De plus, la valeur des propriétés décrites comme acceptant une valeur de chaîne doit être placée entre guillemets. Par exemple, si vous souhaitez spécifier que la propriété de type est un nombre, elle serait exprimée comme suit: type: 'number', mais la valeur elle-même, en tant que valeur numérique, serait exprimée comme ceci : v: 42

Propriété cols

cols est un tableau d'objets décrivant l'ID et le type de chaque colonne. Chaque propriété est un objet doté des propriétés suivantes (sensibles à la casse):

• L'attribut type [obligatoire] définit le type des données de la colonne. Accepte les valeurs de chaîne suivantes (les exemples incluent la propriété v: décrite plus loin) :
  • "booléen" : valeur booléenne JavaScript ("true" ou "false"). Exemple de valeur : v:'true'
  • "number" : valeur numérique JavaScript. Exemples de valeurs: v:7, v:3.14, v:-55
  • "string" : valeur de chaîne JavaScript. Exemple de valeur: v:'hello'
  • "date" - Objet Date JavaScript (mois basé sur zéro), avec l'heure tronquée. Exemple de valeur: v:new Date(2008, 0, 15)
  • "datetime" : objet Date JavaScript comprenant l'heure. Exemple de valeur : v:new Date(2008, 0, 15, 14, 30, 45)
  • "timeofday" : tableau composé de trois nombres et d'un quatrième chiffre facultatif, représentant l'heure (0 indique minuit), la minute, la seconde et la milliseconde facultative. Exemples de valeurs : v:[8, 15, 0], v: [6, 12, 1, 144]
• id [Facultatif] ID de chaîne de la colonne. Doit être unique dans la table. Utilisez des caractères alphanumériques de base, afin que la page hôte ne nécessite pas d'échappements sophistiqués pour accéder à la colonne en JavaScript. Veillez à ne pas choisir de mot clé JavaScript. Exemple : id:'col_1'
• label [Facultatif] Valeur de chaîne affichée par certaines visualisations pour cette colonne. Exemple: label:'Height'
• pattern [Facultatif] Modèle de chaîne utilisé par une source de données pour mettre en forme les valeurs de colonne numériques, de date ou d'heure. Ce nom n'est fourni qu'à titre de référence. Vous n'aurez probablement pas besoin de lire le modèle, et il n'est pas nécessaire pour exister. Le client Google Visualisation n'utilise pas cette valeur (il lit la valeur mise en forme de la cellule). Si l'DataTable provient d'une source de données en réponse à une requête avec une clause format, le modèle que vous avez spécifié dans cette clause sera probablement renvoyé dans cette valeur. Les normes de modèle recommandées sont DecimalFormat et SimpleDateFormat de la bibliothèque ICU.
• p [Facultatif] Objet représentant un mappage de valeurs personnalisées appliquées à la cellule. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation prend en charge des propriétés au niveau de la cellule, elles seront décrites. Sinon, cette propriété sera ignorée. Exemple:p:{style: 'border: 1px solid green;'}.

Exemple avec cols

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

Propriété rows

La propriété rows contient un tableau d'objets de ligne.

Chaque objet ligne possède une propriété obligatoire appelée c, qui est un tableau de cellules sur cette ligne. Elle comporte également une propriété p facultative qui définit une carte de valeurs personnalisées arbitraires à attribuer à l'intégralité de la ligne. Si votre visualisation accepte des propriétés au niveau de la ligne, elle les décrira. Sinon, cette propriété sera ignorée.

Objets de cellule

Chaque cellule du tableau est décrite par un objet doté des propriétés suivantes:

• L'attribut v [facultatif] correspond à la valeur de la cellule. Le type de données doit correspondre à celui de la colonne. Si la cellule est nulle, la propriété v doit être nulle, bien qu'elle puisse toujours avoir des propriétés f et p.
• f [Facultatif] Version de chaîne de la valeur v, mise en forme pour être affichée. En règle générale, les valeurs correspondent, mais ce n'est pas obligatoire. Par conséquent, si vous spécifiez Date(2008, 0, 1) pour v, vous devez spécifier "1er janvier 2008" ou une chaîne de ce type pour cette propriété. Cette valeur n'est pas comparée à la valeur v. La visualisation n'utilisera pas cette valeur pour le calcul, mais uniquement comme étiquette à afficher. Si cette valeur est omise, une version de chaîne de v sera automatiquement générée à l'aide de l'outil de mise en forme par défaut. Les valeurs f peuvent être modifiées à l'aide de votre propre outil de mise en forme, définies avec setFormattedValue() ou setCell(), ou récupérées avec getFormattedValue().
• p [Facultatif] Objet représentant un mappage de valeurs personnalisées appliquées à la cellule. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation prend en charge des propriétés au niveau de la cellule, elle les décrira. Ces propriétés peuvent être récupérées par les méthodes getProperty() et getProperties(). Exemple:p:{style: 'border: 1px solid green;'}.

Les cellules du tableau de lignes doivent respecter le même ordre que la description des colonnes dans cols. Pour indiquer une cellule nulle, vous pouvez spécifier null, laisser un champ vide pour une cellule d'un tableau ou omettre les membres de fin du tableau. Ainsi, pour indiquer une ligne avec une valeur nulle pour les deux premières cellules, vous pouvez spécifier [ , , {cell_val}] ou [null, null, {cell_val}].

Voici un exemple d'objet de table comportant trois colonnes et trois lignes de données:

{
  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'}
        ]}
  ]
}

Propriété p

La propriété p au niveau de la table est un mappage de valeurs personnalisées appliquées à l'ensemble de DataTable. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation accepte des propriétés au niveau du tableau de données, elles seront décrites. Sinon, cette propriété pourra être utilisée par l'application. Exemple:p:{className: 'myDataTable'}.

Classe DataView

Vue en lecture seule d'une DataTable sous-jacente. Un DataView ne permet de sélectionner qu'un sous-ensemble de colonnes et/ou de lignes. Elle permet également de réorganiser les colonnes/lignes et de dupliquer des colonnes/lignes.

Une vue est une fenêtre en direct sur le DataTable sous-jacent, et non un instantané statique des données. Toutefois, vous devez faire attention lorsque vous modifiez la structure de la table elle-même, comme décrit ici:

• L'ajout ou la suppression de colonnes dans la table sous-jacente n'est pas reflété par la vue et peut entraîner un comportement inattendu dans la vue. Vous devrez créer un autre élément DataView à partir de DataTable pour récupérer ces modifications.
• Vous pouvez ajouter ou supprimer des lignes de la table sous-jacente sans risque, et les modifications sont immédiatement appliquées à la vue (mais vous devez appeler draw() sur toutes les visualisations après cette modification pour que le nouvel ensemble de lignes soit affiché). Notez que si votre vue a filtré des lignes en appelant l'une des méthodes setRows() or hideRows(), et que vous ajoutez ou supprimez des lignes de la table sous-jacente, le comportement est inattendu. Vous devez créer un autre élément DataView pour refléter la nouvelle table.
• La modification des valeurs des cellules dans les cellules existantes est sans risque. Les modifications sont immédiatement appliquées à DataView (mais vous devez appeler draw() sur toutes les visualisations après cette modification pour que les nouvelles valeurs des cellules soient affichées).

Il est également possible de créer un DataView à partir d'un autre DataView. Notez que chaque fois qu'une table ou une vue sous-jacente est mentionnée, elle fait référence au niveau situé juste en dessous de ce niveau. En d'autres termes, il fait référence à l'objet de données utilisé pour construire cette DataView.

DataView accepte également les colonnes de calcul. Il s'agit de colonnes dont la valeur est calculée à la volée à l'aide d'une fonction que vous fournissez. Ainsi, vous pouvez, par exemple, inclure une colonne correspondant à la somme de deux colonnes précédentes, ou une colonne qui calcule et affiche le trimestre calendaire d'une date à partir d'une autre colonne. Pour en savoir plus, consultez setColumns().

Lorsque vous modifiez une DataView en masquant ou en affichant des lignes ou des colonnes, la visualisation n'est pas affectée tant que vous n'appelez pas à nouveau draw() sur la visualisation.

Vous pouvez combiner DataView.getFilteredRows() avec DataView.setRows() pour créer une DataView avec un sous-ensemble de données intéressant, comme indiqué ci-dessous:

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

Constructeurs

Il existe deux façons de créer une instance DataView:

Constructeur 1

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

data

DataTable ou DataView permettant d'initialiser la vue. Par défaut, la vue contient toutes les colonnes et les lignes de la table ou de la vue de données sous-jacente, dans l'ordre d'origine. Pour masquer ou afficher des lignes ou des colonnes dans cette vue, appelez les méthodes set...() ou hide...() appropriées.

Voir aussi :

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

Constructeur 2

Ce constructeur crée un nouveau DataView en attribuant un DataView sérialisé à un DataTable. Il vous aide à recréer l'DataView que vous avez sérialisée à l'aide de DataView.toJSON().

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

données

L'objet DataTable que vous avez utilisé pour créer le DataView, sur lequel vous avez appelé DataView.toJSON(). Si cette table est différente de la table d'origine, vous obtiendrez des résultats imprévisibles.

viewAsJson

Chaîne JSON renvoyée par DataView.toJSON(). Il s'agit d'une description des lignes à afficher ou à masquer dans le DataTable data.

Méthodes

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

Une classe ChartWrapper permet d'encapsuler votre graphique et de gérer son chargement, son dessin et l'interrogation de sources de données. La classe présente des méthodes pratiques permettant de définir des valeurs sur le graphique et de le dessiner. Cette classe simplifie la lecture à partir d'une source de données, car vous n'avez pas besoin de créer un gestionnaire de rappel de requête. Vous pouvez également l'utiliser pour enregistrer facilement un graphique afin de le réutiliser.

Un autre avantage de l'utilisation de ChartWrapper est que vous pouvez réduire le nombre de chargements de bibliothèques en utilisant le chargement dynamique. De plus, vous n'avez pas besoin de charger explicitement les packages, car ChartWrapper se charge de la recherche et du chargement des packages de graphiques pour vous. Pour en savoir plus, consultez les exemples ci-dessous.

Toutefois, ChartWrapper ne propage actuellement qu'un sous-ensemble d'événements générés par les graphiques : select, ready et error. Les autres événements ne sont pas transmis via l'instance ChartWrapper. Pour obtenir d'autres événements, vous devez appeler getChart() et vous abonner aux événements directement sur le handle du graphique, comme indiqué ci-dessous:

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

Constructeur

ChartWrapper(opt_spec)

opt_spec

[Facultatif] : objet JSON définissant le graphique ou version de chaîne sérialisée de cet objet. Le format de cet objet est présenté dans la documentation de drawChart(). Si aucun paramètre n'est spécifié, vous devez définir toutes les propriétés appropriées à l'aide des méthodes set... exposées par cet objet.

Méthodes

ChartWrapper propose les méthodes supplémentaires suivantes:

Événements

L'objet ChartWrapper génère les événements suivants. Notez que vous devez appeler ChartWrapper.draw() avant qu'un événement ne soit généré.

Exemple

Les deux extraits de code suivants créent un graphique en courbes équivalent. Le premier exemple utilise la notation littérale JSON pour définir le graphique. Le second utilise les méthodes ChartWrapper pour définir ces valeurs.

<!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>

Même graphique, utilisant désormais des méthodes 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>

Classe ChartEditor

La classe ChartEditor permet d'ouvrir une boîte de dialogue sur la page qui permet à un utilisateur de personnaliser une visualisation à la volée.

Pour utiliser ChartEditor:

1. Chargez le package charteditor. Dans google.charts.load(), chargez le package "charteditor". Vous n'avez pas besoin de charger les packages pour le type de graphique que vous affichez dans l'éditeur. L'éditeur de graphiques chargera n'importe quel package si nécessaire.
2. Créez un objet ChartWrapper qui définit le graphique à personnaliser par l'utilisateur. Ce graphique sera affiché dans la boîte de dialogue, et l'utilisateur utilisera l'éditeur pour repenser le graphique, modifier les types de graphique ou même modifier les données sources.
3. Créez une instance ChartEditor et inscrivez-vous pour écouter l'événement "ok". Cet événement est généré lorsque l'utilisateur clique sur le bouton "OK" de la boîte de dialogue. Une fois le graphique reçu, vous devez appeler ChartEditor.getChartWrapper() pour récupérer le graphique modifié par l'utilisateur.
4. Appelez ChartEditor.openDialog() en transmettant ChartWrapper. La boîte de dialogue s'ouvre. Les boutons de la boîte de dialogue permettent à l'utilisateur de fermer l'éditeur. L'instance ChartEditor est disponible tant qu'elle entre dans le champ d'application. Elle n'est pas automatiquement détruite lorsque l'utilisateur ferme la boîte de dialogue.
5. Pour mettre à jour le graphique dans le code, appelez setChartWrapper().

Méthodes

Options

L'éditeur de graphiques prend en charge les options suivantes:

Événements

L'éditeur de graphiques génère les événements suivants:

Exemple

L'exemple de code suivant ouvre une boîte de dialogue d'éditeur de graphiques avec un graphique en courbes rempli. S'il clique sur "OK", le graphique modifié est enregistré dans le <div> spécifié sur la page.

<!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>

Méthodes de manipulation de données

L'espace de noms google.visualization.data contient des méthodes statiques permettant d'effectuer des opérations de type SQL sur des objets DataTable, par exemple les jointures ou les regroupements par valeur de colonne.

L'espace de noms google.visualization.data expose les méthodes suivantes:

group()

Prend un objet DataTable renseigné et effectue une opération GROUP BY de type SQL, renvoyant une table avec des lignes regroupées en fonction des valeurs de colonne spécifiées. Notez que cela ne modifie pas l'entrée DataTable.

La table renvoyée comprend une ligne pour chaque combinaison de valeurs dans les colonnes de clé spécifiées. Chaque ligne comprend les colonnes de clé, plus une colonne avec une valeur de colonne agrégée sur toutes les lignes correspondant à la combinaison de clés (par exemple, une somme ou le nombre de toutes les valeurs de la colonne spécifiée).

L'espace de noms google.visualization.data inclut plusieurs valeurs d'agrégation utiles (par exemple, sum et count), mais vous pouvez définir les vôtres (par exemple, standardDeviation ou secondHighest). Vous trouverez des instructions pour définir votre propre agrégateur après la description de la méthode.

Syntaxe

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

data_table

La valeur DataTable d'entrée. Cela ne sera pas modifié en appelant group().

keys

Tableau de nombres et/ou d'objets spécifiant les colonnes à utiliser pour le regroupement. La table de résultats comprend toutes les colonnes de ce tableau, ainsi que chaque colonne de colonnes. S'il s'agit d'un nombre, il s'agit d'un index de colonne de l'entrée DataTable à utiliser pour le regroupement. S'il s'agit d'un objet, il inclut une fonction pouvant modifier la colonne spécifiée (par exemple, en ajoutant 1 à la valeur de cette colonne). L'objet doit avoir les propriétés suivantes :

• colonne : nombre correspondant à un index de colonne de dt auquel appliquer la transformation.
• modifier : fonction qui accepte une valeur (la valeur de cellule de cette colonne pour chaque ligne) et renvoie la valeur modifiée. Cette fonction permet de modifier la valeur de la colonne afin de faciliter le regroupement: par exemple, en appelant une fonction quiQuarter qui calcule un trimestre à partir d'une colonne de date, afin que l'API puisse regrouper les lignes par trimestre. La valeur calculée s'affiche dans les colonnes de clé de la table renvoyée. Cette fonction peut être déclarée de manière intégrée dans cet objet ou il peut s'agir d'une fonction que vous définissez ailleurs dans votre code (elle doit faire partie du champ d'application de l'appel). L'API fournit une fonction de modificateur simple. Voici des instructions pour créer vos propres fonctions plus utiles. Vous devez connaître le type de données que cette fonction peut accepter, et ne l'appeler que sur des colonnes de ce type. Vous devez également connaître le type renvoyé par cette fonction et le déclarer dans la propriété type décrite ci-après.
• type : type renvoyé par le modificateur de fonction. Il doit s'agir d'un nom de type de chaîne JavaScript, par exemple "number" ou "boolean".
• label : [facultatif] libellé de chaîne à attribuer à cette colonne dans le DataTable renvoyé.
• id : [facultatif] ID de chaîne à attribuer à cette colonne dans la DataTable renvoyée.

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

colonnes

[Facultatif] Permet de spécifier les colonnes, en plus des colonnes de clé, à inclure dans la table de sortie. Étant donné que toutes les lignes du groupe de lignes sont compressées en une seule ligne de sortie, vous devez déterminer la valeur à afficher pour ce groupe de lignes. Par exemple, vous pouvez choisir d'afficher la valeur de colonne de la première ligne de l'ensemble ou la moyenne de toutes les lignes du groupe. columns est un tableau d'objets doté des propriétés suivantes :

• colonne : nombre spécifiant l'index de la colonne à afficher.
• agrégation : fonction qui accepte un tableau de toutes les valeurs de cette colonne dans ce groupe de lignes et renvoie une valeur unique à afficher dans la ligne de résultat. La valeur renvoyée doit être du type spécifié par la propriété type de l'objet. Vous trouverez ci-dessous des informations détaillées sur la création de votre propre fonction d'agrégation. Vous devez connaître les types de données acceptés par cette méthode et ne l'appeler que sur des colonnes du type approprié. L'API fournit plusieurs fonctions d'agrégation utiles. Consultez la section Fonctions d'agrégation fournies ci-dessous pour obtenir la liste complète ou Créer une fonction d'agrégation pour apprendre à écrire votre propre fonction d'agrégation.
• type : type renvoyé par la fonction d'agrégation. Il doit s'agir d'un nom de type de chaîne JavaScript, par exemple "number" ou "boolean".
• label : [facultatif] étiquette de chaîne à appliquer à cette colonne dans la table renvoyée.
• id : [facultatif] ID de chaîne à appliquer à cette colonne dans la table renvoyée.

Valeur renvoyée

Un élément DataTable avec une colonne pour chaque colonne répertoriée dans les clés et une colonne pour chaque colonne répertoriée dans les colonnes. Le tableau est trié par lignes clés, de gauche à droite.

Exemple

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

Fonctions de modificateur fournies

L'API fournit les fonctions de modification suivantes que vous pouvez transmettre aux clés. modifier pour personnaliser le comportement du regroupement.

Fonctions d'agrégation fournies

L'API fournit les fonctions d'agrégation suivantes que vous pouvez transmettre aux colonnes. agrégation.

Créer une fonction de modification

Vous pouvez créer une fonction de modification pour effectuer une transformation simple des valeurs clés avant que la fonction group() ne regroupe vos lignes. Cette fonction prend une seule valeur de cellule, effectue une action sur celle-ci (par exemple, ajoute 1 à la valeur) et la renvoie. Les types d'entrée et de retour ne doivent pas nécessairement être du même type, mais l'appelant doit connaître les types d'entrée et de sortie. Voici un exemple de fonction qui accepte une date et renvoie le trimestre:

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

Créer une fonction d'agrégation

Vous pouvez créer une fonction d'agrégation qui accepte un ensemble de valeurs de colonne dans un groupe de lignes et renvoie un seul nombre, par exemple un nombre ou une moyenne de valeurs. Voici une implémentation de la fonction d'agrégation "count" fournie, qui renvoie le nombre de lignes présentes dans le groupe de lignes:

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

join()

Cette méthode joint deux tables de données (objets DataTable ou DataView) en une seule table de résultats, comme une instruction SQL JOIN. Vous spécifiez une ou plusieurs paires de colonnes (colonnes clé) entre les deux tables. La table de sortie inclut les lignes selon une méthode de jointure que vous spécifiez: uniquement les lignes où les deux clés correspondent, toutes les lignes d'une table ou toutes les lignes des deux tables, que les clés correspondent ou non. La table des résultats ne comprend que les colonnes de clé, ainsi que les colonnes supplémentaires que vous spécifiez. Notez que dt2 ne peut pas avoir de clés en double, contrairement à dt1. Le terme "clé" désigne la combinaison de toutes les valeurs de colonne de clé, et non d'une valeur spécifique de colonne de clé. Par conséquent, si une ligne comporte les valeurs de cellule A | B | C, et que les colonnes 0 et 1 sont des colonnes de clé, la clé de cette ligne est AB.

Syntaxe

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

dt1

DataTable renseigné à joindre à dt2.

dt2

Valeur DataTable renseignée à joindre à dt1. Cette table ne peut pas avoir plusieurs clés identiques (lorsqu'une clé correspond à une combinaison de valeurs de colonnes de clé).

joinMethod

Chaîne spécifiant le type de jointure. Si la table dt1 comporte plusieurs lignes qui correspondent à une ligne dt2, la table de sortie inclura toutes les lignes dt1 correspondantes. Choisissez l'une des valeurs suivantes :

• "full" : la table de sortie inclut toutes les lignes des deux tables, que les clés correspondent ou non. Les lignes sans correspondance auront des entrées de cellule nulles ; les lignes correspondantes sont jointes.
• "inner" : jointure complète filtrée pour n'inclure que les lignes où les clés correspondent.
• "left" : la table de sortie inclut toutes les lignes de dt1, qu'il existe ou non des lignes correspondantes de dt2.
• À droite : la table de sortie inclut toutes les lignes de dt2, qu'il existe ou non des lignes correspondantes de dt1.

keys

Tableau de colonnes de clé à comparer à partir des deux tables. Chaque paire est un tableau à deux éléments, la première est une clé dans dt1 et la seconde est une clé dans dt2. Ce tableau peut spécifier des colonnes par leur index, leur ID ou leur étiquette (voir getColumnIndex).
Les colonnes doivent être du même type dans les deux tableaux. Toutes les clés spécifiées doivent correspondre conformément à la règle donnée par joinMethod pour inclure une ligne de la table. Les colonnes de clé sont toujours incluses dans la table de sortie. Seul le tableau de gauche dt1 peut inclure des clés en double. Les clés de dt2 doivent être uniques. Ici, le terme "clé" désigne un ensemble unique de colonnes de clé, et non des valeurs de colonnes individuelles. Par exemple, si vos colonnes de clé étaient A et B, la table suivante ne comporterait que des valeurs de clé uniques (et pourrait donc être utilisée en tant que dt2):

A	B
Jennifer	Rouge
Jennifer	Bleu
Fred	Rouge

Exemple:[[0,0], [2,1]] compare les valeurs de la première colonne dans les deux tables, ainsi que de la troisième colonne de dt1 à la deuxième colonne de dt1.

dt1Columns

Tableau de colonnes de dt1 à inclure dans la table de sortie, en plus des colonnes de clé de dt1. Ce tableau peut spécifier des colonnes en fonction de leur index, leur ID ou leur étiquette (voir getColumnIndex).

dt2Columns

Tableau de colonnes de dt2 à inclure dans la table de sortie, en plus des colonnes de clé de dt2. Ce tableau peut spécifier des colonnes en fonction de leur index, leur ID ou leur étiquette (voir getColumnIndex).

Valeur renvoyée

Un objet DataTable avec les colonnes clés, dt1Columns et dt2Columns, Cette table est triée en fonction des colonnes clés, de gauche à droite. Lorsque joinMethod est définie sur "inner", toutes les cellules de clé doivent être renseignées. Pour les autres méthodes de jointure, si aucune clé correspondante n'est trouvée, la table présentera une valeur nulle pour toutes les cellules de clé sans correspondance.

Exemples

*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

Outils de mise en forme

L'API Google Visualisation fournit des outils de mise en forme qui peuvent être utilisés pour reformater les données d'une visualisation. Ces outils de mise en forme modifient la valeur mise en forme de la colonne spécifiée dans toutes les lignes. Remarques :

• Les outils de mise en forme ne modifient que les valeurs mises en forme, et non les valeurs sous-jacentes. Par exemple, la valeur affichée serait "1 000,00 $", mais la valeur sous-jacente serait toujours "1 000".
• Les outils de mise en forme n'affectent qu'une colonne à la fois. Pour reformater plusieurs colonnes, appliquez-en un à chaque colonne que vous souhaitez modifier.
• Si vous utilisez également des outils de mise en forme définis par l'utilisateur, certains d'entre eux remplaceront tous ceux définis par l'utilisateur.

La mise en forme réelle appliquée aux données est déterminée par les paramètres régionaux avec lesquels l'API a été chargée. Pour en savoir plus, consultez Charger des graphiques avec des paramètres régionaux spécifiques .

Important: Les outils de mise en forme ne peuvent être utilisés qu'avec un élément DataTable. Ils ne peuvent pas être utilisés avec un élément DataView (les objets DataView sont en lecture seule).

Voici les étapes générales à suivre pour utiliser un outil de mise en forme:

1. Récupérez l'objet DataTable renseigné.
2. Pour chaque colonne que vous souhaitez reformater :
   1. Créez un objet qui spécifie toutes les options de votre outil de mise en forme. Il s'agit d'un objet JavaScript de base doté d'un ensemble de propriétés et de valeurs. Consultez la documentation de votre outil de mise en forme pour connaître les propriétés compatibles. (Si vous le souhaitez, vous pouvez transmettre un objet de notation littérale d'objet en spécifiant vos options.)
   2. Créez votre outil de mise en forme en transmettant l'objet options.
   3. Appelez formatter.format(table, colIndex), en transmettant le DataTable et le numéro de colonne (basé sur zéro) des données à reformater. Notez que vous ne pouvez appliquer qu'un seul outil de mise en forme à chaque colonne. L'application d'un deuxième outil de mise en forme écrasera simplement les effets du premier.
      Important:De nombreux outils de mise en forme nécessitent des balises HTML pour afficher une mise en forme spéciale. Si votre visualisation accepte une option allowHtml, vous devez la définir sur "true".

Voici un exemple de modification des valeurs de date mises en forme d'une colonne de date pour utiliser un format de date long ("1er janvier 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 plupart des outils de mise en forme proposent les deux méthodes suivantes:

Méthode	Description
google.visualization.formatter_name(options)	Constructeur, où formatter_name est un nom de classe de mise en forme spécifique. options : objet JavaScript générique qui spécifie les options de cet outil de mise en forme. Cet objet est un objet générique avec des paires propriété/valeur avec des propriétés spécifiques à cet outil de mise en forme. Consultez la documentation de votre outil de mise en forme pour connaître les options compatibles. Voici deux exemples de méthodes pour appeler le constructeur de l'objet DateFormat, en transmettant deux propriétés: // 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)	Reformate les données dans la colonne spécifiée. data : DataTable contenant les données à reformater. Vous ne pouvez pas utiliser de DataView ici. colIndex : index basé sur zéro de la colonne à mettre en forme. Pour mettre en forme plusieurs colonnes, vous devez appeler cette méthode plusieurs fois, avec différentes valeurs colIndex.

 

L'API Google Visualization fournit les outils de mise en forme suivants:

Nom de l'outil de mise en forme	Description
ArrowFormat	Ajoute une flèche vers le haut ou vers le bas, indiquant si la valeur de la cellule est supérieure ou inférieure à une valeur spécifiée.
BarFormat	Ajoute une barre colorée, dont la direction et la couleur indiquent si la valeur de la cellule est supérieure ou inférieure à une valeur spécifiée.
ColorFormat	Colore une cellule selon que les valeurs se situent ou non dans une plage spécifiée.
DateFormat	Met en forme une valeur Date ou DateTime de différentes manières, y compris "1er janvier 2009", "01/01/09" et "1er janvier 2009".
NumberFormat	Met en forme divers aspects des valeurs numériques.
PatternFormat	Concatène les valeurs de cellule d'une même ligne dans une cellule spécifiée, ainsi que du texte arbitraire.

ArrowFormat

Ajoute une flèche vers le haut ou vers le bas à une cellule numérique, selon que la valeur est supérieure ou inférieure à une valeur de base spécifiée. Si elle est égale à la valeur de base, aucune flèche ne s'affiche.

Options

ArrowFormat accepte les options suivantes, transmises au constructeur:

Option	Description
base	Nombre indiquant la valeur de base, utilisé pour comparer à la valeur de la cellule. Si la valeur de la cellule est supérieure, elle comporte une flèche verte vers le haut. Si la valeur de la cellule est inférieure, une flèche rouge vers le bas s'affiche. S'il s'agit de la même valeur, aucune flèche ne s'affiche.

Exemple de code

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

Ajoute une barre colorée à une cellule numérique pour indiquer si la valeur de la cellule est supérieure ou inférieure à une valeur de base spécifiée.

Options

BarFormat accepte les options suivantes, transmises au constructeur:

Option	Exemple Description
base	Nombre qui est la valeur de base à laquelle comparer la valeur de la cellule. Si la valeur de la cellule est plus élevée, elle est dessinée à droite de la base. Si elle est inférieure, elle est dessinée à gauche. La valeur par défaut est 0.
colorNegative	Chaîne indiquant la section des valeurs négatives des barres. Les valeurs possibles sont "rouge", "vert" et "bleu". La valeur par défaut est "rouge".
colorPositive	Chaîne indiquant la couleur de la section des valeurs positives des barres. Les valeurs possibles sont "red", "green" et "blue". La valeur par défaut est "blue".
drawZeroLine	Booléen indiquant s'il faut tracer une ligne de base sombre d'un pixel en présence de valeurs négatives. La ligne sombre permet d'améliorer le balayage visuel des barres. La valeur par défaut est "false".
max	Valeur numérique maximale de la plage de barres. La valeur par défaut est la valeur la plus élevée du tableau.
min	Valeur numérique minimale de la plage de barres. La valeur par défaut est la valeur la plus faible du tableau.
showValue	Si la valeur est "true", les valeurs et les barres sont affichées. Si la valeur est "false", seules les barres sont affichées. La valeur par défaut est "true" (vrai).
width	Épaisseur de chaque barre, en pixels. La valeur par défaut est 100.

Exemple de code

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

Attribue des couleurs au premier plan ou à l'arrière-plan d'une cellule numérique, en fonction de la valeur de la cellule. Cet outil de mise en forme est inhabituel, car il ne prend pas ses options dans le constructeur. Appelez plutôt addRange() ou addGradientRange() autant de fois que vous le souhaitez pour ajouter des plages de couleurs avant d'appeler format(). Les couleurs peuvent être spécifiées dans n'importe quel format HTML accepté, par exemple "noir", "#000000" ou "#000".

Méthodes

ColorFormat accepte les méthodes suivantes:

Méthode	Description
google.visualization.ColorFormat()	Constructeur. N'accepte aucun argument.
addRange(from, to, color, bgcolor)	Spécifie une couleur de premier plan et/ou d'arrière-plan pour une cellule, en fonction de la valeur de la cellule. Les cellules dont la valeur se situe dans la plage from – to seront attribuées à color et bgcolor. Il est important de comprendre que la plage n'est pas inclusive, car créer une plage de 1 à 1 000 et une seconde de 1 000 à 2 000 ne couvrira pas la valeur 1 000. from - [String, Number, Date, DateTime or TimeOfDay] Limite inférieure (incluse) de la plage, ou valeur nulle. Si la valeur est nulle, la correspondance est -∞. Les limites de chaîne sont comparées par ordre alphabétique aux valeurs de chaîne. to - [String, Number, Date, DateTime or TimeOfDay] Limite supérieure (non inclusive) de la plage, ou valeur nulle. Si la valeur est nulle, elle correspond à +∞. Les limites de chaîne sont comparées par ordre alphabétique aux valeurs de chaîne. couleur : couleur à appliquer au texte des cellules correspondantes. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (exemple: "#FF0000" ou "rouge"). bgcolor : couleur à appliquer à l'arrière-plan des cellules correspondantes. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (exemple: "#FF0000" ou "rouge").
addGradientRange(from, to, color, fromBgColor, toBgColor)	Attribue une couleur d'arrière-plan à partir d'une plage en fonction de la valeur de la cellule. La couleur est mise à l'échelle pour correspondre à la valeur de la cellule dans une plage allant de la couleur de la limite inférieure à la couleur de la limite supérieure. Notez que cette méthode ne peut pas comparer les valeurs de chaîne, contrairement à addRange(). Conseil: Les plages de couleurs sont souvent difficiles à évaluer pour les utilisateurs. La plage la plus simple et la plus facile à lire est d'une couleur entièrement saturée au blanc (par exemple, #FF0000–FFFFFF). from - [Number, Date, DateTime or TimeOfDay] Limite inférieure (incluse) de la plage, ou valeur nulle. Si la valeur est nulle, elle correspondra à -∞. to - [Number, Date, DateTime, or TimeOfDay] Limite supérieure (non inclusive) de la plage, ou valeur nulle. Si la valeur est nulle, elle correspondra à +∞. couleur : couleur à appliquer au texte des cellules correspondantes. Cette couleur est la même pour toutes les cellules, quelle que soit leur valeur. fromBgColor : couleur d'arrière-plan des cellules contenant des valeurs dans la partie inférieure du dégradé. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (exemple : "#FF0000" ou "rouge"). toBgColor : couleur d'arrière-plan des cellules contenant des valeurs dans la limite supérieure du dégradé. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (exemple : "#FF0000" ou "rouge").
format(dataTable, columnIndex)	La méthode format() standard pour appliquer une mise en forme à la colonne spécifiée.

Exemple de code

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

Met en forme une valeur Date JavaScript de différentes manières, y compris "1er janvier 2016", "1/1/16" et "1er janvier 2016".

Options

DateFormat accepte les options suivantes, transmises au constructeur:

Option	Description
formatType	Option de mise en forme rapide pour la date. Les valeurs de chaîne suivantes sont acceptées, en reformatant la date du 28 février 2016, comme indiqué: "short" : format court (par exemple, "28/02/16" "medium" : format moyen : par exemple, "28 févr. 2016" "long" : format long (par exemple, "28 février 2016" Vous ne pouvez pas spécifier à la fois formatType et pattern.
pattern	Modèle de format personnalisé à appliquer à la valeur, semblable au format de date et d'heure de l'ICU. Par exemple : var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); Vous ne pouvez pas spécifier à la fois formatType et pattern. Vous pouvez obtenir plus d'informations sur les modèles dans la section suivante.
timeZone	Fuseau horaire dans lequel afficher la valeur de date. Il s'agit d'une valeur numérique indiquant GMT + ce nombre de fuseaux horaires (elle peut être négative). Les objets Date sont créés par défaut avec le fuseau horaire supposé de l'ordinateur sur lequel ils sont créés. Cette option permet d'afficher cette valeur dans un fuseau horaire différent. Par exemple, si vous avez créé un objet "Date" à 17h00 sur un ordinateur situé à Greenwich, en Angleterre, et que vous avez spécifié la valeur "-5" (options['timeZone'] = -5, heure du Pacifique Est aux États-Unis), la valeur affichée est 12 midi.

Méthodes

DateFormat accepte les méthodes suivantes:

Méthode	Description
google.visualization.DateFormat(options)	Constructeur. Pour en savoir plus, consultez la section "Options" ci-dessus.
format(dataTable, columnIndex)	La méthode format() standard pour appliquer une mise en forme à la colonne spécifiée.
formatValue(value)	Renvoie la valeur formatée d'une valeur donnée. Cette méthode ne nécessite pas de DataTable.

Exemple de code

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

En savoir plus sur les formats de date

Voici quelques informations supplémentaires sur les formats pris en charge:

Les modèles sont semblables au format de date et d'heure de l'ICU, mais les schémas suivants ne sont pas encore acceptés: A e D F g Y u w W. Pour éviter toute collision avec des motifs, tout texte littéral que vous souhaitez voir apparaître dans la sortie doit être entouré de guillemets simples, à l'exception du guillemet simple qui doit être doublé: par exemple, "K 'o''clock.'".

Schéma	Description	Exemple de résultat
GG	de l'ère.	"ANNONCE"
yy ou yyyy	année.	1996
Lu	Mois de l'année Pour janvier: M produit 1 MM produit 01 MMM : produit en janvier Date du MMMM : janvier	"Juillet" "07"
d	Jour du mois. Les valeurs « d » supplémentaires ajouteront des zéros au début.	10
h	Heure au format 12 heures. Les valeurs "h" supplémentaires ajouteront des zéros au début.	12
H	Heure au format 24 heures. Les valeurs Hk supplémentaires ajoutent des zéros au début.	0
m	Il s'agit d'une minute dans une heure. Les valeurs « M » supplémentaires ajouteront des zéros au début.	30
s	Seconde dans une minute. Les valeurs "s" supplémentaires ajouteront des zéros au début.	55
S	Il s'agit d'une fraction de seconde. Les valeurs "S" supplémentaires seront complétées par des zéros sur la droite.	978
E	Jour de la semaine. Résultats suivants pour "Tuesday": E produit T EE ou EEE Produce Mar ou Mar EEEE Produces Tuesday	"mars" "Mardi"
aa	AM/PM	"PM"
k	Heure dans une journée (1~24). Les valeurs 'k' supplémentaires ajouteront des zéros au début.	24
K	Heure au format AM/PM (0~11). Les valeurs 'k' supplémentaires ajouteront des zéros au début.	0
z	Fuseau horaire. Pour le fuseau horaire 5, génère "UTC+5".	UTC+5
Z	Fuseau horaire au format RFC 822. Pour le fuseau horaire -5: Z, ZZ, ZZZ product -0500 ZZZZ et d'autres produisent « GMT -05:00 »	"-0800" "GMT -05:00"
v	Fuseau horaire (générique).	"Etc/GMT-5"
'	Échap pour le texte	"Date="
"	guillemet simple	''yy

NumberFormat

Décrit la mise en forme des colonnes numériques. Les options de mise en forme incluent la spécification d'un symbole de préfixe (tel qu'un signe dollar) ou d'un signe de ponctuation à utiliser comme repère des milliers.

Options

NumberFormat accepte les options suivantes, transmises au constructeur:

Option	Description
decimalSymbol	Caractère à utiliser comme repère décimal. La valeur par défaut est un point (.).
fractionDigits	Nombre spécifiant le nombre de chiffres à afficher après la virgule. La valeur par défaut est 2. Si vous spécifiez plus de chiffres, des zéros s'affichent pour les valeurs inférieures. Les valeurs tronquées sont arrondies (cinq arrondies au chiffre supérieur).
groupingSymbol	Caractère à utiliser pour regrouper les chiffres à gauche de la virgule en ensembles de trois. La valeur par défaut est la virgule (,).
negativeColor	Couleur du texte pour les valeurs négatives. Aucune valeur par défaut. Les valeurs peuvent être n'importe quelle valeur de couleur HTML acceptable, telle que "rouge" ou "#FF0000".
negativeParens	Valeur booléenne, où "true" indique que les valeurs négatives doivent être entourées de parenthèses. La valeur par défaut est "true".
pattern	Chaîne de format. Lorsqu'elle est fournie, toutes les autres options sont ignorées, à l'exception de negativeColor. La chaîne de format est un sous-ensemble de l' ensemble de modèles ICU . Par exemple, {pattern:'#,###%'} renvoie les valeurs de sortie "1 000%", "750%" et "50%" pour les valeurs 10, 7,5 et 0,5.
prefix	Préfixe de chaîne pour la valeur, par exemple "$".
suffix	Suffixe de chaîne de la valeur, par exemple "%".

Méthodes

NumberFormat accepte les méthodes suivantes:

Méthode	Description
google.visualization.NumberFormat(options)	Constructeur. Pour en savoir plus, consultez la section "Options" ci-dessus.
format(dataTable, columnIndex)	La méthode format() standard pour appliquer une mise en forme à la colonne spécifiée.
formatValue(value)	Renvoie la valeur formatée d'une valeur donnée. Cette méthode ne nécessite pas de DataTable.

Exemple de code

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

Vous permet de fusionner les valeurs de colonnes désignées dans une seule colonne, avec du texte arbitraire. Ainsi, si vous avez une colonne pour le prénom et une colonne pour le nom de famille, vous pouvez remplir une troisième colonne avec {last name}, {first name}. Cet outil de mise en forme ne respecte pas les conventions du constructeur et de la méthode format(). Pour obtenir des instructions, consultez la section "Méthodes" ci-dessous.

Méthodes

PatternFormat accepte les méthodes suivantes:

Méthode	Description
google.visualization.PatternFormat(pattern)	Constructeur. Ne prend pas d'objet d'options. À la place, il utilise un paramètre de chaîne pattern. Il s'agit d'une chaîne qui décrit les valeurs de colonne à mettre dans la colonne de destination, ainsi que tout texte arbitraire. Intégrez des espaces réservés dans votre chaîne pour indiquer la valeur d'une autre colonne à intégrer. Les espaces réservés sont {#}, où # est l'index d'une colonne source à utiliser. L'indice est un indice dans le tableau srcColumnIndices de la méthode format() ci-dessous. Pour inclure un caractère littéral { ou }, échappez-le comme suit : {7} ou \}. Pour inclure un caractère \ littéral, échappez-le comme suit : \\. Exemple de code L'exemple suivant illustre un constructeur pour un modèle qui crée un élément d'ancrage, les premier et deuxième éléments étant issus de la méthode format(): var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	Appel de mise en forme standard, avec quelques paramètres supplémentaires: dataTable : table de données sur laquelle effectuer l'opération. srcColumnIndices : tableau d'un ou de plusieurs index de colonne (basés sur zéro) à extraire en tant que sources du DataTable sous-jacent. Elle sera utilisée comme source de données pour le paramètre pattern dans le constructeur. Les numéros de colonne n'ont pas besoin d'être triés dans l'ordre. opt_dstColumnIndex : [facultatif] colonne de destination dans laquelle placer la sortie de la manipulation pattern. S'il n'est pas spécifié, le premier élément de srcColumIndices sera utilisé comme destination. Consultez les exemples de mise en forme après le tableau.

Voici quelques exemples d'entrées et de sorties pour une table à quatre colonnes.

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

Exemple de code

L'exemple suivant montre comment combiner les données de deux colonnes pour créer une adresse e-mail. Elle utilise un objet DataView pour masquer les colonnes sources d'origine:

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

Une classe d'assistance pour simplifier l'écriture de widgets utilisant l'API de visualisation Google.

Constructeur

google.visualization.GadgetHelper()

Méthodes

Méthode	Valeur renvoyée	Description
createQueryFromPrefs(prefs)	google.visualization.Query	Statique. Créez une instance de google.visualization.Query et définissez ses propriétés en fonction des valeurs des préférences du gadget. Le type de paramètre prefs est _IG_Prefs. La préférence _table_query_url est utilisée pour définir l'URL de la source de données de la requête. La préférence _table_query_refresh_interval permet de définir l'intervalle d'actualisation des requêtes (en secondes).
validateResponse(response)	Booléen	Statique. Le paramètre response est de type google.visualization.QueryResponse. Renvoie true si la réponse contient des données. Renvoie false si l'exécution de la requête a échoué et que la réponse ne contient aucune donnée. Si une erreur s'est produite, cette méthode affiche un message d'erreur.

Classes de requête

Les objets suivants sont disponibles pour envoyer des requêtes de données à une source de données externe, telle que des feuilles de calcul Google.

• Requête : encapsule la requête de données sortante.
• QueryResponse : gère la réponse de la source de données.

Requête

Représente une requête envoyée à une source de données.

Constructeur

google.visualization.Query(dataSourceUrl, opt_options)

Paramètres

dataSourceUrl

[Obligatoire, String] URL à laquelle envoyer la requête. Consultez la documentation sur les graphiques et les feuilles de calcul pour les feuilles de calcul Google.

opt_options

[Facultatif, objet] Mappage des options pour la requête. Remarque : Si vous accédez à une source de données restreinte , n'utilisez pas ce paramètre. Voici les propriétés acceptées :

• sendMethod : [facultatif, chaîne] spécifie la méthode à utiliser pour envoyer la requête. Choisissez l'une des valeurs de chaîne suivantes :
  • 'xhr' : envoyez la requête à l'aide de XmlHttpRequest.
  • scriptInjection : envoie la requête par injection de script.
  • 'makeRequest' - [Disponible uniquement pour les gadgets, qui sont obsolètes] Envoyez la requête à l'aide de la méthode makeRequest() de l'API Gadget. Vous devez également spécifier makeRequestParams, le cas échéant.
  • 'auto' : utilise la méthode spécifiée par le paramètre d'URL tqrt de l'URL de la source de données. tqrt peut avoir les valeurs suivantes : "xhr", "scriptInjection" ou "makeRequest". Si tqrt est manquant ou comporte une valeur non valide, la valeur par défaut est "xhr" pour les requêtes sur le même domaine et "scriptInjection" pour les requêtes interdomaines.
• makeRequestParams - [Objet] Mappage des paramètres d'une requête makeRequest(). Utilisé et obligatoire uniquement si sendMethod est défini sur "makeRequest".

Méthodes

Méthode	Valeur renvoyée	Description
abort()	Aucun	Arrête l'envoi de la requête automatique démarré par setRefreshInterval().
setRefreshInterval(seconds)	Aucun	Définit la requête pour appeler automatiquement la méthode send chaque durée spécifiée (en secondes), à partir du premier appel explicite à send. seconds est un nombre supérieur ou égal à zéro. Si vous utilisez cette méthode, vous devez l'appeler avant d'appeler la méthode send. Annulez cette méthode en l'appelant à nouveau avec zéro (valeur par défaut) ou en appelant abort().
setTimeout(seconds)	Aucun	Définit le délai d'attente (en secondes) avant que la source de données ne génère une erreur de délai avant expiration. seconds est un nombre supérieur à zéro. Le délai avant expiration par défaut est de 30 secondes. Si elle est utilisée, elle doit être appelée avant la méthode send.
setQuery(string)	Aucun	Définit la chaîne de requête. La valeur du paramètre string doit être une requête valide. Si elle est utilisée, elle doit être appelée avant la méthode send. En savoir plus sur le langage de requête
send(callback)	Aucun	Envoie la requête à la source de données. callback doit être une fonction qui sera appelée lorsque la source de données répond. La fonction de rappel ne recevra qu'un seul paramètre de type google.visualization.QueryResponse.

QueryResponse

Représente une réponse d'exécution d'une requête telle qu'elle est reçue de la source de données. Une instance de cette classe est transmise en tant qu'argument à la fonction de rappel définie lors de l'appel de Query.send.

Méthodes

Méthode	Valeur renvoyée	Description
getDataTable()	DataTable	Renvoie la table de données telle que renvoyée par la source de données. Renvoie null si l'exécution de la requête a échoué et qu'aucune donnée n'a été renvoyée.
getDetailedMessage()	Chaîne	Renvoie un message d'erreur détaillé pour les requêtes qui ont échoué. Si l'exécution de la requête aboutit, cette méthode renvoie une chaîne vide. Le message renvoyé est destiné aux développeurs et peut contenir des informations techniques, par exemple "Column {salary} does not exist".
getMessage()	Chaîne	Renvoie un court message d'erreur pour les requêtes qui ont échoué. Si l'exécution de la requête a réussi, cette méthode renvoie une chaîne vide. Le message renvoyé est un court message destiné aux utilisateurs finaux, par exemple "Requête non valide" ou "Accès refusé".
getReasons()	Tableau de chaînes	Renvoie un tableau contenant zéro ou plusieurs entrées. Chaque entrée est une chaîne courte contenant un code d'erreur ou d'avertissement généré lors de l'exécution de la requête. Codes possibles : access_denied : l'utilisateur n'est pas autorisé à accéder à la source de données. invalid_query La requête spécifiée contient une erreur de syntaxe. data_truncated Une ou plusieurs lignes de données correspondant à la sélection de la requête n'ont pas été renvoyées en raison des limites de taille de sortie. (avertissement). timeout La requête n'a pas répondu dans le délai prévu.
hasWarning()	Booléen	Renvoie true si l'exécution de la requête comporte des messages d'avertissement.
isError()	Booléen	Renvoie true si l'exécution de la requête a échoué et que la réponse ne contient aucune table de données. Renvoie <false> si l'exécution de la requête a réussi et que la réponse contient une table de données.

Affichage des erreurs

L'API fournit plusieurs fonctions pour vous aider à afficher des messages d'erreur personnalisés pour vos utilisateurs. Pour utiliser ces fonctions, fournissez un élément de conteneur sur la page (généralement un <div>), dans lequel l'API générera un message d'erreur mis en forme. Ce conteneur peut être soit l'élément de conteneur de visualisation, soit un conteneur réservé aux erreurs. Si vous spécifiez l'élément "containse" de la visualisation, le message d'erreur s'affiche au-dessus de la visualisation. Appelez ensuite la fonction appropriée ci-dessous pour afficher ou supprimer le message d'erreur.

Toutes les fonctions sont statiques dans l'espace de noms google.visualization.errors.

De nombreuses visualisations peuvent générer un événement d'erreur. Consultez l'événement d'erreur ci-dessous pour en savoir plus à ce sujet.

Vous trouverez un exemple d'erreur personnalisée dans la section Exemple de wrapper de requête.

Fonction	Valeur renvoyée	Description
addError(container, message, opt_detailedMessage, opt_options)	Identifiant de chaîne qui identifie l'objet d'erreur créé. Cette valeur unique sur la page peut être utilisée pour supprimer l'erreur ou trouver l'élément conteneur.	Ajoute un bloc d'affichage des erreurs à l'élément de page spécifié, avec le texte et la mise en forme spécifiés. conteneur : élément DOM dans lequel insérer le message d'erreur. Si le conteneur est introuvable, la fonction génère une erreur JavaScript. message : message de chaîne à afficher. opt_detailedMessage : chaîne de message détaillée facultative. Par défaut, il s'agit d'un texte survolé avec la souris, mais vous pouvez modifier la propriété opt_options.showInToolTip décrite ci-dessous. opt_options : objet facultatif avec des propriétés qui définissent différentes options d'affichage du message. Les options suivantes sont acceptées : showInTooltip : valeur booléenne où "true" n'affiche le message détaillé que sous forme de texte d'info-bulle et "false" affiche le message détaillé dans le corps du conteneur, après le message court. La valeur par défaut est "true" (vrai). type : chaîne décrivant le type d'erreur, qui détermine les styles CSS à appliquer à ce message. Les valeurs acceptées sont "error" et "warning". La valeur par défaut est "error". style : chaîne de style du message d'erreur. Ce style remplace les styles appliqués au type d'avertissement (opt_options.type). Exemple : La valeur par défaut 'background-color: #33ff99; padding: 2px;' est une chaîne vide. removable : valeur booléenne, où "true" signifie que le message peut être fermé par un clic de la souris de l'utilisateur. La valeur par défaut est Faux (false).
addErrorFromQueryResponse(container, response)	Valeur d'ID de chaîne qui identifie l'objet d'erreur créé, ou valeur "null" si la réponse n'indique pas d'erreur. Cette valeur unique sur la page peut être utilisée pour supprimer l'erreur ou trouver l'élément conteneur.	Transmettez à cette méthode une réponse à la requête et un conteneur de message d'erreur: si la réponse à la requête indique une erreur de requête, un message d'erreur s'affiche dans l'élément de page spécifié. Si la réponse à la requête est nulle, la méthode génère une erreur JavaScript. Transmettez à ce message la réponse QueryResponse reçue dans votre gestionnaire de requêtes pour afficher une erreur. Elle définit également le style d'affichage adapté au type (erreur ou avertissement, semblable à addError(opt_options.type)). conteneur : élément DOM dans lequel insérer le message d'erreur. Si le conteneur est introuvable, la fonction génère une erreur JavaScript. response : un objet QueryResponse reçu par votre gestionnaire de requêtes en réponse à une requête. Si la valeur est nulle, la méthode renverra une erreur JavaScript.
removeError(id)	Booléen : "true" si l'erreur a été supprimée, "false" dans le cas contraire.	Supprime de la page l'erreur spécifiée par l'ID. id : ID de chaîne d'une erreur créée à l'aide de addError() ou addErrorFromQueryResponse().
removeAll(container)	Aucun	Supprime tous les blocs d'erreurs d'un conteneur spécifié. Si le conteneur spécifié n'existe pas, une erreur est renvoyée. conteneur : élément DOM contenant les chaînes d'erreur à supprimer. Si le conteneur est introuvable, la fonction génère une erreur JavaScript.
getContainer(errorId)	Permet de gérer un élément DOM contenant l'erreur spécifiée, ou la valeur "null" si elle est introuvable.	Récupère un handle vers l'élément conteneur contenant l'erreur spécifiée par errorID. errorId : ID de chaîne d'une erreur créée à l'aide de addError() ou addErrorFromQueryResponse().

Événements

La plupart des visualisations déclenchent des événements pour indiquer que quelque chose s'est produit. En tant qu'utilisateur du graphique, vous souhaiterez souvent écouter ces événements. Si vous codez votre propre visualisation, vous pouvez également déclencher ces événements vous-même.

Les méthodes suivantes permettent aux développeurs d'écouter des événements, de supprimer des gestionnaires d'événements existants ou de déclencher des événements depuis une visualisation.

• google.visualization.events.addListener() et google.visualization.events.addOneTimeListener() écoutent les événements.
• google.visualization.events.removeListener() supprime un écouteur existant.
• google.visualization.events.removeAllListeners() supprime tous les écouteurs d'un graphique spécifique.
• google.visualization.events.trigger() déclenche un événement.

addListener()

Appelez cette méthode pour vous inscrire et recevoir les événements déclenchés par une visualisation hébergée sur votre page. Vous devez documenter quels arguments d'événement, le cas échéant, seront transmis à la fonction de traitement.

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

source_visualization

Un handle vers l'instance de visualisation source.

event_name

Nom de chaîne de l'événement à écouter. Une visualisation doit documenter les événements qu'elle génère.

handling_function

Nom de la fonction JavaScript locale à appeler lorsque source_visualization déclenche l'événement event_name. La fonction de traitement reçoit tous les arguments d'événement en tant que paramètres.

Renvoie

Gestionnaire d'écouteur pour le nouvel écouteur. Le gestionnaire peut être utilisé pour supprimer ultérieurement cet écouteur, si nécessaire, en appelant google.visualization.events.removeListener().

Exemple

Voici un exemple d'inscription pour recevoir l'événement de sélection

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()

Cette méthode est identique à addListener(), mais elle est destinée aux événements qui ne doivent être écoutés qu'une seule fois. Les envois ultérieurs de l'événement n'appellent pas la fonction de traitement.

Exemple d'utilité: chaque tirage entraîne la génération d'un événement ready. Si vous souhaitez que seule la première ready exécute votre code, choisissez addOneTimeListener plutôt que addListener.

removeListener()

Appelez cette méthode pour annuler l'enregistrement d'un écouteur d'événements existant.

google.visualization.events.removeListener(listener_handler)

listener_handler

Gestionnaire d'écouteurs à supprimer, tel que renvoyé par google.visualization.events.addListener().

removeAllListeners()

Appelez cette méthode pour annuler l'enregistrement de tous les écouteurs d'événements d'une instance de visualisation spécifique.

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

Poignée de l'instance de visualisation source à partir de laquelle tous les écouteurs d'événements doivent être supprimés.

trigger()

Appelée par les outils de mise en œuvre de la visualisation. Appelez cette méthode à partir de votre visualisation pour déclencher un événement avec un nom et un ensemble de valeurs arbitraires.

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

source_visualization

Un handle vers l'instance de visualisation source. Si vous appelez cette fonction à partir d'une méthode définie par la visualisation d'envoi, il vous suffit de transmettre le mot clé this.

event_name

Nom de chaîne pour appeler l'événement. Vous pouvez choisir n'importe quelle valeur de chaîne.

event_args

[facultatif] Mappage de paires nom/valeur à transmettre à la méthode de réception. Par exemple : {message: "Bonjour !", score: 10, name: "Fred"}. Vous pouvez transmettre la valeur "null" si aucun événement n'est nécessaire. Le destinataire doit être prêt à accepter la valeur "null" pour ce paramètre.

Exemple

Voici un exemple de visualisation qui génère une méthode nommée "select" lorsque sa méthode clickserver est appelée. Elle ne renvoie aucune valeur.

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

Méthodes et propriétés de visualisation standards

Chaque visualisation devrait exposer l'ensemble suivant de méthodes et de propriétés obligatoires et facultatives. Toutefois, notez qu'il n'existe pas de vérification du type pour appliquer ces normes. Nous vous recommandons donc de lire la documentation de chaque visualisation.

• Constructeur
• draw()
• getAction() [facultatif]
• getSelection() [facultatif]
• removeAction() [facultatif]
• setAction() [facultatif]
• setSelection() [facultatif]

Remarque : Ces méthodes se trouvent dans l'espace de noms de la visualisation, et non dans l'espace de noms google.visualization.

Constructeur

Le constructeur doit porter le nom de votre classe de visualisation et renvoyer une instance de cette classe.

visualization_class_name(dom_element)

dom_element

Pointeur vers un élément DOM dans lequel la visualisation doit être intégrée.

Exemple

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

draw()

Dessine la visualisation sur la page. En arrière-plan, il peut s'agir d'extraire un graphique sur un serveur ou d'en créer un sur la page à l'aide du code de visualisation associé. Vous devez appeler cette méthode chaque fois que les données ou les options changent. L'objet doit être dessiné à l'intérieur de l'élément DOM transmis au constructeur.

draw(data[, options])

données

DataTable ou DataView contenant les données à utiliser pour dessiner le graphique. Il n'existe pas de méthode standard pour extraire un DataTable d'un graphique.

options

[Facultatif] Mappage de paires nom/valeur d'options personnalisées. Exemples : hauteur et largeur, couleurs d'arrière-plan et légendes. La documentation relative à la visualisation doit répertorier les options disponibles et prendre en charge les options par défaut si vous ne spécifiez pas ce paramètre. Vous pouvez utiliser la syntaxe littérale d'objet JavaScript pour transmettre un mappage d'options: par exemple, {x:100, y:200, title:'An Example'}

Exemple

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

getAction()

Cela peut être exposé par des visualisations qui ont des info-bulles et autorisent des actions d'info-bulles.

Renvoie l'objet d'action d'info-bulle avec l'élément actionID demandé.

Exemple :

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

getSelection()

Il est éventuellement exposé par des visualisations qui souhaitent vous permettre d'accéder aux données actuellement sélectionnées dans le graphique.

selection_array getSelection()

Renvoie

selection_array : tableau des objets sélectionnés, chacun décrivant un élément de données dans la table sous-jacente utilisée pour créer la visualisation (DataView ou DataTable). Chaque objet possède les propriétés row et/ou column, avec l'index de la ligne et/ou de la colonne de l'élément sélectionné dans la DataTable sous-jacente. Si la propriété row est nulle, la sélection est une colonne. Si la propriété column est nulle, la sélection est une ligne. Si les deux ne sont pas nulles, il s'agit d'un élément de données spécifique. Vous pouvez appeler la méthode DataTable.getValue() pour obtenir la valeur de l'élément sélectionné. Le tableau récupéré peut être transmis dans setSelection().

Exemple

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()

Cela peut être exposé par des visualisations qui ont des info-bulles et autorisent des actions d'info-bulles.

Supprime de votre graphique l'objet d'action d'info-bulle avec le actionID demandé.

Exemple :

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

setAction()

Cela peut être exposé par des visualisations qui ont des info-bulles et autorisent des actions d'info-bulles. Elle ne fonctionne que pour les graphiques de base (à barres, à colonnes, en courbes, en aires, à nuage de points, combinés, à bulles, à secteurs, en beignet, en chandeliers japonais, histogramme, zone en escalier).

Définit une action d'info-bulle à exécuter lorsque l'utilisateur clique sur le texte de l'action.

setAction(action object)

La méthode setAction utilise un objet comme paramètre d'action. Cet objet doit spécifier trois propriétés: id (ID de l'action en cours de définition), text (texte à afficher dans l'info-bulle de l'action) et action (fonction à exécuter lorsqu'un utilisateur clique sur le texte de l'action).

Toutes les actions d'info-bulle doivent être définies avant d'appeler la méthode draw() du graphique.

Exemple :

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

La méthode setAction peut également définir deux propriétés supplémentaires: visible et enabled. Ces propriétés doivent être des fonctions qui renvoient des valeurs boolean indiquant si l'action d'info-bulle sera visible et/ou activée.

Exemple :

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

Sélectionne éventuellement une entrée de données dans la visualisation, par exemple un point dans un graphique en aires ou une barre dans un graphique à barres. Lorsque cette méthode est appelée, la visualisation doit indiquer visuellement quelle est la nouvelle sélection. L'implémentation de setSelection() ne doit pas déclencher un événement "select". Les visualisations peuvent ignorer une partie de la sélection. Par exemple, une table qui ne peut afficher que les lignes sélectionnées peut ignorer des éléments de cellule ou de colonne dans son implémentation setSelection(), ou sélectionner la ligne entière.

Chaque fois que cette méthode est appelée, tous les éléments sélectionnés sont désélectionnés et la nouvelle liste de sélection transmise doit être appliquée. Il n'existe aucun moyen explicite de désélectionner des éléments individuels. Pour désélectionner des éléments individuels, appelez setSelection() en indiquant les éléments restants sélectionnés. Pour désélectionner tous les éléments, appelez setSelection(), setSelection(null) ou setSelection([]).

setSelection(selection_array)

selection_array

Tableau d'objets, chacun avec une propriété numérique de ligne et/ou de colonne. row et column correspondent au numéro de ligne ou de colonne basé sur zéro d'un élément de la table de données à sélectionner. Pour sélectionner une colonne entière, définissez row sur "null". Pour sélectionner une ligne entière, définissez column sur "null". Exemple:setSelection([{row:0,column:1},{row:1, column:null}]) sélectionne la cellule à (0,1) et toute la ligne 1.

Diverses méthodes statiques

Cette section contient diverses méthodes utiles exposées dans l'espace de noms google.visualization.

arrayToDataTable()

Cette méthode utilise un tableau bidimensionnel et le convertit en tableau de données.

Les types de données des colonnes sont déterminés automatiquement par les données fournies. Les types de données de colonne peuvent également être spécifiés à l'aide de la notation de littéral d'objet dans la première ligne (la ligne d'en-tête de colonne) du tableau (c'est-à-dire {label: 'Start Date', type: 'date'}). Vous pouvez également utiliser des rôles de données facultatifs, mais ils doivent être définis explicitement à l'aide de la notation littérale d'objet. La notation littérale d'objet peut également être utilisée pour n'importe quelle cellule, ce qui vous permet de définir des objets de cellule).

Syntaxe

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

Tableau à deux dimensions, où chaque ligne représente une ligne du tableau de données. Si opt_firstRowIsData est défini sur "false" (valeur par défaut), la première ligne sera interprétée comme des libellés d'en-tête. Les types de données de chaque colonne sont interprétés automatiquement à partir des données fournies. Si une cellule n'a pas de valeur, spécifiez une valeur nulle ou vide selon le cas.

opt_firstRowIsData

Définit si la première ligne définit ou non une ligne d'en-tête. Si la valeur est "true", toutes les lignes sont considérées comme des données. Si la valeur est "false", la première ligne est considérée comme une ligne d'en-tête et les valeurs sont attribuées en tant que libellés de colonne. La valeur par défaut est "false".

Renvoie

Un nouveau DataTable.

Exemples

Le code suivant illustre trois manières de créer le même objet 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()

Cette méthode crée un graphique au cours d'un seul appel. L'avantage de cette méthode est qu'elle nécessite un peu moins de code et que vous pouvez sérialiser et enregistrer les visualisations sous forme de chaînes de texte pour les réutiliser. Cette méthode ne renvoie pas de handle vers le graphique créé. Vous ne pouvez donc pas attribuer d'écouteurs de méthode pour intercepter les événements du graphique.

Syntaxe

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

Chaîne littérale JSON ou objet JavaScript, avec les propriétés suivantes (sensibles à la casse) :

Propriété	Type	Obligatoire	Par défaut	Description
chartType	Chaîne	Obligatoire	none	Nom de classe de la visualisation. Le nom de package google.visualization peut être omis pour les graphiques Google. Si la bibliothèque de visualisations appropriée n'a pas encore été chargée, cette méthode charge la bibliothèque s'il s'agit d'une visualisation Google. Vous devez charger explicitement les visualisations tierces. Exemples:Table, PieChart, example.com.CrazyChart.
containerId	Chaîne	Obligatoire	none	ID de l'élément DOM de votre page qui hébergera la visualisation.
options	Objets	Facultatif	none	Objet décrivant les options de la visualisation. Vous pouvez utiliser la notation littérale JavaScript ou fournir un handle vers l'objet. Exemple:"options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	Objets	Facultatif	Aucun	DataTable utilisé pour remplir la visualisation. Il peut s'agir d'une représentation sous forme de chaîne JSON littérale d'un DataTable, comme décrit ci-dessus, d'un handle vers un objet google.visualization.DataTable renseigné ou d'un tableau à deux dimensions comme celui accepté par arrayToDataTable(opt_firstRowIsData=false) . Vous devez spécifier cette propriété ou la propriété dataSourceUrl.
dataSourceUrl	Chaîne	Facultatif	Aucun	Requête de source de données permettant de renseigner les données du graphique (par exemple, une feuille de calcul Google). Vous devez spécifier cette propriété ou la propriété dataTable.
requête	Chaîne	Facultatif	Aucun	Si vous spécifiez dataSourceUrl, vous pouvez éventuellement spécifier une chaîne de requête de type SQL à l'aide du langage de requête de visualisation pour filtrer ou manipuler les données.
refreshInterval	Nombre	Facultatif	Aucun	Fréquence, en secondes, où la visualisation doit actualiser sa source de requête. N'utilisez cette option que lorsque vous spécifiez dataSourceUrl.
vue	Objet OU tableau	Facultatif	Aucun	Définit un objet d'initialisation DataView qui agit comme un filtre sur les données sous-jacentes, telles que définies par le paramètre dataTable ou dataSourceUrl. Vous pouvez transmettre une chaîne ou un objet d'initialisation DataView, comme celui renvoyé par dataview.toJSON(). Exemple:"view": {"columns": [1, 2]}. Vous pouvez également transmettre un tableau d'objets d'initialisation DataView. Dans ce cas, la première DataView du tableau est appliquée aux données sous-jacentes pour créer une table de données, la seconde DataView est appliquée à la table de données résultant de l'application de la première DataView, et ainsi de suite.

Exemples

Crée un tableau basé sur la source de données d'une feuille de calcul et inclut la requête 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'exemple suivant crée la même table, mais crée un DataTable localement:

<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>

Cet exemple transmet une représentation du graphique sous forme de chaîne JSON, que vous avez peut-être chargée à partir d'un fichier:

<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 s'agit du constructeur de l'élément de barre d'outils qui peut être associé à de nombreuses visualisations. Cette barre d'outils permet à l'utilisateur d'exporter les données de la visualisation dans différents formats ou de fournir une version intégrable de la visualisation à utiliser à différents endroits. Pour en savoir plus et obtenir un exemple de code, consultez la page de la barre d'outils.