本页介绍了图表数据表中角色的概念和使用。
什么是角色？
Google DataTable 和 DataView 对象现在支持明确分配的列角色。列角色描述该列中数据的用途：例如，列可能会保存描述提示文本、数据点注释或不确定性指示器的数据。大多数列角色都适用于其前面的“数据”列，无论该列是紧邻其之前还是连续一组角色列中的第一组之前。例如，“data”列后面可以有两列，一列是“tooltip”，另一列是“annotation”。但在“domain”列之后，我们还通常允许使用“annotation”和“annotationText”列角色。
注意：如果您希望控制用户将鼠标悬停在图表上时显示的提示内容，请参阅提示。
最初，列只有两个角色可用：“domain”（指定长轴值）和“data”（指定条形高度、饼图扇区宽度等）。这些角色是根据表中列的顺序和类型隐式分配的。但是，由于能够明确分配列角色，您现在可以添加可选列来为图表提供有趣的新功能，例如任意注释标签、悬停文本和不确定性条。
如果未明确分配列的角色，系统将根据图表的数据格式规范，根据表格中列的顺序推断出其角色。本页面将介绍您可以明确分配哪些角色，以及如何分配这些角色。
下面对比了使用折线图可以执行的操作（仅使用默认的推断角色）与使用其他明确分配的角色的折线图。
折线图数据表格式：
| 第 0 列 | 第 1 列 | ... | 第 N 列 | |
|---|---|---|---|---|
| Purpose |
|
第 1 行的值 | ... | 第 N 行的值 |
| 数据类型 | number | ... | number | |
| 角色 | 网域 | data | ... | data |
| 可选的受支持 列角色 |
|
|
... |
|
| 没有显式列角色的图表 | 具有显式列角色的图表 |
|---|---|
|
|
|
此图表中未明确应用角色，因此只能使用上面显示的基本数据和网域列布局。 数据表： 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、Interval 和确定性角色的可选列。
数据表： 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 图表支持的所有角色。并非所有图表类型都支持所有角色；每个图表的文档都会说明可用的角色以及角色的去向。对于不同的图表类型，角色的呈现方式有所不同。
| 角色 | 说明 | 示例 |
|---|---|---|
| 注释 | 图表中要显示的相关数据点附近的文本。文本无需任何用户互动即可显示。注解和注解文本可分配给数据点和类别（轴标签）。 注释有两种样式：点（默认）和线条，前者用于在指定点附近绘制注释文本，后者用于在将图表区域一分为二的线上绘制注释文本。您可以通过设置此图表选项来指定线条样式： 数据类型：字符串 默认：空字符串 |
数据： label: 'Year', 'Sales', null, null, 'Expenses', null, null 角色：domain, data,annotation,annotationText, data,annotation,annotationText
'2004', 1000, null, null, 400, null, null
'2005', 1170, null, null ' new model '
此图表中的“A”和“B”是注释。将鼠标悬停在注释上即可查看注释文本。请注意，您必须将鼠标悬停在注解（而不是应用了该注解的数据点）上，才能显示 annotationText 值。 注释和注释文本单元格都接受 null 值；但是，如果您有注释文本值，则必须具有关联的注释值。 |
| annotationText | 用户将鼠标悬停在关联的注释上时显示的扩展文本。 注解和注解文本可分配给数据点和类别（轴标签）。如果您有 AnnotationText 列，则还必须有注解列。相比之下，当用户将鼠标悬停在图表上的关联数据点上时，系统会显示提示文本。 数据类型：字符串 默认：空字符串 |
|
| 确定性 | 指示数据点是否确定。其显示方式取决于图表类型，例如，可能用虚线或条纹填充表示。 对于折线图和面积图，当且仅当两个数据点都确定时，两个数据点之间的细分才是确定的。 数据类型：布尔值，其中 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
在此图表中，“销售”系列有一个加粗的细分，按照第 3 列、第 1 行和第 2 行指定。“费用”系列包含两个突出显示的部分，由第五列指定，即第二行、第三行和第四行。请注意，强调效果需要强调两个边界点。 |
| 间隔 | 表示特定点的潜在数据范围。间隔通常以 I 型条形范围指示器的形式显示。间隔列是数字列；成对添加间隔列，以标记柱形的下限值和上限值。间隔值应以从左到右的递增值添加。 数据类型：数字 默认：无间隔 |
数据： 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
第一个范围列应用于左侧的“销售”数据列。第一段的渲染超出了范围，因为两个边界点都在范围内。第二个范围列适用于左侧的“支出”数据列。第一个路段标记为在范围内，因为其中一个边界点在范围内，其余的线则位于范围外，因为所有其他点都标记为在范围内。 |
| 样式 |
设置数据不同方面的某些属性的样式。这些值包括：
数据类型：字符串，其中可以使用 默认值：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}'
在此图表中，每个条形都使用 注意：如需进一步了解如何自定义点、线和条形的样式，请参阅其他文档。 另请参阅每种图表类型对应的选项，这些选项可用于为其他类型的实体（例如区域、文本和框）指定样式。 |
| 提示 |
用户将鼠标悬停在与此行关联的数据点上时显示的文本。 注意：气泡图可视化图表不支持此操作。气泡图 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 线图要求每个系列有四个数据列）。 数据类型：数字 |
角色层次结构和关联性
下图显示了哪些角色列可以应用于其他角色列。除网域列之外的所有列都应用于可应用该列的最近左邻。
例如，scope 列应用于其左侧最近的 data 列；annotationText 列将应用于其左侧最近的 annotation 列；annotation 将应用于其左侧最近的 data 或 domain 列。
分配角色
角色是作为 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()。