資料格式

本文件說明如何將圖表資料傳送至 Google Chart API。

目錄

  1. 總覽
  2. 基本文字格式
  3. 具有自動調整資源配置的文字格式
  4. 使用自訂縮放功能的文字格式
  5. 簡易編碼格式
  6. 擴充編碼格式
  7. 資料資源調度和軸尺度
  8. JavaScript 編碼指令碼

總覽

幾乎所有圖表的資料都會使用 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。 含有 5 個值，文字編碼的長條圖。
chd=t:_,30,-30,50,80,200

返回頁首

具有自動調整資源配置的文字格式

您可以設定部分圖表，依據資料自動調整資源配置。系統會縮放圖表，讓最大的值顯示在圖表頂端，最小值 (如果所有值大於零，則為零) 則在底部。

圖表中顯示的所有標記值都會顯示實際值，而非縮放值。

這項功能僅適用於文字格式的值，且不適用於所有圖表類型。嘗試使用圖表類型，看看系統是否支援該圖表。

語法

cht=t:val,val,val...
chds=a

例如：


chd=t:5,30,50,80,200
chds=a

請注意，圓餅圖不可使用 < 0 值。

 含有 5 個值，文字編碼的長條圖。
chd=t:-5,30,-30,50,80,200
chds=a

返回頁首

使用自訂縮放功能的文字格式

採用自訂縮放功能的文字格式可讓您指定任意正浮點數，或搭配使用縮放參數，以便為圖表指定自訂範圍。如果您不想將資料限制在特定範圍，或是不想手動調整資料規模來讓圖表內完全填滿，這個圖表可以派上用場。這種格式會視需要為您調整零行。資料格式與基本文字格式相同。

如要自動調整資源配置，請指定 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。

另請注意，雖然 chds 參數，預設的 Y 軸範圍仍是 0 到 100，因此標籤值不會反映實際的資料值。

 有 5 個值的長條圖，採用資料縮放功能進行文字編碼。

chd=t:30,-60,50,140,80,-90
chds=-80,140

返回頁首

簡易編碼格式

簡易編碼格式可讓您指定 0 至 61 之間的整數值 (含首尾)，並以單一英數字元進行編碼。這樣會產生所有資料格式的最低資料字串網址。不過，如果您的折線圖或長條圖超過資料軸的像素超過 100 像素，建議您使用其他格式。這是因為只支援 62 個資料值，資料的精細程度遠遠高於顯示精細程度，而值資料則會稍微減少 (不會太大，但在較大的圖表上顯示)。

請注意，如果您搭配簡易編碼使用 chds 參數，圖表上的資料元素大小不會受到影響，但所有資料點標記值都會受到影響。

語法：

chd=s:
  <series_1>
    ,...,
  <series_n>
<series_1>
字串，其中每個字元都是單一資料點，而序列序列會以半形逗號分隔。系列中的個別值不會分隔。 以下是支援的資料字元及其對應的值：
  • A—Z，其中 A = 0，B = 1，依此類推，到 Z = 25
  • a—z，其中 a = 26，b = 27，依此類推，到 z = 51
  • 0(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,217
chd=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 = 25
  • Aa = 26，Ab = 27，依此類推至 Az = 51
  • A0 = 52，A1 = 53，依此類推，A9 = 61
  • A- = 62，A. = 63
  • BA = 64，BB = 65，依此類推，BZ = 89
  • Ba = 90，Bb = 91，依此類推，Bz = 115
  • B0 = 116，B1 = 117，依此類推，B9 = 125
  • B- = 126，B. = 127
  • 9A = 3904，9B = 3905，依此類推，9Z = 3929
  • 9a = 3930，9b = 3931，依此類推，9z = 3955
  • 90 = 3956，91 = 3957，依此類推，99 = 3965
  • 9- = 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 (chd=t:100)

格式範圍：0-100

100 表示以 100/100 表示。

值 100 (chd=t:100, chds=0,200)

格式範圍：0-200

100 代表以 100/200 表示比例顯示。

值：100 (chd=e:Bk)

格式範圍：0 至 4095

100 表示以 100/4095 表示，向上擴充為。

如要根據圖表調整資料規模，最簡單的方式就是使用文字格式搭配縮放。更複雜的方法是手動調整資料規模，讓資料符合格式支援的範圍。

圓餅圖和文氏圖：使用圓餅圖和文氏圖時，所有值都是相對的，而不是圖表的總比例。

chd=e:BkDIEs chd=t:100,200,300
chds=0,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) 的三張圖表，但格式和軸尺度不同：

簡易編碼，無軸縮放 簡易編碼、縮放軸 基本文字、無軸縮放

chd=s:Paz9
 

簡易編碼值範圍：0 至 61

預設軸範圍 (0-100)

編碼範圍小於標籤軸範圍，因此長條不會對應軸標籤上的實際值。但長條之間會正確成比例。

chd=s:Paz9
    chxr=0,0,61,10

簡易編碼值範圍：0 至 61

軸範圍明確設為 0-61

編碼範圍和軸範圍相等，因此長條會對應軸的正確值。

chd=t:15,26,51,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);

返回頁首