此页面由 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 规则将仅影响类名称为“example”的元素的 <td> 元素。

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

Hello Chart！

下面是一个将 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 语句中使用的图表库的网址，并提供文档的网址。
提供图表的完全限定名称。
创建示例页面，演示如何通过图表支持的选项、事件和自定义方法使用图表。
明确说明图表的数据政策。大多数图表会在浏览器中处理数据，但有些图表可能会将数据发送到服务器，例如创建图表或地图的图片。如果您向服务器发送数据：
- 明确定义要发送哪些数据。
- 注意数据在服务器上保存的时长。
- 记录哪些实体将有权访问数据。例如，公司 XYZ 等。
- 指定是否记录数据以及记录多长时间。

您的文档将与图表代码保存在同一位置（请参阅下文的将图表提交到库）。

将您的图表提交到库

编写好图表后，提交该图表，以便在资源库的“其他图表”部分发布。提交图表意味着您必须与我们签署协议，同意我们不开发恶意软件或滥用用户数据。该库只是一个指向我们已创建或我们已审核的图表的指针列表；您可以选择将实际的 JavaScript 库和文档托管到您自己的网站上，也可以让 Google 为您托管库和文档。指定在将图表发布到资源库时，是否需要我们对其进行托管。

问题排查

如果您的代码不起作用，则下面的一些方法可能可以帮助您解决问题：

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

本地化

如果您希望自己的图表可供不同国家/地区的用户使用，则需要将图表设计为针对不同的语言和文化进行本地化。最基本的本地化工作是根据用户的浏览器设置翻译界面中的标准文本字符串。一种更高级的本地化形式是根据本地化，甚至可能根据界面设计更改数字格式。如果您决定将图表本地化，请在文档中列出图表支持的语言，并提供常用语言的默认设置。在图表界面中添加一个“更改语言”按钮也很实用，以防您弄错了语言。检测浏览器语言的常用方法是查看 Accept-Language HTML 标头。