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

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

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

Remarque sur les tableaux

Certains navigateurs ne gèrent pas correctement les virgules de fin dans les tableaux JavaScript. Par conséquent, ne les utilisez pas. Les valeurs vides au milieu d'un tableau sont acceptées. Par exemple :

data = ['a','b','c', ,]; // BAD
data = ['a','b','c'];   // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.

Classe DataTable

Représente une table de valeurs modifiable en deux dimensions. 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 vue de données.

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

En outre, vous pouvez attribuer des propriétés personnalisées (paires nom/valeur) à une cellule, une ligne, une colonne ou la table entière. Certaines visualisations acceptent des propriétés personnalisées spécifiques. Par exemple, la visualisation des tableaux 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 accepte.

Voir aussi:QueryResponse.getDataTable

Constructeur

Syntaxe

DataTable(opt_data, opt_version)

données_opt
[Facultatif] Données utilisées pour initialiser la table. Il peut s'agir du fichier JSON renvoyé en appelant DataTable.toJSON() sur une table remplie 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 sera renvoyée.
opt_version,
[Facultatif] Valeur numérique indiquant la version du protocole filaire utilisé. Il n'est utilisé que par les implémentations de sources de données de Chart Tools. La version actuelle est 0.6.

Détails

L'objet DataTable permet de conserver les données transmises dans une visualisation. Un 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'intégralité de l'élément DataTable. Les visualisations peuvent les utiliser pour prendre en charge des fonctionnalités supplémentaires. Par exemple, la visualisation des tables 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 du type spécifié par sa colonne. Les cellules peuvent éventuellement utiliser une version "mise en forme" des données. Il s'agit d'une version sous forme de chaîne des données, mise en forme pour une visualisation. Une visualisation peut (mais n'est pas obligatoire) à utiliser la version formatée pour l'affichage, mais utilisera toujours les données elles-mêmes pour le tri ou les calculs effectués (par exemple, pour déterminer l'emplacement d'un point sur un graphique). Vous pouvez, par exemple, attribuer les valeurs "basse" "moyenne" et "élevée" aux valeurs de cellules numériques 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 pour les lignes et les colonnes. Toutefois, plutôt que de supprimer des lignes ou des colonnes, envisagez de créer une DataView qui est une vue sélective de DataTable.

Si vous modifiez les valeurs d'un DataTable après qu'il a été transmis à la méthode draw() d'une visualisation, les modifications ne modifient pas immédiatement le graphique. Vous devez appeler draw() à nouveau pour refléter les modifications.

Remarque:Google Charts n'effectue aucune validation sur les tables de données. Si c'était le cas, l'affichage des graphiques prendrait plus de temps. Si vous fournissez un nombre auquel votre colonne attend une chaîne, ou inversement, Google Charts fera de son mieux pour interpréter la valeur d'une manière logique, mais ne signalera pas d'erreurs.

Exemples

L'exemple suivant illustre l'instanciation et l'insertion d'une valeur DataTable avec une chaîne littérale, avec les mêmes données que celles présentées 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'}]
]);
Dois-je créer mon tableau de données en JavaScript ou en notation littérale d'objet ?

Vous pouvez créer une DataTable en appelant le constructeur sans paramètres, puis en ajoutant des valeurs en appelant les méthodes addColumn()/addRows() répertoriées ci-dessous, ou en transmettant un objet littéral JavaScript rempli pour l'initialiser. Ces deux méthodes sont décrites ci-dessous. Quel outil choisir ?

  • La création et l'insertion d'une table dans JavaScript en appelant addColumn(), addRow() et addRows() sont des codes très lisibles. Cette méthode est utile lorsque vous devez saisir le code à la main. Il est plus lent que d'utiliser la notation littérale d'objet (décrite ci-après), mais dans les tables plus petites (1 000 cellules, par exemple), vous ne remarquerez probablement pas beaucoup de différence.
  • La déclaration directe de l'objet DataTable à l'aide de la notation de littéraux d'objet est considérablement plus rapide dans les grandes tables. Cependant, la syntaxe d'un littéral d'objet peut s'avérer délicate. Utilisez-la si vous pouvez générer la syntaxe de littéral d'objet dans le code, ce qui réduit le risque d'erreurs.

 

Méthodes

Méthode Valeur renvoyée Description

addColumn(type, opt_label, opt_id)

OU

addColumn(description_object)

Number

Ajoute une nouvelle colonne au tableau de données et affiche l'index de la nouvelle colonne. Une valeur null est attribuée à toutes les cellules de la nouvelle colonne. Cette méthode comporte deux signatures:

La première signature contient les paramètres suivants:

  • type : chaîne contenant le type de données des valeurs de la colonne. Le type peut être l'un des suivants: 'string', 'number', 'boolean', 'date', 'datetime', et 'timeofday'.
  • opt_label : [facultatif] chaîne contenant le libellé de la colonne. Le libellé de colonne s'affiche généralement dans la visualisation (par exemple, en tant qu'en-tête de colonne dans un tableau ou sous forme de libellé de légende dans un graphique à secteurs). Si aucune valeur n'est spécifiée, une chaîne vide est attribuée.
  • opt_id : [facultatif] chaîne avec un identifiant unique pour la colonne. Si aucune valeur n'est spécifiée, une chaîne vide est attribuée.

La deuxième signature possède un paramètre d'objet unique comprenant les membres suivants:

  • type : chaîne décrivant le type de données de la colonne. Mêmes valeurs que pour type.
  • label : [chaîne facultative] libellé de la colonne.
  • id : [chaîne facultative] ID de la colonne.
  • role : [chaîne facultative] un rôle pour la colonne.
  • pattern : [chaîne facultative] chaîne de format numérique (ou date) indiquant comment afficher la valeur de colonne.

Voir aussi : getColumnId, getColumnLabel, getColumnType, insertColumn et getColumnRole

addRow(opt_cellArray) Number

Ajoute une nouvelle ligne au tableau de données et affiche l'index de la nouvelle ligne.

  • opt_cellArray [facultatif] : objet de ligne, en notation JavaScript, spécifiant les données de la nouvelle ligne. Si ce paramètre n'est pas inclus, cette méthode ajoute simplement une ligne vide à la fin de la table. Ce paramètre est un tableau de valeurs de cellules: si vous souhaitez uniquement spécifier une valeur pour une cellule, indiquez simplement la valeur de la cellule (par exemple, 55 ou "hello") si vous souhaitez spécifier une valeur formatée et/ou des propriétés pour la cellule, utilisez un objet de cellule (par exemple, {v:55, f:'Cinquante-cinq'}. Vous pouvez combiner des valeurs simples et des objets de cellule dans le même appel de méthode. Utilisez null ou une entrée de tableau vide pour une cellule vide.

Exemples :

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.
addRows(numOrArray) Number

Ajoute des lignes au tableau de données et affiche l'index de la dernière ligne ajoutée. Vous pouvez appeler cette méthode pour créer des lignes vides ou des données utilisées pour les remplir, comme décrit ci-dessous.

  • numOrArray : nombre ou tableau :
    • Nombre : nombre indiquant le nombre de lignes non remplies à ajouter.
    • Tableau : tableau d'objets row utilisés pour remplir un ensemble de nouvelles lignes. Chaque ligne est un objet, comme décrit dans addRow(). Utilisez null ou une entrée de tableau vide pour une cellule vide.

Exemple :

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.
]);

Voir aussi : insertRows

clone() Tableau de données Renvoie un clone de la table de données. Il en résulte une copie profonde de la table de données, à l'exception des propriétés de cellule, des propriétés de ligne, des propriétés de table et des propriétés de colonne, qui sont des copies superficielles. Cela signifie que les propriétés non primitives sont copiées par référence, mais que les propriétés primitives sont copiées par valeur.
getColumnId(columnIndex) Chaîne Renvoie l'identifiant d'une colonne donnée spécifiée par l'index de colonne de la table sous-jacente.
Pour les tables de données récupérées par des requêtes, l'identifiant de colonne est défini par la source de données et peut être utilisé pour faire référence à des colonnes lorsque vous utilisez le langage de requête.
Voir aussi: Query.setQuery
getColumnIndex(columnIdentifier) Chaîne, nombre Renvoie l'index d'une colonne donnée spécifiée par l'index, l'ID ou l'étiquette de la colonne s'il existe dans cette table. Sinon, renvoie la valeur -1. Lorsque columnIdentifier est une chaîne, il permet de rechercher la colonne d'abord par son ID, puis par son étiquette.
Voir aussi : getColumnId, getColumnLabel
getColumnLabel(columnIndex) Chaîne Renvoie l'étiquette d'une colonne donnée spécifiée par l'index de colonne de la table sous-jacente.
Le libellé de colonne s'affiche généralement dans la visualisation. Par exemple, le libellé de colonne peut s'afficher comme en-tête de colonne dans un tableau ou sous forme de libellé de légende dans un graphique à secteurs.
Pour les tables de données récupérées par des requêtes, le libellé de colonne est défini par la source de données ou par la clause label du langage de requête.
Voir aussi : setColumnLabel
getColumnPattern(columnIndex) Chaîne

Renvoie le modèle de mise en forme utilisé pour mettre en forme les valeurs de la colonne spécifiée.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

Pour les tables de données récupérées par des requêtes, le modèle de colonne est défini par la source de données ou par la clause format du langage de requête. Exemple de schéma : '#,##0.00'. Pour en savoir plus sur les modèles, consultez la documentation de référence sur le langage de requête.

getColumnProperties(columnIndex) Objet

Renvoie un mappage de toutes les propriétés de la colonne spécifiée. Notez que l'objet "properties" est renvoyé par référence. Par conséquent, si vous modifiez les valeurs de l'objet récupéré, elles le sont également dans DataTable.

  • columnIndex est l'index numérique de la colonne pour lequel vous souhaitez récupérer les propriétés.
getColumnProperty(columnIndex, name) Automatique

Renvoie la valeur d'une propriété nommée ou null si aucune propriété de ce type n'est définie pour la colonne spécifiée. Le type de retour varie en fonction de la propriété.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • name est le nom de la propriété sous forme de chaîne.

Voir aussi : setColumnProperty setColumnProperties

getColumnRange(columnIndex) Objet

Renvoie les valeurs minimale et maximale des valeurs d'une colonne spécifiée. L'objet renvoyé possède les propriétés min et max. Si la plage ne comporte aucune valeur, min et max contiennent null.

columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

getColumnRole(columnIndex) Chaîne Renvoie le rôle de la colonne spécifiée.
getColumnType(columnIndex) Chaîne

Renvoie le type d'une colonne donnée spécifiée par l'index de colonne.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

Le type de colonne renvoyé est l'un des suivants: 'string', 'number', 'boolean', 'date', 'datetime', et 'timeofday'.

getDistinctValues(columnIndex) Tableau d'objets

Renvoie les valeurs uniques d'une colonne donnée, par ordre croissant.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

Le type des objets renvoyés est identique à celui renvoyé par la méthode getValue.

getFilteredRows(filters) Tableau d'objets

Renvoie les index de ligne correspondant aux lignes correspondant à tous les filtres donnés. Les index sont renvoyés par ordre croissant. Le résultat de cette méthode peut être utilisé comme entrée dans DataView.setRows() pour modifier l'ensemble de lignes affiché dans une visualisation.

filters : tableau d'objets qui décrit une valeur de cellule acceptable. Cette méthode renvoie un index de ligne si elle correspond à tous les filtres définis. Chaque filtre est un objet avec une propriété numérique column qui spécifie l'index de la colonne à évaluer, ainsi que l'un des éléments suivants:

  • Propriété value avec une valeur qui doit correspondre exactement à la cellule de la colonne spécifiée. La valeur doit être du même type que la colonne.
  • Une ou les deux propriétés suivantes, du même type que la colonne filtrée :
    • minValue : valeur minimale de la cellule. La valeur de la cellule dans la colonne spécifiée doit être supérieure ou égale à cette valeur.
    • maxValue : valeur maximale de la cellule. La valeur de la cellule dans la colonne spécifiée doit être inférieure ou égale à cette valeur.
    Une valeur nulle ou non définie pour minValue (ou maxValue) signifie que la limite inférieure (ou supérieure) de la plage ne sera pas appliquée.

Une autre propriété facultative, test, spécifie une fonction à combiner avec le filtrage de valeurs ou de plages. La fonction est appelée avec la valeur de la cellule, les index de ligne et de colonne, et la table de données. Il doit renvoyer la valeur "false" si la ligne doit être exclue du résultat.

Exemple: getFilteredRows([{column: 3, value: 42}, {column: 2, minValue: 'bar', maxValue: 'foo'}, {column: 1, test: (value, rowId, columnId, datatable) => { return value == "baz"; }}]) renvoie un tableau contenant, dans l'ordre croissant, les index de toutes les lignes pour lesquelles la quatrième colonne (index de colonne 3) est exactement 42, et la troisième colonne (index de colonne 2) est comprise entre "bar" et "foo" (inclus).

getFormattedValue(rowIndex, columnIndex) Chaîne

Renvoie la valeur formatée de la cellule aux index de ligne et de colonne donnés.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • ColumnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

Pour en savoir plus sur la mise en forme des valeurs de colonne, consultez la documentation de référence sur le langage de requête.

Voir aussi:setFormattedValue

getNumberOfColumns() Number Renvoie le nombre de colonnes de la table.
getNumberOfRows() Number Renvoie le nombre de lignes de la table.
getProperties(rowIndex, columnIndex) Objet

Renvoie un mappage de toutes les propriétés de la cellule spécifiée. Notez que l'objet "properties" est renvoyé par référence. Par conséquent, si vous modifiez les valeurs de l'objet récupéré, elles le sont également dans DataTable.

  • rowIndex est l'index de ligne de la cellule.
  • columnIndex est l'index de colonne de la cellule.
getProperty(rowIndex, columnIndex, name) Automatique

Renvoie la valeur d'une propriété nommée ou null si aucune propriété de ce type n'est définie pour la cellule spécifiée. Le type de retour varie en fonction de la propriété.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • name est une chaîne avec le nom de la propriété.

Voir aussi : setCell setProperties setProperty

getRowProperties(rowIndex) Objet

Renvoie un mappage de toutes les propriétés de la ligne spécifiée. Notez que l'objet "properties" est renvoyé par référence. Par conséquent, si vous modifiez les valeurs de l'objet récupéré, elles le sont également dans DataTable.

  • rowIndex est l'index de la ligne pour laquelle vous souhaitez récupérer les propriétés.
getRowProperty(rowIndex, name) Automatique

Renvoie la valeur d'une propriété nommée ou null si aucune propriété de ce type n'est définie pour la ligne spécifiée. Le type de retour varie en fonction de la propriété.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • name est une chaîne avec le nom de la propriété.

Voir aussi:setRowProperty setRowProperties

getSortedRows(sortColumns) Tableau de nombres

Renvoie une version triée de la table sans modifier l'ordre des données sous-jacentes. Pour trier définitivement les données sous-jacentes, appelez sort(). Vous pouvez spécifier le tri de différentes manières, en fonction du type que vous transmettez au paramètre sortColumns:

  • Un seul nombre spécifie l'index de la colonne à utiliser comme critère de tri. Le tri s'effectue par ordre croissant. Exemple: sortColumns(3) effectue un tri selon la quatrième colonne, dans l'ordre croissant.
  • Un seul objet contenant le numéro de l'index de colonne à trier et une propriété booléenne facultative desc. Si desc est défini sur "true", la colonne spécifique est triée par ordre décroissant. Sinon, le tri s'effectue par ordre croissant. Exemples : sortColumns({column: 3}) trie les données de la quatrième colonne par ordre croissant, tandis que sortColumns({column: 3, desc: true}) les trie par ordre décroissant de la quatrième colonne.
  • Tableau des nombres des index de colonne à utiliser pour le tri. Le premier chiffre correspond à la colonne principale utilisée pour le tri, le second à la colonne secondaire, et ainsi de suite. Cela signifie que lorsque deux valeurs de la première colonne sont égales, les valeurs de la colonne suivante sont comparées, etc. Exemple : sortColumns([3, 1, 6]) effectue un tri d'abord par la quatrième colonne (par ordre croissant), puis par la deuxième colonne (par ordre croissant), puis par la septième colonne (par ordre croissant).
  • Un tableau d'objets, chacun avec le numéro d'index de colonne à trier, et une propriété booléenne facultative desc. Si desc est défini sur "true", la colonne spécifique est triée par ordre décroissant (l'ordre croissant est la valeur par défaut). Le premier objet correspond à la colonne principale utilisée pour le tri, le second à la colonne secondaire, et ainsi de suite. Cela signifie que lorsque deux valeurs de la première colonne sont égales, les valeurs de la colonne suivante sont comparées, etc. Exemple : sortColumn([{column: 3}, {column: 1, desc: true}, {column: 6, desc: true}]) trie d'abord par la quatrième colonne (par ordre croissant), puis par la colonne 2 par ordre décroissant et par la colonne 7 par ordre décroissant.

La valeur renvoyée est un tableau de nombres. Chaque nombre est un index de ligne DataTable. Si l'itération des lignes DataTable est effectuée dans l'ordre du tableau renvoyé, les lignes sont triées selon le paramètre sortColumns spécifié. La sortie peut être utilisée comme entrée dans DataView.setRows() pour modifier rapidement l'ensemble de lignes affiché dans une visualisation.

Notez que le tri est assuré de manière stable. Cela signifie que si vous effectuez un tri sur des valeurs égales de deux lignes, le même tri renverra les lignes dans le même ordre à chaque fois.
Voir aussi : sort

Exemple : Pour itérer sur des lignes triées selon la troisième colonne, utilisez:

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}
getTableProperties Objet Renvoie une carte de toutes les propriétés de la table.
getTableProperty(name) Automatique

Renvoie la valeur d'une propriété nommée ou null si aucune propriété de ce type n'est définie pour la table. Le type de retour varie en fonction de la propriété.

  • name est une chaîne avec le nom de la propriété.

Voir aussi:setTableProperties setTableProperty

getValue(rowIndex, columnIndex) Objet

Renvoie la valeur de la cellule au niveau des index de ligne et de colonne donnés.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().

Le type de la valeur renvoyée dépend du type de colonne (voir getColumnType):

  • Si le type de colonne est "chaîne", la valeur est une chaîne.
  • Si le type de colonne est "nombre", la valeur est un nombre.
  • Si le type de colonne est "booléen", la valeur est booléenne.
  • Si le type de colonne est "date" ou "datetime", la valeur est un objet "Date".
  • Si le type de colonne est "heure_du_jour", la valeur est un tableau de quatre nombres: [heure, minute, seconde, millisecondes].
  • Si la valeur de la cellule est nulle, elle renvoie null.
insertColumn(columnIndex, type [,label [,id]]) Aucune

Insère une nouvelle colonne dans le tableau de données, à l'index spécifique. Toutes les colonnes existantes à l'index spécifié ou après seront déplacées vers un index supérieur.

  • columnIndex est un nombre avec l'index requis pour la nouvelle colonne.
  • type doit être une chaîne contenant le type de données des valeurs de la colonne. Le type peut être l'un des suivants : 'string', 'number', 'boolean', 'date', 'datetime', et 'timeofday'.
  • label doit être une chaîne avec le libellé de la colonne. Le libellé de colonne s'affiche généralement dans la visualisation, par exemple en tant qu'en-tête de colonne dans un tableau ou sous forme de libellé de légende dans un graphique à secteurs. Si aucune valeur n'est spécifiée, une chaîne vide est attribuée.
  • id doit être une chaîne avec un identifiant unique pour la colonne. Si aucune valeur n'est spécifiée, une chaîne vide est attribuée.

Voir aussi : addColumn

insertRows(rowIndex, numberOrArray) Aucune

Insère le nombre de lignes spécifié dans l'index de ligne spécifié.

  • rowIndex est le numéro d'index dans lequel insérer la ou les nouvelles lignes. Des lignes seront ajoutées à partir du numéro d'index spécifié.
  • numberOrArray correspond à un nombre de nouvelles lignes vides à ajouter ou à un tableau d'une ou plusieurs lignes remplies à ajouter à l'index. Consultez la section addRows() pour connaître la syntaxe permettant d'ajouter un tableau d'objets de ligne.

Voir aussi:addRows

removeColumn(columnIndex) Aucune

Supprime la colonne au niveau de l'index spécifié.

  • columnIndex doit être un nombre avec un index de colonne valide.

Voir également : removeColumns

removeColumns(columnIndex, numberOfColumns) Aucune

Supprime le nombre de colonnes spécifié à partir de la colonne au niveau de l'index spécifié.

  • numberOfColumns est le nombre de colonnes à supprimer.
  • columnIndex doit être un nombre avec un index de colonne valide.

Voir aussi : removeColumn

removeRow(rowIndex) Aucune

Supprime la ligne au niveau de l'index spécifié.

  • rowIndex doit être un nombre avec un index de lignes valide.

Voir aussi : removeRows

removeRows(rowIndex, numberOfRows) Aucune

Supprime le nombre de lignes spécifié à partir de la ligne au niveau de l'index spécifié.

  • numberOfRows est le nombre de lignes à supprimer.
  • rowIndex doit être un nombre avec un index de lignes valide.

Voir aussi:removeRow

setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]]) Aucune

Définit la valeur, la valeur formatée et/ou les propriétés d'une cellule.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • value [Facultatif] est la valeur attribuée à la cellule spécifiée. Pour éviter de remplacer cette valeur, définissez ce paramètre sur undefined. Pour l'effacer, définissez-le sur null. Le type de la valeur dépend du type de colonne (voir getColumnType()) :
    • Si le type de colonne est "chaîne", la valeur doit être une chaîne.
    • Si le type de colonne est "nombre", la valeur doit être un nombre.
    • Si le type de colonne est "booléen", la valeur doit être booléenne.
    • Si le type de colonne est "date" ou "datetime", la valeur doit être un objet "Date".
    • Si le type de colonne est "timeofday", la valeur doit être un tableau de quatre nombres : [hour, minute, second, millisecondes].
  • formattedValue [Facultatif] est une chaîne dont la valeur a le format d'une chaîne. Pour éviter de remplacer cette valeur, définissez ce paramètre sur undefined. Pour l'effacer et demander à l'API d'appliquer la mise en forme par défaut à value si nécessaire, définissez-la sur null. Pour définir explicitement une valeur formatée vide, définissez-la sur une chaîne vide. La valeur formatée est généralement utilisée par les visualisations pour afficher les étiquettes de valeur. Par exemple, la valeur formatée peut apparaître sous forme de texte de libellé dans un graphique à secteurs.
  • properties [Facultatif] est un Object (mappage nom/valeur) avec des propriétés supplémentaires pour cette cellule. Pour éviter de remplacer cette valeur, définissez ce paramètre sur undefined. Pour l'effacer, définissez-le sur null. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

Voir aussi : setValue(), setFormattedValue(), setProperty() et setProperties().

setColumnLabel(columnIndex, label) Aucune

Définit le libellé d'une colonne.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • label est une chaîne avec le libellé à attribuer à la colonne. Le libellé de colonne s'affiche généralement dans la visualisation. Par exemple, l'étiquette de colonne peut s'afficher comme en-tête de colonne dans un tableau ou sous forme de légende dans un graphique à secteurs.

Voir aussi : getColumnLabel

setColumnProperty(columnIndex, name, value) Aucune

Définit une propriété à une seule colonne. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • name est une chaîne avec le nom de la propriété.
  • value est une valeur de n'importe quel type à attribuer à la propriété nommée spécifiée de la colonne spécifiée.

Voir aussi:setColumnProperties getColumnProperty

setColumnProperties(columnIndex, properties) Aucune

Définit plusieurs propriétés de colonne. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • properties est un Object (mappage nom/valeur) avec des propriétés supplémentaires pour cette colonne. Si null est spécifié, toutes les propriétés supplémentaires de la colonne sont supprimées.

Voir également : setColumnProperty getColumnProperty

setFormattedValue(rowIndex, columnIndex, formattedValue) Aucune

Définit la valeur mise en forme d'une cellule.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • formattedValue est une chaîne dont la valeur est formatée pour être affichée. Pour effacer cette valeur et demander à l'API d'appliquer la mise en forme par défaut à la valeur de la cellule si nécessaire, définissez formattedValue null. Pour définir explicitement une valeur formatée vide, définissez-la sur une chaîne vide.

Voir aussi:getFormattedValue

setProperty(rowIndex, columnIndex, name, value) Aucune

Définit une propriété de cellule. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • name est une chaîne avec le nom de la propriété.
  • value est une valeur de n'importe quel type à attribuer à la propriété nommée spécifiée de la cellule spécifiée.

Voir aussi:setCell setProperties getProperty

setProperties(rowIndex, columnIndex, properties) Aucune

Définit plusieurs propriétés de cellule. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns().
  • properties est un Object (mappage nom/valeur) avec des propriétés supplémentaires pour cette cellule. Si null est spécifié, toutes les propriétés supplémentaires de la cellule sont supprimées.

Voir aussi : setCell setProperty getProperty

setRowProperty(rowIndex, name, value) Aucune

Définit une propriété de ligne. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • name est une chaîne avec le nom de la propriété.
  • value est une valeur de n'importe quel type à attribuer à la propriété nommée spécifiée de la ligne spécifiée.

Voir aussi:setRowProperties getRowProperty

setRowProperties(rowIndex, properties) Aucune

Définit plusieurs propriétés de ligne. Certaines visualisations acceptent les propriétés de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation sur la visualisation pour connaître les propriétés compatibles.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • properties est un Object (mappage nom/valeur) avec des propriétés supplémentaires pour cette ligne. Si null est spécifié, toutes les propriétés supplémentaires de la ligne sont supprimées.

Voir aussi:setRowProperty getRowProperty

setTableProperty(name, value) Aucune

Définit une propriété de table unique. Certaines visualisations acceptent les propriétés de table, de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation de visualisation pour connaître les propriétés compatibles.

  • name est une chaîne avec le nom de la propriété.
  • value est une valeur de tout type à attribuer à la propriété nommée spécifiée de la table.

Voir aussi : setTableProperties getTableProperty

setTableProperties(properties) Aucune

Définit plusieurs propriétés de table. Certaines visualisations acceptent les propriétés de table, de ligne, de colonne ou de cellule pour modifier leur affichage ou leur comportement. Consultez la documentation de visualisation pour connaître les propriétés compatibles.

  • properties est un Object (mappage nom/valeur) avec des propriétés supplémentaires pour la table. Si null est spécifié, toutes les propriétés supplémentaires de la table seront supprimées.

Voir aussi : setTableProperty getTableProperty

setValue(rowIndex, columnIndex, value) Aucune

Définit la valeur d'une cellule. En plus d'écraser les valeurs de cellule existantes, cette méthode efface également les valeurs et propriétés de mise en forme de la cellule.

  • rowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().
  • columnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns(). Cette méthode ne vous permet pas de définir une valeur formatée pour cette cellule. Pour ce faire, appelez setFormattedValue().
  • value est la valeur attribuée à la cellule spécifiée. Le type de la valeur renvoyée dépend du type de colonne (voir getColumnType) :
    • Si le type de colonne est "chaîne", la valeur doit être une chaîne.
    • Si le type de colonne est "nombre", la valeur doit être un nombre.
    • Si le type de colonne est "booléen", la valeur doit être booléenne.
    • Si le type de colonne est "date" ou "datetime", la valeur doit être un objet "Date".
    • Si le type de colonne est "timeofday", la valeur doit être un tableau de quatre nombres : [hour, minute, second, millisecondes].
    • Pour tout type de colonne, la valeur peut être définie sur null.

Voir aussi : setCell, setFormattedValue, setProperty, setProperties

sort(sortColumns) Aucune Trie les lignes en fonction des colonnes de tri spécifiées. DataTable est modifié par cette méthode. Pour obtenir une description des détails du tri, consultez getSortedRows(). Cette méthode ne renvoie pas les données triées.
Voir aussi:getSortedRows
Exemple: Pour trier selon la troisième colonne, puis la deuxième colonne, utilisez: data.sort([{column: 2}, {column: 1}]);
toJSON() Chaîne Renvoie une représentation JSON de DataTable qui peut être transmise au constructeur DataTable. Par exemple :
{"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 data Littéral JavaScript du constructeur

Vous pouvez initialiser un DataTable en transmettant un objet littéral de chaîne JavaScript dans le paramètre data. Nous allons appeler cet objet data. Vous pouvez coder cet objet à la main selon 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 à la main, cette section décrit la syntaxe.

Commençons par un exemple d'objet JavaScript simple décrivant une table avec trois lignes et trois colonnes (chaîne, nombre et types de 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!'}
}

Examinons maintenant la syntaxe:

L'objet data comprend deux propriétés de premier niveau obligatoires, cols et rows, et une propriété p facultative qui correspond à un mappage de valeurs arbitraires.

Remarque : Tous les noms de propriété et les constantes de chaîne indiqués sont sensibles à la casse. De plus, les propriétés décrites comme prenant une valeur de chaîne doivent être placées entre guillemets. Par exemple, si vous souhaitez spécifier que la propriété "type" soit un nombre, celle-ci sera exprimée comme suit: type: 'number', mais la valeur elle-même, en tant que valeur numérique, sera exprimée comme suit : 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 avec les propriétés suivantes (sensibles à la casse):

  • type [Obligatoire] Type de données des données de la colonne. Accepte les valeurs de chaîne suivantes (par exemple, pour la propriété v:, décrite ultérieurement) :
    • "boolean" : 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
    • "chaîne" : 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 de date JavaScript incluant 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 facultatif, représentant l'heure (0 indique minuit), les minutes, les secondes 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 pour que la page hôte ne nécessite pas d'échappement sophistiqué 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 que certaines visualisations affichent 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 numériques de colonne, 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 d'exister. Le client Google Visualization n'utilise pas cette valeur (il lit la valeur formatée de la cellule). Si 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é avec cette valeur. Les normes de modèle recommandées sont les ICU DecimalFormat et SimpleDateFormat.
  • p [Facultatif] Objet correspondant à une carte de valeurs personnalisées appliquées à la cellule. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation accepte des propriétés au niveau des cellules, elle les décrira. Sinon, elle sera ignorée.Exemple : p:{style: 'border: 1px solid green;'}.

Exemple cols

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

rows Propriété

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

Chaque objet de ligne possède une propriété obligatoire appelée c, qui est un tableau de cellules dans cette ligne. Il possède également une propriété p facultative qui définit un mappage de valeurs personnalisées arbitraires à attribuer à toute la ligne. Si votre visualisation accepte les propriétés au niveau des lignes, elle les décrira. Sinon, elle sera ignorée.

Objets cellulaires

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

  • v [Facultatif] : valeur de la cellule. Le type de données doit correspondre au type de données de la colonne. Si la cellule est nulle, la propriété v doit être nulle, bien qu'elle puisse toujours disposer des propriétés f et p.
  • f [Facultatif] Version de la valeur v sous forme de chaîne formatée pour l'affichage. Généralement, les valeurs sont identiques, 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 similaire pour cette propriété. Cette valeur n'est pas comparée à la valeur v. La valeur de calcul utilisée dans la visualisation n'est utilisée qu'en tant que libellé à afficher. En cas d'omission, une version de chaîne de v sera automatiquement générée à l'aide du formateur par défaut. Les valeurs f peuvent être modifiées avec votre propre outil de mise en forme, définies avec setFormattedValue() ou setCell(), ou récupérées avec getFormattedValue().
  • p [Facultatif] Objet correspondant à une carte de valeurs personnalisées appliquées à la cellule. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation accepte des propriétés au niveau des cellules, 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 être dans le même ordre que les descriptions des colonnes de cols. Pour indiquer une cellule nulle, vous pouvez spécifier null, laisser vide une cellule dans un tableau ou omettre les membres de tableau en fin de ligne. Ainsi, pour indiquer une ligne avec la valeur null pour les deux premières cellules, vous pouvez spécifier [ , , {cell_val}] ou [null, null, {cell_val}].

Voici un exemple d'objet de table avec trois colonnes, contenant 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 l'élément DataTable. Ces valeurs peuvent être de n'importe quel type JavaScript. Si votre visualisation accepte des propriétés au niveau de la table de données, elle les décrira. Sinon, elle sera disponible pour une utilisation par l'application. Exemple : p:{className: 'myDataTable'}.

Classe DataView

Vue en lecture seule d'un objet DataTable sous-jacent Un DataView permet de sélectionner uniquement un sous-ensemble de colonnes et/ou de lignes. Elle permet également de réorganiser les colonnes/lignes et de dupliquer les colonnes/lignes.

Une vue est une fenêtre active du DataTable sous-jacent, et non un instantané statique des données. Toutefois, vous devez toujours être prudent 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é dans la vue, et peut entraîner un comportement inattendu dans la vue. Vous devrez créer une nouvelle DataView à partir de DataTable pour appliquer ces modifications.
  • L'ajout ou la suppression de lignes de la table sous-jacente est sécurisé et les modifications seront immédiatement appliquées à la vue (mais vous devrez appeler draw() sur toutes les visualisations après cette modification pour que la nouvelle ligne soit affichée). Notez que si votre vue a filtré les lignes en appelant l'une des méthodes setRows() or hideRows(), et que vous ajoutez ou supprimez des lignes dans la table sous-jacente, le comportement est inattendu : vous devez créer une nouvelle valeur DataView pour refléter la nouvelle table.
  • La modification des valeurs de cellule dans des cellules existantes est sûre, et les modifications sont immédiatement propagées dans l'élément DataView (mais vous devez appeler draw() sur toutes les visualisations après cette modification pour que les nouvelles valeurs de cellule soient affichées).

Il est également possible de créer un DataView à partir d'un autre DataView. Notez que lorsqu'une table ou vue sous-jacente est mentionnée, elle fait référence au niveau immédiatement inférieur à ce niveau. En d'autres termes, il fait référence à l'objet de données utilisé pour construire cet objet 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 qui est la somme de deux colonnes précédentes ou une colonne qui calcule et affiche le trimestre civil d'une date provenant d'une autre colonne. Pour en savoir plus, consultez setColumns().

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

Vous pouvez combiner DataView.getFilteredRows() et DataView.setRows() pour créer un DataView avec un sous-ensemble de données intéressant, comme illustré 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 utilisé pour initialiser la vue. Par défaut, la vue contient toutes les colonnes et lignes de la table ou de la vue de données sous-jacentes, 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.

Article associé :

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

 

Constructeur 2

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

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)
données
Objet DataTable que vous avez utilisé pour créer 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.
afficher Asson
Chaîne JSON renvoyée par DataView.toJSON(). Il s'agit d'une description des lignes à afficher ou masquer dans le tableau de données data.

Méthodes

Méthode Valeur renvoyée Description
Voir les descriptions en DataTable. Identique aux méthodes DataTable équivalentes, à la différence près que les index de ligne/colonne font référence à l'index dans la vue, et non dans la table/vue sous-jacente.
getTableColumnIndex(viewColumnIndex) Number

Renvoie dans cette vue l'index dans la table (ou la vue) sous-jacente d'une colonne donnée spécifiée par son index. viewColumnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns(). Affiche -1 s'il s'agit d'une colonne générée.

Exemple: Si setColumns([3, 1, 4]) a déjà été appelé, getTableColumnIndex(2) renvoie 4.

getTableRowIndex(viewRowIndex) Number

Renvoie dans cette vue l'index dans la table (ou vue) sous-jacente d'une ligne spécifiée par son index. viewRowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows().

Exemple : Si setRows([3, 1, 4]) a déjà été appelé, getTableRowIndex(2) renvoie 4.

getViewColumnIndex(tableColumnIndex) Number

Renvoie dans cette vue l'index qui correspond à une colonne donnée spécifiée par son index dans la table (ou la vue) sous-jacente. S'il existe plusieurs index de ce type, le premier (plus petit) renvoie le premier. Si aucun index de ce type n'existe (la colonne spécifiée ne figure pas dans la vue), renvoie -1. tableColumnIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de colonnes renvoyé par la méthode getNumberOfColumns() de la table/vue sous-jacente.

Exemple : Si setColumns([3, 1, 4]) a déjà été appelé, getViewColumnIndex(4) renvoie 2.

getViewColumns() Tableau de nombres

Renvoie les colonnes de cette vue, dans l'ordre. Autrement dit, si vous appelez setColumns avec un tableau, puis getViewColumns(), vous devez obtenir un tableau identique.

getViewRowIndex(tableRowIndex) Number

Renvoie dans cette vue l'index qui correspond à une ligne donnée spécifiée par son index dans la table (ou la vue) sous-jacente. S'il existe plusieurs index de ce type, le premier (plus petit) renvoie le premier. S'il n'existe aucun index de ce type (la ligne spécifiée ne figure pas dans la vue), renvoie -1. tableRowIndex doit être un nombre supérieur ou égal à zéro et inférieur au nombre de lignes renvoyé par la méthode getNumberOfRows() de la table/vue sous-jacente.

Exemple : Si setRows([3, 1, 4]) a déjà été appelé, getViewRowIndex(4) renvoie 2.

getViewRows() Tableau de nombres

Renvoie les lignes de cette vue, dans l'ordre. Autrement dit, si vous appelez setRows avec un tableau, puis getViewRows(), vous devez obtenir un tableau identique.

hideColumns(columnIndexes) none

Masque les colonnes spécifiées de la vue actuelle. columnIndexes est un tableau de nombres représentant les index des colonnes à masquer. Ces index représentent les numéros d'index dans la table/vue sous-jacente. Les nombres dans columnIndexes ne doivent pas nécessairement être dans l'ordre ([3,4,1] est acceptable). Les colonnes restantes conservent leur ordre d'index lors des itérations. La saisie d'un numéro d'index pour une colonne déjà masquée n'est pas une erreur, mais la saisie d'un index qui n'existe pas dans la table/vue sous-jacente génère une erreur. Pour afficher les colonnes, appelez setColumns().

Exemple : Si vous avez une table avec 10 colonnes et que vous appelez setColumns([2,7,1,7,9]), puis hideColumns([7,9]), les colonnes de la vue seront alors [2,1].

hideRows(min, max) Aucune

Masque toutes les lignes dont les index se trouvent entre les valeurs minimale et maximale (incluse) de la vue actuelle. Il s'agit d'une syntaxe de commodité pour hideRows(rowIndexes) ci-dessus. Par exemple, hideRows(5, 10) équivaut à hideRows([5, 6, 7, 8, 9, 10]).

hideRows(rowIndexes) Aucune

Masque les lignes spécifiées de la vue actuelle. rowIndexes est un tableau de nombres représentant les index des lignes à masquer. Ces index représentent les numéros d'index dans la table/vue sous-jacente. Les nombres indiqués dans rowIndexes ne doivent pas nécessairement être dans l'ordre ([3,4,1] est acceptable). Les lignes restantes conservent leur ordre d'index. La saisie d'un numéro d'index pour une ligne déjà masquée n'est pas une erreur, mais la saisie d'un index qui n'existe pas dans la table/vue sous-jacente génère une erreur. Pour afficher des lignes, appelez setRows().

Exemple : Si vous avez une table avec 10 lignes et que vous appelez setRows([2,7,1,7,9]), puis hideRows([7,9]), les lignes de la vue seront [2,1].

setColumns(columnIndexes) Aucune

Spécifie les colonnes visibles dans cette vue. Toutes les colonnes non spécifiées seront masquées. Il s'agit d'un tableau d'index de colonne dans la table/vue sous-jacente, ou dans les colonnes calculées. Si vous n'appelez pas cette méthode, toutes les colonnes sont affichées par défaut. Le tableau peut également contenir des doublons pour afficher la même colonne plusieurs fois. Les colonnes seront affichées dans l'ordre spécifié.

  • columnIndexes - Tableau de nombres et/ou d'objets (pouvant être mélangés) :
    • Les nombres indiquent l'index de la colonne de données source à inclure dans la vue. Les données sont importées non modifiées. Si vous devez définir explicitement un rôle ou des propriétés de colonne supplémentaires, spécifiez un objet avec une propriété sourceColumn.
    • Les objets spécifient une colonne de calcul. Une colonne de calcul crée une valeur à la volée pour chaque ligne et l'ajoute à la vue. L'objet doit avoir les propriétés suivantes :
      • calc [fonction] : fonction appelée pour chaque ligne de la colonne afin de calculer une valeur pour cette cellule. La signature de la fonction est func(dataTable, row), où dataTable correspond à la DataTable source et row à l'index de la ligne de données source. La fonction doit renvoyer une valeur unique du type spécifié par type.
      • type [chaîne] : type JavaScript de la valeur renvoyée par la fonction calc.
      • label [facultatif, chaîne] : étiquette facultative à attribuer à cette colonne générée. Si aucune valeur n'est spécifiée, la colonne "Vue" n'a pas d'étiquette.
      • id [facultatif, chaîne] : ID facultatif à attribuer à cette colonne générée.
      • sourceColumn : [facultatif, nombre] colonne source à utiliser comme valeur. Si elle est spécifiée, ne spécifiez pas la propriété calc ni type. Cela revient à transmettre un nombre au lieu d'un objet, mais vous permet de spécifier un rôle et des propriétés pour la nouvelle colonne.
      • properties [facultatif, objet] : objet contenant des propriétés arbitraires à attribuer à cette colonne. Si elle n'est pas spécifiée, la colonne "View" n'aura aucune propriété.
      • role [facultatif, chaîne] : rôle à attribuer à cette colonne. S'il n'est pas spécifié, le rôle existant ne sera pas importé.

Exemples :

// 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);
}
setRows(min, max) Aucune

Définit les lignes de cette vue comme étant tous les index (dans la table/vue sous-jacente) compris entre min et max (inclus). Il s'agit d'une syntaxe simplifiée pour setRows(rowIndexes) ci-dessous. Par exemple, setRows(5, 10) équivaut à setRows([5, 6, 7, 8, 9, 10]).

setRows(rowIndexes) Aucune

Définit les lignes visibles dans cette vue, en fonction des numéros d'index de la table/vue sous-jacente. rowIndexes doit être un tableau de numéros d'index spécifiant les lignes à afficher dans la vue. Le tableau spécifie l'ordre d'affichage des lignes, qui peuvent être dupliquées. Notez que seules les lignes spécifiées dans rowIndexes sont affichées. Cette méthode efface toutes les autres lignes de la vue. Le tableau peut également contenir des doublons, ce qui duplique effectivement la ligne spécifiée dans cette vue (par exemple, setRows([3, 4, 3, 2]) entraîne l'affichage deux fois de la ligne 3 dans cette vue). Le tableau fournit ainsi un mappage des lignes de la table/vue sous-jacente à cette vue. Vous pouvez utiliser getFilteredRows() ou getSortedRows() pour générer une entrée pour cette méthode.

Exemple : Pour créer une vue avec les lignes 3 et zéro d'une table/vue sous-jacente : view.setRows([3, 0])

toDataTable() Tableau de données Renvoie un objet DataTable renseigné avec les lignes et colonnes visibles de DataView.
toJSON() chaîne Renvoie une représentation de chaîne de cet élément DataView. Cette chaîne ne contient pas les données réelles. Elle ne contient que les paramètres spécifiques à DataView tels que les lignes et les colonnes visibles. Vous pouvez stocker cette chaîne et la transmettre au DataView.fromJSON() constructeur statique pour recréer cette vue. Cela n'inclut pas les colonnes générées.

Classe ChartWrapper

Une classe ChartWrapper permet d'encapsuler votre graphique et de gérer toutes les requêtes de chargement, de dessin et de source de données qu'il inclut. 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 à créer de gestionnaire de rappel de requête. Vous pouvez également l'utiliser pour enregistrer facilement un graphique en vue de le réutiliser.

Un autre avantage de l'utilisation de ChartWrapper est que vous pouvez réduire le nombre de chargements de la bibliothèque en utilisant le chargement dynamique. De plus, vous n'avez pas besoin de charger explicitement les packages, car ChartWrapper se charge de rechercher et de charger les packages de graphique 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 drawdraw(). Si aucune valeur n'est spécifiée, 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 expose les méthodes supplémentaires suivantes:

Méthode Type renvoyé Description
draw(opt_container_ref) Aucune

Dessine le graphique. Vous devez appeler cette méthode après toute modification apportée au graphique ou aux données pour afficher les modifications.

  • opt_container_ref [facultatif] : référence à un élément de conteneur valide sur la page. S'il est spécifié, le graphique y est dessiné. Sinon, le graphique est dessiné dans l'élément dont l'ID est spécifié par containerId.
toJSON() Chaîne Renvoie une version de chaîne de la représentation JSON du graphique.
clone() Wrapper de graphique Renvoie une copie complète du wrapper de graphique.
getDataSourceUrl() Chaîne Si ce graphique extrait ses données d'une source de données, il renvoie l'URL de cette source de données. Sinon, renvoie la valeur "null".
getDataTable() google.visualization.DataTable

Si ce graphique obtient ses données à partir d'un DataTable défini localement, renvoie une référence à la DataTable du graphique. Si ce graphique extrait ses données d'une source de données, il renvoie la valeur "null".

Toutes les modifications que vous apporterez à l'objet renvoyé seront reflétées par le graphique la prochaine fois que vous appellerez ChartWrapper.draw().

getChartType() Chaîne Nom de classe du graphique encapsulé. S'il s'agit d'un graphique Google, le nom ne sera pas qualifié de google.visualization. Par exemple, s'il s'agissait d'un graphique en arbre, il renvoyait "Treemap" au lieu de "google.visualization.treemap".
getChartName() Chaîne Renvoie le nom du graphique attribué par setChartName().
getChart() Documentation de référence sur les objets de graphique Renvoie une référence au graphique créé par ce ChartWrapper, par exemple google.visualization.BarChart ou google.visualization.ColumnChart . La requête renvoie la valeur "null" jusqu'à ce que vous ayez appelé draw() sur l'objet ChartWrapper et génère un événement prêt. Les méthodes appelées sur l'objet renvoyé seront répercutées sur la page.
getContainerId() Chaîne ID de l'élément de conteneur DOM du graphique.
getQuery() Chaîne Chaîne de requête pour ce graphique, s'il en possède une et interroge une source de données.
getRefreshInterval() Number Tout intervalle d'actualisation de ce graphique, s'il interroge une source de données La valeur zéro indique qu'il n'y a aucune actualisation.
getOption(key, opt_default_val) Tous les types

Affiche la valeur d'option de graphique spécifiée

  • key : nom de l'option à récupérer. Il peut s'agir d'un nom complet, tel que 'vAxis.title'.
  • opt_default_value [facultatif] : si la valeur spécifiée n'est pas définie ou est nulle, cette valeur est renvoyée.
getOptions() Objet Renvoie l'objet d'options pour ce graphique.
getView() Objet OU Tableau Renvoie l'objet d'initialisation DataView, au même format que dataview.toJSON(), ou un tableau de ces objets.
setDataSourceUrl(url) Aucune Définit l'URL d'une source de données à utiliser pour ce graphique. Si vous définissez également un tableau de données pour cet objet, l'URL de la source de données sera ignorée.
setDataTable(table) Aucune Définit le tableau de données pour le graphique. Transmettez l'un des éléments suivants: null, un objet DataTable, une représentation JSON d'un objet DataTable ou un tableau suivant la syntaxe de arrayToDataTable().
setChartType(type) Aucune Définit le type de graphique. Transmettez le nom de classe du graphique encapsulé. S'il s'agit d'un graphique Google, ne le remplissez pas avec google.visualization. Ainsi, pour un graphique à secteurs, transmettez "PieChart".
setChartName(name) Aucune Définit un nom arbitraire pour le graphique. Cette valeur n'apparaît nulle part sur le graphique, sauf si un graphique personnalisé est explicitement conçu pour l'utiliser.
setContainerId(id) Aucune Définit l'ID de l'élément DOM conteneur du graphique.
setQuery(query_string) Aucune Définit une chaîne de requête si le graphique interroge une source de données. Vous devez également définir l'URL de la source de données si vous spécifiez cette valeur.
setRefreshInterval(interval) Aucune Définit l'intervalle d'actualisation de ce graphique, s'il interroge une source de données. Vous devez également définir une URL de source de données si vous spécifiez cette valeur. La valeur zéro indique qu'il n'y a pas d'actualisation.
setOption(key, value) Aucune Définit une valeur d'option de graphique unique, où key est le nom de l'option et value est la valeur. Pour annuler la définition d'une option, transmettez la valeur null. Notez que key peut être un nom complet, tel que 'vAxis.title'.
setOptions(options_obj) Aucune Définit un objet d'options complet pour un graphique.
setView(view_spec) Aucune Définit un objet initialiseur DataView qui agit comme un filtre sur les données sous-jacentes. Le wrapper de graphique doit comporter des données sous-jacentes issues d'une table de données ou d'une source de données à laquelle appliquer cette vue. Vous pouvez transmettre une chaîne ou un objet d'initialisation DataView, comme celui renvoyé par dataview.toJSON(). 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.

Événements

L'objet ChartWrapper génère les événements suivants. Notez que vous devez appeler ChartWrapper.draw() avant que des événements ne soient générés.

Nom Description Propriétés
error Déclenché en cas d'erreur lors de la tentative d'affichage du graphique identifiant, message
ready Le graphique est prêt pour les appels de méthode externe. Si vous souhaitez interagir avec le graphique et appeler des méthodes après l'avoir tracé, vous devez configurer un écouteur pour cet événement avant d'appeler la méthode draw et de ne les appeler qu'après le déclenchement de l'événement. Aucune
select Déclenché lorsque l'utilisateur clique sur une barre ou une légende Lorsqu'un élément de graphique est sélectionné, la cellule correspondante dans le tableau de données est sélectionnée. Lorsqu'une légende est sélectionnée, la colonne correspondante dans le tableau de données est sélectionnée. Pour savoir ce qui a été sélectionné, appelez ChartWrapper.getChart().getSelection(). Notez que cette valeur ne s'affiche que lorsque le type de graphique sous-jacent génère un événement de sélection. Aucune

Exemple

Les deux extraits de code suivants permettent de créer un graphique en courbes équivalent. Le premier exemple utilise la notation littérale JSON pour définir le graphique, le second utilise des 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 maintenant 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 d'encart qui permet à l'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 charge les packages pour vous si nécessaire.
  2. Créez un objet ChartWrapper qui définit le graphique que l'utilisateur peut personnaliser. Ce graphique s'affiche dans la boîte de dialogue, et l'utilisateur peut le modifier à l'aide de l'éditeur, modifier les types de graphiques 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 déclenché lorsque l'utilisateur clique sur le bouton "OK" dans la boîte de dialogue. Une fois le graphique modifié par l'utilisateur, vous devez appeler ChartEditor.getChartWrapper() pour le récupérer.
  4. Appelez ChartEditor.openDialog() en transmettant ChartWrapper. La boîte de dialogue s'ouvre. Les boutons 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

Méthode Valeur renvoyée Description
openDialog(chartWrapper, opt_options) nul

Ouvre l'éditeur de graphiques en tant que boîte de dialogue intégrée sur la page. La fonction renvoie un résultat immédiat. Elle n'attend pas que la boîte de dialogue soit fermée. Si vous ne perdez pas le champ d'application de l'instance, vous pouvez appeler openDialog() à nouveau pour rouvrir la boîte de dialogue, bien que vous deviez de nouveau transmettre un objet ChartWrapper.

  • chartWrapper : objet ChartWrapper définissant le graphique initial à afficher dans la fenêtre. Le graphique doit comporter un élément DataTable renseigné ou connecté à une source de données valide. Ce wrapper est copié en interne dans l'éditeur de graphique. Par conséquent, toute modification ultérieure que vous apporterez à votre handle ChartWrapper ne sera pas reflétée dans la copie de l'éditeur de graphique.
  • opt_options : [facultatif] objet contenant toutes les options de l'éditeur de graphique. Consultez le tableau des options ci-dessous.
getChartWrapper() ChartWrapper Renvoie un ChartWrapper représentant le graphique, avec des modifications utilisateur.
setChartWrapper(chartWrapper) nul

Utilisez cette méthode pour mettre à jour le graphique rendu dans l'éditeur.

chartWrapper : objet ChartWrapper représentant le nouveau graphique à afficher. Le graphique doit comporter un DataTable renseigné ou connecté à une source de données valide.

closeDialog() nul Ferme la boîte de dialogue de l'éditeur de graphiques.

Options

L'éditeur de graphiques accepte les options suivantes:

Nom Type Par défaut Description
dataSourceInput Poignée de l'élément ou "urlbox" nul

Permet à l'utilisateur de spécifier une source de données pour le graphique. Cette propriété peut être l'une des deux valeurs suivantes:

  • urlbox : affiche l'URL de la source de données du graphique dans une boîte de dialogue modifiable sur la boîte de dialogue. L'utilisateur peut le modifier, et le graphique est redessiné en fonction de la nouvelle source de données.
  • Élément DOM : permet de fournir un élément HTML personnalisé à utiliser pour sélectionner une source de données. Transmettez un handle à un élément HTML, soit créé dans le code, soit copié à partir de la page. Cet élément sera affiché dans la boîte de dialogue. Utilisez-le pour permettre à l'utilisateur de choisir la source de données du graphique. Par exemple, créez une zone de liste contenant plusieurs URL de sources de données ou des noms conviviaux que l'utilisateur pourra choisir. L'élément doit implémenter un gestionnaire de sélection et l'utiliser pour modifier la source de données du graphique. Par exemple, vous pouvez modifier la valeur DataTable sous-jacente ou modifier le champ dataSourceUrl du graphique.

Événements

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

Nom Description Propriétés
ok Déclenché lorsque l'utilisateur clique sur le bouton "OK" dans la boîte de dialogue. Après avoir reçu cette méthode, vous devez appeler getChartWrapper() pour récupérer le graphique configuré par l'utilisateur. none
cancel Déclenché lorsque l'utilisateur clique sur le bouton "Annuler" de la boîte de dialogue. none

Exemple

L'exemple de code suivant ouvre une boîte de dialogue d'éditeur de graphique avec un graphique en courbes rempli. Si l'utilisateur 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 des 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 joindre ou les regrouper par valeur de colonne.

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

Méthode Description
google.visualization.data.group Effectue une action SQL GROUP BY pour renvoyer une table regroupée par valeurs dans les colonnes spécifiées.
google.visualization.data.join Jointure de deux tables de données sur une ou plusieurs colonnes de clé

group()

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

Le tableau renvoyé inclut 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 qui correspondent à la combinaison de clés (par exemple, une somme ou un nombre de toutes les valeurs de la colonne spécifiée).

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

Syntaxe

google.visualization.data.group(data_table, keys, columns)
data_table [tableau_de_données]
L'entrée DataTable. Ce paramètre ne sera pas modifié en appelant group().
keys
Tableau de nombres et/ou d'objets spécifiant les colonnes à regrouper. La table de résultats inclut toutes les colonnes de ce tableau, ainsi que toutes les colonnes des colonnes. S'il s'agit d'un nombre, il s'agit d'un index de colonne du DataTable d'entrée à utiliser comme groupement. Si un objet est inclus, il inclut une fonction permettant de modifier la colonne spécifiée (par exemple, ajoutez 1 à la valeur de cette colonne). L'objet doit avoir les propriétés suivantes :
  • column : nombre qui est un index de colonne de dt auquel appliquer la transformation.
  • modifier : fonction qui accepte une valeur (la valeur de cellule dans cette colonne pour chaque ligne) et renvoie la valeur modifiée. Cette fonction permet de modifier la valeur de la colonne pour faciliter le regroupement. Par exemple, en appelant une fonction whichQuarter qui calcule un trimestre à partir d'une colonne de date, afin que l'API puisse regrouper les lignes par trimestre. La valeur calculée est affichée 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 définie ailleurs dans votre code (elle doit être comprise dans le champ d'application de l'appel). L'API fournit une fonction de modification simple. Suivez ces instructions pour créer vos propres fonctions plus utiles. Vous devez connaître le type de données que cette fonction peut accepter et l'appeler uniquement sur les colonnes de ce type. Vous devez également connaître le type renvoyé de cette fonction et le déclarer dans la propriété type décrite ci-dessous.
  • type : type renvoyé par la fonction modificateur de la fonction. Il doit s'agir d'un nom de type de chaîne JavaScript, par exemple "nombre" ou "booléen".
  • libellé : [facultatif] étiquette de chaîne pour attribuer cette colonne dans le DataTable renvoyé.
  • id : [facultatif] ID de chaîne à attribuer à cette colonne dans le DataTable renvoyé.

Exemples:[0], [0,2], [0,{column:1, modifier:myPlusOneFunc, type:'number'},2]
colonnes
[Facultatif] : permet de spécifier les colonnes à inclure dans la table de sortie, en plus des colonnes de clé. É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 la colonne de la première ligne de l'ensemble ou une moyenne de toutes les lignes de ce groupe. columns est un tableau d'objets avec les propriétés suivantes :
  • colonne : nombre indiquant l'index de la colonne à afficher.
  • aggregation : une fonction qui accepte un tableau de toutes les valeurs de cette colonne dans ce groupe de lignes et renvoie une seule valeur à afficher dans la ligne de résultats. La valeur renvoyée doit être du type spécifié par la propriété type de l'objet. Vous trouverez ci-dessous plus de détails 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 l'appeler uniquement sur les 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 ou consultez la section Créer une fonction d'agrégation pour savoir comment écrire votre propre fonction d'agrégation.
  • type : type renvoyé de la fonction d'agrégation. Il doit s'agir d'un nom de type de chaîne JavaScript, par exemple "nombre" ou "booléen".
  • étiquette : [facultatif] étiquette de chaîne à appliquer à cette colonne de la table renvoyée.
  • id : [facultatif] ID de chaîne à appliquer à cette colonne de la table renvoyée.

Valeur renvoyée

DataTable avec une colonne pour chaque colonne répertoriée dans keys et une colonne pour chaque colonne répertoriée dans columns. 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 modificateur suivantes que vous pouvez transmettre dans keys. modifier pour personnaliser le comportement de regroupement.

Fonction Type de tableau d'entrée Type renvoyé Description
google.visualization.data.month Date number (nombre) Pour une date donnée, la fonction renvoie la valeur du mois de base zéro (0, 1, 2, etc.).

Fonctions d'agrégation fournies

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

Fonction Type de tableau d'entrée Type renvoyé Description
google.visualization.data.avg number (nombre) number (nombre) Valeur moyenne du tableau transmis.
google.visualization.data.count tous les types number (nombre) Nombre de lignes dans le groupe. Les valeurs nulles et en double sont comptabilisées.
google.visualization.data.max nombre, chaîne, date nombre, chaîne, date, null Valeur maximale du tableau. Pour les chaînes, il s'agit du premier élément d'une liste triée par ordre lexicographique. Pour les valeurs de date, il s'agit de la date la plus récente. Les valeurs nulles sont ignorées. Renvoie la valeur "null" si aucune valeur maximale n'est définie.
google.visualization.data.min nombre, chaîne, date nombre, chaîne, date, null Valeur minimale du tableau. Pour les chaînes, il s'agit du dernier élément d'une liste triée par ordre lexicographique. Pour les valeurs de date, il s'agit de la date la plus ancienne. Les valeurs nulles sont ignorées. Renvoie la valeur "null" s'il n'y a pas de minimum.
google.visualization.data.sum number (nombre) number (nombre) La somme de toutes les valeurs du tableau.

Créer une fonction de modificateur

Vous pouvez créer une fonction de modificateur pour effectuer une transformation onkey simple 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), puis 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 renvoyées). Voici une implémentation de la fonction d'agrégation de nombres fournie, qui renvoie le nombre de lignes 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, semblable à une instruction SQL JOIN. Vous spécifiez une ou plusieurs paires de colonnes (colonnes key) entre les deux tables, et la table de sortie inclut les lignes selon une méthode de jointure que vous spécifiez: uniquement les lignes dans lesquelles 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 de résultats n'inclut que les colonnes de clé, plus 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 de colonne de clé spécifique. Ainsi, 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é pour effectuer une jointure avec dt2.
dt2
Valeur DataTable renseignée pour effectuer une jointure avec dt1. Cette table ne peut pas avoir plusieurs clés identiques (une clé étant une combinaison de valeurs de colonne de clé).
joinMethod ;
Chaîne spécifiant le type de jointure. Si dt1 comporte plusieurs lignes correspondant à une ligne dt2, la table de sortie inclut 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. Les lignes sans correspondance comportent des entrées de cellule nulles. Les lignes correspondantes sont jointes.
  • "inner" : la 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.
  • "right" : 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, le premier étant une clé dans dt1, le second est une clé dans dt2. Ce tableau peut spécifier des colonnes en fonction de leur index, identifiant ou libellé. Consultez la section getColumnIndex.
Les colonnes doivent être du même type dans les deux tables. Toutes les clés spécifiées doivent correspondre à la règle fournie par joinMethod pour inclure une ligne de la table. Les colonnes de clé sont toujours incluses dans la table de sortie. Seul dt1, le tableau de gauche, peut inclure des clés en double. Les clés de dt2 doivent être uniques. Le terme "clé" désigne ici un ensemble unique de colonnes de clé, et non des valeurs de colonne individuelles. Par exemple, si vos colonnes de clé sont A et B, le tableau suivant ne contiendrait que des valeurs de clé uniques (et pourrait donc être utilisée comme dt2):
R B
Jen Rouge
Jen Bleu
Fred Rouge
Exemple:[[0,0], [2,1]] compare les valeurs de la première colonne des deux tables ainsi que de la troisième colonne de dt1 avec la deuxième colonne de dt2.
dt1Colonnes
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, identifiant ou libellé. Consultez la section getColumnIndex.
dt2Colonnes
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, identifiant ou libellé. Consultez la section getColumnIndex.

Valeur renvoyée

DataTable avec les colonnes de clé dt1Columns et dt2Columns. Ce tableau est trié en fonction des colonnes de clé, de gauche à droite. Lorsque joinMethod est défini 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 affichera une valeur NULL 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

Formateurs

L'API Google Visualization fournit des outils de mise en forme qui peuvent être utilisés pour reformater les données d'une visualisation. Ces formateurs modifient la valeur formatée de la colonne spécifiée dans toutes les lignes. Gardez à l'esprit les points suivants :

  • Les outils de mise en forme ne modifient que les valeurs formatées, pas les valeurs sous-jacentes. Par exemple, la valeur affichée serait "1 000,00 $", mais la valeur sous-jacente serait encore "1 000".
  • Les outils de mise en forme n'affectent qu'une colonne à la fois. Pour reformater plusieurs colonnes, appliquez un outil de mise en forme à chaque colonne que vous souhaitez modifier.
  • Si vous utilisez également des formateurs définis par l'utilisateur, certains formateurs de visualisation Google remplaceront tous les formateurs définis par l'utilisateur.
  • La mise en forme appliquée aux données est dérivée des paramètres régionaux avec lesquels l'API a été chargée. Pour en savoir plus, consultez Charger des graphiques avec un paramètre régional spécifique.

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

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

    1. Obtenez votre objet DataTable renseigné.
    2. Pour chaque colonne à reformater :
      1. Créez un objet spécifiant toutes les options de votre outil de mise en forme. Il s'agit d'un objet JavaScript de base avec un ensemble de propriétés et de valeurs. Consultez la documentation de votre formateur pour connaître les propriétés compatibles. Vous pouvez éventuellement transmettre un objet de notation de littéral d'objet en spécifiant vos options.
      2. Créez votre outil de mise en forme en transmettant votre objet d'options.
      3. Appelez formatter.format(table, colIndex) en transmettant les numéros de colonne DataTable et (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 de la première.
        Important:De nombreux formateurs ont besoin que les balises HTML affichent 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 d'une colonne de dates 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 exposent les deux méthodes suivantes:

    Méthode Description
    google.visualization.formatter_name(options)

    Constructeur, où formatter_name est un nom de classe de formateur 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 spécifique pour connaître les options disponibles. Voici deux exemples d'appels du constructeur pour 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 de 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 formater plusieurs colonnes, vous devez appeler cette méthode plusieurs fois, avec des valeurs colIndex différentes.

     

    L'API de visualisation de Google fournit les formats 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 (Format de barre) Ajoute une barre de couleur dont l'orientation 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 sont comprises dans une plage spécifiée.
    Format de date Formate une valeur Date ou DateTime de différentes manières, par exemple "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 avec un texte arbitraire.

    Format de flèche

    Ajoute une flèche vers le haut ou vers le bas dans 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 n'est affichée.

    Options

    ArrowFormat accepte les options suivantes, qui sont transmises au constructeur:

    Option Description
    base

    Nombre indiquant la valeur de base, utilisée pour effectuer une comparaison avec la valeur de la cellule. Si la valeur de la cellule est supérieure, la cellule inclura une flèche verte vers le haut. Si la valeur de la cellule est inférieure, elle inclura une flèche rouge vers le bas. Si la valeur est la même, aucune flèche.

    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 de couleur à une cellule numérique indiquant 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, qui sont transmises au constructeur:

    Option

    Exemple

    Description
    base Nombre représentant la valeur de base par rapport à 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 de la valeur négative 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 "bleu".
    drawZeroLine Booléen indiquant s'il faut tracer une ligne de base sombre de 1 pixel en présence de valeurs négatives. La ligne foncée améliore la recherche visuelle des barres. La valeur par défaut est "false".
    max Valeur maximale de la plage de la barre. La valeur par défaut est la valeur la plus élevée du tableau.
    min Valeur minimale de la plage de la barre. La valeur par défaut est la valeur la plus basse 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 Vrai (true).
    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%'});

    Format de couleur

    Détermine les 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. Vous devez appeler 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 acceptable, 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 de couleur d'arrière-plan pour une cellule, en fonction de la valeur de la cellule. Toutes les cellules dont la valeur se situe dans les plages from à to spécifiées se voient attribuer les propriétés 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 de 1 000.

    • from : [String, Number, Date, DateTime, or TimeOfDay] La limite inférieure (incluse) de la plage, ou "null". Si la valeur est "null", elle correspond à "-∞". Les limites de chaîne sont comparées par ordre alphabétique aux valeurs de chaîne.
    • to : [String, Number, Date, DateTime, or TimeOfDay] La limite haute (non inclusive) de la plage, ou "null". Si la valeur est null, elle correspond à +∞. Les limites de chaîne sont comparées par ordre alphabétique aux valeurs de chaîne.
    • color : couleur à appliquer au texte des cellules correspondantes. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes constantes de couleur (par 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 (par 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 comprise entre une couleur de limite inférieure et une couleur de 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 avec précision. La plage la plus simple et la plus facile à lire consiste à utiliser une couleur entièrement saturée en blanc (par exemple, #FF0000—FFFFFF).

    • from : [Number, Date, DateTime, or TimeOfDay] : limite inférieure (incluse) de la plage, ou valeur null. Si la valeur est "null", elle correspond à "-∞".
    • to : [Number, Date, DateTime, or TimeOfDay] : limite supérieure (non incluse) de la plage, ou valeur null. Si la valeur est null, elle correspond à +∞.
    • color : 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 au bas du dégradé. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (par exemple, "#FF0000" ou "rouge").
    • toBgColor : couleur d'arrière-plan des cellules contenant des valeurs à l'extrémité supérieure du dégradé. Les valeurs peuvent être des valeurs "#RRGGBB" ou des constantes de couleur définies (par exemple, "#FF0000" ou "rouge").

     

    format(dataTable, columnIndex) Méthode format() standard pour appliquer la 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%'});

    Format de date

    Formate une valeur JavaScript Date de différentes manières, par exemple "1er janvier 2016", "01/01/16" et "1er janvier 2016".

    Options

    DateFormat accepte les options suivantes, qui sont transmises au constructeur:

    Option Description
    formatType

    Une 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é ci-dessous:

    • 'short' - Short format: ex. : "28/02/16"
    • "medium" : format moyen : "28 février 2016"
    • 'long' - Long format: ex. : "28 février 2016"

    Vous ne pouvez pas spécifier à la fois formatType et pattern.

    pattern

    Format 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. Pour en savoir plus sur les modèles, consultez 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 (négatif). Les objets de 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 de 17h sur un ordinateur situé à Greenwich en Angleterre et que vous avez spécifié le fuseau horaire défini sur -5 (options['timeZone'] = -5, heure de la côte Est des États-Unis), la valeur affichée sera 12h.

    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) Méthode format() standard pour appliquer la mise en forme à la colonne spécifiée.
    formatValue(value)

    Affiche 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 modèles de date

    Voici quelques informations supplémentaires sur les formats acceptés:

    Ces formats sont semblables au format de date et d'heure de l'ICU, mais les modèles suivants ne sont pas encore acceptés: A e D F g Y u w W. Pour éviter les conflits avec les modèles, tout texte littéral que vous souhaitez afficher dans le résultat doit être entouré de guillemets simples, à l'exception du guillemet simple, qui doit être doublé : "K 'o''clock.'".

    Modèle Description Exemple de résultat
    GG Era. "ANNONCE"
    aa ou aaaa année. 1996
    M

    Mois de l'année Pour janvier:

    • M produit 1
    • MM produit 01
    • MMM produit Jan
    • MMMM produit janvier

    "Juillet"

    "07"

    j Jour du mois Des "d" supplémentaires ajoutent des zéros au début. 10
    h Heure au format 12 heures. Des valeurs "h" supplémentaires seront ajoutées par 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 Minute en heures. Des valeurs "M" supplémentaires seront ajoutées au début des zéros. 30
    s Seconde dans la minute. Les valeurs "supplémentaires" ajoutent des zéros au début. 55
    S Deuxième fraction. Les valeurs "S" supplémentaires sont entourées de zéros à droite. 978
    E

    Jour de la semaine Résultats pour "mardi" :

    • E produit T
    • EE ou EEE produi des mardis ou du mardi
    • EEEE produit le mardi

    "Mar."

    "Mardi"

    aa AM/PM "PM"
    k Heure de la journée (1~24). Les valeurs "k" supplémentaires ajoutent des zéros au début. 24
    K Heure au format AM/PM (0-11). Les valeurs "k" supplémentaires ajoutent des zéros au début. 0
    z

    Fuseau horaire Pour le fuseau horaire 5, indique "UTC+5".

    "UTC+5"
    Z

    Fuseau horaire au format RFC 822. Pour le fuseau horaire -5:

    Z, ZZ, ZZZ produits -0500

    ZZZZ et plus génèrent "GMT -05:00"

    "-0800"

    "GMT -05:00"

    v

    Fuseau horaire (générique)

    "Etc/GMT-5"
    ' échapper pour le texte 'Date='
    '' guillemet simple yyy

    NombreFormat

    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 (un signe dollar, par exemple) ou de la ponctuation à utiliser comme repère des milliers.

    Options

    NumberFormat accepte les options suivantes, qui sont transmises au constructeur:

    Option Description
    decimalSymbol

    Un caractère à utiliser comme repère décimal. La valeur par défaut est un point (.).

    fractionDigits

    Nombre indiquant le nombre de chiffres à afficher après la virgule. La valeur par défaut est 2. Si vous spécifiez plus de chiffres que le nombre indiqué, des zéros s'affichent pour les valeurs inférieures. Les valeurs tronquées sont arrondies (cinq valeurs arrondies).

    groupingSymbol Caractère permettant de regrouper des chiffres à gauche de la décimale en ensembles de trois. La valeur par défaut est une virgule (,).
    negativeColor Couleur du texte pour les valeurs négatives. Aucune valeur par défaut. Les valeurs peuvent correspondre à n'importe quelle valeur de couleur HTML acceptable, telle que "rouge" ou "#FF0000".
    negativeParens Une 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'elles sont fournies, 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 d'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 pour 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) Méthode format() standard pour appliquer la mise en forme à la colonne spécifiée.
    formatValue(value)

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

    FormatFormat

    Permet de fusionner les valeurs des colonnes désignées en une seule colonne, avec le texte arbitraire. Par exemple, si vous aviez une colonne pour le prénom et une autre pour le nom de famille, vous pouvez insérer une troisième colonne avec {last name}, {first name}. Cet outil de mise en forme ne respecte pas les conventions du constructeur et 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 options. Elle utilise à la place un paramètre de pattern de chaîne. Il s'agit d'une chaîne qui décrit les valeurs de colonne à inclure 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'index est un index du tableau srcColumnIndexs de la méthode format() ci-dessous. Pour inclure un caractère { ou } littéral, échappez-le comme suit: \{ ou \}. Pour inclure un littéral \, échappez-le en \\.

    Exemple de code

    L'exemple suivant illustre un constructeur pour un modèle qui crée un élément d'ancrage, avec les premier et deuxième éléments 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 opérer.
    • srcColumnIndexs : tableau d'un ou plusieurs index de colonne (basés sur zéro) à utiliser comme sources à partir du DataTable sous-jacent. Il sera utilisé comme source de données pour le paramètre pattern dans le constructeur. Les numéros de colonne n'ont pas nécessairement besoin d'être triés.
    • opt_dstColumnIndex : [facultatif] colonne de destination où placer la sortie de la manipulation du pattern. S'il n'est pas spécifié, le premier élément de srcColumIndexs 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. Il 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%'});

    Gadget Helper

    Classe d'aide pour simplifier l'écriture de gadgets utilisant l'API Google Visualization.

    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 définies dans les préférences du gadget. Le type du paramètre prefs est _IG_Prefs
    1. La préférence _table_query_url permet de définir l'URL de la source de données de la requête.
    2. 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 : enveloppe 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, Chaîne] à laquelle envoyer la requête. Consultez la documentation relative aux graphiques et aux feuilles de calcul concernant les feuilles de calcul Google.
    opt_options.
    [Facultatif, Objet] : mappage d'options pour la requête. Remarque: Si vous accédez à une source de données restreinte, vous ne devez pas utiliser ce paramètre. Voici les propriétés compatibles :
    • 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' : envoie la requête à l'aide de XmlHttpRequest.
      • 'scriptInjection' : envoie la requête à l'aide d'une 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. Si spécifié, vous devez également spécifier makeRequestParams.
      • 'auto' : utilisez 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 l'élément tqrt est manquant ou qu'il contient une valeur non valide, la valeur par défaut est "xhr" pour les requêtes du même domaine et "scriptInjection" pour les requêtes interdomaines.
    • makeRequestParams : [objet] : mappage de paramètres pour une requête makeRequest(). Utilisé et obligatoire uniquement si sendMethod est "makeRequest".

    Méthodes

    Méthode Valeur renvoyée Description
    abort() Aucune Arrête l'envoi de requête automatisé démarré avec setRefreshInterval().
    setRefreshInterval(seconds) Aucune

    Définit la requête pour qu'elle appelle automatiquement la méthode send toutes les durées spécifiées (en secondes), à partir du premier appel explicite vers 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 la rappelant avec zéro (valeur par défaut) ou en appelant abort().

    setTimeout(seconds) Aucune Définit le nombre de secondes d'attente de la réponse de la source de données avant de générer 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, cette méthode doit être appelée avant d'appeler la méthode send.
    setQuery(string) Aucune Définit la chaîne de requête. La valeur du paramètre string doit être une requête valide.
    Si cette méthode est utilisée, elle doit être appelée avant la méthode send. En savoir plus sur le langage de requête
    send(callback) Aucune Envoie la requête à la source de données. callback doit être une fonction appelée lorsque la source de données répond. La fonction de rappel reçoit un seul paramètre de type google.visualization.QueryResponse.

    Requête

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

    Méthodes

    Méthode Valeur renvoyée Description
    getDataTable() Tableau de données Renvoie la table de données telle qu'elle est 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 Affiche un message d'erreur détaillé pour les requêtes ayant échoué. Si l'exécution de la requête a abouti, cette méthode renvoie une chaîne vide. Le message renvoyé est destiné aux développeurs et peut contenir des informations techniques, par exemple "Colonne {salary} inexistant".
    getMessage() Chaîne Renvoie un court message d'erreur pour les requêtes ayant échoué. Si l'exécution de la requête a abouti, 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 de zéro entrée. Chaque entrée est une chaîne courte avec 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 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 si 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 conteneur sur la page (généralement un <div>) dans lequel l'API dessine un message d'erreur mis en forme. Ce conteneur peut être l'élément conteneur de visualisation ou un conteneur destiné uniquement aux erreurs. Si vous spécifiez l'élément de visualisation, le message d'erreur sera affiché 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 des fonctions statiques de l'espace de noms google.visualization.errors.

    De nombreuses visualisations peuvent générer un événement d'erreur. Consultez la section "Événement d'erreur" ci-dessous pour en savoir plus.

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

    Fonction Valeur renvoyée Description
    addError(container, message, opt_detailedMessage, opt_options) Valeur de l'ID de chaîne qui identifie l'objet d'erreur créé. Il s'agit d'une valeur unique sur la page. Elle permet de supprimer l'erreur ou de rechercher l'élément qui la contient.

    Ajoute un bloc d'affichage d'erreur à l'élément de page spécifié, avec le texte et la mise en forme spécifiés.

    • container : é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 à afficher.
    • opt_detailedMessage : chaîne de message détaillée facultative. Par défaut, il s'agit d'un texte survolé par la souris, mais vous pouvez le modifier dans la propriété opt_options.showInToolTip décrite ci-dessous.
    • opt_options : objet facultatif dont les propriétés définissent diverses options d'affichage pour le message. Les options suivantes sont acceptées :
      • showInTooltip : valeur booléenne où "true" affiche le message détaillé seulement 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 Vrai (true).
      • 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 pour le message d'erreur. Ce style remplacera tous les styles appliqués au type d'avertissement (opt_options.type). Exemple : 'background-color: #33ff99; padding: 2px;'La valeur par défaut 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 "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'a pas indiqué d'erreur. Il s'agit d'une valeur unique sur la page. Elle permet de supprimer l'erreur ou de rechercher l'élément qui la contient.

    Transmettre une conteneur de réponse et de message d'erreur à cette méthode: si la réponse de requête indique une erreur de requête, affiche un message d'erreur dans l'élément de page spécifié. Si la réponse est nulle, la méthode renverra une erreur JavaScript. Transmettez à votre message la QueryResponse reçue dans votre gestionnaire de requêtes pour afficher une erreur. Elle définit également le style d'affichage en fonction du type (erreur ou avertissement, semblable à addError(opt_options.type)).

    • container : é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 : 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 ID.

    • id : ID de chaîne d'une erreur créée à l'aide de addError() ou addErrorFromQueryResponse().
    removeAll(container) Aucune

    Supprime tous les blocs d'erreurs d'un conteneur spécifié. Si le conteneur spécifié n'existe pas, une erreur est générée.

    • container : é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) Identifiant d'un élément DOM contenant l'erreur spécifiée, ou valeur null si l'élément 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 qu'un événement s'est produit. En tant qu'utilisateur du graphique, vous voudrez souvent écouter ces événements. Si vous codez votre propre visualisation, vous pouvez également déclencher vous-même ces événements.

    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.

    addListener()

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

    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 l'événement source_visualization est déclenché. La fonction de gestion transmet les arguments d'événements en tant que paramètres.

    Renvoie

    Gestionnaire d'écouteurs pour le nouvel écouteur. Vous pouvez utiliser le gestionnaire pour supprimer cet écouteur ultérieurement 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 valeur est identique à addListener(), mais est destinée aux événements qui ne doivent être écoutés qu'une seule fois. Les lancers suivants de l'événement n'appellent pas la fonction de traitement.

    Voici un exemple de cas d'utilisation: chaque tirage entraîne un événement ready. Si vous souhaitez que seul le premier élément ready exécute votre code, privilégiez 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)
    gestionnaire_listener
    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
    Un handle vers l'instance de visualisation source à partir duquel tous les écouteurs d'événements doivent être supprimés.

    trigger()

    Appelées par les implémenteurs de visualisations. 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, vous pouvez simplement 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, nom : "Fred"}. Vous pouvez transmettre "null" si aucun événement n'est nécessaire. Le destinataire doit être prêt à accepter "null" pour ce paramètre.

    Exemple

    Voici un exemple de visualisation qui invoque une méthode nommée "select" lorsque sa méthode onclick est appelée. Il ne transmet 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);
    }

    Propriétés et méthodes de visualisation standards

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

    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 avoir le nom de votre classe de visualisation et renvoyer une instance de cette classe.

    visualization_class_name(dom_element)
    élément_dom
    Un 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, vous pouvez récupérer un graphique sur un serveur ou créer le graphique 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é dans 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 aucune méthode standard pour extraire un DataTable d'un graphique.
    options
    [Facultatif] Mappage des paires nom/valeur des options personnalisées. Exemples : hauteur et largeur, couleurs d'arrière-plan et sous-titres. La documentation sur la visualisation doit lister les options disponibles et doit être compatible avec les options par défaut si vous ne spécifiez pas ce paramètre. Vous pouvez utiliser la syntaxe de littéral d'objet JavaScript pour transmettre un mappage d'options : {x:100, y:200, title:'An Example'}

    Exemple

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

    getAction()

    Elle est éventuellement visible par les visualisations qui ont des info-bulles et autorisent les actions d'info-bulle.

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

    Exemple :

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

    getSelection()

    Il est éventuellement exposé par les visualisations qui vous permettent 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 de la table sous-jacente permettant de créer la visualisation (une DataView ou une DataTable). Chaque objet possède les propriétés row et/ou column, ainsi que 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 valeurs 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 à 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()

    Elle est éventuellement visible par les visualisations qui ont des info-bulles et autorisent les actions d'info-bulle.

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

    Exemple :

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

    setAction()

    Elle est éventuellement visible par les visualisations qui ont des info-bulles et autorisent les actions d'info-bulle. Il ne fonctionne que pour les graphiques de base (barres, colonnes, lignes, aire, disperser, combo, bulle, tarte, beignet, chandelier, histogramme, aire 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 (l'ID de l'action définie, text), le texte qui doit apparaître dans l'info-bulle, et action, la fonction à exécuter lorsqu'un utilisateur clique sur le texte de l'action.

    Toutes les actions de l'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 de l'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()

    Cette option permet de sélectionner 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 la nouvelle sélection. L'implémentation de setSelection() ne doit pas déclencher d'événement "select". Les visualisations peuvent ignorer une partie de la sélection. Par exemple, une table ne pouvant afficher que des lignes sélectionnées peut ignorer les é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() avec les éléments pour rester sélectionnés ; pour désélectionner tous les éléments, appelez setSelection(), setSelection(null) ou setSelection([]).

    setSelection(selection_array)
    tableau_sélection
    Tableau d'objets, chacun avec une propriété de ligne et/ou de colonne numérique. row et column sont le numéro de ligne ou de colonne basé sur zéro d'un élément du tableau de données à sélectionner. Pour sélectionner une colonne entière, définissez la valeur 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 aux coordonnées (0,1) et toute la ligne 1.

    Différentes 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 la convertit en table 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 (ligne d'en-tête de colonne) du tableau ({label: 'Start Date', type: 'date'}, par exemple). Les rôles de données facultatifs peuvent également être utilisés, mais ils doivent être définis explicitement à l'aide de la notation de littéral d'objet. La notation de littéral 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
    Un tableau bidimensionnel, 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 est interprétée comme une étiquette d'en-tête. Les types de données de chaque colonne sont interprétés automatiquement à partir des données fournies. Si aucune valeur n'est indiquée dans une cellule, indiquez une valeur nulle ou vide.
    opt_firstRowIsData.
    Indique si la première ligne définit une ligne d'en-tête ou non. 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 supposée être 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 façons 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 en un seul appel. L'avantage de cette méthode est qu'elle nécessite moins de code, et que vous pouvez sérialiser et enregistrer des visualisations sous forme de chaînes de texte à réutiliser. Cette méthode ne renvoie pas de handle vers le graphique créé. Vous ne pouvez donc pas affecter des écouteurs de méthode pour intercepter les événements du graphique.

    Syntaxe

    google.visualization.drawChart(chart_JSON_or_object)
    chart_JSON_or_object
    Il s'agit soit d'une chaîne littérale JSON, soit d'un objet JavaScript, avec les propriétés suivantes (sensibles à la casse) :
    Propriété Type Obligatoire Par défaut Description
    type de graphique Chaîne Obligatoire none Nom de classe de la visualisation. Le nom du package google.visualization peut être omis pour les graphiques Google. Si la bibliothèque de visualisation appropriée n'a pas encore été chargée, cette méthode la chargera pour vous 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 la page qui hébergera la visualisation.
    options Objet Facultative none Objet décrivant les options de la visualisation. Vous pouvez utiliser une notation littérale JavaScript ou fournir un handle vers l'objet. Exemple : "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
    Table des données Objet Facultative Aucune DataTable utilisé pour renseigner la visualisation. Il peut s'agir d'une représentation littérale au format JSON d'une table de données, comme décrit ci-dessus, d'un handle vers un objet google.visualization.DataTable renseigné ou d'un tableau bidimensionnel tel que celui accepté par arrayToDataTable(opt_firstRowIsData=false) . Vous devez spécifier cette propriété ou la propriété dataSourceUrl.
    URL de la source de données Chaîne Facultative Aucune Une requête de source de données pour insérer les données du graphique (par exemple, une feuille de calcul Google) Vous devez spécifier cette propriété ou la propriété dataTable.
    query Chaîne Facultative Aucune 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.
    IntervalleIntervalle Number Facultative Aucune Fréquence d'actualisation (en secondes) de la source de la requête dans la visualisation. Utilisez-la uniquement lorsque vous spécifiez dataSourceUrl.
    vue Objet OU Tableau Facultative Aucune Définit un objet initialiseur DataView qui agit comme un filtre sur les données sous-jacentes, tel que défini 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, le premier DataView du tableau est appliqué aux données sous-jacentes pour créer une table de données, le second DataView est appliqué à la table de données résultant de l'application du premier DataView, et ainsi de suite.

    Exemples

    Crée un graphique de tableau à partir d'une source de données de 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 en local:

    <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 JSON du graphique, 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 visualisation dans différents formats ou de fournir une version intégrable de la visualisation pour une utilisation à différents endroits. Pour en savoir plus et obtenir un exemple de code, consultez la page de la barre d'outils.