本文件說明如何將圖表資料傳送至 Google Chart API。
目錄
總覽
幾乎所有圖表的資料都會使用 chd
參數傳送。資料必須以下列其中一種格式傳送:
- 基本文字格式基本上是介於 0 至 100 (含) 之間的簡單浮點數。這種格式方便手動讀取及寫入。
- 採用自動調整資源配置功能的文字格式,可配合資料調整圖表大小。
- 具有自訂縮放功能的文字格式與基本文字格式類似,但可讓您使用第二個網址參數指定自訂範圍。
- 簡易編碼格式可讓您指定介於 0 至 61 (含) 之間 (含首尾) 並以單一英數字元編碼的整數值。此編碼會產生任何資料格式最小的資料字串 (如果任何值大於 9)。
- 擴充編碼格式可讓您指定介於 0 到 4095 之間的整數值 (含兩個英數字元)。擴充編碼最適合含有大量資料和龐大資料的圖表。
資料值會隨使用的格式而縮放;請參閱資料資源調度與軸縮放一文,瞭解如何根據圖表來調整資料。
我們提供了 JavaScript 程式碼片段,可將資料編碼為簡易編碼或擴充編碼格式。或者,有幾位 Google 圖表群組成員也提供了其他程式庫來協助格式化:搜尋封存檔以便找出這些資料庫。
基本文字格式
基本文字格式資料可讓您將 0 到 100 (含首尾) 之間的浮點值指定為數字。低於 0 的值會標示為遺漏;超過 100 的值會截斷為 100。基本文字格式的優點在於網址中的值易於閱讀及理解,而預設軸標籤則能準確顯示資料值。不過,文字格式設定 (無論是簡單還是使用自訂參數) 會產生所有格式最長的資料字串。
如果資料包含指定文字格式設定範圍以外的值,您可以將資料轉換成資料中最大值的百分比,藉此調整資料規模。或者,您也可以使用搭配自訂縮放功能的文字格式設定,藉此處理縮放操作。
語法:
chd=t:val,val,val|val,val,val...
- <資料>
- 每個數列是指一或多個以半形逗號分隔的值。請使用直立線字元 (
|
) 分隔多個序列值,值是介於 0 至 100 (含首尾) 之間的浮點數。小於零的值或底線字元 ( _ ) 均視為空值。超過 100 個的值會截斷至 100 個。
範例:
內含五個值的表格。底線會視為空值,-30 值低於最小值,因此會遭捨棄,200 個值則截斷為 100。 | chd=t:_,30,-30,50,80,200 |
具有自動調整資源配置的文字格式
您可以設定部分圖表,依據資料自動調整資源配置。系統會縮放圖表,讓最大的值顯示在圖表頂端,最小值 (如果所有值大於零,則為零) 則在底部。
圖表中顯示的所有標記值都會顯示實際值,而非縮放值。
這項功能僅適用於文字格式的值,且不適用於所有圖表類型。嘗試使用圖表類型,看看系統是否支援該圖表。
語法
cht=t:val,val,val... chds=a
例如:
請注意,圓餅圖不可使用 < 0 值。 |
chd=t:-5,30,-30,50,80,200 |
使用自訂縮放功能的文字格式
採用自訂縮放功能的文字格式可讓您指定任意正浮點數,或搭配使用縮放參數,以便為圖表指定自訂範圍。如果您不想將資料限制在特定範圍,或是不想手動調整資料規模來讓圖表內完全填滿,這個圖表可以派上用場。這種格式會視需要為您調整零行。資料格式與基本文字格式相同。
如要自動調整資源配置,請指定 chds=a
。
文字格式 (無論是簡單還是使用自訂參數) 會產生所有格式最長的資料字串。
語法:
使用自訂縮放功能的文字格式設定需要兩個參數:
chd=t:val,val,val|val,val,val chds=<series_1_min>,<series_1_max>,...,<series_n_min>,<series_n_max>
- chd=t:<data>
- 與純文字資料格式相同:每個序列有一或多個以半形逗號分隔的值,並以直立線字元 (
|
) 分隔多個序列。每序列允許的值範圍則透過chds
參數指定。 - 黑人
- 每個資料序列的一或多個允許的最小值和最大值,並以半形逗號分隔。您必須同時提供最大值和最小值。如果提供的配對數量少於資料序列數量,系統會將最後一個組合套用至其餘的所有資料序列。請注意,這不會變更軸範圍;如要變更軸範圍,您必須設定
chxr
參數。 有效值範圍介於 (+/-)9.999e(+/-)199 之間。您可以指定標準值或 E 標記法格式。- <series_1_min>
- 第一個系列的最小值。較低的值會標示為遺漏。
- <series_1_max>
- 第一個序列允許的值。如果是較大的值,系統會截斷這個值。
範例:
長條圖的最小/最大尺度為 -80-140。30、-60、50、140 和 80 的值在比例範圍內,因此不會遭到截斷。請注意,系統會為您調整零線,也就是高於 Y 軸的 80/(140 + 80) = 0.36。 另請注意,雖然 |
|
簡易編碼格式
簡易編碼格式可讓您指定 0 至 61 之間的整數值 (含首尾),並以單一英數字元進行編碼。這樣會產生所有資料格式的最低資料字串網址。不過,如果您的折線圖或長條圖超過資料軸的像素超過 100 像素,建議您使用其他格式。這是因為只支援 62 個資料值,資料的精細程度遠遠高於顯示精細程度,而值資料則會稍微減少 (不會太大,但在較大的圖表上顯示)。
請注意,如果您搭配簡易編碼使用 chds
參數,圖表上的資料元素大小不會受到影響,但所有資料點標記值都會受到影響。
語法:
chd=s: <series_1> ,..., <series_n>
- <series_1>
- 字串,其中每個字元都是單一資料點,而序列序列會以半形逗號分隔。系列中的個別值不會分隔。 以下是支援的資料字元及其對應的值:
A—Z
,其中A
= 0,B
= 1,依此類推,到Z
= 25a—z
,其中a
= 26,b
= 27,依此類推,到z
= 510(zero)—9
,其中0
= 52,9
= 61- 底線字元 (
_
) 表示缺少值
您可以使用以下工具對單一值進行編碼,或使用 JavaScript 程式碼擴充及編碼整個網址字串。
範例:
等同於文字編碼字串 chd=t:1,19,27,53,61,-1|12,39,57,45,51,27 |
<title="chs=320x200&cht=bvs&chd=s:btb19_,mn5tzb&chco=ffcc33,ffe9a4&chxr=0,0,61,5&chxt=y" alt="堆疊長條圖, 307,072,072,072,291,217chd=s:BTb19_,Mn5tzb |
擴充編碼格式
擴充編碼格式可讓您指定介於 0 到 4095 (含) 之間的整數值,並以兩個英數字元進行編碼。這種格式的語法與簡易編碼略有不同。
請注意,如果您搭配簡易編碼使用 chds
參數,圖表中的資料元素大小不會受到影響,但所有資料點標記值都會受到影響。
語法:
chd=e: <series_1> ,..., <series_n>
- <series_1>
- 字串,其中兩個字元各為單一資料點,而序列之間以半形逗號分隔。系列中的個別值不會分隔。 支援的編碼字元如下:
A—Z
a—z
0—9
- 週期 (
.
) - 連字號 (
-
) - 缺少的值會以雙底線 (
__
) 表示。
編碼值的縮寫說明如下:
AA
= 0、AB
= 1,依此類推至AZ
= 25Aa
= 26,Ab
= 27,依此類推至Az
= 51A0
= 52,A1
= 53,依此類推,A9
= 61A-
= 62,A.
= 63BA
= 64,BB
= 65,依此類推,BZ
= 89Ba
= 90,Bb
= 91,依此類推,Bz
= 115B0
= 116,B1
= 117,依此類推,B9
= 125B-
= 126,B.
= 1279A
= 3904,9B
= 3905,依此類推,9Z
= 39299a
= 3930,9b
= 3931,依此類推,9z
= 395590
= 3956,91
= 3957,依此類推,99
= 39659-
= 3966,9.
= 3967-A
= 3968,-B
= 3969,依此類推,-Z
= 3993-a
= 3994,-b
= 3995,依此類推,-z
= 4019-0
= 4020,-1
= 4021,依此類推數為-9
= 4029--
= 4030,-.
= 4031.A
= 4032、.B
= 4033 等等.Z
= 4057.a
= 4058,.b
= 4059,依此類推至.z
= 4083.0
= 4084,.1
= 4085,依此類推至.9
= 4093.-
= 4094,..
= 4095
您可以使用以下工具對單一值進行編碼,或使用 JavaScript 程式碼擴充及編碼整個網址字串。
範例:
等同於文字編碼字串 chd=t:90,1000,2700,3500|3968,-1,1100,250 |
chd=e:BaPoqM2s,-A__RMD6 |
資料資源調度和軸尺度
系統會透過明確 (搭配自訂縮放使用文字格式時) 或隱含 (所有其他類型) 的方式,根據圖表調整資料。這表示,每張圖表都會根據格式的「可用範圍」進行縮放,而「不是」您提供的資料「實際範圍」。
建議您調整資料規模,讓資料涵蓋格式允許的完整值範圍,讓資料更明顯。您可以調整資料規模,以符合您使用的格式,或是明確指定資料範圍 (也就是搭配自訂縮放使用文字格式)。
請注意,軸標籤值是完全獨立的尺度計算而得,與資料值沒有任何作用,但是使用預設範圍 0-100。但您可以變更該範圍。
本節將說明這兩種問題。
根據格式範圍調整資料 [Pie 和 Venn 以外的所有圖表]
不同的格式支援不同的值範圍。資料會縮放至您的格式範圍,讓格式支援的最大值顯示在該軸頂端,而您的格式最小值會顯示在底部。以下範例使用基本文字格式 (範圍 0 至 100)、含有自訂縮放比例的文字 (自訂範圍 0 至 200) 和延伸編碼格式 (範圍 0 至 4095) 顯示相同的值 (100)。
基本文字格式 | 使用自訂縮放功能的文字格式 | 擴充編碼格式 |
---|---|---|
值:100 ( 格式範圍:0-100 100 表示以 100/100 表示。 |
值 100 ( 格式範圍:0-200 100 代表以 100/200 表示比例顯示。 |
值:100 ( 格式範圍:0 至 4095 100 表示以 100/4095 表示,向上擴充為。 |
如要根據圖表調整資料規模,最簡單的方式就是使用文字格式搭配縮放。更複雜的方法是手動調整資料規模,讓資料符合格式支援的範圍。
圓餅圖和文氏圖:使用圓餅圖和文氏圖時,所有值都是相對的,而不是圖表的總比例。
chd=e:BkDIEs |
chd=t:100,200,300 |
軸標籤範圍會獨立計算 [長條圖、線條、雷達、散佈圖和 K 線圖]
您可以使用 chxt
參數顯示軸值。不過請注意,軸標籤計算結果不會反映圖表資料,但是由 API 獨立計算,或由您明確指定。
預設軸範圍為 0 到 100,無論資料值或資料資源調度為何。因此,如果您在使用擴充編碼 (範圍 0 到 4095) 的圖表上使用預設軸標籤顯示 Y 軸,除非您明確變更這個標籤,否則 Y 軸標籤仍會讀取 0 到 100,詳情請參閱下方說明。以下範例顯示資料值為 100 的擴充編碼長條圖中,預設 Y 軸標籤:
chd=e:Bk
(等同於 chd=t:100
)
不過,您可以使用 chxr
參數指定軸範圍。如要讓軸值反映實際資料值,請務必指定符合格式範圍的最小值和最大值。請注意,基本文字格式的比例已經 0 到 100,因此根據預設,使用基本文字格式設定 (不含自訂縮放功能),軸值將符合資料值。讓我們透過幾個例子來說明。以下是含有相同資料 (15,26,51,61) 的三張圖表,但格式和軸尺度不同:
簡易編碼,無軸縮放 | 簡易編碼、縮放軸 | 基本文字、無軸縮放 |
---|---|---|
簡易編碼值範圍:0 至 61 預設軸範圍 (0-100) 編碼範圍小於標籤軸範圍,因此長條不會對應軸標籤上的實際值。但長條之間會正確成比例。 |
簡易編碼值範圍:0 至 61 軸範圍明確設為 0-61 編碼範圍和軸範圍相等,因此長條會對應軸的正確值。 |
基本文字格式值範圍:0 至 100 預設軸範圍 (0-100) 編碼範圍和軸範圍相同,因此根據預設,準確的資料值會顯示在軸上。 文字格式範圍大於簡易編碼格式範圍 (100 個單位與 61 個單位),因此長條的大小比其他圖表小,但所有圖表均保持比例。 |
JavaScript 編碼指令碼
在實際使用時,以程式輔助方式將資料編碼可能比手動操作容易。
下列 JavaScript 程式碼片段會將單一系列編碼為 simple 或 extended 編碼,且能調整資料值以符合該編碼的完整範圍。資料必須以正數陣列提供。只要提供的值不是正數,即會使用底線字元 (_
) 編碼為遺漏值。
var simpleEncoding = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'; // This function scales the submitted values so that // maxVal becomes the highest value. function simpleEncode(valueArray,maxValue) { var chartData = ['s:']; for (var i = 0; i < valueArray.length; i++) { var currentValue = valueArray[i]; if (!isNaN(currentValue) && currentValue >= 0) { chartData.push(simpleEncoding.charAt(Math.round((simpleEncoding.length-1) * currentValue / maxValue))); } else { chartData.push('_'); } } return chartData.join(''); } // Same as simple encoding, but for extended encoding. var EXTENDED_MAP= 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.'; var EXTENDED_MAP_LENGTH = EXTENDED_MAP.length; function extendedEncode(arrVals, maxVal) { var chartData = 'e:'; for(i = 0, len = arrVals.length; i < len; i++) { // In case the array vals were translated to strings. var numericVal = new Number(arrVals[i]); // Scale the value to maxVal. var scaledVal = Math.floor(EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH * numericVal / maxVal); if(scaledVal > (EXTENDED_MAP_LENGTH * EXTENDED_MAP_LENGTH) - 1) { chartData += ".."; } else if (scaledVal < 0) { chartData += '__'; } else { // Calculate first and second digits and add them to the output. var quotient = Math.floor(scaledVal / EXTENDED_MAP_LENGTH); var remainder = scaledVal - EXTENDED_MAP_LENGTH * quotient; chartData += EXTENDED_MAP.charAt(quotient) + EXTENDED_MAP.charAt(remainder); } } return chartData; }
如要對資料進行編碼,請呼叫 simpleEncode
或 extendedEncode
函式,並傳入包含您資料的陣列 (valueArray
) 和資料的最大值 (maxValue
)。如要在最高值與圖表頂端之間建立一些空間,請將 maxValue
設為大於資料陣列中的最大數值,如下所示:
var valueArray = new Array(0,1,4,4,6,11,14,17,23,28,33,36,43,59,65); var maxValue = 70; simpleEncode(valueArray, maxValue);