Rôles associés aux colonnes

Cette page décrit le concept et l'utilisation des rôles dans les tableaux de données de graphiques.

  1. Que sont les rôles ?
  2. Quels rôles sont disponibles ?
  3. Hiérarchie et associabilité des rôles
  4. 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
  • annotation
  • texteTexte
  • annotation
  • texteTexte
  • certain
  • emphase
  • interval
  • champ d'application
  • style
  • info-bulle
  • annotation
  • texteTexte
  • certain
  • emphase
  • interval
  • champ d'application
  • style
  • info-bulle

 

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.

  • annotation spécifient des libellés statiques dans le graphique. Ici, "A", "B", "C" sont des annotations.
  • Les colonnes annotationText spécifient du texte de pointage lorsque vous passez la souris sur l'annotation (pas le point de données).
  • interval indiquent les points supérieur et inférieur des barres en I sur le graphique. Le graphique comporte trois barres I.
  • certainity indiquent si les données à ce stade sont certaines. Le dernier point de données est incertain. Par conséquent, la ligne qui le mène est en pointillés.

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 : annotations: {'column_id': {style: 'line'}}

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:

  • color
  • opacity
  • stroke-width
  • stroke-color
  • stroke-opacity
  • fill-color
  • fill-opacity

Type de données: chaîne, où plusieurs styles peuvent être appliqués à l'aide d'une syntaxe 'firstProperty: value; secondProperty: value', ou bien définissez des styles spécifiques pour bar, line, et point en spécifiant le type et en encapsulant les propriétés du style entre accolades (par exemple, bar { //properties go here }).

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 style. Les styles peuvent être définis pour un point, une ligne ou une barre en particulier (voir la ligne Spider Man) ou, en général, pour appliquer les styles à tous les points, lignes et barres, en fonction du type de graphique.

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