建立圖表類型

本頁說明如何自行開發圖表類型,並提供給使用者。

觀眾

本頁假設您已閱讀使用圖表頁面。同時假設您已熟悉 JavaScript 和物件導向程式設計。目前網路上有許多 JavaScript 教學課程可供參考。

建立圖表

使用者會透過您建立的 JavaScript 程式庫看到圖表。以下是建立圖表庫的步驟:

  1. 為程式碼選擇命名空間。其他網頁也會代管您的程式碼;建議您避免發生命名衝突。
  2. 實作圖表物件。實作公開以下內容的 JavaScript 物件:
    • 建構函式
    • 一種 draw() 方法,可在傳遞至建構函式的 DOM 元素中繪製物件。
    • 供用戶端使用的任何其他選用標準方法,例如 getSelection(),以及
    • 您要向客戶公開的任何自訂方法。
  3. [選用] 實作您要讓用戶端擷取的任何事件
  4. 編寫圖表的說明文件。如未提供文件,使用者可能就無法嵌入文件。
  5. 在圖表庫中張貼圖表。

小費

  • 您可以下載 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() 方法可接受兩個參數:

  1. 包含要顯示的資料的 DataTable
  2. 圖表名稱/值選項的選用對應。系統會依據您為特定圖表定義的選項名稱和值類型。例如,在下方的 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 DebuggerFirebug 外掛程式。在 IE 中,您可以使用 Microsoft Script Debugger
  • 搜尋 Google Chart API 討論群組。 如果貼文中無法解答你的問題,請在群組中張貼問題,並附上問題網頁的連結。

本地化

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