本頁面由 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 陳述式的圖表程式庫網址，並提供說明文件的網址。
輸入圖表的完整名稱。
建立範例頁面，說明如何透過圖表呈現圖表、支援的選項、事件和自訂方法。
清楚描述圖表的資料政策。大部分圖表會在瀏覽器中處理資料，但有些圖表可能會將資料傳送至伺服器，例如建立圖表或地圖的圖片。如果你確實將資料傳送至伺服器：
- 清楚定義要傳送的資料。
- 請注意，資料會在伺服器上保存多久。
- 記錄哪些實體可以存取資料。例如 XYZ 公司等。
- 指定是否要記錄資料以及持續時間。

您的文件將和圖表程式碼在同一個位置託管 (請參閱下方的將圖表提交至圖片庫)。

將圖表提交給圖片庫

撰寫圖表後，請提交圖表，將圖片提交到圖庫中的「其他圖表」部分。提交圖表代表您必須和 Google 簽署協議，表示他們不會製造惡意軟體，或濫用使用者資料。資料庫只是 Google 所建立或已審核的圖表指標清單；您可以選擇在自己的網站上代管實際 JavaScript 程式庫和說明文件，也可以讓 Google 為您代管程式庫和說明文件。指定您要將圖表張貼到圖片庫時是否要代管圖表。

疑難排解

如果您的程式碼似乎無法運作，以下這些方法可協助您解決問題：

檢查是否有錯字。請記住，JavaScript 語言須區分大小寫。
使用 JavaScript 除錯工具。在 Firefox 中，您可以使用 JavaScript 主控台、Venkman 偵錯工具或 Firebug 外掛程式。在 IE 中，您可以使用 Microsoft Script Debugger。
搜尋 Google Chart API 討論群組。如果找不到解答問題的貼文，請將您的問題張貼到群組中，並附上可呈現該問題的網頁連結。

本地化

若您希望圖表能使用不同國家/地區的使用者，建議您針對不同語言和文化設計圖表。最基本的本地化方式，就是根據使用者的瀏覽器設定，在使用者介面上翻譯標準文字字串。更進階的本地化方式，是根據本地化甚至甚至是使用者介面設計，變更數字格式。如果您決定將圖表本地化，請列出圖表支援的語言，並提供預設設定的預設設定。您也可以在圖表的使用者介面中加入「變更語言」按鈕，以防語言錯誤。偵測瀏覽器語言的常見原因是查看 Accept-Language HTML 標頭。