数据格式

本文档介绍了如何将图表数据发送到 Google Chart API。

目录

  1. 概览
  2. 基本文本格式
  3. 具有自动扩缩功能的文本格式
  4. 具有自定义缩放功能的文本格式
  5. 简单的编码格式
  6. 扩展编码格式
  7. 数据缩放和轴缩放
  8. JavaScript 编码脚本

概览

几乎所有图表的数据都是使用 chd 参数发送的。数据必须采用以下某种格式发送：

  • 基本文本格式本质上是 0—100（包括 0 和 100）之间的简单的浮点数。这种格式易于读取和写入。
  • 可自动扩缩的文本格式会根据您的数据缩放图表。
  • 具有自定义缩放的文本格式与基本文本格式类似，但它允许您使用第二个网址参数来指定自定义范围。
  • 简单的编码格式可让您指定 0—61 之间的整数值（包括 0 和 61），并使用单个字母数字字符进行编码。此编码会生成任何数据格式中最短的数据字符串（如果有任何值大于 9）。
  • 扩展编码格式：可让您指定 0—4095 之间的整数值（包括 0 和 4095），并使用两个字母数字字符进行编码。扩展编码最适合包含大量数据和较大数据范围的图表。

系统会缩放数据值以适合所使用的格式；有关如何处理数据以适合图表的说明，请参阅数据缩放和轴缩放。

我们提供了 JavaScript 代码段，用于将数据编码为简单编码格式或扩展编码格式。此外，一些 Google 图表群组成员还贡献了其他库来帮助设置格式：您可以在归档中搜索找到它们。

基本文本格式

基本文本格式的数据允许您将 0—100（包括 0 和 100）之间的浮点值指定为数字。小于 0 的值会被标记为缺失；大于 100 的值则会被截断为 100。基本文本格式的优势在于，网址中的值易于读取和理解，并且默认的轴标签会准确显示数据值。不过，文本格式设置（无论是简单格式化还是使用自定义参数）所生成的数据字符串在所有格式中是最长的。

如果您的数据包含的值超出文本格式指定范围，可以将数据转换为占数据中最大值的百分比。或者，您也可以使用具有自定义缩放功能的文本格式来为您处理缩放。

语法：

chd=t:val,val,val|val,val,val...
<data>
每个系列都包含一个或多个以英文逗号分隔的值。请使用竖线字符 (|) 分隔多个系列。值为 0—100（含 0 和 100）的浮点数。小于零的值或下划线字符 ( _ ) 被视为 null 值。大于 100 的值则保留为 100。

 

示例：

包含五个值的表格。下划线被视为 null 值，值 -30 低于最小值，因此会被舍弃，而值 200 会被截断为 100。 包含 5 个值且经过文本编码的条形图表。
chd=t:_,30,-30,50,80,200

返回页首

具有自动扩缩功能的文本格式

您可以将某些图表配置为自动扩缩以适应其数据。图表会进行缩放，以便最大值位于图表顶部，最小值（如果所有值均大于零，则为 0）位于底部。

图表上显示的所有标记值都会显示其实际值，而不是经过缩放的值。

此功能仅适用于文本格式的值，且不适用于所有图表类型。尝试使用您的图表类型，看看它是否受支持。

语法

cht=t:val,val,val...
chds=a

示例：


chd=t:5,30,50,80,200
chds=a

请注意，对于饼形图表，您不应使用小于 0 的值。

 包含 5 个值且经过文本编码的条形图表。
chd=t:-5,30,-30,50,80,200
chds=a

返回页首

具有自定义缩放功能的文本格式

通过具有自定义缩放功能的文本格式，您可以指定任意正数或负浮点数，还可以通过缩放参数指定自定义图表范围。当您不想将数据限制在特定范围内，或者不希望手动缩放数据以使其适合在图表内显示时，此图表会非常有用。此格式会根据需要为您调整零位线。此格式与基本文本格式所生成的数据格式相同。

如需自动扩缩，请指定 chds=a。

文本格式设置（无论是简单设置还是使用自定义参数）所生成的数据字符串在所有格式中是最长的。

语法：

具有自定义缩放功能的文本格式需要使用两个参数：

chd=t:val,val,val|val,val,val
chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
chd=t:<data>
与普通数据格式相同：每个系列包含一个或多个以英文逗号分隔的值，多个系列之间用竖线字符 (|) 分隔。每个系列中的允许值范围由 chds 参数指定。
chds
每个数据系列的一个或多个允许最小值和最大值的集合，以英文逗号分隔。您必须同时提供最大值和最小值。如果提供的键值对数量少于数据系列的数量，最后一对数据系列将应用于剩余的所有数据系列。请注意，这不会更改轴范围；如需更改轴范围，您必须设置 chxr 参数。 有效值范围为 (+/-)9.999e(+/-)199。您可以使用标准或 E 表示法指定值。
<series_1_min>series_1_min
第一个系列中允许的最小值。较低的值会被标记为缺失。
<series_1_max>series_1_max
第一个系列中允许的最大值。更高的值则会被截断为该值。

 

示例：

一个条形图，最小值/最大值范围为 -80—140。30、-60、50、140 和 80 值均在该范围内，因此不会被截断。请注意，系统会为您调整零位线，即 80/(140 + 80) = 0.36（沿 y 轴向上）。

另请注意，尽管设置了 chds 参数，默认的 y 轴范围仍为 0—100，因此标签值并不能反映实际的数据值。

 包含 5 个值且经过具有数据缩放功能的文本编码处理的条形图表。

chd=t:30,-60,50,140,80,-90
chds=-80,140

返回页首

简单的编码格式

简单的编码格式可让您指定 0—61 之间的整数值（包括 0 和 61），并使用单个字母数字字符进行编码。这样生成的数据字符串网址在所有数据格式中是最短的。但是，如果您的折线图或条形图沿数据轴的长度超过 100 像素，您可能需要使用其他格式。这是因为，如果仅支持 62 个数据值，数据粒度会远远大于显示粒度，并且值只会出现很小的偏差（不多，但在较大的图表上可见）。

请注意，如果您将 chds 参数用于简单编码，则图表上的数据元素大小不会受到影响，但所有数据点标记值都会受到影响。

语法：

chd=s:
  <series_1>
    ,...,
  <series_n>
<series_1>
字符串（每个字符都是一个数据点）和各系列之间以英文逗号分隔。系列中各个值之间不进行分隔。 以下是支持的数据字符及其对应的值
：
  • A—Z（其中 A = 0，B = 1，以此类推），Z = 25
  • a—z（其中 a = 26，b = 27，以此类推），z = 51
  • 0(zero)—9，其中 0 = 52，9 = 61
  • 下划线字符 (_) 表示缺少值

您可以使用以下工具对单个值进行编码，也可以使用 JavaScript 代码对整个网址字符串进行缩放和编码。

示例：

相当于文本编码字符串 chd=t:1,19,27,53,61,-1|12,39,57,45,51,27 <title="chs=320x200&cht=bvs&chd30x0b66767666666666666666...866.6.6.6.6 总质量
chd=s:BTb19_,Mn5tzb

返回页首

扩展型编码格式

扩展编码格式可让您指定 0—4095 之间的整数值（包括 0 和 4095），并使用两个字母数字字符进行编码。它使用的语法与简单编码略有不同。

请注意，如果您将 chds 参数用于简单编码，则图表上数据元素的大小不会受到影响，但所有数据点标记值都会受到影响。

语法：

chd=e:
  <series_1>
    ,...,
  <series_n>
<series_1>
一个字符串，其中每两个字符是一个数据点，一系列用英文逗号分隔。系列中各个值之间不进行分隔。 以下是支持的编码字符
：
  • A—Z
  • a—z
  • 0—9
  • 句点 (.)
  • 连字符 (-)
  • 缺失值使用双下划线 (__) 表示。

下文简单说明了经过编码的值：

  • AA = 0，AB = 1，以此类推，AZ = 25
  • Aa = 26，Ab = 27，以此类推，Az = 51
  • A0 = 52，A1 = 53，以此类推，A9 = 61
  • A- = 62，A. = 63
  • BA = 64，BB = 65，以此类推，BZ = 89
  • Ba = 90，Bb = 91，以此类推，Bz = 115
  • B0 = 116，B1 = 117，以此类推，B9 = 125
  • B- = 126，B. = 127
  • 9A = 3904，9B = 3905，以此类推，9Z = 3929
  • 9a = 3930，9b = 3931，以此类推，9z = 3955
  • 90 = 3956，91 = 3957，以此类推，99 = 3965
  • 9- = 3966，9. = 3967
  • -A = 3968，-B = 3969，以此类推，-Z = 3993
  • -a = 3994，-b = 3995，以此类推，-z = 4019
  • -0 = 4020，-1 = 4021，以此类推，-9 = 4029
  • -- = 4030，-. = 4031
  • .A = 4032，.B = 4033，以此类推，.Z = 4057
  • .a = 4058，.b = 4059，以此类推，.z = 4083
  • .0 = 4084，.1 = 4085，以此类推，.9 = 4093
  • .- = 4094，.. = 4095

您可以使用以下工具对单个值进行编码，也可以使用 JavaScript 代码对整个网址字符串进行缩放和编码。

示例：

相当于文本编码字符串 chd=t:90,1000,2700,3500|3968,-1,1100,250 包含两个系列的堆叠条形图表，其中每个系列包含四个值，均采用扩展型编码。
chd=e:BaPoqM2s,-A__RMD6

返回页首

数据缩放和轴缩放

系统会以显式方式（使用具有自定义缩放功能的文本格式时）或隐式方式（所有其他类型）缩放数据以适合您的图表。也就是说，每个图表都会缩放以适应相应格式的可用范围，而不是您提供的数据的实际范围。

您可能需要对数据进行缩放，使其涵盖您的格式允许的完整值范围，以使差异更加明显。 您可以通过以下任一方式来缩放数据：根据您使用的格式缩放数据，或明确指定数据范围（即，使用具有自定义缩放功能的文本格式）。

请注意，轴标签值根据完全独立的量表进行计算，与数据值无关，但使用默认范围 0—100。不过，您可以更改此范围。

这些问题在本部分中均有介绍。

数据会缩放以适合格式范围 [除饼图和维恩图之外的所有图表]

不同的格式支持不同的值范围。您的数据将根据格式范围进行缩放，因此，您格式支持的最大值呈现在该轴的顶部，而格式的最小值呈现在该轴的顶部。以下示例显示了使用基本文本格式（范围 0-100）、可自定义缩放比例（自定义范围 0-200）和扩展编码格式（范围 0-4095）的相同值 (100)。

基本文本格式 具有自定义缩放功能的文本格式 扩展型编码格式
使用具有自定义缩放功能的基本文本格式的条形图表

值：100 (chd=t:100)

格式范围：0—100

值 100 显示为 100/范围上限为 100。

值 100 (chd=t:100, chds=0,200)

格式范围：0—200

值 100 显示为 100/范围上限为 200。

值：100 (chd=e:Bk)

格式范围：0—4095

值 100 显示为 100/范围上限为 4095。

使用具有缩放的文本格式来缩放数据以适合图表的简单方法是。更为复杂的方法是手动缩放数据，使其适合您格式支持的范围内。

饼图和维恩图表：对于饼图和维恩图表，所有值都是彼此相对的，而不是与图表的总范围。

chd=e:BkDIEs chd=t:100,200,300
chds=0,300

单独计算轴标签范围 [条形图、折线图、雷达图、散点图和 K 线图]

您可以使用 chxt 参数选择显示轴值。但请务必注意，计算轴标签时并不会反映图表数据，而是由 API 单独计算或者由您明确指定。

默认的轴范围为 0—100，无论数据值或数据缩放如何。 因此，例如，如果您在采用扩展编码（范围 0-4095）的图表上使用默认轴标签显示 y 轴，那么除非您明确更改 y 轴标签，否则 y 轴标签仍会显示为 0-100，如下所述。以下示例显示了数据值为 100 的扩展编码条形图中的默认 y 轴标签：


chd=e:Bk（等同于 chd=t:100）

不过，您可以使用 chxr 参数指定轴范围。如果您希望轴值反映实际数据值，则必须指定与您的格式范围匹配的最小和最大轴值。请注意，基本文本格式的比例已在 0—100 之间，因此，如果您使用基本文本格式（不进行自定义缩放），那么轴值会默认与数据值匹配。让我们通过几个示例来说明这一点。以下三个图表包含相同的数据 (15,26,51,61)，但格式和轴刻度不同：

简单编码，未采用轴缩放 简单编码，已采用轴缩放 基本文本，未采用轴缩放

chd=s:Paz9
 

简单编码值范围：0—61

默认轴范围 (0—100)

编码范围小于标签轴范围，因此条形与轴标签上的实际值不对应。但是，各条形已按比例进行了适当的比例。

chd=s:Paz9
    chxr=0,0,61,10

简单编码值范围：0—61

轴范围已明确设置为 0—61

编码范围和轴范围相等，因此条形对应于轴上的正确值。

chd=t:15,26,51,61
 

基本文本格式值范围：0—100

默认轴范围 (0—100)

编码范围和轴范围同样相同，因此默认情况下，轴上会显示准确的数据值。

由于文本格式范围大于简单的编码格式范围（100 个单位对 61 个单位），因此此处的条形比其他图表中的条形小，但所有图表彼此成比例。

返回页首

JavaScript 编码脚本

在实际使用中，以编程方式对数据进行编码可能比手动编码更简单。

以下代码段会将单个系列编码为简单编码或扩展编码，并缩放数据值以适应该编码的完整范围。extended数据必须以正数数组的形式提供。如果提供的值不是正数，系统会使用下划线字符 (_) 将其编码为缺失值。

var simpleEncoding =
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';

// This function scales the submitted values so that
// maxVal becomes the highest value.
function simpleEncode(valueArray,maxValue) {
  var chartData = ['s:'];
  for (var i = 0; i < valueArray.length; i++) {
    var currentValue = valueArray[i];
    if (!isNaN(currentValue) && currentValue >= 0) {
    chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) *
      currentValue / maxValue)));
    }
      else {
      chartData.push('_');
      }
  }
  return chartData.join('');
}

// Same as simple encoding, but for extended encoding.
var EXTENDED_MAP=
  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.';
var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length;
function extendedEncode(arrVals, maxVal) {
  var chartData = 'e:';

  for(i = 0, len = arrVals.length; i < len; i++) {
    // In case the array vals were translated to strings.
    var numericVal = new Number(arrVals[i]);
    // Scale the value to maxVal.
    var scaledVal = Math.floor(EXTENDED_MAP_LENGTH *
        EXTENDED_MAP_LENGTH * numericVal / maxVal);

    if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) {
      chartData += "..";
    } else if (scaledVal < 0) {
      chartData += '__';
    } else {
      // Calculate first and second digits and add them to the output.
      var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH);
      var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient;
      chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder);
    }
  }

  return chartData;
}

如需对数据进行编码，请调用 simpleEncode 或 extendedEncode 函数，并传入包含您的数据 (valueArray) 和数据最大值 (maxValue) 的数组。若要在最高值和图表顶部之间留出一些空间，请将 maxValue 设置为大于数据数组中的最大数字，如下所示：

var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65);
var maxValue = 70;
simpleEncode(valueArray, maxValue);

返回页首