本頁面由 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.
  ...
}

您好！

以下是將 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 控制台、 Venkman Debugger 或 Firebug 外掛程式。在 IE 中，您可以使用 Microsoft Script Debugger。
搜尋 Google Chart API 討論群組。如果貼文中無法解答你的問題，請在群組中張貼問題，並附上問題網頁的連結。

本地化

如果您預期各個國家/地區的使用者都會使用您的圖表，建議您在設計圖表時，考量不同的語言和文化。最基本的本地化就是根據使用者的瀏覽器設定，翻譯使用者介面中的標準文字字串。如要採用更進階的本地化方式，您需要根據本地化 (甚至是 UI 設計) 變更數字格式。如果您決定將圖表本地化，請在說明文件中列出圖表支援的語言，並提供常用語言的預設設定。此外，在圖表 UI 中加入「變更語言」按鈕也很有用，以免語言出現錯誤。如要偵測瀏覽器語言，常見的方法是查看 Accept-Language HTML 標頭。