本頁說明如何自行開發圖表類型,並提供給使用者。
觀眾
本頁假設您已閱讀使用圖表頁面。同時假設您已熟悉 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 標頭。