Google Visualization API 參考資料

本頁面列出 Google Visualization API 所公開的物件，以及由所有圖表呈現的標準方法。

注意：Google Visualization API 命名空間為 google.visualization.*

DataTable 類別

代表可變動的二維值表。如要製作 DataTable 的唯讀副本 (可選擇篩選以顯示特定值、資料列或資料欄)，請建立 DataView。

系統會為每個資料欄指派一個資料類型，以及多個選用屬性，包括 ID、標籤和模式字串。

此外，您可以為任何儲存格、列、欄或整個表格指派自訂屬性 (名稱/值組合)。部分視覺呈現支援特定自訂屬性；舉例來說，資料表視覺化支援名為「樣式」的儲存格屬性，可讓您為算繪的資料表儲存格指派內嵌 CSS 樣式字串。圖表應在其說明文件中說明其支援的任何自訂屬性。

另請參閱： QueryResponse.getDataTable

建構函式

語法

DataTable(opt_data, opt_version)

opt_data

[選用] 用於初始化資料表的資料。方法可以是在已填入資料表上呼叫 DataTable.toJSON()，或是包含用來初始化資料表資料的 JavaScript 物件。JavaScript 常值物件的結構請參閱這裡。如未提供這項參數，系統會傳回新的空白資料表。

opt_version

[選用] 此為數值，用來指定所用線路通訊協定的版本。僅供圖表工具的資料來源實作者使用。目前的版本為 0.6 版。

詳細資料

DataTable 物件是用來保存傳遞至視覺化內容的資料。DataTable 是基本的二維資料表，每欄的所有資料都必須使用相同的資料類型。每個資料欄都有描述元，包括資料類型、該資料欄的標籤 (可以用圖表顯示)，以及 ID 可用於參照特定資料欄 (除了使用資料欄索引以外)。DataTable 物件也支援指派給特定值、資料列、資料欄或整個 DataTable 的任意屬性對應。視覺化圖表可以用來支援其他功能。舉例來說，資料表視覺化會使用自訂屬性，讓您將任意類別名稱或樣式指派給個別儲存格。

表格中的每個儲存格都包含一個值。儲存格可以含有空值，或是其資料欄所指定類型的值。儲存格可選擇採用「格式化」格式的資料；這是字串版本的資料，會依照圖表加以顯示格式。圖表可以 (但不一定要) 使用格式化版本顯示，但一律使用資料本身進行任何排序或計算 (例如決定圖表中放置點的位置)。舉例來說，您可以將「低」、「medium」和「high」兩個值指派為格式化值，指派給數字儲存格 1、2 和 3。

如要在呼叫建構函式後新增資料列，您可以對單一資料列呼叫 addRow()，或對多個資料列呼叫 addRows()。您也可以呼叫 addColumn() 方法新增資料欄。資料列和資料欄也有移除方法，但與其移除資料列或資料欄，不妨建立 DataView，這是 DataTable 的選擇性檢視畫面。

如果您在 DataTable 中的值傳遞至視覺呈現的 draw() 方法後變更值，變更不會立即變更圖表。如要反映任何變更，您必須再次呼叫 draw()。

注意：Google 圖表不會對資料表執行任何驗證。如果少了，圖表的顯示速度就會比較慢。如果您提供資料欄預期為字串的數字，Google Charts 會盡可能以合理的方式解讀值，但不會加上標記錯誤。

以下範例說明如何將 DataTable 例項化並填入常值字串，其資料與上述 JavaScript 範例中顯示的相同：

var dt = new google.visualization.DataTable({
    cols: [{id: 'task', label: 'Task', type: 'string'},
           {id: 'hours', label: 'Hours per Day', type: 'number'}],
    rows: [{c:[{v: 'Work'}, {v: 11}]},
           {c:[{v: 'Eat'}, {v: 2}]},
           {c:[{v: 'Commute'}, {v: 2}]},
           {c:[{v: 'Watch TV'}, {v:2}]},
           {c:[{v: 'Sleep'}, {v:7, f:'7.000'}]}]
    }, 0.6);

以下範例會建立新的空白 DataTable，然後手動填入與上述相同的資料：

var data = new google.visualization.DataTable();
data.addColumn('string', 'Task');
data.addColumn('number', 'Hours per Day');
data.addRows([
  ['Work', 11],
  ['Eat', 2],
  ['Commute', 2],
  ['Watch TV', 2],
  ['Sleep', {v:7, f:'7.000'}]
]);

方法

data.addRow();  // Add an empty row
data.addRow(['Hermione', new Date(1999,0,1)]); // Add a row with a string and a date value.

// Add a row with two cells, the second with a formatted value.
data.addRow(['Hermione', {v: new Date(1999,0,1),
                          f: 'January First, Nineteen ninety-nine'}
]);

data.addRow(['Col1Val', null, 'Col3Val']); // Second column is undefined.
data.addRow(['Col1Val', , 'Col3Val']);     // Same as previous.

data.addRows([
  ['Ivan', new Date(1977,2,28)],
  ['Igor', new Date(1962,7,5)],
  ['Felix', new Date(1983,11,17)],
  ['Bob', null] // No date set for Bob.
]);

var rowInds = data.getSortedRows([{column: 2}]);
for (var i = 0; i < rowInds.length; i++) {
  var v = data.getValue(rowInds[i], 2);
}

{"cols":[{"id":"Col1","label":"","type":"date"}],
 "rows":[
   {"c":[{"v":"a"},{"v":"Date(2010,10,6)"}]},
   {"c":[{"v":"b"},{"v":"Date(2010,10,7)"}]}
 ]
}

建構函式的 JavaScript 常值 data 參數格式

您可以將 JavaScript 字串常值物件傳遞至 data 參數以初始化 DataTable。我們將這個物件稱為 data 物件您可以根據下方說明手動編寫這個物件的程式碼，或者如果您知道如何使用 Python，而且網站能夠使用該物件，您也可以使用輔助 Python 程式庫。不過，如果您想手動建構物件，本節將提供語法說明。

首先，以下示範簡單的 JavaScript 物件範例，這個物件描述了內含三列和三個資料欄 (字串、數字和日期類型) 的資料表：

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ],
  p: {foo: 'hello', bar: 'world!'}
}

現在我們來說明語法：

data 物件包含兩個必要的頂層屬性 cols 和 rows，以及選用的 p 屬性 (可對應任意值)。

注意：顯示的所有屬性名稱和字串常數都區分大小寫。此外，如果屬性描述為字串值，則其值必須以引號括住。舉例來說，如要將類型屬性指定為數字，則應以下列方式表示：type: 'number'，但值本身為數字的表示方式如下：v: 42

cols 資源

cols 是物件陣列，用於說明每個資料欄的 ID 和類型。每個屬性都是一個含有下列屬性的物件 (區分大小寫)：

• type [必要] 資料欄中資料的資料類型。支援下列字串值 (範例包括 v: 屬性，稍後將會說明)：
  • 「boolean」：JavaScript 布林值 (「true」或「false」)。範例值： v:'true'
  • 「number」：JavaScript 數字值。範例值：v:7、v:3.14、v:-55
  • 「string」：JavaScript 字串值。範例值：v:'hello'
  • 「date」：JavaScript Date 物件 (以零算起)，時間會遭到截斷。範例值：v:new Date(2008, 0, 15)
  • 「datetime」：包含時間的 JavaScript 日期物件。範例值： v:new Date(2008, 0, 15, 14, 30, 45)
  • 「timeofday」：3 個數字和選擇性第四的陣列，代表小時 (0 代表午夜)、分、秒和選用的毫秒。範例值：v:[8, 15, 0]、v: [6, 12, 1, 144]
• id [選用] 資料欄的字串 ID。資料表中不得重複。請使用基本的英數字元，因此主機頁面不需花俏的逸出方式，就能存取 JavaScript 中的資料欄。請小心不要選擇 JavaScript 關鍵字。示例： id:'col_1'
• label [選用] 某些圖表為此資料欄顯示的字串值。範例：label:'Height'
• pattern [選用] 資料來源使用的字串模式，設定數字、日期或時間資料欄值的格式。這僅供參考，您可能不需要讀取該模式，也並不需要存在。Google 視覺化用戶端不會使用這個值 (讀取儲存格的格式化值)。如果 DataTable 來自資料來源，以回應含有 format 子句的查詢，則可能會在這個值中傳回您在此子句中指定的模式。建議的模式標準為 ICU DecimalFormat 和 SimpleDateFormat 。
• p [選用] 一種物件，是套用至儲存格的自訂值對應。這些值可以是任何 JavaScript 類型。如果您的視覺呈現支援任何儲存格層級的屬性，系統就會描述這些屬性，否則系統會忽略這個屬性。 範例： p:{style: 'border: 1px solid green;'}。

cols 示例

cols: [{id: 'A', label: 'NEW A', type: 'string'},
       {id: 'B', label: 'B-label', type: 'number'},
       {id: 'C', label: 'C-label', type: 'date'}]

rows 資源

rows 屬性會保留資料列物件的陣列。

每個資料列物件都有一個名為 c 的必要屬性，這是該資料列中儲存格的陣列。其中也包含選用的 p 屬性，用於定義要指派給整個資料列的任意自訂值的對應。如果您的視覺呈現支援任何列層級的屬性來說明這些屬性，系統就會忽略這個屬性。

儲存格物件

表格中的每個儲存格都會由具有下列屬性的物件來描述：

• v：[選用] 儲存格的值。資料類型應與資料欄的資料類型相符。如果儲存格為空值，v 屬性應為空值，但仍可有 f 和 p 屬性。
• f [選用] v 值的字串版本，已設定格式。一般來說，這些值會相符，但並非必要，因此如果您為 v 指定 Date(2008, 0, 1)，則應針對這項屬性指定「2008 年 1 月 1 日」或類似字串。系統不會根據 v 值檢查這個值。視覺化呈現不會使用這個值進行計算，只會當做顯示的標籤。如果省略此值，系統會使用預設格式設定工具自動產生 v 的字串版本。您可以使用自己的格式設定工具修改 f 值，或透過 setFormattedValue() 或 setCell() 設定，或是透過 getFormattedValue() 擷取。
• p [選用] 一種物件，是套用至儲存格的自訂值對應。這些值可以是任何 JavaScript 類型。如果您的視覺呈現支援任何儲存格層級的屬性，系統就會提供說明文字。這些屬性可由 getProperty() 和 getProperties() 方法擷取。 範例： p:{style: 'border: 1px solid green;'}。

資料列陣列中的儲存格順序應與 cols 中的資料欄說明順序相同。如要表示空值儲存格，您可以指定 null、將陣列中的儲存格留空，或省略結尾陣列成員。因此，如要表示前兩個儲存格的列含有空值，您可以指定 [ , , {cell_val}] 或 [null, null, {cell_val}]。

以下是含有三個資料欄的範例資料表物件，該物件已填入三列資料：

{
  cols: [{id: 'A', label: 'NEW A', type: 'string'},
         {id: 'B', label: 'B-label', type: 'number'},
         {id: 'C', label: 'C-label', type: 'date'}
  ],
  rows: [{c:[{v: 'a'},
             {v: 1.0, f: 'One'},
             {v: new Date(2008, 1, 28, 0, 31, 26), f: '2/28/08 12:31 AM'}
        ]},
         {c:[{v: 'b'},
             {v: 2.0, f: 'Two'},
             {v: new Date(2008, 2, 30, 0, 31, 26), f: '3/30/08 12:31 AM'}
        ]},
         {c:[{v: 'c'},
             {v: 3.0, f: 'Three'},
             {v: new Date(2008, 3, 30, 0, 31, 26), f: '4/30/08 12:31 AM'}
        ]}
  ]
}

p 屬性

資料表層級的 p 屬性是套用至整個 DataTable 的自訂值對應。這些值可以是任何 JavaScript 類型。如果您的視覺呈現支援任何資料表層級屬性，就會說明該屬性；否則，此屬性即可用於應用程式。 範例： p:{className: 'myDataTable'}。

DataView 類別

基礎 DataTable 的唯讀檢視畫面。DataView 僅允許選取部分資料欄和/或資料列，這也可讓您重新排序資料欄/資料列，以及複製資料欄/資料列。

檢視畫面是基礎 DataTable 上的即時視窗，而非資料的靜態快照。但是，您仍然必須小心變更資料表本身的「結構」，如下所述：

• 新增或移除基礎資料表中的「資料欄」不會反映在檢視表中，且可能會導致檢視畫面出現非預期的行為；您必須從 DataTable 建立新的 DataView，才能納入這些變更。
• 在基礎資料表中新增或移除「資料列」安全無虞，變更會立即套用至檢視區塊 (但在這項變更完成後，您必須對所有視覺化內容呼叫 draw()，才能顯示新資料列)。請注意，如果您的檢視表已透過呼叫其中一種 setRows() or hideRows() 方法篩除資料列，並在基礎資料表中新增或移除資料列，則行為會是非預期的行為；您必須建立新的 DataView 來反映新的資料表。
• 變更現有儲存格中的儲存格值安全無虞，且變更會立即套用到 DataView (但在這項變更完成後，您必須對所有視覺呈現呼叫 draw()，才能顯示新的儲存格值)。

也可以從其他 DataView 建立 DataView。請注意，每當提及基礎資料表或檢視表時，這裡所指的層級是指這個層級正下方的等級。換句話說，它是指用於建構這個 DataView 的資料物件。

DataView 也支援計算結果欄；這些資料欄的值是由您提供的函式即時計算而得。例如，您可以加入包含兩個前面資料欄的總和，或是另一個資料欄計算並顯示日期季度的資料欄。詳情請參閱 setColumns()。

如果您隱藏或顯示資料列或資料欄來修改 DataView，則除非您再次呼叫視覺化的 draw()，否則圖表不會受到影響。

您可以將 DataView.getFilteredRows() 與 DataView.setRows() 結合，建立包含一些有趣資料子集的 DataView，如下所示：

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(6);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));
data.setCell(3, 0, 'Frank');
data.setCell(3, 1, new Date(2007, 11, 28));
data.setCell(4, 0, 'Floyd');
data.setCell(4, 1, new Date(2005, 3, 13));
data.setCell(5, 0, 'Fritz');
data.setCell(5, 1, new Date(2007, 9, 2));

// Create a view that shows everyone hired since 2007.
var view = new google.visualization.DataView(data);
view.setRows(view.getFilteredRows([{column: 1, minValue: new Date(2007, 0, 1)}]));
var table = new google.visualization.Table(document.getElementById('test_dataview'));
table.draw(view, {sortColumn: 1});

建構函式

您可以透過以下兩種方式建立新的 DataView 執行個體：

建構函式 1

var myView = new google.visualization.DataView(data)

data

用於初始化檢視畫面的 DataTable 或 DataView。根據預設，檢視表包含基礎資料表或檢視表中的所有欄和資料列，並按照原始順序排列。如要在這個檢視畫面中隱藏或顯示資料列或資料欄，請呼叫適當的 set...() 或 hide...() 方法。

另請參閱：

setColumns()、hideColumns()、setRows()、hideRows()。

建構函式 2

此建構函式會將序列化的 DataView 指派給 DataTable 來建立新的 DataView。這可協助您使用 DataView.toJSON() 重新建立序列化的 DataView。

var myView = google.visualization.DataView.fromJSON(data, viewAsJson)

資料

用來建立 DataView 的 DataTable 物件，在該物件中稱為 DataView.toJSON()。如果這份資料表與原始資料表不同，就會產生無法預測的結果。

viewAsJson

DataView.toJSON() 傳回的 JSON 字串。此說明說明瞭「資料」資料表中要顯示或隱藏哪些資料列。

方法

// Show some columns directly from the underlying data.
// Shows column 3 twice.
view.setColumns([3, 4, 3, 2]);

// Underlying table has a column specifying a value in centimeters.
// The view imports this directly, and creates a calculated column
// that converts the value into inches.
view.setColumns([1,{calc:cmToInches, type:'number', label:'Height in Inches'}]);
function cmToInches(dataTable, rowNum){
  return Math.floor(dataTable.getValue(rowNum, 1) / 2.54);
}

ChartWrapper 類別

ChartWrapper 類別可用於包裝圖表，並處理圖表的所有載入、繪圖和資料來源查詢。這個類別會公開方便設定圖表值及繪製圖表的值。這個類別可簡化從資料來源讀取作業，因為您不需要建立查詢回呼處理常式。也可以儲存圖表，以便日後重複使用。

使用 ChartWrapper 的另一個好處是，您可以使用動態載入來減少程式庫負載。此外，您不需要明確載入套件，因為 ChartWrapper 會為您查詢及載入圖表套件。詳情請參閱下方範例。

不過，ChartWrapper 目前只會傳播圖表擲回的部分事件：選取、就緒和錯誤。其他事件不會透過 ChartWrapper 執行個體傳輸。如要取得其他事件，您必須呼叫 getChart() 並直接在圖表控點上訂閱事件，如下所示：

var wrapper;
function drawVisualization() {

  // Draw a column chart
  wrapper = new google.visualization.ChartWrapper({
    chartType: 'ColumnChart',
    dataTable: [['Germany', 'USA', 'Brazil', 'Canada', 'France', 'RU'],
                [700, 300, 400, 500, 600, 800]],
    options: {'title': 'Countries'},
    containerId: 'visualization'
  });

  // Never called.
  google.visualization.events.addListener(wrapper, 'onmouseover', uselessHandler);

  // Must wait for the ready event in order to
  // request the chart and subscribe to 'onmouseover'.
  google.visualization.events.addListener(wrapper, 'ready', onReady);

  wrapper.draw();

  // Never called
  function uselessHandler() {
    alert("I am never called!");
  }

  function onReady() {
    google.visualization.events.addListener(wrapper.getChart(), 'onmouseover', usefulHandler);
  }

  // Called
  function usefulHandler() {
    alert("Mouseover event!");
  }
}

建構函式

ChartWrapper(opt_spec)

opt_spec

[選用] - 可以是定義圖表的 JSON 物件，或是該物件的序列化字串版本。如需此物件的格式，請參閱 drawChart() 說明文件。如未指定，您必須使用這個物件所公開的 set... 方法，設定所有適當的屬性。

方法

ChartWrapper 提供下列其他方法：

活動

ChartWrapper 物件會擲回以下事件。請注意，您必須在擲回任何事件前呼叫 ChartWrapper.draw()。

範例

以下兩個程式碼片段會建立對應的折線圖。第一個範例使用 JSON 常值標記法定義圖表，第二個範例則使用 ChartWrapper 方法來設定這些值。

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>Google Visualization API Sample</title>
<!--
  One script tag loads all the required libraries!
-->
<script type="text/javascript"
      src='https://www.gstatic.com/charts/loader.js'></script>
<script>
  google.charts.load('current);
  google.charts.setOnLoadCallback(drawVisualization);

  function drawVisualization() {
    var wrap = new google.visualization.ChartWrapper({
       'chartType':'LineChart',
       'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
       'containerId':'visualization',
       'query':'SELECT A,D WHERE D > 100 ORDER BY D',
       'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
       });
     wrap.draw();
  }
</script>
</head>
<body>
  <div id="visualization" style="height: 400px; width: 400px;"></div>
</body>
</html>

相同的圖表，現在使用 setter 方法：

<!DOCTYPE html>
<html>
<head>
<meta http-equiv='content-type' content='text/html; charset=utf-8'/>
<title>Google Visualization API Sample</title>
<!-- One script tag loads all the required libraries!
-->
<script type="text/javascript"
    src='https://www.gstatic.com/charts/loader.js'></script>
<script type="text/javascript">
  google.charts.load('current');
  google.charts.setOnLoadCallback(drawVisualization);
  function drawVisualization() {
    // Define the chart using setters:
    var wrap = new google.visualization.ChartWrapper();
    wrap.setChartType('LineChart');
    wrap.setDataSourceUrl('http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');
    wrap.setContainerId('visualization');
    wrap.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    wrap.setOptions({'title':'Population Density (people/km^2)', 'legend':'none'});
    wrap.draw();
  }
</script>
</head>
<body>
  <div id='visualization' style='height: 400px; width: 400px;'></div>
</body>
</html>

ChartEditor 類別

ChartEditor 類別是用於開啟網頁內對話方塊，讓使用者即時自訂視覺化內容。

使用 ChartEditor 的方式如下：

1. 載入 charteditor 套件。 在 google.charts.load() 中，載入套件「charteditor」。您不需要針對要在編輯器中轉譯的圖表類型載入套件；圖表編輯器會視需要載入任何套件。
2. 建立 ChartWrapper 物件，定義供使用者自訂的圖表。這個圖表會顯示在對話方塊中，使用者可使用編輯器重新設計圖表、變更圖表類型，甚至是變更來源資料。
3. 建立新的 ChartEditor 執行個體，並註冊以監聽「ok」事件。使用者按一下對話方塊中的「OK」按鈕時，就會擲回這個事件。收到後，您應該呼叫 ChartEditor.getChartWrapper() 來擷取使用者修改的圖表。
4. 呼叫 ChartEditor.openDialog()，傳入 ChartWrapper。系統隨即會開啟對話方塊。對話方塊按鈕可讓使用者關閉編輯器。ChartEditor 執行個體只要位於範圍內即可使用，不會在使用者關閉對話方塊後自動刪除。
5. 如要更新程式碼中圖表，請呼叫 setChartWrapper()。

方法

選項

圖表編輯器支援下列選項：

活動

圖表編輯器會擲回下列事件：

範例

以下範例程式碼會開啟圖表編輯器對話方塊，其中顯示已填入的折線圖。如果使用者按一下「確定」，編輯過的圖表就會儲存至頁面中指定的 <div>。

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
  <title>
    Google Visualization API Sample
  </title>
  <script type="text/javascript"
    src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
    google.charts.load('current', {packages: ['charteditor']});
  </script>
  <script type="text/javascript">
    google.charts.setOnLoadCallback(loadEditor);
    var chartEditor = null;

    function loadEditor() {
      // Create the chart to edit.
      var wrapper = new google.visualization.ChartWrapper({
         'chartType':'LineChart',
         'dataSourceUrl':'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1',
         'query':'SELECT A,D WHERE D > 100 ORDER BY D',
         'options': {'title':'Population Density (people/km^2)', 'legend':'none'}
      });

      chartEditor = new google.visualization.ChartEditor();
      google.visualization.events.addListener(chartEditor, 'ok', redrawChart);
      chartEditor.openDialog(wrapper, {});
    }

    // On "OK" save the chart to a <div> on the page.
    function redrawChart(){
      chartEditor.getChartWrapper().draw(document.getElementById('vis_div'));
    }

  </script>
</head>
<body>
  <div id="vis_div" style="height: 400px; width: 600px;"></div>
</body>
</html>

資料操縱方法

google.visualization.data 命名空間保留靜態方法，對 DataTable 物件執行類似 SQL 的作業，例如彙整這些物件或依資料欄值分組。

google.visualization.data 命名空間公開下列方法：

group()

取用填入的 DataTable 物件，並執行類似 SQL 的 GROUP BY 作業，傳回資料表，這些資料表的列數以指定資料欄值分組。請注意，這不會修改輸入 DataTable。

傳回的資料表會針對指定索引鍵資料欄中的每一組值納入一列。每個資料列都會包含索引鍵資料欄，以及符合鍵組合的所有資料列中，含有匯總資料欄值的資料欄 (例如指定資料欄中所有值的加總或計數)。

google.visualization.data 命名空間包含數個實用的匯總值 (例如 sum 和 count)，但您可以自行定義 (例如 standardDeviation 或 secondHighest)。您可以在方法說明之後，查看如何定義自己的匯總器。

語法

google.visualization.data.group(data_table, keys, columns)

data_table

輸入內容 DataTable。這不會透過呼叫 group() 來修改。

keys

數字和/或物件的陣列，用於指定要做為分組依據的資料欄。結果資料表包含此陣列中的所有資料欄，以及資料欄中的所有資料欄。如果數字，則為輸入 DataTable 的欄索引，做為分組依據。如果是物件，其中會包含可以修改指定資料欄的函式 (例如，在該欄的值中新增 1)。物件須具備下列屬性：

• 資料欄 - 從 dt 要套用轉換的目標欄索引的數字。
• 修飾符 - 可接受一個值 (該欄中每一列的儲存格值)，並傳回修改過的值。此函式可用於修改資料欄值來協助分組：例如，呼叫會從日期資料欄計算季度的 conQuarter 函式，讓 API 可以依季將資料列分組。計算值會顯示在傳回資料表的索引鍵資料欄中。這個函式可在這個物件中以內嵌方式宣告，也可以是您在程式碼其他位置定義的函式 (必須在呼叫範圍內)。API 提供一個簡單的修飾符函式；請參閱這篇文章的操作說明，瞭解如何自行建立更實用的函式。您必須知道這個函式可接受的資料類型，且只能在該類型的資料欄上呼叫該類型。您也必須知道這個函式的傳回類型，並在下述的 type 屬性中宣告此函式。
• type - 函式 modifier 傳回的類型。應為 JavaScript 字串類型名稱，例如「數字」或「布林值」。
• label - [選用] 要在傳回的 DataTable 中指派這個資料欄的字串標籤。
• id - [選用] 用來在傳回的 DataTable 中指派此資料欄的字串 ID。

範例： [0]、[0,2]、[0,{column:1, modifier:myPlusOneFunc, type:'number'},2]

資料欄

[選用] 除了索引鍵資料欄以外，您還可以指定要納入輸出資料表的資料欄。由於資料列群組中的所有資料列都會壓縮成單一輸出資料列，因此您必須決定該資料列群組要顯示的值。舉例來說，您可以選擇顯示資料集中第一列的資料欄值，或顯示該群組中所有資料列的平均值。 資料欄是物件的陣列，包含下列屬性：

• 資料欄 - 指定要顯示的資料欄索引的數字。
• 匯總 - 這個函式會接受此資料列群組中該資料欄所有值的陣列，並傳回一個要在結果列中顯示的單一值。傳回值必須是物件 type 屬性指定的類型。以下提供自行建立匯總函式的詳細資訊。您必須知道這個方法接受的資料類型，並只在適當類型的資料欄中呼叫該資料類型。API 提供多個實用的匯總函式。如需清單，請參閱下方的「提供的匯總函式」一節，或「建立匯總函式」一文，瞭解如何編寫自己的匯總函式。
• type - 匯總函式的傳回類型。應為 JavaScript 字串類型名稱，例如「數字」或「布林值」。
• label - [選用] 要在傳回資料表中套用至這個資料欄的字串標籤。
• id - [選用] 要在傳回資料表中套用至此資料欄的字串 ID。

傳回值

DataTable，每個 keys 欄列出的每個資料欄都有一個資料欄，而資料欄中所列的每一欄則各有一個資料欄。資料表會按照索引鍵列，從左到右排序。

範例

// This call will group the table by column 0 values.
// It will also show column 3, which will be a sum of
// values in that column for that row group.
var result = google.visualization.data.group(
  dt,
  [0],
  [{'column': 3, 'aggregation': google.visualization.data.sum, 'type': 'number'}]
);

*Input table*
1  'john'  'doe'            10
1  'jane'  'doe'           100
3  'jill'  'jones'          50
3  'jack'  'jones'          75
5  'al'    'weisenheimer'  500

*Output table*
1  110
3  125
5  500

提供的修飾符函式

API 提供下列修飾符函式，您可以將這些函式傳入金鑰中。modifier 參數來自訂分組行為。

提供的匯總函式

API 提供下列匯總函式，您可以將這些函式傳入資料欄中。aggregate 參數陣列。

建立修飾符函式

您可以建立修飾符函式，在 group() 函式將資料列分組之前，對索引鍵值執行簡單的轉換。這個函式會使用單一儲存格值、對其執行動作 (例如為值加上 1)，然後再傳回該函式。輸入和傳回類型不必相同，但呼叫端必須知道輸入和輸出類型。下方為可接受日期並傳回季度的函式範例：

// Input type: Date
// Return type: number (1-4)
function getQuarter(someDate) {
  return Math.floor(someDate.getMonth()/3) + 1;
}

建立匯總函式

您可以建立匯總函式，在資料列群組中接受一組資料欄值並傳回單一數字：例如，傳回值的計數或平均值。以下實作提供的計數匯總函式，會傳回資料列群組中的資料列計數：

// Input type: Array of any type
// Return type: number
function count(values) {
  return values.length;
}

join()

這個方法與 SQL JOIN 陳述式類似，可將兩個資料表 (DataTable 或 DataView 物件) 彙整為單一結果資料表。您可以在兩個資料表之間指定一或多個資料欄組合 (key 資料欄)，輸出資料表會根據您指定的彙整方法包含這些資料列：僅限同時符合兩個鍵的資料列；單一資料表中的所有資料列；或兩個資料表中的所有資料列 (無論鍵是否相符)。結果資料表僅包含索引鍵資料欄，以及您指定的任何其他資料欄。請注意，dt2 不能有重複的鍵，但 dt1 可以。「鍵」一詞是指所有鍵資料欄值的組合，而非特定索引鍵資料欄值的組合。因此，如果資料列包含儲存格值 A | B | C 和資料欄 0 和 1，就是索引鍵資料欄，那麼該資料列的鍵是 AB。

語法

google.visualization.data.join(dt1, dt2, joinMethod,
                                 keys, dt1Columns, dt2Columns);

dt1

填入的 DataTable 以便與 dt2 彙整。

dt2

填入要與 dt1 彙整的 DataTable。這個資料表不能含有多個相同的鍵 (索引鍵是索引鍵資料欄值的組合)。

joinMethod

指定彙整類型的字串。如果 dt1 有多個資料列與 dt2 資料列相符，輸出資料表就會包含所有相符的 dt1 資料列。請選取下列值：

• 「full」：無論鍵是否相符，輸出資料表都會包含這兩個資料表中的所有資料列。不相符的資料列將包含空值的儲存格項目；相符的資料列會合併。
• 「inner」：經過篩選的完整彙整作業，只包含鍵符合的資料列。
• 「left」：輸出資料表包含 dt1 中的所有資料列，無論 dt2 中是否有相符的資料列。
• 「right」：輸出資料表包含 dt2 中的所有資料列，無論 dt1 中是否有相符的資料列。

keys

兩個資料表要比較的索引鍵資料欄陣列。每個組合都是兩個元素陣列，第一個是 dt1 中的鍵，第二個則是 dt2 中的鍵。此陣列可根據索引、ID 或標籤指定資料欄，請參閱 getColumnIndex。
兩個資料表的資料欄類型必須相同。所有指定的索引鍵都必須根據 joinMethod 提供的規則比對，才能包含資料表中的資料列。輸出資料表一律會包含索引鍵資料欄。只有左側資料表的 dt1 可以包含重複的鍵；dt2 中的鍵不得重複。這裡的「鍵」一詞是指一組不重複的索引鍵資料欄，而非個別資料欄值。例如，如果索引鍵資料欄是 A 和 B，下表將只會有不重複的索引鍵值 (因此可做為 dt2)：

A	B
千	紅色
千	藍色的
Fred	紅色

範例： [[0,0], [2,1]] 會比較兩個資料表中第一欄、dt1 的第三欄與 dt1 的第二個資料欄的值。

dt1Columns

dt1 中資料欄陣列，除了 dt1 的鍵欄以外，還要納入輸出資料表。此陣列可以按照索引、ID 或標籤指定資料欄，請參閱 getColumnIndex。

dt2Columns

dt2 中資料欄陣列，除了 dt2 的鍵欄以外，還要納入輸出資料表。此陣列可以按照索引、ID 或標籤指定資料欄，請參閱 getColumnIndex。

傳回值

包含索引鍵資料欄 dt1Columns 和 dt1Columns 的 DataTable。這個資料表是依索引鍵資料欄由左至右排序。當 joinMethod 為「inner」時，應填入所有鍵儲存格。針對其他彙整方法，如果找不到相符的鍵，則該資料表的任何不相符鍵儲存格都會有空值。

例子

*Tables*
dt1                        dt2
bob  | 111 | red           bob   | 111 | point
bob  | 111 | green         ellyn | 222 | square
bob  | 333 | orange        jane  | 555 | circle
fred | 555 | blue          jane  | 777 | triangle
jane | 777 | yellow        fred  | 666 | dodecahedron
* Note that right table has duplicate Jane entries, but the key we will use is
* columns 0 and 1. The left table has duplicate key values, but that is
* allowed.

*Inner join* google.visualization.data.join(dt1, dt2, 'inner', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red    | point
bob  | 111 | green  | point
jane | 777 | yellow | triangle
* Note that both rows from dt1 are included and matched to
* the equivalent dt2 row.


*Full join* google.visualization.data.join(dt1, dt2, 'full', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red    | point
bob   | 111 | green  | point
bob   | 333 | orange | null
ellyn | 222 | null | square
fred  | 555 | blue   | null
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle


*Left join*  google.visualization.data.join(dt1, dt2, 'left', [[0,0],[1,1]], [2], [2]);
bob  | 111 | red | point
bob  | 111 | green | point
bob  | 333 | orange | null
fred | 555 | blue | null
jane | 777 | yellow | triangle


*Right join*  google.visualization.data.join(dt1, dt2, 'right', [[0,0],[1,1]], [2], [2]);
bob   | 111 | red | point
bob   | 111 | green | point
ellyn | 222 | null | square
fred  | 666 | null | dodecahedron
jane  | 555 | null | circle
jane  | 777 | yellow | triangle

格式設定工具

Google Visualization API 提供格式設定工具，可用於將視覺化資料重新格式化。這些格式設定工具會變更所有資料列中指定資料欄的格式化值。請注意：

• 格式轉換程式只會修改格式化值，不會修改基礎值。舉例來說，顯示的值會是「$1,000.00」，但基礎值仍為「1000」。
• 格式器一次只會影響一個資料欄。如要將多個資料欄重新格式化，請將格式設定工具套用至您要變更的每個資料欄。
• 如果您也使用使用者定義的格式設定工具，某些 Google 視覺化格式設定工具會覆寫所有使用者定義的格式設定工具。

套用至資料的實際格式是由 API 載入時使用的語言代碼衍生而來。詳情請參閱「 載入特定語言代碼的圖表 」。

重要事項：格式設定工具只能與 DataTable 搭配使用，無法與 DataView 搭配使用 (DataView 物件為唯讀狀態)。

以下是使用格式設定工具的一般步驟：

1. 取得已填入的 DataTable 物件。
2. 為要重新設定格式的每個資料欄：
   1. 建立物件，指定格式設定工具的所有選項。這是具有一組屬性和值的基本 JavaScript 物件。請參閱格式設定工具的說明文件，瞭解支援的屬性。(您也可以選擇傳入物件常值標記物件，以指定選項)。
   2. 建立格式設定工具，傳入選項物件。
   3. 呼叫 formatter.format(table, colIndex)，傳入 DataTable 和 (以零為基準) 的資料欄編號，以便重新格式化。請注意，您只能對每個資料欄套用一個格式設定工具；套用第二個格式設定工具只會覆寫第一個格式設定工具的效果。
      重要事項：許多格式設定工具都需要 HTML 標記來顯示特殊的格式；如果您的視覺呈現支援 allowHtml 選項，請將其設為 true。

以下範例說明如何將日期資料欄的格式值變更為使用長日期格式 (「2009 年 1 月 1 日」)：

var data = new google.visualization.DataTable();
data.addColumn('string', 'Employee Name');
data.addColumn('date', 'Start Date');
data.addRows(3);
data.setCell(0, 0, 'Mike');
data.setCell(0, 1, new Date(2008, 1, 28));
data.setCell(1, 0, 'Bob');
data.setCell(1, 1, new Date(2007, 5, 1));
data.setCell(2, 0, 'Alice');
data.setCell(2, 1, new Date(2006, 7, 16));

// Create a formatter.
// This example uses object literal notation to define the options.
var formatter = new google.visualization.DateFormat({formatType: 'long'});

// Reformat our data.
formatter.format(data, 1);

// Draw our data
var table = new google.visualization.Table(document.getElementById('dateformat_div'));
table.draw(data, {showRowNumber: true});

大部分的格式器提供以下兩種方法：

方法	說明
google.visualization.formatter_name(options)	建構函式，其中 formatter_name 是規格格式設定類別名稱。 options - 一般 JavaScript 物件，用於指定該格式設定工具的選項。這個物件屬於一般物件，含屬性/值組合，以及該格式器專屬的屬性。如要瞭解支援的選項，請參閱特定格式設定工具的說明文件。以下兩個範例說明如何呼叫 DateFormat 物件的建構函式，並傳入兩個屬性： // Object literal technique var formatter = new google.visualization.DateFormat({formatType: 'long', timeZone: -5}); // Equivalent property setting technique var options = new Object(); options['formatType'] = 'long'; options['timeZone'] = -5; var formatter = new google.visualization.DateFormat(options);
format(data, colIndex)	在指定資料欄中重新格式化資料。 data - 包含要重新格式化資料的 DataTable。無法在這裡使用 DataView。 colIndex - 要設定格式的資料欄索引 (從零開始)。如要設定多個資料欄的格式，您必須以不同的 colIndex 值多次呼叫此方法。

 

Google Visualization API 提供以下格式設定器：

格式設定工具名稱	說明
ArrowFormat	新增向上或向下箭頭，指出儲存格值是否高於或低於指定值。
BarFormat	新增彩色長條，方向和顏色指出儲存格值是否高於或低於指定值。
ColorFormat	根據值是否落在指定範圍內，為儲存格加上顏色。
DateFormat	以多種不同方式設定 Date 或 DateTime 值的格式，包括「2009 年 1 月 1 日」、「2009 年 1 月 1 日」和「2009 年 1 月 1 日」。
NumberFormat	設定數值的各個方面格式。
PatternFormat	將同一資料列中的儲存格值和任意文字串連至指定的儲存格。

ArrowFormat

依據值是高於或低於指定底值，將向上或向下箭頭新增至數字儲存格。如果等於底數，就不會顯示箭頭。

選項

ArrowFormat 支援下列選項並傳入建構函式：

選項	說明
base	代表底數的數字，用來與儲存格值比較。如果儲存格的值比較高，儲存格就會包含綠色向上箭頭；如果儲存格值較低，則會出現紅色向下箭頭；如果儲存格值相同，則無箭頭。

程式碼範例

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues Change');
data.addRows([
  ['Shoes', {v:12, f:'12.0%'}],
  ['Sports', {v:-7.3, f:'-7.3%'}],
  ['Toys', {v:0, f:'0%'}],
  ['Electronics', {v:-2.1, f:'-2.1%'}],
  ['Food', {v:22, f:'22.0%'}]
]);

var table = new google.visualization.Table(document.getElementById('arrowformat_div'));

var formatter = new google.visualization.ArrowFormat();
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true});

BarFormat

在數字儲存格中加入彩色長條，指示儲存格值是否高於或低於指定底值。

選項

BarFormat 支援下列選項並傳入建構函式：

選項	範例 說明
base	要與儲存格值比較的底值數字。如果儲存格值較高，就會繪製在底座的右側；如果儲存格值較低，就會向左繪製。預設值為 0。
colorNegative	字串，指出長條的負值部分。可能的值包括「red」、「green」和「blue」。預設值為「red」。
colorPositive	指出長條中正值部分顏色的字串。可能的值包括「red」、「green」和「blue」。預設值為「blue」。
drawZeroLine	布林值，表示在存在負值時，是否要繪製 1 像素的深色底線。 黑暗線的確是增強長條的視覺掃描效果。預設值為「false」。
max	長條範圍的最大值。預設值為資料表中的最高值。
min	長條範圍的最小值。預設值為資料表中的最低值。
showValue	如為 true，則顯示值和長條；如果為 false，則只會顯示長條。預設值為 true。
width	每個長條的粗細，以像素為單位。預設值為 100。

程式碼範例

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('barformat_div'));

var formatter = new google.visualization.BarFormat({width: 120});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

ColorFormat

依據儲存格的值，將顏色指派給數字儲存格的前景或背景。這個格式設定工具並不常見，因為其不會在建構函式中取得其選項。您必須先呼叫 addRange() 或 addGradientRange() (次數不限)，然後再呼叫 format() 才能新增色彩範圍。您可以使用任何可接受的 HTML 格式指定顏色，例如「black」、「#000000」或「#000」。

方法

ColorFormat 支援下列方法：

方法	說明
google.visualization.ColorFormat()	建構函式。不採用引數。
addRange(from, to, color, bgcolor)	依據儲存格的值指定前景顏色和/或背景顏色。任何值為指定 from—to 範圍的儲存格，都會指派為 color 和 bgcolor。請務必瞭解這個範圍是不包容的，因為如果建立介於 1 到 1,000 和 1,000 至 2,000 之間的範圍，則無法涵蓋值 1,000！ from - [String, Number, Date, DateTime, or TimeOfDay] 範圍的下限 (含) 或空值。如果為空值，系統會比對 -∞。系統會按字母順序和字串值比較字串邊界， to - [String, Number, Date, DateTime, or TimeOfDay]] 範圍的高邊界 (不包含) 或空值。如果為空值，會比對 +∞。系統會按字母順序與字串值比較字串邊界。 color - 相符儲存格中要套用至文字的顏色。值可以是「#RRGGBB」值或已定義顏色常數 (例如「#FF0000」或「red」)。 bgcolor - 相符儲存格背景要套用的顏色。值可以是「#RRGGBB」值或已定義顏色常數 (例如「#FF0000」或「red」)。
addGradientRange(from, to, color, fromBgColor, toBgColor)	依據儲存格值指定範圍的背景顏色。色彩會縮放，以符合儲存格的值在下限和上限顏色範圍之間。請注意，這個方法無法比較字串值，因為 addRange() 可以。提示：色彩範圍通常難以準確計算；最容易閱讀且最容易閱讀的範圍是從完全飽和至白色 (例如#FF0000—FFFFFF)。 from - [Number, Date, DateTime, or TimeOfDay] 範圍的下限 (含) 或空值。如果為空值，則會比對 -∞。 to - [Number, Date, DateTime, or TimeOfDay] 範圍的較高邊界 (不包含)，或空值。如果為空值，系統會比對 +∞。 color - 相符儲存格中要套用至文字的顏色。無論儲存格的值為何，所有儲存格的這個顏色都相同。 fromBgColor - 在漸層低端保留值的儲存格背景顏色。值可以是「#RRGGBB」值或已定義顏色常數 (例如「#FF0000」或「red」)。 toBgColor - 在漸層高端保留值的儲存格背景顏色。值可以是「#RRGGBB」值或已定義顏色常數 (例如「#FF0000」或「red」)。
format(dataTable, columnIndex)	標準 format() 方法，可將格式套用至指定資料欄。

程式碼範例

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('colorformat_div'));

var formatter = new google.visualization.ColorFormat();
formatter.addRange(-20000, 0, 'white', 'orange');
formatter.addRange(20000, null, 'red', '#33ff33');
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

DateFormat

以多種方式設定 JavaScript Date 值，包括「2016 年 1 月 1 日」、「2016 年 1 月 1 日」和「2016 年 1 月 1 日」。

選項

DateFormat 支援下列選項並傳入建構函式：

選項	說明
formatType	日期的快速格式設定選項。系統支援下列字串值，並重新格式化 2016 年 2 月 28 日，如下所示： 「short」- 簡短格式：例如「2016 年 2 月 28 日」 「中」- 媒介格式：例如「2016 年 2 月 28 日」 「long」- 格式：例如「2016 年 2 月 28 日」 您無法同時指定 formatType 和 pattern。
pattern	要套用至值的自訂格式模式，類似 ICU 日期和時間格式。例如：var formatter3 = new google.visualization.DateFormat({pattern: "EEE, MMM d, ''yy"}); 您無法同時指定 formatType 和 pattern。如要進一步瞭解模式，請參閱下一節。
timeZone	顯示日期值的時區。此為數值，表示 GMT + 這個時區數量 (可以是負數)。建立日期物件時，預設會使用建立物件所在電腦的假設時區，此選項可用於在不同時區中顯示該值。舉例來說，如果您在英國格林威治的電腦建立下午 5 點的日期物件，並指定 -5 (options['timeZone'] = -5，或是美國的東部太平洋時間)，顯示的值會是 12 中午。

方法

DateFormat 支援下列方法：

方法	說明
google.visualization.DateFormat(options)	建構函式。詳情請參閱上方的選項一節。
format(dataTable, columnIndex)	將格式套用至指定資料欄的標準 format() 方法。
formatValue(value)	傳回指定值的格式化值。 這個方法不需要 DataTable。

程式碼範例

function drawDateFormatTable() {
  var data = new google.visualization.DataTable();
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date (Long)');
  data.addColumn('date', 'Start Date (Medium)');
  data.addColumn('date', 'Start Date (Short)');
  data.addRows([
    ['Mike', new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26),
             new Date(2008, 1, 28, 0, 31, 26)],
    ['Bob', new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0),
            new Date(2007, 5, 1, 0)],
    ['Alice', new Date(2006, 7, 16),
              new Date(2006, 7, 16),
              new Date(2006, 7, 16)]
  ]);

  // Create three formatters in three styles.
  var formatter_long = new google.visualization.DateFormat({formatType: 'long'});
  var formatter_medium = new google.visualization.DateFormat({formatType: 'medium'});
  var formatter_short = new google.visualization.DateFormat({formatType: 'short'});

  // Reformat our data.
  formatter_long.format(data, 1);
  formatter_medium.format(data,2);
  formatter_short.format(data, 3);

  // Draw our data
  var table = new google.visualization.Table(document.getElementById('dateformat_div'));
  table.draw(data, {showRowNumber: true, width: '100%', height: '100%'});
}

進一步瞭解日期模式

以下進一步說明系統支援的模式：

模式類似於 ICU 日期和時間格式，但系統尚未支援下列模式：A e D F g Y u w W。為避免與模式發生衝突，您要在輸出內容中顯示的任何常值，前後均應以單引號括住，但單引號除外，例如單引號雙引號。例如："K 'o''clock.'"。

模式	說明	輸出內容範例
GG	時代設計師。	「AD」
yy 或 yyyy	。	1996
M	月份。一月： M 生產 1 MM 會產生 01 行銷組合模式分析在 1 月製造 行銷組合模式分析在 1 月產生	「7 月」 「07」
d	一個月內的第幾天。額外 'd' 值會在前面加上零。	10
小時	12 小時制調整時段。額外的 'h' 值會在前面加上零。	12
H	採 24 小時制，以小時為單位。如果設定額外的十六進位值，則會在前面加上零。	0
m	一小時內的第幾分鐘。額外的「M」值會在前面加上零。	30
秒	一分鐘內的第幾秒。額外的 值會在前面加上零。	55
六	小數秒秒。額外的「S」值會在右側填充為零。	978
E	星期幾。下方為「Tuesday」(星期二) 的輸出內容： E 產生 T EE 或 EEE EEEE 每週二生產	「星期二」 「星期二」
aa	上午/下午	「下午」
k	一天內的時刻 (1~24)。如果多餘的「k」值，則會加上開頭的零。	24
K	上午/下午的時段 (0~11)。如果多餘的「k」值，則會加上開頭的零。	0
z	時區。時區 5 會產生「UTC+5」	「UTC+5」
Z	RFC 822 格式的時區。時區 -5： Z、ZZ、ZZZ 產生 -0500 其他內容會產生「GMT -05:00」	「-0800」 「GMT -05:00」
v	時區 (一般)。	「錯誤/格林威治標準時間-5」
'	逸出為文字	日期=
''	單引號	Y

NumberFormat

說明數字資料欄的格式。格式選項包括指定前置字元符號 (例如錢幣符號)，或是用於數千個標記的標點符號。

選項

NumberFormat 支援下列選項並傳入建構函式：

選項	說明
decimalSymbol	做為小數標記使用的字元。預設值為點 (.)。
fractionDigits	指定小數點後要顯示的位數。預設值為 2。如果您指定的位數大於包含的數字，則較小的值將顯示零。截斷的值將無條件進位 (5 無條件進位)。
groupingSymbol	這個字元的用途是將小數左邊的數字分組成 3 組。預設值為逗號 (,)。
negativeColor	負值的文字顏色。沒有預設值。值可以是任何可接受的 HTML 顏色值，例如「red」或「#FF0000」。
negativeParens	布林值，其中 true 代表負值應以括號括住。預設值為 true。
pattern	格式字串。如有提供，系統會忽略 negativeColor 以外的所有其他選項。 格式字串是 ICU 模式集 的一部分。 舉例來說，{pattern:'#,###%'} 會產生「1,000%」、「750%」和「50%」來代表值 10、7.5 及 0.5。
prefix	值的字串前置字串，例如「$」。
suffix	值的字串後置字串，例如「%」。

方法

NumberFormat 支援下列方法：

方法	說明
google.visualization.NumberFormat(options)	建構函式。詳情請參閱上方的選項一節。
format(dataTable, columnIndex)	標準 format() 方法，可將格式套用至指定資料欄。
formatValue(value)	傳回指定值的格式化值。這個方法不需要 DataTable。

程式碼範例

var data = new google.visualization.DataTable();
data.addColumn('string', 'Department');
data.addColumn('number', 'Revenues');
data.addRows([
  ['Shoes', 10700],
  ['Sports', -15400],
  ['Toys', 12500],
  ['Electronics', -2100],
  ['Food', 22600],
  ['Art', 1100]
]);

var table = new google.visualization.Table(document.getElementById('numberformat_div'));

var formatter = new google.visualization.NumberFormat(
    {prefix: '$', negativeColor: 'red', negativeParens: true});
formatter.format(data, 1); // Apply formatter to second column

table.draw(data, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

PatternFormat

可讓您將指定資料欄的值和任意文字合併成單一資料欄。舉例來說，如果其中一個資料欄包含名字和姓氏，您可以在第三欄中填入「{last name}」{first name}。這個格式轉換工具不符合建構函式和 format() 方法的慣例。如需操作說明，請參閱下方的「方法」一節。

方法

PatternFormat 支援下列方法：

方法	說明
google.visualization.PatternFormat(pattern)	建構函式。不接受選項物件。而是採用字串 pattern 參數。這個字串說明要放入目的地資料欄的哪些資料欄值，以及任何文字。將預留位置嵌入字串，以指出要嵌入的其他資料欄的值。預留位置是 {#}，其中 # 是要使用的來源資料欄索引。該索引是下方 format() 方法中 srcColumnIndices 陣列中的索引。如要加入常值 { 或 } 字元，應採用以下逸出形式：\{ 或 \}。如要加入常值 \ 符號，請逸出為 \\。 程式碼範例 下例示範可建立錨點元素的模式建構函式，其中包含從 format() 方法擷取的第一個和第二個元素： var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>');
format(dataTable, srcColumnIndices, opt_dstColumnIndex)	標準格式呼叫，包含一些其他參數： dataTable - 要運作的資料表。 srcColumnIndices - 一或多個 (以零為基準) 資料欄索引的陣列，要從基礎 DataTable 中提取為來源。該欄位會用來做為建構函式中 pattern 參數的資料來源。欄編號「不」必須排序。 opt_dstColumnIndex - [選用] 用於放置 pattern 操作輸出內容的目的地資料欄。如未指定，系統會使用 srcColumIndices 中的第一個元素做為目的地。 請參閱表格之後的格式設定範例。

以下是一些四欄資料表的輸入和輸出內容範例。

Row before formatting (4 columns, last is blank):
John  |  Paul  |  Jones  |  [empty]

var formatter = new google.visualization.PatternFormat("{0} {1} {2}");
formatter.format(data, [0,1,2], 3);
Output:
  John  |  Paul  |  Jones  |  John Paul Jones

var formatter = new google.visualization.PatternFormat("{1}, {0}");
formatter.format(data, [0,2], 3);
Output:
  John  |  Paul  |  Jones  |  Jones, John

程式碼範例

以下範例說明如何合併兩個資料欄的資料，以建立電子郵件地址。此介面會使用 DataView 物件來隱藏原始來源資料欄：

var data = new google.visualization.DataTable();
data.addColumn('string', 'Name');
data.addColumn('string', 'Email');
data.addRows([
  ['John Lennon', 'john@beatles.co.uk'],
  ['Paul McCartney', 'paul@beatles.co.uk'],
  ['George Harrison', 'george@beatles.co.uk'],
  ['Ringo Starr', 'ringo@beatles.co.uk']
]);

var table = new google.visualization.Table(document.getElementById('patternformat_div'));

var formatter = new google.visualization.PatternFormat(
    '<a href="mailto:{1}">{0}</a>');
// Apply formatter and set the formatted value of the first column.
formatter.format(data, [0, 1]);

var view = new google.visualization.DataView(data);
view.setColumns([0]); // Create a view with the first column only.

table.draw(view, {allowHtml: true, showRowNumber: true, width: '100%', height: '100%'});

GadgetHelper

這個輔助類別可簡化使用 Google Visualization API 的小工具編寫程序。

建構函式

google.visualization.GadgetHelper()

方法

方法	傳回值	說明
createQueryFromPrefs(prefs)	google.visualization.Query	靜態。建立新的 google.visualization.Query 執行個體，並根據小工具偏好設定中的值設定其屬性。prefs 參數的類型為 _IG_Prefs。 偏好設定 _table_query_url 是用來設定查詢資料來源網址。 偏好設定 _table_query_refresh_interval 是用來設定查詢重新整理間隔 (以秒為單位)。
validateResponse(response)	布林值	靜態。參數「response」的類型為 google.visualization.QueryResponse。如果回應包含資料，則傳回 true。如果查詢執行失敗，且回應未包含資料，則會傳回 false。如果發生錯誤，這個方法會顯示錯誤訊息。

查詢類別

您可以使用下列物件，將資料查詢傳送至外部資料來源，例如 Google 試算表。

• 查詢 - 包裝傳出資料要求。
• QueryResponse - 處理資料來源的回應。

查詢

代表傳送至資料來源的查詢。

建構函式

google.visualization.Query(dataSourceUrl, opt_options)

參數

dataSourceUrl

[必要、字串] 查詢的傳送目標網址。請參閱 Google 試算表的圖表與試算表說明文件。

opt_options

[選用 Object] 要求選項對應。注意事項： 如果您存取的是 受限制的資料來源 ，請勿使用這個參數，支援的屬性如下：

• sendMethod - [選用，字串] 指定傳送查詢的方法。選擇下列其中一個字串值：
  • 'xhr' - 使用 XmlHttpRequest 傳送查詢。
  • 'scriptInjection' - 使用指令碼插入功能傳送查詢。
  • 'makeRequest' - [僅適用於已淘汰的小工具] 使用 Widget API 傳送查詢 makeRequest() 方法。如有指定，請一併指定 makeRequestParams。
  • 'auto' - 使用資料來源網址中 tqrt 網址參數所指定的方法。tqrt 的值可能為「xhr」、「scriptInjection」或「makeRequest」。如果缺少 tqrt 或含有無效的值，則相同網域要求的預設值為「xhr」，跨網域要求的預設值為「scriptInjection」。
• makeRequestParams - [Object] makeRequest() 查詢的參數對應。只有在 sendMethod 為「makeRequest」時，才需要使用這項屬性。

方法

方法	傳回值	說明
abort()	無	停止以 setRefreshInterval() 啟動的自動查詢傳送作業。
setRefreshInterval(seconds)	無	設定查詢，從第一次明確呼叫 send 開始，每指定時間長度 (以秒為單位) 自動呼叫 send 方法。seconds 是大於或等於零的數字。 如果您使用這個方法，應在呼叫 send 方法之前呼叫此方法。 如要取消這個方法，請再次呼叫 0 (預設值) 或呼叫 abort()。
setTimeout(seconds)	無	設定在產生逾時錯誤前，等待資料來源回應的秒數。seconds 是大於零的數字。 預設逾時時間為 30 秒。如果使用此方法，應在呼叫 send 方法之前呼叫。
setQuery(string)	無	設定查詢字串。string 參數的值必須是有效的查詢。 如果使用了此方法，則應在呼叫 send 方法之前呼叫。進一步瞭解查詢語言。
send(callback)	無	將查詢傳送至資料來源。callback 應為資料來源回應時要呼叫的函式。回呼函式會收到 google.visualization.QueryResponse 類型的單一參數。

QueryResponse

代表從資料來源接收查詢執行的回應。這個類別的例項會以引數的形式傳遞到在呼叫 Query.send 時設定的回呼函式。

方法

方法	傳回值	說明
getDataTable()	DataTable	傳回資料來源傳回的資料表。如果查詢執行失敗，且未傳回任何資料，則會傳回 null。
getDetailedMessage()	字串	傳回失敗查詢的詳細錯誤訊息。如果查詢執行成功，這個方法會傳回空字串。系統傳回的訊息是供開發人員使用的訊息，可能含有技術資訊，例如「{salary} 欄不存在」。
getMessage()	字串	傳回失敗的查詢所導致的簡短錯誤訊息。如果查詢執行成功，這個方法會傳回空字串。傳回的訊息是給使用者的簡短訊息，例如「查詢無效」或「存取遭拒」。
getReasons()	字串陣列	傳回零或多個項目的陣列。每個項目都是含有錯誤或警告代碼的簡短字串，在執行查詢時會產生錯誤或警告。可能的驗證碼： access_denied 使用者權限不足，無法存取資料來源。 invalid_query 指定的查詢語法有誤。 data_truncated 輸出大小限制，因此未傳回與查詢所選相符的一或多個資料列。(警告)。 timeout 查詢未在預期時間內回應。
hasWarning()	布林值	如果查詢執行時有任何警告訊息，則會傳回 true。
isError()	布林值	如果查詢執行失敗，且回應未包含任何資料表，則會傳回 true。如果查詢執行成功，且回應中包含資料表，則會傳回 <false>。

顯示錯誤

該 API 提供多種函式，協助您向使用者顯示自訂錯誤訊息。如要使用這些函式，請提供網頁上的容器元素 (通常是 <div>)，API 就會在該處繪製格式化錯誤訊息。這個容器可以是視覺化容器元素，也可以是只顯示錯誤的容器。如果您指定視覺呈現包含元素，則錯誤訊息會顯示在圖表上方。接著，呼叫下方適當的函式來顯示或移除錯誤訊息。

所有函式都是 google.visualization.errors 命名空間中的靜態函式。

許多圖表都可能會擲回錯誤事件，詳情請參閱下方的錯誤事件。

您可以在查詢包裝函式範例中查看自訂錯誤範例。

函式	傳回值	說明
addError(container, message, opt_detailedMessage, opt_options)	識別所建立錯誤物件的字串 ID 值。這是網頁上的不重複值，可用來移除錯誤或尋找包含的元素。	在指定的網頁元素中加入錯誤顯示區塊，並套用指定的文字和格式設定。 container - 要插入錯誤訊息的 DOM 元素。如果找不到容器，函式會擲回 JavaScript 錯誤。 message - 要顯示的字串訊息。 opt_detailedMessage - 選擇性的詳細訊息字串。根據預設，這會是滑鼠遊標懸停文字，但您可以在下方所述的 opt_options.showInToolTip 屬性中進行變更。 opt_options - 選用的物件，包含設定訊息的各種顯示選項。支援下列選項： showInTooltip - 為布林值，其中 true 只會以工具提示文字顯示詳細訊息，false 則會在簡短訊息後方於容器主體中顯示詳細訊息。預設值為 true。 type - 說明錯誤類型的字串，用來決定此訊息應套用哪些 CSS 樣式。支援的值為「error」和「warning」。預設值為「error」。 style - 錯誤訊息的樣式字串。這個樣式會覆寫警告類型 (opt_options.type) 套用的所有樣式。範例：'background-color: #33ff99; padding: 2px;' 預設值為空白字串。 removable - 布林值，「true」表示，使用者只要利用滑鼠按一下就能關閉訊息。預設值為 false。
addErrorFromQueryResponse(container, response)	用於識別已建立錯誤物件的字串 ID 值；如果回應未指出錯誤，則為空值。這是網頁的唯一值，可用來移除錯誤或尋找此錯誤所屬的元素。	將查詢回應和錯誤訊息容器傳送至此方法：如果查詢回應指出查詢錯誤，在指定的網頁元素中顯示錯誤訊息。如果查詢回應為空值，此方法會擲回 JavaScript 錯誤。將查詢處理常式收到的 QueryResponse 傳遞至這則訊息，即可顯示錯誤。它也會根據類型 (錯誤或警告，與 addError(opt_options.type) 類似) 設定適當的顯示樣式 container - 要插入錯誤訊息的 DOM 元素。如果找不到容器，函式會擲回 JavaScript 錯誤。 response - 查詢處理常式為回應查詢而收到的 QueryResponse 物件。如果此為空值，此方法會擲回 JavaScript 錯誤。
removeError(id)	Boolean：如果錯誤已遭移除，則傳回 true，否則傳回 false。	從網頁中移除由 ID 指定的錯誤。 id：使用 addError() 或 addErrorFromQueryResponse() 建立的錯誤字串 ID。
removeAll(container)	無	移除指定容器中的所有錯誤區塊。如果指定的容器不存在，就會擲回錯誤。 container - 保留要移除的錯誤字串的 DOM 元素。如果找不到容器，函式會擲回 JavaScript 錯誤。
getContainer(errorId)	處理包含指定錯誤的 DOM 元素，如果找不到，則處理空值。	擷取容器元素控制代碼，保留由 errorID 指定的錯誤。 errorId - 使用 addError() 或 addErrorFromQueryResponse() 建立的錯誤字串 ID。

事件

大多數視覺呈現都會觸發事件，以表示發生了某個事件。身為圖表的使用者，您通常會想監聽這些事件。如果您自行編寫圖表的程式碼，建議您也要自行觸發這類事件。

透過下列方法，開發人員可從圖表內部監聽事件、移除現有事件處理常式或觸發事件。

• google.visualization.events.addListener() 和 google.visualization.events.addOneTimeListener() 監聽事件。
• google.visualization.events.removeListener() 會移除現有的事件監聽器
• google.visualization.events.removeAllListeners() 會移除特定圖表的所有事件監聽器
• google.visualization.events.trigger() 事件：觸發事件。

addListener()

呼叫這個方法以註冊，以接收由網頁上代管的視覺化內容觸發的事件。您應記錄哪些事件引數 (如有) 會傳遞至處理函式。

google.visualization.events.addListener(source_visualization,
  event_name, handling_function)

source_visualization

來源視覺化執行個體的控制代碼。

event_name

要監聽的事件字串名稱。圖表應記錄擲回的事件。

handling_function

source_visualization 觸發 event_name 事件時要呼叫的本機 JavaScript 函式名稱。系統會將任何事件引數做為參數傳遞給處理函式。

退貨

新事件監聽器的事件監聽器處理常式。處理常式稍後可以視需要呼叫 google.visualization.events.removeListener() 來移除這個事件監聽器。

範例

以下舉例說明如何註冊以接收選取事件

var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler() {
  alert('A table row was selected');
}

addOneTimeListener()

這與 addListener() 相同，但適用於只應監聽一次的事件。後續擲回事件時，系統並不會叫用處理函式。

實用範例：每次繪圖都會擲回 ready 事件。如果您只想讓第一個 ready 執行程式碼，可以選擇 addOneTimeListener，而不是 addListener。

removeListener()

呼叫這個方法，即可取消註冊現有的事件監聽器。

google.visualization.events.removeListener(listener_handler)

listener_handler

要移除的事件監聽器處理常式，由 google.visualization.events.addListener() 傳回。

removeAllListeners()

呼叫這個方法，即可取消註冊特定視覺化執行個體的所有事件監聽器。

google.visualization.events.removeAllListeners(source_visualization)

source_visualization

來源視覺化例項的處理常式，該例項應從中移除所有事件監聽器。

trigger()

由視覺化實作器呼叫。在視覺化內容中呼叫此方法，即可觸發具有任意名稱和一組值的事件。

google.visualization.events.trigger(source_visualization, event_name,
  event_args)

source_visualization

來源視覺化執行個體的處理常式。如要在傳送圖表定義的方法中呼叫這個函式，只要傳入 this 關鍵字即可。

event_name

用於呼叫事件的字串名稱。您可以視需要選擇任何字串值。

event_args

[選用] 要傳遞至接收方法的名稱/值組合對應。例如： {message: "Hello there!", score: 10, name: "Fred"}。如果不需要事件，您可以傳遞空值；接收端應準備好針對這個參數接受空值。

範例

以下範例的圖表範例會在呼叫「click」方法時，擲回名為「select」的方法。不會傳回任何值。

MyVisualization.prototype.onclick = function(rowIndex) {
  this.highlightRow(this.selectedRow, false); // Clear previous selection
  this.highlightRow(rowIndex, true); // Highlight new selection

  // Save the selected row index in case getSelection is called.
  this.selectedRow = rowIndex;

  // Trigger a select event.
  google.visualization.events.trigger(this, 'select', null);
}

標準視覺化方法和屬性

每個視覺呈現都應顯示下列一組必要和選用方法和屬性。不過請注意，我們不會執行類型檢查來強制執行這些標準，因此請詳閱各項圖表的說明文件。

• 建構函式
• draw()
• getAction() [選用]
• getSelection() [選用]
• removeAction() [選用]
• setAction() [選用]
• setSelection() [選用]

注意： 這些方法位於視覺化的命名空間，而「不是」google.visualization 命名空間。

建構函式

建構函式應有視覺類別的名稱，並傳回該類別的例項。

visualization_class_name(dom_element)

dom_element

指向要嵌入視覺化內容的 DOM 元素指標。

範例

var org = new google.visualization.OrgChart(document.getElementById('org_div')); 

draw()

在網頁上繪製視覺化內容。在背景中，您可以使用伺服器擷取圖片，或使用連結的視覺化程式碼建立網頁上的圖片。每次資料或選項有所變更，您都應呼叫這個方法。請在傳遞至建構函式的 DOM 元素內繪製物件。

draw(data[, options])

資料

DataTable 或 DataView，保留用於繪製圖表的資料。目前沒有從圖表中擷取 DataTable 的標準方法。

選項

[選用] 自訂選項名稱/值組合的對應。例如高度和寬度、背景顏色和說明文字。視覺化說明文件應會列出可用的選項，並且在未指定這個參數的情況下支援預設選項。您可以使用 JavaScript 物件常值語法傳入選項對應，例如 {x:100, y:200, title:'An Example'}

範例

chart.draw(myData, {width: 400, height: 240, is3D: true, title: 'My Daily Activities'});

getAction()

如果該圖表包含工具提示，並且允許工具提示動作，圖表就會選擇性顯示這項資訊。

傳回含有要求的 actionID 的工具提示動作物件。

範例：

// Returns the action object with the ID 'alertAction'.
chart.getAction('alertAction');

getSelection()

這會以圖表的形式顯示，讓您用來存取圖像中目前選取的資料。

selection_array getSelection()

退貨

selection_array 所選物件陣列，分別描述用於建立圖表的基礎資料表中的資料元素 (DataView 或 DataTable)。每個物件都有 row 和/或 column 屬性，且基礎 DataTable 中具有所選項目的列和/或欄索引。如果 row 屬性為空值，則選取屬性為資料欄；如果 column 屬性為空值，則選取列為資料列；如果兩者皆為非空值，則代表特定資料項目。您可以呼叫 DataTable.getValue() 方法，取得所選項目的值。擷取的陣列可傳遞至 setSelection()。

範例

function myClickHandler(){
  var selection = myVis.getSelection();
  var message = '';

  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      message += '{row:' + item.row + ',column:' + item.column + '}';
    } else if (item.row != null) {
      message += '{row:' + item.row + '}';
    } else if (item.column != null) {
      message += '{column:' + item.column + '}';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

removeAction()

如果該圖表包含工具提示，並且允許工具提示動作，圖表就會選擇性顯示這項資訊。

從圖表中移除包含要求的 actionID 的工具提示動作物件。

範例：

// Removes an action from chart with the ID of 'alertAction'.
chart.removeAction('alertAction');

setAction()

如果該圖表包含工具提示並且允許工具提示動作，圖表就會選擇性顯示這項資訊。這項功能僅適用於核心圖表 (長條圖、柱狀圖、折線圖、面積、散佈圖、堆疊、對話框、泡泡、圓餅圖、甜甜圈、K 線圖、直方圖、階梯狀面積圖)。

設定在使用者點選動作文字時執行的工具提示動作。

setAction(action object)

setAction 方法會將物件做為動作參數。這個物件應指定 3 個屬性：id (所設定動作的 ID)、text (應顯示在動作工具提示中的文字) 和 action (使用者按一下動作文字時應執行的函式)。

請在呼叫圖表的 draw() 方法之前，設定所有及所有工具提示動作。

範例：

// Sets a tooltip action which will pop an alert box on the screen when triggered.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  }
});

setAction 方法也可以定義兩個額外屬性：visible 和 enabled。這些屬性應為傳回 boolean 值的函式，指出工具提示動作是否會顯示和/或啟用。

範例：

// The visible/enabled functions can contain any logic to determine their state
// as long as they return boolean values.
chart.setAction({
  id: 'alertAction',
  text: 'Trigger Alert',
  action: function() {
    alert('You have triggered an alert');
  },
  visible: function() {
    return true;
  },
  enabled: function() {
    return true;
  }
});

setSelection()

您可以選擇在圖表中選取資料項目，例如面積圖中的資料點，或是長條圖中的長條。呼叫這個方法時，視覺化呈現應以視覺化的方式呈現新的選項。setSelection() 的實作方式不應觸發「選取」事件。視覺呈現可能會忽略部分選取範圍。舉例來說，如果資料表能夠僅顯示所選資料列，其 setSelection() 實作項目可能會忽略儲存格或資料欄元素，或者可以選取整個資料列。

每次呼叫此方法時，所有所選項目都會取消選取，並套用傳入的新選取清單。目前沒有可取消選取個別項目的明確方法。如要取消選取個別項目，請呼叫 setSelection() 以保持選取項目；如要取消選取所有元素，請呼叫 setSelection()、setSelection(null) 或 setSelection([])。

setSelection(selection_array)

selection_array

物件的陣列，每個物件都有數值列和/或欄屬性。row 和 column 是資料表中要選取的項目 (從零開始)，或欄數。如要選取整個資料欄，請將 row 設為空值；如要選取整個資料列，請將 column 設為空值。範例： setSelection([{row:0,column:1},{row:1, column:null}]) 同時選取 (0,1) 和整列 1 的儲存格。

各種靜態方法

本節包含 google.visualization 命名空間中公開的各種實用方法。

arrayToDataTable()

這個方法會採用二維陣列，並將其轉換為 DataTable。

資料欄資料類型會自動取決於你提供的資料。您也可以使用陣列第一列 (資料欄標題列) 的物件常值標記法 (即 {label: 'Start Date', type: 'date'}) 指定資料欄資料類型。您也可以參考選用的資料角色，但必須使用物件常值標記法明確定義資料欄資料類型。物件常值標記法也可以用於任何儲存格，方便您定義「儲存格物件」。

語法

google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)

twoDArray

二維陣列，其中每一列都代表資料表中的一個資料列。如果 opt_firstRowIsData 為 false (預設值)，系統會將第一列解讀為標頭標籤。系統會自動根據指定資料解讀每個資料欄的資料類型。如果儲存格沒有值，請視情況指定空值或空白值。

opt_firstRowIsData

第一個資料列是否定義了標題列。如為 true，所有資料列都會假設為資料。如為 false，系統會假設第一列是標題列，並將值指派為資料欄標籤。預設值為 false。

退貨

新的 DataTable。

例子

以下程式碼展示了建立相同 DataTable 物件的三種方法：

// Version 1: arrayToDataTable method
var data2 = google.visualization.arrayToDataTable([
  [{label: 'Country', type: 'string'},
   {label: 'Population', type: 'number'},
   {label: 'Area', type: 'number'},
   {type: 'string', role: 'annotation'}],
  ['CN', 1324, 9640821, 'Annotated'],
  ['IN', 1133, 3287263, 'Annotated'],
  ['US', 304, 9629091, 'Annotated'],
  ['ID', 232, 1904569, 'Annotated'],
  ['BR', 187, 8514877, 'Annotated']
]);

// Version 2: DataTable.addRows
var data3 = new google.visualization.DataTable();
data3.addColumn('string','Country');
data3.addColumn('number','Population');
data3.addColumn('number','Area');
data3.addRows([
  ['CN', 1324, 9640821],
  ['IN', 1133, 3287263],
  ['US', 304, 9629091],
  ['ID', 232, 1904569],
  ['BR', 187, 8514877]
]);

// Version 3: DataTable.setValue
var data = new google.visualization.DataTable();
data.addColumn('string','Country');
data.addColumn('number', 'Population');
data.addColumn('number', 'Area');
data.addRows(5);
data.setValue(0, 0, 'CN');
data.setValue(0, 1, 1324);
data.setValue(0, 2, 9640821);
data.setValue(1, 0, 'IN');
data.setValue(1, 1, 1133);
data.setValue(1, 2, 3287263);
data.setValue(2, 0, 'US');
data.setValue(2, 1, 304);
data.setValue(2, 2, 9629091);
data.setValue(3, 0, 'ID');
data.setValue(3, 1, 232);
data.setValue(3, 2, 1904569);
data.setValue(4, 0, 'BR');
data.setValue(4, 1, 187);
data.setValue(4, 2, 8514877);

drawChart()

這個方法會在單一呼叫中建立圖表。使用這個方法的優點在於需要較少的程式碼，您可以將視覺化內容序列化並儲存為文字字串，以便重複使用。這個方法不會為已建立的圖表傳回控制代碼，因此您無法指派方法事件監聽器來擷取圖表事件。

語法

google.visualization.drawChart(chart_JSON_or_object)

chart_JSON_or_object

JSON 常值字串或 JavaScript 物件，其下列屬性 (區分大小寫)：

屬性	類型	這是必填欄位	預設	說明
chartType	字串	這是必填欄位	無	視覺化內容的類別名稱。Google 圖表可以省略 google.visualization 套件名稱。如果尚未載入適當的視覺化程式庫，如果這是 Google 視覺化功能，此方法會為您載入程式庫，您必須明確載入第三方視覺化內容。範例： Table、PieChart、example.com.CrazyChart。
containerId	字串	這是必填欄位	無	在網頁上代管視覺呈現的 DOM 元素 ID。
選項	物件	選用	無	說明視覺呈現選項的物件。您可以使用 JavaScript 常值標記法，或是提供物件的控制代碼。範例： "options": {"width": 400, "height": 240, "is3D": true, "title": "Company Performance"}
dataTable	物件	選用	無	用於填入視覺化圖表的 DataTable。這可以是 DataTable 的常值 JSON 字串表示法 (如上文所述)，或是已填入 google.visualization.DataTable 物件的控制代碼，或類似 arrayToDataTable(opt_firstRowIsData=false) 接受的 2D 陣列。您必須指定這個屬性或 dataSourceUrl 屬性。
dataSourceUrl	字串	選用	無	要填入圖表資料的資料來源查詢 (例如 Google 試算表)。您必須指定這個屬性或 dataTable 屬性。
項查詢	字串	選用	無	如果指定 dataSourceUrl，就能選用視覺化查詢語言指定類似 SQL 的查詢字串，來篩選或操控資料。
refreshInterval	編號	選用	無	視覺呈現應重新整理查詢來源的頻率 (以秒為單位)。只有在指定 dataSourceUrl 時才能使用此項目。
檢視表	物件或陣列	選用	無	設定 DataView 初始化器物件，做為 dataTable 或 dataSourceUrl 參數定義的基礎資料的篩選器。您可以傳入字串或 DataView 初始化物件，例如 dataview.toJSON() 傳回的物件。範例： "view": {"columns": [1, 2]}您也可以傳遞 DataView 初始化器物件的陣列，在此情況下，系統會將陣列中的第一個 DataView 套用至基礎資料，並套用至基礎資料，然後將第二個 DataView 套用至從第一個 DataView 套用後產生的資料表，以此類推。

例子

根據試算表資料來源建立表格圖表，並納入查詢 SELECT A,D WHERE D > 100 ORDER BY D

<script type="text/javascript">
  google.charts.load('current');  // Note: No need to specify chart packages.
  function drawVisualization() {
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",
      "query":"SELECT A,D WHERE D > 100 ORDER BY D",
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true
      }
   });
 }
google.charts.setOnLoadCallback(drawVisualization);
</script>

此範例會建立相同的資料表，但會在本機建立 DataTable：

<script type='text/javascript'>
  google.charts.load('current');
  function drawVisualization() {
    var dataTable = [
      ["Country", "Population Density"],
      ["Indonesia", 117],
      ["China", 137],
      ["Nigeria", 142],
      ["Pakistan", 198],
      ["India", 336],
      ["Japan", 339],
      ["Bangladesh", 1045]
    ];
    google.visualization.drawChart({
      "containerId": "visualization_div",
      "dataTable": dataTable,
      "refreshInterval": 5,
      "chartType": "Table",
      "options": {
        "alternatingRowStyle": true,
        "showRowNumber" : true,
      }
    });
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

以下範例會以 JSON 字串表示的圖表，您可能已從檔案載入：

<script type="text/javascript">
  google.charts.load('current');
  var myStoredString = '{"containerId": "visualization_div",' +
    '"dataSourceUrl": "https://spreadsheets.google.com/a/google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1",' +
    '"query":"SELECT A,D WHERE D > 100 ORDER BY D",' +
    '"refreshInterval": 5,' +
    '"chartType": "Table",' +
    '"options": {' +
    '   "alternatingRowStyle": true,' +
    '   "showRowNumber" : true' +
    '}' +
  '}';
  function drawVisualization() {
    google.visualization.drawChart(myStoredString);
  }
  google.charts.setOnLoadCallback(drawVisualization);
</script>

drawToolbar()

這是工具列元素的建構函式，可附加至許多視覺呈現。使用者可以透過這個工具列，將視覺化資料匯出為不同格式，或提供可嵌入的視覺化版本，以便在不同位置使用。如需詳細資訊和程式碼範例，請參閱工具列頁面。