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'}] ]);
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()
etaddRows()
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 |
---|---|---|
OU
|
Number |
Ajoute une nouvelle colonne au tableau de données et affiche l'index de la nouvelle colonne. Une valeur La première signature contient les paramètres suivants:
La deuxième signature possède un paramètre d'objet unique comprenant les membres suivants:
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.
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.
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.
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 |
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
|
getColumnProperty(columnIndex, name)
|
Automatique |
Renvoie la valeur d'une propriété nommée ou
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
|
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.
Le type de colonne renvoyé est l'un des suivants: |
getDistinctValues(columnIndex) |
Tableau d'objets |
Renvoie les valeurs uniques d'une colonne donnée, par ordre croissant.
Le type des objets renvoyés est identique à celui renvoyé par la méthode |
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
Une autre propriété facultative,
Exemple: |
getFormattedValue(rowIndex, columnIndex)
|
Chaîne |
Renvoie la valeur formatée de la cellule aux index de ligne et de colonne donnés.
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
|
getProperty(rowIndex, columnIndex, name)
|
Automatique |
Renvoie la valeur d'une propriété nommée ou
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
|
getRowProperty(rowIndex, name)
|
Automatique |
Renvoie la valeur d'une propriété nommée ou
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
La valeur renvoyée est un tableau de nombres. Chaque nombre est un index de ligne
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. 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
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.
Le type de la valeur renvoyée dépend du type de colonne (voir getColumnType):
|
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.
Voir aussi : addColumn |
insertRows(rowIndex, numberOrArray) |
Aucune |
Insère le nombre de lignes spécifié dans l'index de ligne spécifié.
Voir aussi:addRows |
removeColumn(columnIndex) |
Aucune |
Supprime la colonne au niveau de l'index spécifié.
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é.
Voir aussi : removeColumn |
removeRow(rowIndex) |
Aucune |
Supprime la ligne au niveau de l'index spécifié.
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é.
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.
Voir aussi : setValue(), setFormattedValue(), setProperty() et setProperties(). |
setColumnLabel(columnIndex, label)
|
Aucune |
Définit le libellé d'une colonne.
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.
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.
Voir également : setColumnProperty getColumnProperty |
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
Aucune |
Définit la valeur mise en forme d'une cellule.
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.
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.
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.
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.
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.
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.
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.
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]
-
"boolean" : valeur booléenne JavaScript ("true" ou "false"). Exemple de valeur :
-
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). SiDataTable
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'}]
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.
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ésf
etp
. -
f
[Facultatif] Version de la valeurv
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écifiezDate(2008, 0, 1)
pourv
, vous devez spécifier "1er janvier 2008" ou une chaîne similaire pour cette propriété. Cette valeur n'est pas comparée à la valeurv
. 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 dev
sera automatiquement générée à l'aide du formateur par défaut. Les valeursf
peuvent être modifiées avec votre propre outil de mise en forme, définies avecsetFormattedValue()
ousetCell()
, ou récupérées avecgetFormattedValue()
. -
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éthodesgetProperty()
etgetProperties()
. 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 deDataTable
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éthodessetRows() 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 valeurDataView
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 appelerdraw()
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
ouDataView
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éthodesset...()
ouhide...()
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éerDataView
, 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.
Exemple: Si |
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.
Exemple : Si |
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.
Exemple : Si |
getViewColumns() |
Tableau de nombres |
Renvoie les colonnes de cette vue, dans l'ordre. Autrement dit, si vous appelez |
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.
Exemple : Si |
getViewRows() |
Tableau de nombres |
Renvoie les lignes de cette vue, dans l'ordre. Autrement dit, si vous appelez |
hideColumns(columnIndexes) |
none |
Masque les colonnes spécifiées de la vue actuelle.
Exemple : Si vous avez une table avec 10 colonnes et que vous appelez |
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) |
Aucune |
Masque les lignes spécifiées de la vue actuelle.
Exemple : Si vous avez une table avec 10 lignes et que vous appelez |
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é.
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) |
Aucune |
Définit les lignes visibles dans cette vue, en fonction des numéros d'index de la table/vue sous-jacente.
Exemple : Pour créer une vue avec les lignes 3 et zéro d'une table/vue sous-jacente : |
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.
|
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
Toutes les modifications que vous apporterez à l'objet renvoyé seront reflétées par le graphique la prochaine fois que vous appellerez |
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
|
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:
-
Chargez le package
charteditor
. Dansgoogle.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. -
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. -
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. -
Appelez
ChartEditor.openDialog()
en transmettantChartWrapper
. La boîte de dialogue s'ouvre. Les boutons de dialogue permettent à l'utilisateur de fermer l'éditeur. L'instanceChartEditor
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. - 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
|
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 |
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:
|
É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 appelantgroup()
. - 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 [[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.
- Obtenez votre objet
DataTable
renseigné. - Pour chaque colonne à reformater :
- 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.
- Créez votre outil de mise en forme en transmettant votre objet d'options.
-
Appelez
formatter
.format(table, colIndex)
en transmettant les numéros de colonneDataTable
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 optionallowHtml
, vous devez la définir sur "true".
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:
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.
// 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.
|
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 | ExempleDescription |
---|---|
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.
|
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 à
|
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:
Vous ne pouvez pas spécifier à la fois |
pattern |
Format de format personnalisé à appliquer à la valeur, semblable au format de date et d'heure de l'ICU.
Par exemple :
Vous ne pouvez pas spécifier à la fois |
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 |
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:
|
"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" :
|
"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
La chaîne de format est un sous-ensemble de l'ensemble de modèles d'ICU.
Par exemple, |
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 |
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
Exemple de codeL'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 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:
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
|
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émenttqrt
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".
-
sendMethod : [facultatif, chaîne] spécifie la méthode à utiliser pour envoyer la requête. Choisissez l'une des valeurs de chaîne suivantes :
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 Si vous utilisez cette méthode, vous devez l'appeler avant d'appeler la méthode
Annulez cette méthode en la rappelant avec zéro (valeur par défaut) ou en appelant |
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 :
|
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.
|
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 à
|
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.
|
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.
|
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.
|
É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.
- google.visualization.events.addListener() et google.visualization.events.addOneTimeListener() écoute les événements
- google.visualization.events.removeListener() supprime un écouteur existant
- google.visualization.events.removeAllListeners() supprime tous les écouteurs d'un graphique spécifique.
- google.visualization.events.trigger() déclenche un événement.
addListener()
Appelez cette méthode pour vous inscrire et recevoir 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.
- Constructeur
- draw()
- getAction() [facultatif]
- getSelection() [facultatif]
- removeAction() [facultatif]
- setAction() [facultatif]
- setSelection() [facultatif)
Remarque: Ces méthodes se trouvent dans l'espace de noms de la visualisation, et non dans l'espace de noms google.visualization.
Constructeur
Le constructeur doit 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
ouDataView
contenant les données à utiliser pour dessiner le graphique. Il n'existe aucune méthode standard pour extraire unDataTable
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
etcolumn
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 valeurrow
sur null. Pour sélectionner une ligne entière, définissezcolumn
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.