Cette page décrit le concept et l'utilisation des rôles dans les tableaux de données de graphiques.
- Que sont les rôles ?
- Quels rôles sont disponibles ?
- Hiérarchie et associabilité des rôles
- Attribuer un rôle
Que sont les rôles ?
Les objets Google DataTable et DataView acceptent désormais les rôles de colonne explicitement attribués. Un rôle de colonne décrit l'objectif des données qu'elle contient. Par exemple, une colonne peut contenir des données décrivant le texte de l'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 "données" qui la précède, qu'elle soit placée juste avant ou avant le premier groupe de colonnes de rôle consécutive. Par exemple, vous pouvez avoir deux colonnes après une colonne "données", une pour "info-bulle" et une pour "annotation". Cependant, après la colonne "domaine", nous autorisons également 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 Info-bulles.
À l'origine, seuls deux rôles étaient disponibles pour une colonne : "domain", qui spécifie les principales valeurs d'axe, et "data", qui spécifie la hauteur des barres, la largeur des secteurs du graphique, etc. Ces rôles ont été attribués implicitement, en fonction de l'ordre et du type des colonnes de la table. Toutefois, vous pouvez désormais attribuer explicitement des rôles de colonne. Vous pouvez désormais ajouter des colonnes facultatives qui fournissent de nouvelles caractéristiques intéressantes à un graphique, telles que des libellés d'annotation arbitraires, du texte de pointage 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 des colonnes dans le tableau, conformément aux spécifications de format de données du graphique. Cette page présente les rôles que vous pouvez attribuer explicitement et explique comment les attribuer.
Voici un comparatif de ce que vous pouvez faire avec un graphique à courbes utilisant uniquement les rôles déduits par défaut, par rapport à d'autres rôles explicitement attribués.
Format du tableau de données du graphique en courbes:
Colonne 0 | Colonne 1 | … | Colonne N | |
---|---|---|---|---|
Objectif | Valeurs de la ligne 1 | … | Valeurs de la ligne N | |
Type de données | number (nombre) | … | number (nombre) | |
Rôle | domaine | données | … | données |
Rôles de colonne facultatifs compatibles |
|
|
… |
|
Graphique sans rôles de colonne explicites | Graphique avec rôles de colonne explicites |
---|---|
|
|
Ce graphique n'applique pas explicitement les rôles et ne peut donc utiliser que la disposition de base des données et des colonnes de domaine illustrée ci-dessus. Tableau 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 explicitement des rôles. Vous pouvez donc ajouter des colonnes facultatives. Ce graphique comporte des colonnes facultatives pour les rôles Annotation, AnnotationText, Intervalle et Certitude.
Tableau 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 rôles sont disponibles ?
Le tableau suivant répertorie tous les rôles attribués à 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 à proximité du point de données associé. Le texte s'affiche sans aucune intervention de l'utilisateur. Les annotations et le texte d'annotation peuvent être attribués à des points de données et à des catégories (libellés d'axe). Il existe deux styles d'annotations: le point (par défaut), qui dessine le texte d'annotation à proximité du point spécifié, et le point, qui trace le texte d'annotation sur une ligne qui divise la zone du graphique. Vous pouvez spécifier le style de la ligne en définissant l'option de graphique suivante : Type de données: chaîne Par défaut: chaîne vide |
Données : :
Les "A" et "B" de ce graphique sont des annotations. Pointez sur l'annotation pour en afficher le texte. Notez que vous devez pointer sur l'annotation, et non sur le point de données auquel elle est appliquée, pour afficher la valeur annotationText. Les valeurs NULL sont acceptées pour les cellules d'annotation et d'annotationText. Cependant, si vous avez une valeur d'annotationText, vous devez avoir une valeur d'annotation associée. |
annotationText | Texte étendu à afficher lorsque l'utilisateur pointe sur l'annotation associée. Les annotations et le texte d'annotation peuvent être attribués à des points de données et à des catégories (libellés d'axe). Si vous disposez d'une colonne d'annotationText, vous devez également en avoir une. En revanche, le texte de l'info-bulle s'affiche lorsque l'utilisateur passe la souris 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. Le mode d'affichage dépend du type de graphique (par exemple, 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ù "vrai" est "certain", "faux" incertain. Valeur par défaut: true |
|
soulignement | Met en évidence les points de données de graphique spécifiés. Affiché sous forme de ligne épaisse et/ou de grand point. Pour les graphiques en courbes et en aires, le segment entre deux points de données n'est mis en évidence que si les deux points de données sont mis en évidence. Type de données: booléen Par défaut: faux |
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" comprend un segment axé sur la colonne 3, les lignes 1 et 2. La série "Dépenses" comporte deux segments mis en évidence par la cinquième colonne : les lignes 2, 3 et 4. Notez que l'accent nécessite la mise en valeur des 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 forme d'indicateurs de plage de style I-bar. Les colonnes d'intervalle sont des colonnes numériques. Ajoutez des colonnes d'intervalle par paires, en marquant les valeurs basse et élevée de la barre. Les valeurs d'intervalle doivent être ajoutées dans l'ordre croissant, de gauche à droite. Type de données: nombre Par défaut: pas d'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. Les intervalles le plus haut et le plus bas autour d'un point indiquent les parties supérieure et inférieure de la barre. Remarque: Pour en savoir plus sur les intervalles, consultez Intervalles. |
portée | Indique si un point est dans le champ d'application ou non. Si un point n'entre pas dans le champ d'application, son accent n'est pas mis en évidence. 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 des points de terminaison est compris dans la portée. 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 de champ d'application s'applique à la colonne de données "Ventes" à sa gauche. Le premier segment est rendu en dehors du champ d'application, car les deux points de limite ne sont pas dans le champ d'application. La deuxième colonne de champ d'application s'applique à la colonne de données "Frais". Le premier segment est marqué comme étant dans le champ d'application, car l'un de ses points limites est dans le champ d'application. Le reste de la ligne est en dehors du champ d'application, car tous les autres points sont indiqués comme étant hors champ d'application. |
style |
Stylise 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 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 d'informations sur la personnalisation du style des points, lignes et barres. Vous pouvez également consulter les options pour chaque type de graphique, où des styles peuvent être spécifiés pour d'autres types d'entités, tels que les zones, le texte et les zones. |
info-bulle |
Texte à afficher lorsque l'utilisateur passe la souris sur le point de données associé à cette ligne. Remarque : Cela n'est pas compatible avec la visualisation Graphique à bulles. Le contenu des info-bulles HTML du graphique à bulles n'est pas personnalisable. Type de données: chaîne Valeur par défaut 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 de l'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 page Info-bulles. |
domaine | Vous n'avez pas besoin d'attribuer ce rôle explicitement, sauf si vous concevez un graphique multidomaine (comme illustré ici). Le format de base du tableau de données permet au moteur de graphique de déterminer quelles colonnes sont des colonnes de domaine. Toutefois, vous devez savoir quelles colonnes sont des colonnes de domaine afin de savoir quelles autres colonnes peuvent la modifier. Les colonnes de domaine indiquent les libellés qui apparaissent sur l'axe principal 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 une 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 modifient le deuxième domaine ("Trimestre 2008"). Les deux domaines sont superposés sur les mêmes échelles d'axe. |
données | Vous n'avez pas besoin d'attribuer explicitement ce rôle. Le format de base de la table de données permet au moteur de graphique de déterminer quelles colonnes sont des colonnes de domaine. Toutefois, vous devez savoir quelles colonnes sont des colonnes de données afin de savoir quelles autres colonnes peuvent le modifier. Les colonnes de rôle de données spécifient les données de série à afficher dans le graphique. Pour la plupart des graphiques, une colonne = une série, mais cela peut varier en fonction du 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 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 à d'autres colonnes de rôle. Toutes les colonnes, à l'exception des colonnes de domaine, s'appliquent au voisin le plus proche de gauche auquel elles peuvent s'appliquer.
Ainsi, par exemple, une colonne scope s'applique à la colonne data la plus proche à gauche ; une colonne annotationText s'appliquera à la colonne annotation la plus proche à gauche ; une annotation s'appliquera à la colonne data ou domain 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 permettent de générer 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. Cette fonctionnalité est utile lors de la création d'une colonne de calcul. Pour en savoir plus, consultez la page DataView.setColumns()
.