本頁面列出 Google 視覺化 API 所公開的物件,以及所有視覺化呈現公開的標準方法。
注意:Google 視覺化 API 命名空間為 google.visualization.*
陣列注意事項
部分瀏覽器無法在 JavaScript 陣列中妥善處理結尾的逗號,因此請勿使用這些字元。 陣列中間的空白值則可使用。舉例來說:
data = ['a','b','c', ,]; // BAD
data = ['a','b','c']; // OK
data = ['a','b', ,'d']; // Also OK. The third value is undefined.
DataTable 類別
表示二維可變動值表格。如要建立 DataTable
的唯讀副本 (可選擇篩選以顯示特定值、資料列或資料欄),請建立 DataView。
系統會為每個資料欄指派資料類型,以及數個選用屬性,包括 ID、標籤和模式字串。
此外,您可以將自訂屬性 (名稱/值組合) 指派給任何儲存格、資料列、資料欄或整個資料表。部分視覺化呈現支援特定自訂屬性;舉例來說,資料表視覺化支援名為「style」的儲存格屬性,可讓您為轉譯過的表格儲存格指派內嵌 CSS 樣式字串。視覺化元件應在說明文件中描述其支援的任何自訂屬性。
另請參閱:QueryResponse.getDataTable
建構函式
語法
DataTable(opt_data, opt_version)
- opt_data
-
[選用] 用來初始化資料表的資料。這可以是透過在已填入資料表上呼叫
DataTable.toJSON()
傳回的 JSON,或包含用來初始化資料表資料的 JavaScript 物件。JavaScript 文字物件的結構在這裡說明。如未提供這項參數,系統將傳回新的空白資料表。 - opt_version
- [選用] 這個數值會指定使用的傳輸通訊協定版本。只有 Chart Tools Datasource 實作者才會使用。目前版本為 0.6。
詳細資料
DataTable
物件是用來保存傳入視覺化資料的資料。DataTable
是基本的二維表格,每個資料欄中的資料都必須使用相同的資料類型。每個資料欄都有一個描述元,其中包含其資料類型、該欄的標籤 (可能以視覺化形式顯示),以及可用來參照特定資料欄 (做為使用資料欄索引的替代方案) 的 ID。DataTable
物件也支援對應指派給特定值、資料列、資料欄或整個 DataTable
的任意屬性。視覺化呈現可以使用這些功能來支援更多功能。舉例來說,資料表視覺化會使用自訂屬性,讓您為個別儲存格指派任意類別名稱或樣式。
表格中的每個儲存格都包含一個值。儲存格可以是空值或資料欄所指定的類型值。儲存格可採用「格式化」的資料版本,這是資料形式的字串,以視覺化方式顯示。視覺化圖表可以 (但非強制) 使用格式化版本顯示,但一律都會使用資料本身進行任何排序或計算 (例如決定圖表的放置位置)。例如,將「low」、「medium」和「high」的值指派為格式化的儲存格值 1、2 和 3。
如要在呼叫建構函式之後新增資料列,您可以呼叫單一資料列的 addRow()
,或多個資料列呼叫 addRows()
。您也可以呼叫 addColumn()
方法以新增資料欄。資料列和資料欄也有移除方法,但與其移除資料列或資料欄,不如建立 DataView
做為 DataTable
選擇性檢視的檢視畫面。
如果您在將 DataTable
的值傳送至視覺化的 draw()
方法後變更值,這些變更不會立即變更。您必須再次呼叫 draw()
以反映任何變更。
注意:Google 圖表不會對資料表執行任何驗證。(如果有,顯示速度就會比較慢)。如果您提供的數字是資料欄預期的字串,反之亦然。
範例
下列範例示範如何使用常值字串將 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'}] ]);
建立 DataTable
時,您可以呼叫不含參數的建構函式,然後呼叫下列 addColumn()
/addRows()
方法以新增值,或者傳入填入的 JavaScript 文字物件進行初始化。以下將說明這兩種方法。您該使用哪一個?
-
透過呼叫
addColumn()
、addRow()
和addRows()
,以 JavaScript 建立和填入資料表是容易理解的程式碼。這個方法會由您手動輸入程式碼時使用。這個做法的執行速度會比使用物件常值標記法 (如後文所述) 慢,但在較小的資料表 (例如 1,000 個儲存格) 中,您可能會發現差異很大。 -
在大型資料表中使用物件常值標記法直接宣告
DataTable
物件可大幅加快作業速度。然而,使用正確的語法可能並不容易;如果您可以在程式碼中產生物件常值語法,即可降低錯誤的可能性。
方法
方法 | 傳回值 | 說明 |
---|---|---|
或
|
數字 |
在資料表中新增資料欄,並傳回新資料欄的索引。新資料欄的所有儲存格都會獲派 第一個簽名具有下列參數:
第二個簽名具有單一物件參數,其成員如下:
另請參閱:getColumnId、getColumnLabel、getColumnType、insertColumn、getColumnRole |
addRow(opt_cellArray) |
數字 |
在資料表中新增資料列,並傳回新資料列的索引。
例如: 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. |
addRows(numOrArray) |
數字 |
在資料表中新增資料列,並傳回最後新增列的索引。您可以呼叫此方法來建立新的空白資料列,或用於填入資料列的資料,如下所述。
範例: 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. ]); 另請參閱:insertRows |
clone() |
資料表 | 傳回資料表的本機副本。結果是資料表的深層副本,但儲存格屬性、資料列屬性、資料表屬性和資料欄屬性皆為淺層複本,這表示非原始屬性是透過參照方式複製,但原始屬性則是值複製。 |
getColumnId(columnIndex) |
字串 |
傳回基礎資料表中資料欄索引指定的特定資料欄 ID。 針對查詢擷取的資料表,資料欄 ID 是由資料來源設定,且在使用查詢語言時,可用於參照資料欄。 另請參閱: Query.setQuery |
getColumnIndex(columnIdentifier) |
字串、數字 |
如果資料欄索引、ID 或標籤位於指定資料表,則傳回該資料欄的索引,否則傳回 -1。當 columnIdentifier 是字串時,會先使用它的 ID 先尋找資料欄,然後再按標籤尋找。另請參閱: getColumnId、 getColumnLabel |
getColumnLabel(columnIndex) |
字串 |
傳回基礎資料表中資料欄索引指定的特定資料欄標籤。 系統通常會在視覺呈現中顯示資料欄標籤。例如,資料欄標籤可以顯示為資料表的欄標題,或在圓餅圖中顯示圖例標籤。 對查詢擷取的資料表來說,資料欄標籤是由資料來源設定,或是由查詢語言的 label 子句設定。另請參閱: setColumnLabel |
getColumnPattern(columnIndex) |
字串 |
傳回用於設定指定欄值的格式。
以查詢擷取的資料表來說,資料欄模式是由資料來源或查詢語言的 |
getColumnProperties(columnIndex)
|
物件 |
傳回指定欄所有屬性的對應圖。請注意,屬性物件會由參照傳回,因此變更已擷取物件中的值,會改變
|
getColumnProperty(columnIndex, name)
|
自動 |
傳回已命名屬性的值,如果沒有為指定資料欄設定這類屬性,則會傳回
|
getColumnRange(columnIndex) |
物件 |
傳回指定資料欄中值的最小值和最大值。傳回的物件具有
|
getColumnRole(columnIndex) |
字串 | 傳回指定資料欄的角色。 |
getColumnType(columnIndex) |
字串 |
傳回資料欄索引所指定的特定資料欄類型。
傳回的欄類型可以是下列其中一種值: |
getDistinctValues(columnIndex) |
物件陣列 |
傳回特定資料欄中唯一的值,並以遞增順序顯示。
傳回物件的類型與 |
getFilteredRows(filters) |
物件陣列 |
傳回符合所有指定篩選條件的列索引。索引會依遞增順序傳回。這個方法的輸出可作為
另一個選用屬性
範例: |
getFormattedValue(rowIndex, columnIndex)
|
字串 |
傳回特定列及欄索引的儲存格格式值。
如要進一步瞭解格式化資料欄值,請參閱查詢語言參考資料。 另請參閱:setFormattedValue |
getNumberOfColumns() |
數字 | 傳回資料表中的資料欄數量。 |
getNumberOfRows() |
數字 | 傳回資料表中的資料列數。 |
getProperties(rowIndex, columnIndex)
|
物件 |
傳回指定儲存格的所有屬性對應。請注意,屬性物件會由參照傳回,因此變更已擷取物件中的值會變更
|
getProperty(rowIndex, columnIndex, name)
|
自動 |
傳回已命名屬性的值,如果沒有為指定的儲存格設定這類屬性,則會傳回
另請參閱: setCell setProperties setProperty |
getRowProperties(rowIndex)
|
物件 |
傳回指定列所有屬性的對應圖。請注意,屬性物件會由參照傳回,因此變更已擷取物件中的值,會改變
|
getRowProperty(rowIndex, name)
|
自動 |
傳回已命名屬性的值。如果指定的資料列並未設定這類屬性,則傳回
|
getSortedRows(sortColumns) |
數字陣列 |
傳回經過排序的資料表版本,且不需要修改基礎資料的順序。如要永久排序基礎資料,請呼叫
傳回的值是數字陣列,每個數字都是
請注意,排序作業都是穩定的;也就是說,如果依據兩個資料列的值相等,每次排序都會以相同的順序傳回資料列。 示例:如要疊代第三列排序的資料列,請使用: var rowInds = data.getSortedRows([{column: 2}]); for (var i = 0; i < rowInds.length; i++) { var v = data.getValue(rowInds[i], 2); } |
getTableProperties
|
物件 | 傳回資料表所有屬性的對應。 |
getTableProperty(name) |
自動 |
傳回已命名屬性的值,如果沒有為資料表設定這類屬性,則傳回「
|
getValue(rowIndex, columnIndex) |
物件 |
傳回指定列索引和欄索引的儲存格值。
傳回值的類型取決於資料欄類型 (請參閱 getColumnType):
|
insertColumn(columnIndex, type [,label [,id]])
|
無 |
在資料表的指定索引內插入新的資料欄。指定索引前後的所有現有資料欄都會移至較高的索引。
另請參閱:addColumn |
insertRows(rowIndex, numberOrArray) |
無 |
在指定的列索引處插入指定列數。
另請參閱:addRows |
removeColumn(columnIndex) |
無 |
移除指定索引處的欄。
另請參閱:removeColumns |
removeColumns(columnIndex, numberOfColumns)
|
無 |
從指定索引的欄中移除指定的欄數。
另請參閱:removeColumn |
removeRow(rowIndex) |
無 |
移除指定索引處的資料列。
另請參閱:removeRows |
removeRows(rowIndex, numberOfRows) |
無 |
從指定索引的資料列中移除指定列數。
另請參閱:removeRow |
setCell(rowIndex, columnIndex [, value [, formattedValue [, properties]]])
|
無 |
設定儲存格的值、格式化值和/或屬性。
另請參閱:setValue()、setFormattedValue()、setProperty()、setProperties()。 |
setColumnLabel(columnIndex, label)
|
無 |
設定資料欄的標籤。
另請參閱:getColumnLabel |
setColumnProperty(columnIndex, name, value)
|
無 |
設定單一欄屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setColumnProperties(columnIndex, properties)
|
無 |
設定多個欄屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setFormattedValue(rowIndex, columnIndex, formattedValue)
|
無 |
設定儲存格的格式化值。
另請參閱:getFormattedValue |
setProperty(rowIndex, columnIndex, name, value)
|
無 |
設定儲存格屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
另請參閱: setCell setProperties getProperty |
setProperties(rowIndex, columnIndex, properties)
|
無 |
設定多個儲存格屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
另請參閱: setCell setProperty getProperty |
setRowProperty(rowIndex, name, value)
|
無 |
設定列屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setRowProperties(rowIndex, properties)
|
無 |
設定多個資料列屬性。部分視覺化呈現支援資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setTableProperty(name, value)
|
無 |
設定單一表格屬性。部分視覺化呈現可支援資料表、資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setTableProperties(properties) |
無 |
設定多個表格屬性。部分視覺化呈現可支援資料表、資料列、資料欄或儲存格屬性,以修改其顯示方式或行為;請參閱視覺化說明文件,瞭解支援的屬性。
|
setValue(rowIndex, columnIndex, value) |
無 |
設定儲存格的值。除了覆寫任何現有的儲存格值之外,這個方法也會清除儲存格的任何格式化值和屬性。
|
sort(sortColumns) |
無 |
根據指定的排序欄為資料列排序。此方法會修改 DataTable 。如需排序詳細資料的說明,請參閱 getSortedRows() 。這個方法不會傳回排序的資料。另請參閱: getSortedRows 範例:如要依第三個資料欄排序,然後再按第二個資料欄排序,請使用: data.sort([{column: 2}, {column: 1}]);
|
toJSON() |
字串 |
傳回可傳遞至 DataTable 建構函式的 DataTable 的 JSON 表示法。例如: {"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: 屬性,如稍後說明):-
「布林值」- 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)
-
「TTL」:包含時間的 JavaScript Date 物件。範例值:
v:new Date(2008, 0, 15, 14, 30, 45)
-
「timeofday」:由 3 位數和選用數字組成的陣列,以小時 (0 表示午夜)、分鐘、秒和選填毫秒數表示。範例值:
v:[8, 15, 0]
、v: [6, 12, 1, 144]
-
「布林值」- JavaScript 布林值 (「true」或「false」)。範例值:
-
id
:[選用] 資料欄的字串 ID。資料表中不得重複。使用基本的英數字元,因此代管網頁不需要使用逸出逸出即可在 JavaScript 中存取資料欄。小心,請不要選擇 JavaScript 關鍵字。範例:id:'col_1'
-
label
:[選用] 此資料欄顯示的部分視覺化內容字串值。範例:label:'Height'
-
pattern
:[選用] 字串模式,用於格式化數字、日期或時間資料欄值的字串模式。這僅供參考,您可能不需要讀取模式,也不需要存在。Google 視覺化用戶端不使用這個值 (系統會讀取儲存格的格式化值)。如果DataTable
源自於資料來源使用格式子句的查詢,則您在該子句中指定的模式可能會傳回這個值。建議的模式標準為 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
屬性會保留資料列物件的陣列。
每個資料列物件都有一個名為 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 字串。這是指從 data DataTable 中顯示或隱藏的資料列。
方法
方法 | 傳回值 | 說明 |
---|---|---|
請參閱DataTable 的說明。 |
與對等 DataTable 方法相同,但資料列/資料欄索引會參照檢視畫面中的索引,而非基礎資料表/檢視畫面中的索引。
|
|
getTableColumnIndex(viewColumnIndex)
|
數字 |
傳回此資料欄中基礎資料欄 (或檢視表) 中由其索引指定之指定資料欄的索引。
範例:如果先前呼叫了 |
getTableRowIndex(viewRowIndex) |
數字 |
傳回此檢視畫面的基礎資料列 (或檢視表) 中由其索引指定的指定索引 (或檢視表) 的索引。
範例:如果先前呼叫了 |
getViewColumnIndex(tableColumnIndex)
|
數字 |
傳回此檢視畫面中的索引,該索引對應至基礎資料表 (或檢視表) 中其索引指定的指定資料欄。如果有多個這類索引,則傳回第一個 (最小) 的索引。如果沒有這類索引 (指定的資料欄不在檢視畫面中),則會傳回 -1。
範例:如果先前呼叫了 |
getViewColumns() |
數字陣列 |
依序傳回這個檢視畫面中的資料欄。也就是說,如果使用部分陣列呼叫 |
getViewRowIndex(tableRowIndex) |
數字 |
傳回此檢視畫面中的索引,該索引對應至在基礎資料表 (或檢視畫面) 中以索引指定的指定資料列。如果有多個這類索引,則傳回第一個 (最小) 的索引。如果沒有這類索引 (指定的資料列不在檢視畫面中),則會傳回 -1。
範例:如果先前呼叫了 |
getViewRows() |
數字陣列 |
依序傳回這個檢視畫面中的列。也就是說,如果使用部分陣列呼叫 |
hideColumns(columnIndexes) |
無 |
在目前的檢視畫面中隱藏指定資料欄。
範例:如果資料表包含 10 個資料欄,並依序呼叫 |
hideRows(min, max) |
無 |
隱藏目前檢視中索引介於介於最小值與最大值 (含) 之間的所有資料列。這是上述 |
hideRows(rowIndexes) |
無 |
在目前的檢視畫面中隱藏指定列。
範例:如果資料表包含 10 個資料列,並依序呼叫 |
setColumns(columnIndexes) |
無 |
指定這個資料檢視中要顯示哪些資料欄。任何未指定的欄則會隱藏。這是基礎資料表/檢視表或計算資料欄中資料欄索引的陣列。如未呼叫這個方法,則預設為顯示所有資料欄。陣列也可能包含重複項目,以便多次顯示同一個資料欄。資料欄將依照指定順序顯示。
範例: // 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); } |
setRows(min, max) |
無 |
將此檢視畫面中的資料列設為所有索引 (位於基礎資料表/檢視畫面中) 介於最小值與最大值 (含) 之間。下方是 |
setRows(rowIndexes) |
無 |
根據基礎資料表/檢視表的索引號碼,設定此檢視畫面中可見的資料列。
範例:如要建立含有基礎資料表/檢視表第 3 和零的第 2 列的檢視畫面,請按照下列步驟操作: |
toDataTable() |
資料表 |
傳回填入 DataView 可見列與欄的 DataTable 物件。 |
toJSON() |
string |
傳回此 DataView 的字串表示法。這個字串不包含實際資料,其中僅包含 DataView 的特定設定,例如可見的列和欄。您可以儲存這個字串,並將其傳送至靜態的 DataView.fromJSON() 建構函式,以重新建立這個檢視畫面。但這不會包含產生的資料欄。 |
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 提供下列其他方法:
方法 | 傳回類型 | 說明 |
---|---|---|
draw(opt_container_ref) |
無 |
繪製圖表。當您對圖表或資料做出任何變更之後,必須呼叫此方法來顯示變更。
|
toJSON() |
字串 | 傳回圖表的 JSON 表示法字串版本。 |
clone() |
排行榜排行榜 | 傳回圖表包裝函式的深層複本。 |
getDataSourceUrl() |
字串 | 如果這張圖表是從資料來源取得資料,則會傳回這個資料來源的網址。否則,則會傳回空值。 |
getDataTable() |
google.visualization.DataTable |
如果這個圖表會從本機定義的
下次呼叫 |
getChartType() |
字串 |
已包裝圖表的類別名稱。如果這是 Google 圖表,名稱就無法與 google.visualization 搭配使用。舉例來說,如果這是一張樹狀圖,它會傳回「Treemap」,而不是「google.visualization.treemap」。 |
getChartName() |
字串 | 傳回 setChartName() 指派的圖表名稱。 |
getChart() |
圖表物件參考資料 |
傳回此 ChartWrapper 所繪製圖表的參照,例如
google.visualization.BarChart
或
google.visualization.ColumnChart
。此方法會傳回空值,直到您在 ChartWrapper 物件上呼叫 draw() 之後,才會擲回就緒的事件。所傳回物件的呼叫將會反映在網頁上。 |
getContainerId() |
字串 | 圖表 DOM 容器元素的 ID。 |
getQuery() |
字串 | 這個圖表的查詢字串 (如果有的話),然後查詢資料來源。 |
getRefreshInterval() |
數字 | 這張圖表的任何重新整理時間間隔 (如果查詢了資料來源)。0 表示不重新整理。 |
getOption(key, opt_default_val) |
不限類型 |
傳回指定的圖表選項值
|
getOptions() |
物件 | 傳回此圖表的選項物件。 |
getView() |
物件或陣列 |
傳回與 dataview.toJSON() 相同的格式中的 DataView 初始化器物件或這類物件的陣列。
|
setDataSourceUrl(url) |
無 | 設定要用於此圖表的資料來源網址。如果您同時為這個物件設定資料表,系統會忽略資料來源網址。 |
setDataTable(table) |
無 | 設定圖表的 DataTable。傳入下列其中一個值:null、DataTable 物件、DataTable 的 JSON 表示法,或符合 arrayToDataTable() 語法的陣列。 |
setChartType(type) |
無 |
設定圖表類型。傳入包裝圖表的類別名稱。如果這是 Google 圖表,請勿以 google.visualization 表示。舉例來說,如果是圓餅圖,請傳入「圓餅圖」。
|
setChartName(name) |
無 | 設定圖表的任意名稱。除非圖表已明確設計成使用圖表,否則不會顯示在圖表的任何地方。 |
setContainerId(id) |
無 | 設定圖表所含 DOM 元素的 ID。 |
setQuery(query_string) |
無 | 設定查詢字串 (如果這個圖表查詢資料來源)。指定這個值時,您必須設定資料來源網址。 |
setRefreshInterval(interval) |
無 | 設定這個圖表的重新整理時間間隔 (如果查詢了資料來源)。指定這個值時,您必須設定資料來源網址。0 表示不會重新整理。 |
setOption(key, value) |
無 |
設定單一圖表選項值,其中 key 為選項名稱,value 則是值。如要取消設定選項,請為該值傳入 null。請注意,key 可以是合格名稱,例如 'vAxis.title' 。 |
setOptions(options_obj) |
無 | 設定圖表的完整選項物件。 |
setView(view_spec) |
無 |
設定 DataView 初始化器物件,用來做為基礎資料的篩選條件。圖表包裝函式必須具備 DataTable 或資料來源要套用此檢視表的基礎資料。您可以傳入字串或 DataView 初始化器物件,例如 dataview.toJSON() 傳回的物件。您也可以傳入 DataView 初始化器物件的陣列,在這種情況下,系統會將陣列中的第一個 DataView 套用到基礎資料,以建立新的資料資料表。第二個 DataView 會套用至套用第一個 DataView 等資料表後產生的資料表,依此類推。 |
活動
ChartWrapper 物件會擲回下列事件。請注意,您必須先呼叫 ChartWrapper.draw()
,才能擲回任何事件。
名稱 | 說明 | 屬性 |
---|---|---|
error |
嘗試轉譯圖表時發生錯誤。 | id、message |
ready |
圖表可供外部方法呼叫使用。如果您想要與圖表互動,並在繪製後呼叫方法,請先為這個事件設定監聽器,然後再呼叫 draw 方法,並且只在事件觸發後呼叫這些方法。 |
無 |
select |
使用者點選長條圖或圖例時觸發。選取圖表元素時,系統會選取資料表中對應的儲存格;選取圖例後,就會選取資料表中對應的資料欄。如要瞭解所選項目,請呼叫 ChartWrapper.getChart().
getSelection() 。請注意,這只會在基礎圖表類型擲回選取事件時擲回。 |
無 |
範例
下列兩個程式碼片段會建立對等的折線圖。第一個範例使用 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:
-
載入
charteditor
套件。在google.charts.load()
中載入套件「charteditor」。您不需要為編輯器中呈現的圖表類型載入套件,圖表編輯器會視需要載入任何套件。 -
建立
ChartWrapper
物件,藉此為使用者定義圖表。這個對話方塊會顯示在對話方塊中,而使用者可以透過編輯器重新設計圖表、變更圖表類型,甚至是變更來源資料。 -
建立新的 ChartEditor 執行個體並註冊以監聽「ok」事件。使用者按一下對話方塊中的 [確定] 按鈕時,就會擲回這個事件。收到呼叫時,應呼叫
ChartEditor.getChartWrapper()
以擷取使用者修改的圖表。 -
呼叫
ChartEditor.openDialog()
以傳入ChartWrapper
。系統隨即會開啟對話方塊。對話方塊按鈕可讓使用者關閉編輯器。只要ChartEditor
執行個體在範圍內,就可供使用;不過,使用者關閉對話方塊後,系統不會自動刪除該執行個體。 - 如要更新程式碼中的圖表,請呼叫
setChartWrapper()
。
方法
方法 | 傳回值 | 說明 |
---|---|---|
openDialog(chartWrapper, opt_options) |
空值 |
在頁面中開啟內嵌對話方塊,開啟圖表編輯器。函式會立即傳回,而且不會等待對話方塊關閉。如果未遺失執行個體範圍,可以再次呼叫
|
getChartWrapper() |
ChartWrapper |
傳回 ChartWrapper ,代表使用者修改的圖表。 |
setChartWrapper(chartWrapper) |
空值 |
使用此方法來更新編輯器中的圖表。
chartWrapper - |
closeDialog() |
空值 | 關閉圖表編輯器對話方塊。 |
選項
圖表編輯器支援下列選項:
名稱 | 類型 | 預設 | 說明 |
---|---|---|---|
dataSourceInput |
元素控制代碼或「urlbox」 | 空值 |
可用來讓使用者指定圖表的資料來源。這個屬性可以是以下兩個值之一:
|
活動
圖表編輯器會擲回下列事件:
名稱 | 說明 | 屬性 |
---|---|---|
ok |
使用者按一下對話方塊中的 [確定] 按鈕時觸發。收到這個方法之後,您必須呼叫 getChartWrapper() 以擷取使用者設定的圖表。 |
無 |
cancel |
使用者按一下對話方塊中的 [取消] 按鈕時觸發。 | 無 |
範例
以下範例程式碼會開啟圖表編輯器對話方塊,當中顯示已填入的折線圖。如果使用者點選 [確定],編輯過的圖表就會儲存到網頁上指定的 <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
命名空間公開下列方法:
方法 | 說明 |
---|---|
google.visualization.data.group
|
執行 SQL GROUP BY 動作,以傳回依指定資料欄的值分組的資料表。 |
google.visualization.data.join
|
彙整兩個關鍵資料欄中的兩個資料表。 |
group()
使用已填入的 DataTable
物件並執行類似 SQL 的 GROUP BY 作業,並傳回內含指定資料欄值資料列的資料列。請注意,這樣做不會修改輸入 DataTable
。
傳回的表格會針對指定鍵資料欄中的每個值組合各建立一個資料列。每一列都含有索引鍵資料欄,以及一個與資料欄組合相符的所有資料列中匯總資料欄值的一個資料欄 (例如指定資料欄內所有值的加總或計數)。
google.visualization.data
命名空間包含數個實用的匯總值 (例如 sum 和 count),但您可以定義自己的匯總值 (例如 standardDeviation 或 secondHighest)。方法說明之後,會提供如何自行定義集結網站的操作說明。
語法
google.visualization.data.group(data_table, keys, columns)
- 資料表格
-
輸入的
DataTable
。不會呼叫group()
來修改這項設定。 - keys
- 數字和/或物件的陣列,用於指定要分組的欄。結果資料表包含這個陣列中的所有資料欄,以及資料欄中的每個資料欄。如果為數字,則為輸入
DataTable
的欄索引,用於分組。如果物件為一個物件,將包含可修改指定欄的函式 (例如,在該資料欄中的值增加 1)。該物件必須具備下列屬性:- column - 這個數字是 dt 中資料欄的套用索引,用於套用轉換。
- modifier - 可接受一個值 (每個資料列中該儲存格的儲存格值) 的函式,然後傳回修改後的值。此函式可用來修改資料欄值,以協助分組:例如,呼叫以日期欄計算季度的 whatQuarter 函式,這樣 API 就可以依季度將資料列分組。計算結果會顯示在回傳資料表的鍵欄中。此函式可在這個物件中以內嵌方式宣告,也可以是您在程式碼其他位置定義的函式 (必須位於呼叫範圍內)。這個 API 提供一個簡易修飾符函式;如要瞭解如何自行建立更實用的函式,請參閱這篇文章的操作說明。您必須知道這個函式可接受的資料類型,且只在該類型的資料欄上呼叫。您也必須知道這個函式的傳回類型,然後在下方所述的 type 屬性中宣告該函式。
- type - 由函式修飾符傳回的類型。應為 JavaScript 字串類型名稱,例如:「數字」或「布林值」。
-
label - [選用] 字串標籤,會在傳回的
DataTable
中指派這個資料欄。 -
「id」 - [選用],用於在傳回的
DataTable
中指派這個資料欄的字串 ID。
範例:[0]
、[0,2]
、[0,{column:1, modifier:myPlusOneFunc, type:'number'},2]
- 欄
-
[選用] 除了您指定的資料欄外,您還可以指定要納入輸出資料表的資料欄。由於資料列群組中的所有資料列都會壓縮為單一輸出資料列,因此您必須決定該資料列群組顯示的值。例如,您可以選擇顯示集合的第一列資料欄值,或顯示該群組內所有資料列的平均值。columns 是物件陣列,其屬性如下:
- 資料欄 - 用來指定要顯示資料欄索引的數字。
- aggregate - 這個函式會接受此資料列群組中這個資料欄所有值的陣列,並傳回單一值以顯示在結果列中。傳回值的類型必須為物件的 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 參數來自訂分組行為。
函式 | 輸入陣列類型 | 傳回類型 | 說明 |
---|---|---|---|
google.visualization.data.month |
日期 | 數字 | 如果有指定日期,它會傳回零零月值(0、1、2 等)。 |
提供的匯總函式
API 提供下列可匯總至資料欄的匯總函式。aggregate 參數陣列。
函式 | 輸入陣列類型 | 傳回類型 | 說明 |
---|---|---|---|
google.visualization.data.avg |
數字 | 數字 | 傳入的陣列平均值。 |
google.visualization.data.count |
任何類型 | 數字 | 群組中的資料列數量。系統會計算空值與重複值。 |
google.visualization.data.max |
數字,字串,日期 | number, string, Date, null | 陣列中的最大值。如果是字串,這是按照時間排序排序的第一個項目;如為日期值,則為最新的日期。系統會忽略空值。如果沒有上限,則傳回空值。 |
google.visualization.data.min |
數字,字串,日期 | number, string, Date, null | 陣列中的最小值。如果是字串,這是按照時間排序排序的最後一個項目;如為日期值,則為最早的日期。系統會忽略空值。如果沒有最小值,則傳回空值。 |
google.visualization.data.sum |
數字 | 數字 | 陣列中所有值的加總。 |
建立修飾符函式
在 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()
這個方法會將兩個資料表 (DataTable
或 DataView
物件) 合併成單一結果資料表,類似 SQL JOIN 陳述式。您指定兩個資料表之間的一或多個資料欄組合 (key 資料欄),輸出資料表會依據您指定的彙整方法納入資料列:僅包含兩個索引鍵的資料列;兩個資料列中的資料列均相同;或兩個資料表中的所有資料列,無論是否相符。結果資料表僅包含索引鍵資料欄,以及您指定的任何其他資料欄。請注意,dt2 不能有重複的索引鍵,但 dt1 可以。「鍵」一詞表示所有鍵資料欄值的組合,而非特定鍵資料欄值;如果資料列含有儲存格值 A | B | C 且資料欄 0 和 1 都是索引鍵資料欄,則該資料列的索引鍵為 AB。
語法
google.visualization.data.join(dt1, dt2, joinMethod, keys, dt1Columns, dt2Columns);
- dt1
- 填入的
DataTable
以便與 dt2 彙整。 - dt2
-
填入的
DataTable
與 dt1 彙整。這個資料表不能有多個相同的鍵 (其中某個鍵是索引鍵資料欄的組合)。 - joinMethod
- 指定彙整類型的字串。如果 dt1 有多個與 dt2 資料列相符的資料列,輸出資料表會包含所有相符的 dt1 資料列。選擇下列的值:
- 'full' - 輸出資料表包含所有來自兩個資料表的資料列,無論金鑰是否相符。不相符的資料列會包含空的儲存格,並將相符的資料列合併。
- 'inner' - 完整彙整:僅篩選與鍵相符的列。
- 'left' - 輸出資料表包含來自 dt1 的所有資料列,無論是否相符的 dt2 資料列。
- 'right' - 輸出資料表含有來自 dt2 的所有資料列,無論是否有來自 dt1 的相符資料列。
- keys
- 要與這兩個資料表相比的索引鍵資料欄陣列。每一組都是兩個元素陣列,第一個元素是 dt1 中的鍵,第二個則是 dt2 中的金鑰。這個陣列可以根據索引、ID 或標籤指定資料欄,詳情請參閱
getColumnIndex
。
這兩個資料表的資料欄類型必須相同。所有指定的鍵都必須符合 joinMethod 指定的規則,才能納入資料表中的資料列。輸出資料欄一律含有輸出資料欄。只有左側資料表的 dt1 可包含重複的鍵;dt2 中的金鑰不得重複。這裡的「鍵」表示一組不重複的資料欄,而非個別資料欄值。例如,如果您的索引鍵資料欄是 A 和 B,下表將僅具有不重複的鍵值 (因此可能會用做 dt2):答 B 1 月 紅色 1 月 Blue 弗雷德 紅色 [[0,0], [2,1]]
會比較兩個資料表中第一個資料欄的值,以及來自 dt1 的第三個資料欄的值和 dt2 的第二個資料欄。 - dt1 欄
- 除了 dt1 的索引鍵資料欄之外,輸出資料表所納入的 dt1 資料欄陣列。這個陣列可以根據索引、ID 或標籤來指定資料欄,詳情請參閱
getColumnIndex
。 - dt2 欄
- 除了 dt2 的索引鍵資料欄之外,輸出資料表所納入的 dt2 資料欄陣列。這個陣列可以根據索引、ID 或標籤來指定資料欄,詳情請參閱
getColumnIndex
。
傳回值
包含主要資料欄、dt1Columns 和 dt2Columns 的 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 視覺化 API 提供格式化工具,可用來重新設定視覺化資料中的資料格式。這些格式會變更所有資料欄中指定資料欄的格式化值。請注意:
- 格式化工具只會修改格式化的值,不能修改基礎值。例如,顯示的值會是「$1,000.00」,但基礎值仍是「1000」。
- 格式化工具一次只能影響一個資料欄;如要重新格式化多個資料欄,請將格式轉換器套用至要變更的每個資料欄。
- 如果您同時使用使用者定義的格式設定工具,某些 Google 視覺化格式轉換工具會覆寫所有使用者定義的格式設定工具。
- 取得填入的
DataTable
物件。 - 針對您要重新格式化的每一欄:
- 建立可指定格式轉換器選項的所有物件。這是一個基本的 JavaScript 物件,內含一組屬性與值。請參閱格式器的說明文件,瞭解系統支援哪些屬性。(您也可以選擇傳入物件文字標記物件以指定選項)。
- 建立格式轉換程式,傳入選項物件。
-
呼叫
formatter
.format(table, colIndex)
,傳入DataTable
與 (零) 資料欄編號以重新格式化資料。請注意,您只能為每個資料欄套用單一格式設定工具;套用第二個格式設定工具只會覆寫第一個格式。
重要事項:許多格式設定工具都需要 HTML 標記才能顯示特殊格式;如果您的視覺呈現支援allowHtml
選項,則應將其設為 true。
資料套用的實際格式設定衍生自 API 的載入地區。詳情請參閱使用特定語言代碼載入圖表。
重要事項:格式化工具只能搭配 DataTable
使用,無法與 DataView
搭配使用 (DataView
物件為唯讀狀態)。
以下是使用格式化工具的一般步驟:
以下範例說明如何將日期欄的日期格式值變更為使用較長的日期格式 (「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 是指定的格式化者類別名稱。
// 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) |
重新格式化指定資料欄中的資料。
|
Google 視覺化 API 提供下列格式:
格式名稱 | 說明 |
---|---|
箭頭格式 | 新增向上或向下箭頭,表示儲存格值是否高於或低於指定值。 |
BarFormat | 新增色條,其方向和顏色表示儲存格值是否高於或低於指定值。 |
顏色格式 | 根據值是否落在指定範圍內,調整儲存格的顏色。 |
日期格式 | 日期或日期時間的值可採用多種不同方式,包括「2009 年 1 月 1 日」、「1/0/9」和「2009 年 1 月 1 日」。 |
數字格式 | 設定數值的各方面格式。 |
圖案格式 | 將同一列中的儲存格值與任意文字串連。 |
箭頭格式
根據數值本身是否高於或低於指定值,在數字儲存格中新增向上或向下箭頭。如果等於基本值,則不會顯示箭頭。
選項
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 |
字串,用於表示長條的正值區段顏色。可能的值包括「紅色」、「綠色」和「藍色」。預設值為「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%'});
色彩格式
根據儲存格值,為數字儲存格的前景或背景指派顏色。這個格式轉換是很正常的,因為它不會採用建構函式中的選項。因此,建議您在呼叫 format()
之前,視需要多次呼叫 addRange()
或 addGradientRange()
,以便新增色彩範圍。您可以使用任何可接受的 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 的值!
|
addGradientRange(from, to, color, fromBgColor,
toBgColor)
|
根據儲存格的值指派範圍中的背景顏色。該顏色會依照儲存格的下限值 (由下邊界顏色到上邊界顏色) 進行縮放。請注意,這個方法無法比較字串值,因為
|
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%'});
日期格式
以多種方式設定 JavaScript Date
值的格式,包括「2016 年 1 月 1 日」、「1/1/16」和「2016 年 1 月 1 日」。
選項
DateFormat
支援以下選項,並傳入建構函式:
選項 | 說明 |
---|---|
formatType |
日期的快速格式設定選項。系統支援下列字串值,重新設定 2016 年 2 月 28 日的日期,如下所示:
您無法同時指定 |
pattern |
要套用至值的自訂格式模式,類似 ICU 日期和時間格式。例如:
您無法同時指定 |
timeZone |
顯示日期值的時區。此值為數值,表示 GMT 加上這個時區的時區 (可以是負數)。系統預設會使用建立時所用電腦之時區的時區建立日期物件;這個選項是用來以不同時區顯示該值。舉例來說,假設您在位於格林威治的博物館建立下午 5 點的日期物件,並將時區設為 -5 (美國則是 options['timeZone'] = -5 ,或是美國東部時間),則顯示的值會是中午 12 點。
|
方法
DateFormat
支援以下方法:
方法 | 說明 |
---|---|
google.visualization.DateFormat(options) |
建構函式。詳情請參閱上方的選項部分。 |
format(dataTable, columnIndex) |
將 format() 方法套用至指定資料欄的格式。 |
formatValue(value) |
傳回指定值的格式化值。
這個方法不需要 |
程式碼範例
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 D F g Y u w W。為了避免與模式衝突,您想要在輸出內容中顯示的任何文字都應以單引號括住,但單引號應以雙引號括住,例如:"K 'o''clock.'"
。
模式 | 說明 | 輸出範例 |
---|---|---|
GG | Era 設計人員。 | 「廣告」 |
y 或 yyyy | 。 | 1996 |
M |
月份。1 月:
|
「7 月」 「07」 |
天 | 日。多餘的「d」值將會加零。 | 10 |
小時 | 小時 (12 小時制)。額外的「h」值會加零。 | 12 |
H | 小時 (以 24 小時製表示)。額外的 HK 值會加上開頭的零。 | 0 |
分 | 以分鐘為單位,額外的「M」值將會加零。 | 30 |
秒 | 以秒為單位額外的 會加零。 | 55 |
S | 片段的秒數。額外的「S」值會在右邊加上零。 | 978 |
E |
星期幾「星期二」輸出項目如下:
|
週二 "星期二" |
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 種 ZZZZ 等廠牌的產品包括「GMT -05:00」 |
「-0800」 「GMT -05:00」 |
非常 | 時區 (一般)。 |
「Etc/GMT-5」 |
' | 逸出 - 文字 | 日期日期 |
」 | 單引號 | 'yy |
數字格式
說明數值欄的格式。格式選項包括指定前置字串符號 (例如錢幣符號) 或用作數千個標記的標點符號。
選項
NumberFormat
支援以下選項,並傳入建構函式:
選項 | 說明 |
---|---|
decimalSymbol |
要做為小數標記字元。預設值為點 (.)。 |
fractionDigits |
指定小數點後要顯示的數字數量。預設值為 2。如果您指定的位數大於指定數值,則小數值會顯示為零。經過截斷後將無條件進位至 5 位數。 |
groupingSymbol |
用於將小數點左側的數字分組,分為三組。預設值為半形逗號 (,)。 |
negativeColor |
負值的值文字顏色。沒有預設值。值可以是任何可接受的 HTML 色彩值,例如「red」或「#FF0000」。 |
negativeParens |
布林值,其中 true 表示應以括號括住負值。預設值為是。 |
pattern |
格式字串。提供時,除了
格式字串是 ICU 模式集的一部分。舉例來說, |
prefix |
值的字串前置字元,例如「$」。 |
suffix |
值的字串後置字串,例如「%」。 |
方法
NumberFormat
支援以下方法:
方法 | 說明 |
---|---|
google.visualization.NumberFormat(options) |
建構函式。詳情請參閱上方的選項部分。 |
format(dataTable, columnIndex) |
要對指定資料欄套用格式設定的標準 format() 方法。 |
formatValue(value) |
傳回指定值的格式化值。這個方法不需要 |
程式碼範例
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%'});
圖案格式
可讓您將指定資料欄的值與任意文字合併為單一資料欄。例如,如果您有一個名字欄和姓氏欄,就可以在第三個資料欄中填入「{last name}」的{last name}資料欄。這個格式工具不會遵循建構函式和 format()
方法的慣例。如需操作說明,請參閱下方的「方法」一節。
方法
PatternFormat
支援以下方法:
方法 | 說明 |
---|---|
google.visualization.PatternFormat(pattern) |
建構函式。不會使用選項物件。而是接受字串 pattern 參數。這個字串可說明要填入目標資料欄的欄值和任意文字。在您的字串中嵌入預留位置,指出要嵌入其他資料欄的值。預留位置是
程式碼範例下列範例示範用於建立錨點元素的模式建構函式,其中第一個和第二個元素均取自 var formatter = new google.visualization.PatternFormat( '<a href="mailto:{1}">{0}</a>'); |
format(dataTable, srcColumnIndices,
opt_dstColumnIndex)
|
標準格式呼叫,以及一些額外參數:
請參閱表格下方的格式設定範例。 |
以下列舉幾個四欄表格的輸入和輸出範例。
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%'});
小工具協助工具
這個輔助類別可簡化使用 Google 視覺化 API 編寫小工具。
建構函式
google.visualization.GadgetHelper()
方法
方法 | 傳回值 | 說明 |
---|---|---|
createQueryFromPrefs(prefs) |
google.visualization.Query |
靜態。建立新的 google.visualization.Query 例項,並根據小工具偏好設定的值設定其屬性。參數 prefs 的類型為 _IG_Prefs
|
validateResponse(response) |
布林值 |
靜態。參數 response 的類型為 google.visualization.QueryResponse。如果回應中包含資料,則傳回 true 。如果查詢執行失敗,且回應不包含資料,則會傳回 false 。如果發生錯誤,這個方法會顯示錯誤訊息。 |
查詢類別
下列物件可用於傳送資料查詢至外部資料來源,例如 Google 試算表。
- 查詢 - 納入傳出資料要求。
- QueryResponse - 處理資料來源的回應。
查詢
代表傳送至資料來源的查詢。
建構函式
google.visualization.Query(dataSourceUrl, opt_options)
參數
- 資料來源網址
- [必要, 字串] 要傳送查詢的網址。請參閱 Google 試算表適用的圖表與試算表說明文件。
- opt_options
-
[選用,物件] 要求的選項對應。注意:如要存取受限的資料來源,請勿使用這個參數。支援的屬性如下:
-
sendMethod - [選用,字串] 指定用來傳送查詢的方法。選擇下列其中一個字串值:
- 'xhr' - 使用 XmlHttpRequest 傳送查詢。
- 'scriptInjection' - 使用指令碼插入來傳送查詢。
-
'makeRequest' - [僅適用於 PRODUCTs,亦即已淘汰] 使用 Widget API 傳送查詢
makeRequest()
方法。如果有指定,您也應指定 makeRequestParams。 -
'auto' - 使用資料來源網址中
tqrt
網址參數指定的方法。tqrt
的值可能如下:「xhr」、「scriptInjection」或「makeRequest」。如果缺少tqrt
或值無效,相同的網域要求將預設為「xhr」,跨網域要求將預設為「scriptInjection」。
-
makeRequestParams - [Object]
makeRequest()
查詢的參數對應。只有在 sendMethod 為「makeRequest」時,才需要使用這個屬性。
-
sendMethod - [選用,字串] 指定用來傳送查詢的方法。選擇下列其中一個字串值:
方法
方法 | 傳回值 | 說明 |
---|---|---|
abort() |
無 |
停止使用 setRefreshInterval() 啟動的自動查詢傳送。 |
setRefreshInterval(seconds)
|
無 |
設定查詢,讓系統從第一次明確呼叫 如果您使用這個方法,請先呼叫此方法再呼叫
如要取消此方法,您可以再次呼叫零 (預設),或呼叫 |
setTimeout(seconds) |
無 |
設定在收到逾時錯誤前,等待資料來源回應的秒數。seconds 是大於 0 的數字。預設的逾時設定為 30 秒。如果使用此方法,應在呼叫 send 方法之前呼叫。 |
setQuery(string) |
無 |
設定查詢字串。string 參數的值必須是有效的查詢。如果使用此方法,應在呼叫 send 方法之前呼叫。進一步瞭解查詢語言。 |
send(callback) |
無 |
將查詢傳送至資料來源。callback 應為函式在資料回應時呼叫的函式。回呼函式會收到 google.visualization.QueryResponse 類型的單一參數。 |
QueryResponse
代表從資料來源收到的查詢執行作業回應。此類別的例項會以引數的形式傳送至 Query.send 呼叫時所設定的回呼函式。
方法
方法 | 傳回值 | 說明 |
---|---|---|
getDataTable() |
資料表 |
傳回資料來源傳回的資料表。如果查詢執行失敗,且未傳回任何資料,則會傳回 null 。 |
getDetailedMessage() |
字串 | 對失敗的查詢傳回詳細錯誤訊息。如果查詢執行成功,此方法會傳回空字串。此訊息是為開發人員撰寫的訊息,其中可能包含技術資訊,例如「「{salary}」欄不存在」。 |
getMessage() |
字串 | 針對失敗的查詢傳回簡短錯誤訊息。如果查詢執行成功,這個方法會傳回空字串。傳回的訊息是專為使用者所設計的簡短訊息,例如「無效的查詢」或「存取遭拒」。 |
getReasons() |
字串陣列 |
傳回 0 個更多項目的陣列。每個項目都是一個簡短字串,內含在執行查詢時產生的錯誤或警告碼。可能的代碼如下:
|
hasWarning() |
布林值 | 如果查詢執行出現任何警告訊息,則傳回 true 。 |
isError() |
布林值 |
如果查詢執行失敗,且回應不包含任何資料表,則傳回 true 。如果查詢執行成功,且回應中包含資料表,則傳回 <false>。 |
錯誤顯示
這個 API 提供多種功能,可協助您向使用者顯示自訂錯誤訊息。如要使用這些函式,請在頁面上提供容器元素 (通常是 <div>
),API 會在當中繪製格式化的錯誤訊息。此容器可以是視覺化容器元素,或是只用於發生錯誤的容器。如果您指定視覺化元素包含的元素的元素,系統會在視覺呈現上方顯示錯誤訊息。然後呼叫下方的適當函式,即可顯示或移除錯誤訊息。
所有函式都是「google.visualization.errors
」命名空間中的靜態函式。
許多視覺呈現可能會擲回錯誤事件;詳情請參閱下方的錯誤事件。
您可以前往查詢包裝函式範例查看自訂錯誤範例。
函式 | 傳回值 | 說明 |
---|---|---|
addError(container, message, opt_detailedMessage,
opt_options)
|
字串 ID 值,可用來識別已建立的錯誤物件。這是網頁中唯一的值,可用來移除錯誤或找出其包含的元素。 |
為特定頁面元素加上錯誤顯示區塊,並加入指定文字和格式設定。
|
addErrorFromQueryResponse(container, response) |
字串 ID 值,用於識別已建立的錯誤物件;如果回應未指出任何錯誤,則會傳回空值。這是網頁上唯一的值,可用來移除錯誤或找出其包含的元素。 |
將查詢回應和錯誤訊息容器傳遞至此方法:如果查詢回應指出查詢錯誤,就會在指定的網頁元素中顯示錯誤訊息。如果查詢回應為空值,此方法將擲回 JavaScript 錯誤。將查詢處理常式收到的 QueryResponse 傳送至此訊息以顯示錯誤。系統也會根據類型調整顯示樣式 (錯誤或警告,類似於
|
removeError(id) |
布林值:如果錯誤遭到移除,則傳回 True,否則傳回 False。 |
從頁面移除 ID 指定的錯誤。
|
removeAll(container) |
無 |
移除指定容器中的所有錯誤區塊。如果指定的容器不存在,就會擲回錯誤。
|
getContainer(errorId) |
處理含有指定錯誤的 DOM 元素;如果找不到該錯誤,則傳回 null。 |
擷取容器元素控點,該元素包含 errorID 指定的錯誤。
|
活動
大多數視覺呈現都會觸發事件以指出發生特定事件。圖表的使用者通常會想要聆聽這些事件。如果您自行編寫視覺化程式碼,也希望自行觸發這類事件。
下列方法可讓開發人員監聽視覺事件、移除現有事件處理常式,或從視覺中觸發事件。
- 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)
- 來源視覺效果
- 來源視覺化執行個體的處理常式。
- 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)
- 清單講者
- 由 google.visualization.events.addListener() 傳回的事件監聽器處理常式。
removeAllListeners()
呼叫這個方法,即可取消註冊特定視覺化執行個體的所有事件監聽器。
google.visualization.events.removeAllListeners(source_visualization)
- 來源視覺效果
- 指定來源視覺化執行個體的控點,用於移除所有事件監聽器。
trigger()
透過視覺化的實作工具呼叫。從視覺化工具呼叫此方法,即可以任意名稱和一組值啟動事件。
google.visualization.events.trigger(source_visualization, event_name, event_args)
- 來源視覺效果
-
來源視覺化執行個體的控點。如果您是從傳送視覺化資料定義的方法中呼叫此函式,只要傳入
this
關鍵字即可。 - event_name
- 呼叫事件的字串名稱。您可以選擇任何所需的字串值。
- event_args
- [選用] 要傳送到接收方法的名稱/值組合。例如:{message: "Hello 台!", Score: 10, name: "Fred"}。如果不需要事件,您可以傳遞空值;接收器應準備好接受此參數的空值。
示例
以下圖表範例在呼叫 onclick 方法時,會呼叫名為「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()
您可以選擇利用具有工具提示的視覺化方式來呈現,也可以顯示工具提示動作。這項功能僅適用於核心圖表 (長條圖、柱狀圖、折線圖、面積圖、散佈圖、對話框、圓餅圖、圓環圖、燭台、階梯圖、階梯面積圖)。
設定在使用者點選動作文字時要執行的工具提示動作。
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()
這個方法使用 2D 陣列,並將其轉換為 DataTable。
系統會根據所提供的資料自動決定資料欄資料類型。您也可以使用陣列的第一列 (資料欄標題列) 中的物件常值標記法指定資料欄資料類型,例如 {label: 'Start Date', type: 'date'}
。您也可以使用選用資料角色,但必須使用物件常值標記法明確定義這些資料類型。物件常值標記也可用於任何儲存格,可讓您定義儲存格物件)。
語法
google.visualization.arrayToDataTable(twoDArray, opt_firstRowIsData)
- YouTube 陣列
- 二維陣列,每一列代表資料表中的一個資料列。如果 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 物件,其屬性如下 (區分大小寫):
屬性 | 類型 | 必填 | 預設 | 說明 |
---|---|---|---|---|
圖表類型 | 字串 | 必填 | 無 |
視覺呈現的類別名稱。Google 圖表可以省略 google.visualization 套件名稱。如果尚未載入適當的視覺化資料庫,這個方法會載入 Google 的視覺化資料庫。您必須明確載入第三方視覺化呈現內容。範例:Table 、PieChart 、example.com.CrazyChart 。
|
容器 ID | 字串 | 必填 | 無 | 要代管視覺呈現的 DOM 元素 ID。 |
選項 | 物件 | 選用 | 無 |
說明視覺呈現選項的物件。您可以使用 JavaScript 文字標記法,或提供物件控制代碼。範例:
"options": {"width": 400, "height": 240,
"is3D": true, "title": "Company Performance"}
|
資料表 | 物件 | 選用 | 無 |
用於填入視覺呈現的 DataTable 。這可以是 DataTable 的常值 JSON 字串表示法,如上述所述,或是填入的 google.visualization.DataTable 物件控制代碼,或
arrayToDataTable(opt_firstRowIsData=false)
接受的二維陣列。您必須指定這個屬性或 dataSourceUrl 屬性。 |
資料來源網址 | 字串 | 選用 | 無 |
用於填入圖表資料的資料來源查詢 (例如 Google 試算表)。您必須指定這個屬性或 dataTable 屬性。 |
查詢 | 字串 | 選用 | 無 |
指定 dataSourceUrl 時,您可以視需要使用視覺化查詢語言來指定類似 SQL 的查詢字串,以篩選或操控資料。
|
refreshInterval | 數字 | 選用 | 無 |
視覺呈現應重新整理查詢來源的頻率 (以秒為單位)。只有在指定 dataSourceUrl 時,才能使用此屬性。 |
檢視表 | 物件或陣列 | 選用 | 無 |
設定 DataView 初始化器物件,其會以 dataTable 或 dataSourceUrl 參數定義的基礎資料篩選器。您可以傳入字串或 DataView 初始化器物件,例如 dataview.toJSON() 傳回的物件。範例: "view": {"columns": [1, 2]} 您還可以傳遞 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()
這是可附加至許多視覺呈現的工具列元素的建構函式。這個工具列可讓使用者將視覺化資料匯出成不同格式,或提供可嵌入的視覺化版本,以便在不同位置使用。如需詳細資訊,請參閱工具列頁面和程式碼範例。