列角色

本页面介绍了图表数据表中角色的概念和用法。

  1. 什么是角色?
  2. 有哪些角色可用?
  3. 角色层次结构和关联性
  4. 分配角色

什么是角色?

Google DataTable 和 DataView 对象现在支持明确分配的列角色。列角色描述列中数据的用途:例如,列可以保存描述提示文本、数据点注解或不确定性指示的数据。大多数列角色都会应用于其前面的“数据”列,无论是紧挨着前面的列,还是紧接着一组角色列的第一个列,都是这样。例如,您可以在“数据”列后添加两列,一列用于“提示”,另一列用于“注释”。但除了“domain”列之外,我们通常还允许使用“annotation”和“annotationText”列角色。

注意:如果您希望控制当用户将鼠标悬停在图表上时所显示的提示内容,请参阅提示

最初,一个列仅有两个角色:“domain”,用于指定长轴值;“data”,用于指定柱形高度和饼图切片宽度,等等。这些角色是根据表中列的顺序隐式分配的。但是,由于能够明确分配列角色,您现在可以添加可选列,为图表提供有趣的新功能,例如任意注解标签、悬停文本和不确定性条形。

如果您未显式指定列的角色,则系统会根据列的数据顺序根据图表的数据格式规范推断其角色。此页面将向您介绍您可以明确分配哪些角色,以及如何分配这些角色。

以下比较了仅使用默认推断角色与明确分配的其他角色可以用于折线图的功能。

折线图数据表格式

  第 0 列 第 1 列 …… N
目的
  • X 轴组标签(离散
  • X 轴值(连续
第 1 行的值 …… 第 N 行
数据类型
  • 字符串(离散)
  • 数字、日期、日期时间或
    时段(连续)
number …… number
角色 数据 …… 数据
支持的可选
列角色
  • 注解
  • AnnotationText
  • 注解
  • AnnotationText
  • 确定
  • 强调
  • interval
  • 范围
  • style
  • 工具提示
……
  • 注解
  • AnnotationText
  • 确定
  • 强调
  • interval
  • 范围
  • style
  • 工具提示

 

不含显式列角色的图表 具有显式列角色的图表

此图表未明确应用角色,因此只能使用上面所示的基本数据和网域列布局。

DataTable

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

此图表明确分配了角色,因此您可以添加可选列。此图表包含用于注解、annotationText、间隔和确定性角色的可选列。

  • 注解列用于在图表中指定静态标签;这里的“A”、“B”、“C”为注解。
  • 当您将鼠标光标悬停在注释(而非数据点)上时,系统会为 annotationText 列指定悬停文本。
  • 间隔列用于指定图表上 I 柱形的顶部和底部点。图表中有三个条形。
  • 不确定性列指示该时间点的数据是否确定。最后一个数据点是不确定的,因此指向该数据点的那一条虚线。

DataTable

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

有哪些角色可供选择?

下表列出了 Google 图表支持的所有角色。并非所有图表类型都支持所有角色;每个图表的文档都会说明哪些角色可用,以及角色在哪里。对于不同的图表类型,角色的呈现方式有所不同。

角色 说明 示例
注释

要在图表上的相应数据点附近显示的文字。文字会在没有任何用户互动的情况下显示。注解和注解文本可同时分配给数据点和类别(轴标签)。

注释有以下两种样式:点(默认)用于在指定的点附近绘制注释文本;以及线条(在绘制图表区域的两行上绘制注释文本)。您可以通过设置此图表选项来指定线条样式:annotations: {'column_id': {style: 'line'}}

数据类型:字符串

默认:空字符串

数据


此图表中的“A”和“B”是注释。将鼠标悬停在注解上可查看注解文本。请注意,您必须将鼠标悬停在注解上,而不是将鼠标悬停在其上应用的数据点上,才能显示 AnnotationText 值。

注解和 AnnotationText 单元格都接受 null 值;但是,如果您有 AnnotationText 值,则必须有关联的注解值。

annotationText

用户将鼠标悬停在关联的注释上时显示的扩展文本。 注解和注解文本可同时分配给数据点和类别(轴标签)。如果您有 AnnotationText 列,还必须有一个 Annotation 列。相反,当用户将鼠标悬停在图表上的关联数据点上时,就会显示提示文字。

数据类型:字符串

默认:空字符串

确定性

指明数据点是否确定。显示方式取决于图表类型 - 例如,可能由虚线或条纹填充表示。

对于折线图和面积图,当且仅当两个数据点都确定时,才会确定两个数据点之间的细分。

数据类型:布尔值,其中 true 表示确定,false 表示不确定。

默认:true

强调

强调指定的图表数据点。显示为粗线和/或大点。

对于折线图和面积图,当且仅当同时强调两个数据点时,系统才会突出显示这两个数据点之间的细分。

数据类型:布尔值

默认:false

数据

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

在此图表中,“销售”系列包含一个突出显示的细分受众群,其中第三列对应第 1 行和第 2 行。“支出”系列包含两个强调细分,第 5 列分别为第 2 列、第 3 行和第 4 行。请注意,强调时需要同时强调两个边界点。

间隔

表示特定数据点的潜在数据范围。间隔通常以 I-bar 样式范围指示器的形式显示。间隔列是数字列;成对添加间隔列,标记柱形的低值和高值。间隔值应从左到右逐渐增加。

数据类型:number

默认:无间隔

数据

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

在此图表中,间隔值定义了围绕点的 I 柱。值从左到右增加。 点顶部和底部之间的间隔标记了柱形的顶部和底部。

注意:如需详细了解间隔,请参阅间隔

范围

指示点是否位于范围内。如果某个点超出作用域,则该视图的视觉强度不再突出。

对于折线图和面积图,如果任一端点在范围内,则两个数据点之间的细分会在范围内。

数据类型:布尔值,其中 true 表示在范围内。

默认:true

数据

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

第一个范围列应用于其左侧的“销售”数据列。第一个段的渲染超出了范围,因为两个边界点都超出范围。第二个范围列适用于其左侧的“费用”数据列。第一个段被标记为范围内,因为它的一个边界点在范围内;线的其余范围超出范围,因为所有其他点都标记为不在范围内。

样式

设置数据不同方面某些属性的样式。这些值包括:

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

数据类型:字符串,可以使用 'firstProperty: value; secondProperty: value' 语法应用多个样式,也可以通过指定类型并将样式属性封装在大括号内(例如 bar { //properties go here })为 bar, line,point 设置特定样式。

默认:null

数据

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}'

      

在此图表中,每个条形的样式独立于其他条形,使用 style 列角色进行设置。您可专门设置点、线或条的样式(请参阅“蜘蛛侠”行),也可:将样式应用于所有点、线和条(具体取决于图表类型)。

注意:如需详细了解如何自定义线的样式,请参阅其他文档。 另请参阅每种类型的图表的选项,您可以为其他类型的实体(例如区域、文本和框)指定样式。

提示

用户将鼠标悬停在与此行关联的数据点上时要显示的文本。

注意气泡图可视化图表不支持此操作。气泡图 HTML 提示的内容不可自定义。

数据类型:字符串

默认:数据点值

数据

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'

将鼠标悬停在数据点即可显示提示文本。提示数据会分配到两行中的所有列(即第 3 列和第 5 列)。

注意:如需详细了解自定义提示,请参阅提示

域名

除非设计了多网域图表(如下所示),否则不应明确分配此角色;数据表的基本格式可让图表引擎推断哪些列是网域列。不过,您应该知道哪些列是网域列,以便了解哪些其他列可以进行修改。

网域列会沿着图表的长轴指定标签。有时,多个网域列可用于支持同一图表中的多个范围。

数据类型:通常为字符串,但偶有数字或日期

数据

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

此示例演示了一个多网域图表。前两个数据列修改第一个网域(“2009 Quarter”),最后两个数据列修改第二个网域(“2008 Quarter”)。两个网域都重叠在相同的轴刻度上。

数据

您无需明确分配此角色;数据表的基本格式可让图表引擎推断哪些列是网域列。不过,您应该知道哪些列是数据列,以便了解哪些其他列可以进行修改。

数据角色列指定要在图表中显示的系列数据。对于大多数图表,一个柱形 = 一个系列,但这可能因图表类型而异(例如,散点图需要为第一个系列绘制两个数据列,而每个额外系列则对应一个额外数据列;而 K 线图表则需要为每个系列绘制四个数据列)。

数据类型:number

 

角色层次结构和关联性

下图显示了哪些角色列可应用于其他角色列。除网域列之外的所有列都适用于可应用该列的最近邻点

因此,例如,scope 列应用于其左侧最近的 data 列;annotationText 列将应用于其左侧最近的 annotation 列;annotation 将应用于其左侧最近的 datadomain 列。

分配角色

角色在 DataTable 对象中作为列的属性进行分配。您可以通过多种方式创建角色列,但以下是最常见的方式:

前两种方法绘制以下图表:

DataTable.addColumn 方法

以下示例在三个条形上创建了一个带有间隔标记的条形图。间隔标记由第三列和第四列使用 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'});

JavaScript 字面量表示法

在 JSON 字面量中,您必须指定值为 "role":"role-type" 的列的 p 属性。以下示例演示了如何使用 JavaScript 字面量表示法指定角色。此操作只能在创建表时完成。

{"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
}

DataView.setColumns 方法

创建视图时,您可以明确设置列的角色。这在创建新的计算列时很有用。如需了解详情,请参阅 DataView.setColumns()