Cette page décrit le concept et l'utilisation des rôles dans les tables de données des graphiques.
- Présentation des rôles
- Quels sont les rôles disponibles ?
- Hiérarchie et associabilité des rôles
- Attribuer un rôle
Présentation des rôles
Les objets Google DataTable et DataView sont désormais compatibles avec les rôles de colonne explicitement attribués. Le rôle de colonne décrit l'objectif des données de cette colonne. Par exemple, une colonne peut contenir des données décrivant le texte d'une info-bulle, des annotations de points de données ou des indicateurs d'incertitude. La plupart des rôles de colonne s'appliquent à la colonne "data" qui la précède, qu'elle soit juste avant ou avant la première colonne d'un groupe consécutif de rôles. Par exemple, vous pouvez avoir deux colonnes après une colonne "données", l'une pour "info-bulle" et l'autre pour "annotation". Toutefois, après la colonne "domain", nous autorisons généralement les rôles de colonne "annotation" et "annotationText".
Remarque: Si vous souhaitez contrôler le contenu des info-bulles qui s'affichent lorsque l'utilisateur pointe sur un graphique, consultez les info-bulles.
À l'origine, seuls deux rôles étaient disponibles pour une colonne: "domain", qui spécifie les principales valeurs des axes, et "data", qui spécifie la hauteur des barres, la largeur des secteurs, etc. Ces rôles ont été attribués implicitement, en fonction de l'ordre et du type des colonnes de la table. Toutefois, avec la possibilité d'attribuer explicitement des rôles de colonne, vous pouvez désormais ajouter des colonnes facultatives qui fournissent de nouvelles fonctionnalités intéressantes à un graphique, telles que des étiquettes d'annotation arbitraires, du texte d'infobulle et des barres d'incertitude.
Si vous n'attribuez pas explicitement le rôle d'une colonne, celui-ci est déduit de l'ordre de la colonne dans la table, conformément à la spécification du format de données du graphique. Cette page vous présente les rôles que vous pouvez attribuer explicitement, ainsi que la manière de les attribuer.
Voici une comparaison de ce que vous pouvez faire avec un graphique en courbes n'utilisant que les rôles déduits par défaut, par rapport à d'autres rôles attribués explicitement.
Format de la table de données d'un graphique en courbes:
| Colonne 0 | Colonne 1 | ... | Colonne N | |
|---|---|---|---|---|
| Objectif | Valeurs de la ligne 1 | ... | Valeurs de la ligne N | |
| Type de données | Nombre | ... | Nombre | |
| Rôle | domaine | Données | ... | Données |
| Rôles facultatifs compatibles avec les colonnes |
|
|
... |
|
| Graphique sans rôles de colonne explicites | Graphique avec des rôles de colonne explicites |
|---|---|
|
|
|
Ce graphique n'applique pas explicitement les rôles. Par conséquent, vous ne pouvez utiliser que la disposition de base en colonnes des données et des domaines présentée ci-dessus. Table de données: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addRows([
['April',1000],
['May', 1170],
['June', 660],
['July', 1030]
]); |
Ce graphique attribue les rôles explicitement, et les colonnes facultatives peuvent donc être ajoutées. Ce graphique comporte des colonnes facultatives pour les rôles d'annotation, d'annotationText, d'intervalle et de certitude.
Table de données: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'string', role:'annotation'}); // annotation role col.
data.addColumn({type:'string', role:'annotationText'}); // annotationText col.
data.addColumn({type:'boolean',role:'certainty'}); // certainty col.
data.addRows([
['April',1000, 900, 1100, 'A','Stolen data', true],
['May', 1170, 1000, 1200, 'B','Coffee spill', true],
['June', 660, 550, 800, 'C','Wumpus attack', true],
['July', 1030, null, null, null, null, false]
]); |
Quels sont les rôles disponibles ?
Le tableau suivant répertorie tous les rôles compatibles avec Google Charts. Tous les rôles ne sont pas compatibles avec tous les types de graphiques. La documentation de chaque graphique décrit les rôles disponibles et leur emplacement. Les rôles sont affichés différemment selon les types de graphiques.
| Rôle | Description | Exemple |
|---|---|---|
| annotation | Texte à afficher sur le graphique à côté du point de données associé. Le texte s'affiche sans intervention de l'utilisateur. Les annotations et le texte des annotations peuvent être attribués à la fois aux points de données et aux catégories (étiquettes d'axe). Il existe deux styles d'annotations: point (par défaut), qui trace le texte de l'annotation à proximité du point spécifié, et ligne, qui trace le texte de l'annotation sur une ligne qui divise la zone du graphique en deux. Vous pouvez spécifier le style de ligne en définissant cette option de graphique: Type de données: chaîne Par défaut: chaîne vide |
Données: label: 'Year', 'Sales', null, null, 'Expenses', null, null
role: domain, data, annotation, annotationText, data, annotation, annotationText
'2004', 1000, null, null, 400, null, null
'2005', 1170, '6'2', null', '6', null', '6' 2
Les « A » et « B » de ce graphique sont des annotations. Pointez sur l'annotation pour en afficher le texte. Notez que vous devez passer la souris sur l'annotation, et non sur le point de données auquel elle est appliquée, pour afficher la valeur annotationText. Les valeurs nulles sont acceptées pour les cellules annotation et annotationText. Toutefois, si vous disposez d'une valeur annotationText, celle-ci doit être associée à une valeur d'annotation. |
| annotationText | Texte étendu à afficher lorsque l'utilisateur pointe sur l'annotation associée. Les annotations et le texte des annotations peuvent être attribués à la fois aux points de données et aux catégories (étiquettes d'axe). Si vous disposez d'une colonne annotationText, vous devez également avoir une colonne d'annotation. En revanche, le texte d'info-bulle s'affiche lorsque l'utilisateur pointe sur le point de données associé dans le graphique. Type de données: chaîne Par défaut: chaîne vide |
|
| certitude | Indique si un point de données est certain ou non. Le mode d'affichage dépend du type de graphique. Il peut, par exemple, être indiqué par des lignes en pointillés ou un remplissage rayé. Pour les graphiques en courbes et en aires, le segment entre deux points de données est certain si et seulement si les deux points de données sont certains. Type de données: booléen, où "true" est certain et "false" est incertain. Valeur par défaut: true |
|
| emphase | Met l'accent sur les points de données spécifiés du graphique. Elle est affichée sous la forme d'une ligne épaisse et/ou d'un grand point. Pour les graphiques en courbes et en aires, le segment entre deux points de données est mis en évidence si et seulement si les deux points de données sont accentués. Type de données: booléen Valeur par défaut : "false" |
Données: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, emphasis, data, emphasis
'2004', 1000, true, 400, false
'2005', 1170, true, 460, true
'2006', 660, false, 1120, true
'2007', 1030, false, 540, true
Dans ce graphique, la série "Ventes" comporte un segment accentué, désigné par la troisième colonne, les lignes 1 et 2. La série "Dépenses" comporte deux segments accentués, désignés par la cinquième colonne : les lignes deux, trois et quatre. Notez que l'accentuation nécessite de mettre en valeur les deux points de délimitation. |
| intervalle | Indique une plage de données potentielle pour un point spécifique. Les intervalles sont généralement affichés sous la forme d'indicateurs de plage de style "I-bar". Les colonnes d'intervalle sont des colonnes numériques. Ajoutez les colonnes d'intervalle par paires, en marquant les valeurs basse et haute de la barre. Les valeurs d'intervalle doivent être ajoutées par ordre croissant, de gauche à droite. Type de données: nombre Par défaut: aucun intervalle |
Données: label: 'Day', 'Stock value', null, null
role: domain, data, interval, interval
'Mon', 38, 20, 45
'Tue', 55, 31, 66
'Wed', 77, 50, 80
'Thurs', 66, 50, 77
Dans ce graphique, les valeurs d'intervalle définissent une barre en I autour des points. Les valeurs augmentent de gauche à droite. L'intervalle le plus élevé et le plus bas autour d'un point marque le haut et le bas de la barre. Remarque: Pour en savoir plus sur les intervalles, consultez la section Intervalles. |
| portée | Indique si un point est dans le champ d'application ou hors du champ d'application. Si un point est hors de la portée, il est visuellement minimisé. Pour les graphiques en courbes et en aires, le segment entre deux points de données entre dans le champ d'application si l'un ou l'autre des points de terminaison entre dans le champ d'application. Type de données: booléen, où "true" correspond au champ d'application. Valeur par défaut: true |
Données: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, scope, data, scope
'2004', 1000, false, 400, true
'2005', 1170, false, 460, false
'2006', 660, true, 1120, false
'2007', 1030, true, 540, false
La première colonne d 'étendue s'applique à la colonne de données de ventes, à sa gauche. Le premier segment est affiché hors du champ d'application, car les deux points limites ne sont pas concernés. La deuxième colonne de champ d'application s'applique à la colonne de données "Dépenses", à sa gauche. Le premier segment est marqué comme étant dans la portée, car l'un de ses points limites entre dans le champ d'application ; le reste de la ligne est hors du champ d'application, car tous les autres points sont marqués comme hors du champ d'application. |
| style |
Appliquez un style à certaines propriétés de différents aspects de vos données. Ces valeurs sont les suivantes:
Type de données: chaîne, où plusieurs styles peuvent être appliqués à l'aide d'une syntaxe Valeur par défaut: null |
Données:
label: 'Character', 'Popularity', 'Style',
role: domain, data, style,
'Hulk', 50, 'color: green',
'Captain America', 75, 'color: #0000cf;' +
'stroke-color: #cf001d',
'Wolverine', 90, 'opacity: 0.5;' +
'stroke-width: 5;' +
'stroke-color: #01a0ff;' +
'fill-color: #fff600',
'Iron Man', 60, 'color: #db9500;' +
'stroke-width: 10;' +
'stroke-color: #a30300',
'Spider Man', 100, 'bar {' +
'fill-color: #c8001d;' +
'stroke-width: 3;' +
'stroke-color: #1800c8}'
Dans ce graphique, chaque barre est stylisée indépendamment des autres à l'aide du rôle de colonne Remarque: Vous trouverez plus de détails sur la personnalisation du style des points, des lignes et des barres dans une autre section. Consultez également les options de chaque type de graphique, où des styles peuvent être spécifiés pour d'autres types d'entités, tels que des zones, du texte et des zones. |
| info-bulle |
Texte à afficher lorsque l'utilisateur pointe sur le point de données associé à cette ligne. Remarque:cela n'est pas pris en charge par la visualisation Graphique à bulles. Le contenu des info-bulles HTML du graphique à bulles n'est pas personnalisable. Type de données: chaîne Par défaut: valeur du point de données |
Données: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, tooltip, data, tooltip
'2004', 1000, '1M$ sales, 400, '$0.4M expenses
in 2004' in 2004'
'2005', 1170, '1.17M$ sales, 460, '$0.46M expenses
in 2005' in 2005'
'2006', 660, '.66$ sales, 1120, '$1.12M expenses
in 2006' in 2006'
'2007', 1030, '1.03M$ sales, 540, '$0.54M expenses
in 2007' in 2007'
Pointez sur les points de données pour afficher le texte de l'info-bulle. Les données d'info-bulle sont attribuées à tous les points des deux lignes, dans les colonnes 3 et 5. Remarque: Pour en savoir plus sur la personnalisation des info-bulles, consultez la section Info-bulles. |
| domaine | Vous ne devriez pas avoir besoin d'attribuer ce rôle explicitement, sauf si vous concevez un graphique multidomaine (illustré ici). Le format de base de la table de données permet au moteur de création de graphiques d'identifier les colonnes correspondant à des domaines. Toutefois, vous devez savoir quelles colonnes sont des colonnes de domaine afin de savoir quelles autres colonnes peuvent les modifier. Les colonnes des domaines spécifient les étiquettes le long du grand axe du graphique. Plusieurs colonnes de domaine peuvent parfois être utilisées pour prendre en charge plusieurs échelles dans le même graphique. Type de données: généralement chaîne, mais parfois un nombre ou une date |
Données:
label: '2009, '2009, '2009, '2008, '2008 '2008
Quarter', Sales', Expenses', Quarter', Sales', Expenses'
role: domain, data, data, domain, data, data
'Q1/09', 1000, 400, 'Q1/08', 800, 300
'Q2/09', 1170, 460, 'Q2/08', 750, 400
'Q3/09', 660, 1120, 'Q3/08', 700, 540
'Q4/09', 1030, 540, 'Q4/08', 820, 620
Cet exemple illustre un graphique multidomaine. Les deux premières colonnes de données modifient le premier domaine ("Trimestre 2009") et les deux dernières colonnes de données le deuxième domaine ("Trimestre 2008"). Les deux domaines sont superposés sur les mêmes échelles d'axe. |
| données | Il n'est pas nécessaire d'attribuer ce rôle explicitement. En effet, le format de base de la table de données permet au moteur de création de graphiques d'identifier les colonnes correspondant à des domaines. Cependant, vous devez savoir quelles colonnes sont des colonnes de données afin de savoir quelles autres colonnes peuvent les modifier. Les colonnes des rôles de données spécifient les données de série à afficher dans le graphique. Pour la plupart des graphiques, une colonne correspond à une série, mais cela peut varier selon le type de graphique. Par exemple, les graphiques à nuage de points nécessitent deux colonnes de données pour la première série et une autre pour chaque série supplémentaire. Les graphiques en chandeliers japonais nécessitent quatre colonnes de données pour chaque série. Type de données: nombre |
Hiérarchie et associabilité des rôles
Le schéma suivant montre quelles colonnes de rôle peuvent s'appliquer à quelles autres colonnes de rôle. Toutes les colonnes, à l'exception des colonnes de domaine, s'appliquent au plus proche gauche auquel elles peuvent être appliquées.
Ainsi, par exemple, une colonne scope s'applique à la colonne data la plus proche à sa gauche, la colonne annotationText s'appliquera à la colonne annotation la plus proche à sa gauche, tandis qu'une colonne annotation s'appliquera à la colonne data ou domaine la plus proche à sa gauche.
Attribuer un rôle
Les rôles sont attribués en tant que propriété de la colonne dans un objet DataTable. Il existe plusieurs façons de créer une colonne de rôle, mais voici les plus courantes:
Les deux premières techniques dessinent le graphique suivant:
Méthode DataTable.addColumn
L'exemple suivant crée un graphique à barres avec un repère d'intervalle sur trois des barres. Les repères d'intervalle sont spécifiés par les troisième et quatrième colonnes à l'aide de la méthode DataTable.addColumn().
var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain column.
data.addColumn('number', 'Sales'); // Implicit data column.
data.addColumn({type:'number', role:'interval'});
data.addColumn({type:'number', role:'interval'});
data.addColumn('number', 'Expenses');
data.addRows([
['April',1000, 900, 1100, 400],
['May', 1170, 1000, 1200, 460],
['June', 660, 550, 800, 1120],
['July', 1030, , , 540]
]);
var chart = new google.visualization.BarChart(
document.getElementById('visualization'));
chart.draw(data,
{width: 800, height: 600, title: 'Company Performance'});
Notation littérale JavaScript
Dans le littéral JSON, vous devez spécifier une propriété p de la colonne avec la valeur "role":"role-type".
L'exemple suivant montre comment spécifier des rôles à l'aide de la notation littérale JavaScript. Cette opération ne peut être effectuée qu'au moment de la création de la table.
{"cols":[
{"id":"","label":"Month","pattern":"","type":"string"},
{"id":"","label":"Sales","pattern":"","type":"number"},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"Expenses","pattern":"","type":"number"}],
"rows":[
{"c":[
{"v":"April","f":null},
{"v":1000,"f":null},
{"v":900,"f":null},
{"v":1100,"f":null},
{"v":400,"f":null}]},
{"c":[
{"v":"May","f":null},
{"v":1170,"f":null},
{"v":1000,"f":null},
{"v":1200,"f":null},
{"v":460,"f":null}]},
{"c":[{"v":"June","f":null},
{"v":660,"f":null},
{"v":550,"f":null},
{"v":800,"f":null},
{"v":1120,"f":null}]},
{"c":[
{"v":"July","f":null},
{"v":1030,"f":null},
{"v":null,"f":null},
{"v":null,"f":null},
{"v":540,"f":null}]}],
"p":null
}
Méthode DataView.setColumns
Lorsque vous créez une vue, vous pouvez définir explicitement le rôle d'une colonne. Cela s'avère utile lorsque vous créez une colonne de calcul. Pour en savoir plus, consultez DataView.setColumns().