此页面由 Cloud Translation API 翻译。

创建图表类型

此页面介绍了如何开发您自己的图表类型并使其可供用户使用。

观众

本页面假定您已阅读使用图表页面。此外，本教程还假定您熟悉 JavaScript 和面向对象的编程。您可以从网上找到很多 JavaScript 教程。

创建图表

图表通过您创建的 JavaScript 库向用户显示。以下是创建图表库的步骤：

为您的代码选择命名空间。其他页面将托管您的代码；您应尽量避免命名冲突。
实现图表对象。实现公开以下对象的 JavaScript 对象：
- 构造函数
- draw() 方法，用于在传递给构造函数的 DOM 元素内绘制对象。
- 客户端可以使用的任何其他可选标准方法，例如 getSelection()，以及
- 您想要向客户公开的任何自定义方法。
[可选] 实现您希望客户端捕获的任何事件 。
编写图表文档。如果不加以记录，用户可能无法嵌入这些内容。
在图表库中发布您的图表。

提示

您可以下载 goog.visualization API 类和方法定义，以在 IDE（代码编辑器）中启用自动补全功能。从 http://www.google.com/uds/modules/gviz/gviz-api.js 下载该文件，然后将其保存到您的项目中。虽然 IDE 可能有所不同，但大多数 IDE 都会自动将其编入索引并启用自动补全功能。请注意，文件并非总是最新版本；如需查看最新的 API 参考文档，请查看参考页面。

选择命名空间

您的图表可以嵌入到托管其他图表或其他无关 JavaScript 的网页上。为避免与其他代码或 CSS 类名称发生命名冲突，您应该为图表代码选择唯一的命名空间。对于命名空间而言，一个理想的选择是用于托管脚本的网址（去掉 WWW 和任何扩展程序）。例如，如果您的图表将发布在 www.example.com 上，则应使用 example 作为唯一命名空间。您可以添加其他后缀，以 . 标记进一步对图表进行分组（所有 Google 图表都有命名空间 google.visualization）。使用命名空间对象来存储可能需要的图表对象以及任何全局变量。

以下示例展示了如何创建一个命名空间对象来保存名为 MyTable 的图表类以及所需的任何全局变量：

// Namespace, implemented as a global variable.
var example = {};

// MyTable class constructor.
example.MyTable = function(container) {
  // ...
}

// MyTable.draw() method.
example.MyTable.prototype.draw = function(data, options) {
  // ...
}

避免 CSS 冲突

如果您使用 CSS，请确保不要编写可能影响页面上其他图表的 CSS 规则。例如，强烈建议不要使用 td {color: blue;} 之类的规则，因为它会影响页面上的任何其他 <td> 元素，而不仅仅是图表。解决此问题的一种方法是，将整个图表包含在带有类名称的 <div> 中，并让所有 CSS 规则仅应用于具有该类名称的元素的后代元素。例如，以下 CSS 规则只会影响 <td> 元素，这些元素具有类名称“example”作为祖先。

td.example {color: blue;}

然后，您可以使用 <div> 封装图表：

<div class="example">
  ...
</div>

实现图表

您需要将图表实现为一个 JavaScript 对象，以公开“参考”部分中所述的标准方法。两种必需的方法是构造函数和 draw() 方法。您还可以向用户公开适合您图表的任何其他方法。请注意，使用起来更方便。

构造函数

您的图表应公开一个接受单个参数的构造函数，即一个用来绘制图表的 DOM 元素。通常，图表会在构造函数中存储此元素的本地副本以供日后使用：

function example.MyTable(container) {
  this.container = container
}

`draw()` 方法

您的图表类应在该图表类的原型中定义 draw() 方法。draw() 方法接受两个参数：

一个 DataTable，用于存放要显示的数据。
（可选）图表的名称/值选项映射。这些选项的名称和值类型由您为特定图表定义。例如，在下面的 Hello Chart 示例中，该图表支持一个名为“showLineNumber”的选项，其值为布尔值类型。您应支持每个选项的默认值，以防用户未传递特定选项的值。此参数是可选参数，因此，如果您未传入此参数，还应准备好使用所有默认值（了解详情）。

example.MyTable.prototype.draw = function(data, options) {
  // Process data and options and render output into the container element.
  ...
}

你好，图表！

下面是一个简单的图表，会将DataTable数据显示为 HTML 表格：

下面是实现代码：

// Declare a unique namespace.
var example = {};

// Class constructor. Parameter container is a DOM elementon the client that
// that will contain the chart.
example.MyTable = function(container) {
  this.containerElement = container;
}

// Main drawing logic.
// Parameters:
//   data is data to display, type google.visualization.DataTable.
//   options is a name/value map of options. Our example takes one option.
example.MyTable.prototype.draw = function(data, options) {

  // Create an HTML table
  var showLineNumber = options.showLineNumber; // Boolean configuration option.

  var html = [];
  html.push('<table border="1">');

  // Header row
  html.push('<tr>');
  if (showLineNumber) {
    html.push('<th>Seq</th>');
  }
  for (var col = 0; col < data.getNumberOfColumns(); col++) {
    html.push('<th>' + this.escapeHtml(data.getColumnLabel(col)) + '</th>');
  }
  html.push('</tr>');

  for (var row = 0; row < data.getNumberOfRows(); row++) {
    html.push('<tr>');
    if (showLineNumber) {
      html.push('<td align="right">', (row + 1), '</td>');
    }

    for (var col = 0; col < data.getNumberOfColumns(); col++) {
      html.push(data.getColumnType(col) == 'number' ? '<td align="right">' : '<td>');
      html.push(this.escapeHtml(data.getFormattedValue(row, col)));
      html.push('</td>');
    }
    html.push('</tr>');
  }
  html.push('</table>');

  this.containerElement.innerHTML = html.join('');
}

// Utility function to escape HTML special characters
example.MyTable.prototype.escapeHtml = function(text) {
  if (text == null)
    return '';
  return text.replace(/&/g, '&').replace(/</g, '<')
      .replace(/>/g, '>').replace(/"/g, '"');
}

将图表添加到网页中

如需使用之前的图表，请将其保存到可通过浏览器访问的 .js 文件中。然后保存以下代码，将 <script> 源代码参数更改为指向您的 JavaScript 文件：

<html>
  <head>
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript" src="mytablevis.js"></script>
    <script type="text/javascript">
      google.charts.load("current");

      // Set callback to run when API is loaded
      google.charts.setOnLoadCallback(drawVisualization);

      // Called when the Chart API is loaded.
      function drawVisualization() {

        // Create and populate a data table.
        var data = new google.visualization.DataTable();
        data.addColumn('string', 'Task');
        data.addColumn('number', 'Daily Hours');
        data.addRows(5);
        data.setCell(0, 0, 'Work');
        data.setCell(0, 1, 11);
        // Add more data rows and cells here

        // Instantiate our table object.
        var vis = new example.MyTable(document.getElementById('mydiv'));

        // Draw our table with the data we created locally.
        vis.draw(data, {showLineNumber: true});
       }
   </script>
  <title>MyTable example page</title></head>
  <body>
    <div id="mydiv"></div>
    <p>This page demonstrates hosting a table visualization.</p>
  </body>
</html>

实现事件

如果您希望图表触发有用的事件（例如，计时器事件或用户发起的事件，例如点击），则需要使用事件的详细信息（名称、要发送的属性等）调用 google.visualization.events.trigger 函数。如需了解详情，请参阅事件页面。您可以通过向事件对象添加属性来向客户端公开事件详情，也可以在图表上公开某种类型的 get...() 方法，然后客户端可以调用该方法来获取事件详情。无论是哪种情况，都应记录相应的方法或事件属性。

记录图表

如果没有妥善记录图表，您可能不会获得很多用户。请务必记录以下内容：

请说明您支持的所有方法。draw() 方法对于所有图表都是通用的，但每个图表都可以支持自己的其他方法。（除非构造函数具有非标准行为，否则可能不需要记录）。您可以在参考页面上找到预期方法列表。
描述 draw() 方法支持的所有选项。其中包括每个选项的名称、预期值类型及其默认值。
描述您触发的所有事件。这意味着每个事件的名称和属性，以及每个事件的触发时间。
列出应在客户端的 <script> include 语句中使用的图表库的网址，并提供文档的网址。
提供图表的完全限定名称。
创建示例页，演示如何使用图表及其支持的选项、事件和自定义方法。
清楚描述图表的数据政策。大多数图表都在浏览器中处理数据，但有些图表可能会将数据发送到服务器，例如创建图表图片或地图的图片。如果您向服务器发送了数据：
- 明确定义发送哪些数据。
- 请注意数据将在服务器上保存多长时间。
- 记录哪些实体将有权访问数据。例如，Company XYZ 等。
- 指定是否记录数据以及记录多长时间。

您的文件将托管在图表代码所在的位置（请参阅下文中的将图表提交到库）。

将图表提交到资源库

编写完图表后，请将其提交到我们库的“其他图表”部分中发布。提交图表意味着您必须与我们签订协议，同意不创建恶意软件或滥用用户数据。该库只是一个列表，其中包含了我们创建的或我们审核过的图表的指针；您可以选择在您自己的网站上托管实际的 JavaScript 库和文档，或者让 Google 为您托管库和文档。指定是否要在将图表发布到图库时托管该图表。

问题排查

如果您的代码似乎不起作用，您可以尝试使用以下方法解决问题：

查找拼写错误。切记 JavaScript 是一种区分大小写的语言。
使用JavaScript调试程序。在 Firefox 中，您可以使用 JavaScript 控制台、Venkman Debugger 或 Firebug 插件。在 IE 中，您可以使用 Microsoft 脚本调试程序。
搜索 Google Chart API 论坛。如果您找不到能解答您的问题的帖子，请在论坛中发布您的问题以及一个可演示该问题的网页链接。

本地化

如果您预期不同国家/地区的用户会使用您的图表，不妨将图表设计为针对不同的语言和文化进行本地化。最基本的本地化工作是根据用户的浏览器设置翻译界面中的标准文本字符串。更高级的本地化形式是根据本地化情况（甚至可能是界面设计）更改数字格式。如果您决定将图表本地化，请在文档中列出您的图表支持哪些语言，并提供常用语言的默认设置。此外，在图表界面中添加“更改语言”按钮也很有用，以防语言有误。检测浏览器语言的一种常用方法是查看 Accept-Language HTML 标头。