DataTables 和 DataViews

本資訊頁面說明圖表使用的內部資料表示法、用於將資料傳遞至圖表的 DataTable 和 DataView 類別，以及將 DataTable 執行個體化及填入的各種方式。

目錄

1. 圖表如何呈現資料
2. 我的圖表會使用哪些資料表結構定義？
3. DataTables 與 DataViews
4. 建立及填入資料表
   1. 建立新的 DataTable，然後呼叫 addColumn()/addRows()/addRow()/setCell()
   2. arrayToDataTable()
   3. JavaScript 常值初始化器
   4. 傳送資料來源查詢
5. dataTableToCsv()
6. 更多資訊

如何在圖表中呈現資料

所有圖表都會將資料儲存在資料表中。以下是已填入兩欄資料表的簡化示意圖：

index: 0 type: string label: 'Task'	index: 1 type: number label: 'Hours per day'
「公司」	11
「用餐」	2
「通勤」	2
「看電視」	2
「睡眠」	7

資料會儲存在以 (row、column) 參照的儲存格中，其中 row 是零資料列資料列索引，column 則是零元資料欄索引或您指定的專屬 ID。

以下是支援資料表支援的元素和屬性的完整清單，請參閱「建構函式的 JavaScript 常值參數格式」一文：

• 表格 - 由欄和列組成的陣列，以及可指派的任意名稱/值組合的選擇性對應。圖表目前未使用表格層級屬性。
• 欄 - 每個欄都支援必要的資料類型，以及選用的字串標籤、ID、模式，以及任意名稱/值屬性的對應。這個標籤是容易使用的字串，可顯示在圖表上；ID 為選用的欄，可用來取代資料欄索引。在程式碼中，資料欄可由零索引或選用 ID 參照。如需支援的資料類型清單，請參閱 DataTable.addColumn()。
• 列 - 資料列是儲存格陣列，可供指定任意名稱/值的組合 (選擇性)。
• 儲存格 - 每個儲存格都是一個物件，內含特定欄類型的實際值，以及所提供的字串格式 (選用) 值。例如：數值欄可能會指派 7 這個值，而格式化值則是「7」。 如果系統提供格式化值，圖表就會使用實際值進行計算和轉譯，但可能會視情況顯示格式化值，例如使用者將滑鼠遊標移到特定點時。每個儲存格也都有選擇性名稱/值組合的選用對應。

我的圖表會使用哪些資料表結構定義？

不同的圖表使用不同格式的表格：例如，圓餅圖預期包含兩欄表格，其中含有字串欄和數字欄，每列說明一個片段，第一欄則是切片標籤，第二欄則是切片值。但散佈圖應該是一個由兩個數值欄組成的資料表，其中每列都是一個點，而兩欄則是該點的 X 和 Y 值。請參閱圖表的說明文件，瞭解所需資料格式。

DataTables 和 DataView

在 JavaScript 中，DataTable 物件或 DataView 物件會以圖表呈現圖表資料表。在某些情況下，您可能會看到資料使用的 JavaScript 常值或 JSON 版本，例如透過 Chart Tools Datasource 透過網際網路傳送資料，或做為 ChartWrapper 的可能輸入值。

DataTable 是用於建立原始資料表。DataView 是一種便利類別，可提供 DataTable 的唯讀檢視畫面，並能在不修改連結的原始原始資料的情況下快速隱藏或重新排序資料列或資料欄。以下是這兩個類別的簡短比較：

資料表	資料檢視
讀取/寫入	唯讀
可以留空，然後填入	是現有 DataTable 的參照。無法從頭開始填入；必須使用現有 DataTable 的參照來執行個體化。
資料會佔用儲存空間。	資料是現有 DataTable 的參照，不會耗用空間。
可新增/編輯/刪除資料列、資料欄和資料，且所有變更都是永久性的。	可以在不修改基礎資料的情況下排序或篩選資料列。列和欄可以隱藏及顯示。
可複製	可傳回 DataTable 版本的檢視畫面
是來源資料，不包含參照	即時參照 DataTable；DataTable 資料中的任何變更都會立即反映在檢視畫面中。
可當做資料來源傳入圖表	可當做資料來源傳入圖表
不支援計算結果欄	支援計算資料欄，也就是合併或操控其他資料欄即時計算的值。
沒有隱藏列或欄	可隱藏或顯示所選資料欄

建立並填入 DataTable

建立並填入 DataTable 的方法有很多種：

• 建立新的 DataTable，然後呼叫 addColumn()/addRows()/addRow()/setCell()
• arrayToDataTable()
• JavaScript 常值初始化器
• 傳送資料來源查詢

空白的 DataTable + addColumn()/addRows()/addRow()/setCell()

步驟：

1. 將新的 DataTable 執行個體化
2. 新增欄
3. 新增一或多個資料列，可選擇填入資料。您可以新增空白列，之後再填入資料。你可以新增或移除其他資料列，也可以個別編輯儲存格值。

優點：

• 您可以指定每個資料欄的資料類型和標籤。
• 適合在瀏覽器中產生資料表，且使用 JSON 常值方法不容易錯字。

缺點：

• 當在網路伺服器上產生網頁時，建立 JSON 文字字串以傳送至 DataTable 建構函式並不實用。
• 視瀏覽器的速度而定，速度可能比大型資料表 (約 1,000 個以上的儲存格) 的 JSON 文字字串慢。

例如：

以下舉幾個例子來運用不同技巧，來建立相同的資料表：

// ------- Version 1------------
// Add rows + data at the same time
// -----------------------------
var data = new google.visualization.DataTable();

// Declare columns
data.addColumn('string', 'Employee Name');
data.addColumn('datetime', 'Hire Date');

// Add data.
data.addRows([
  ['Mike', {v:new Date(2008,1,28), f:'February 28, 2008'}], // Example of specifying actual and formatted values.
  ['Bob', new Date(2007,5,1)],                              // More typically this would be done using a
  ['Alice', new Date(2006,7,16)],                           // formatter.
  ['Frank', new Date(2007,11,28)],
  ['Floyd', new Date(2005,3,13)],
  ['Fritz', new Date(2011,6,1)]
]);



// ------- Version 2------------
// Add empty rows, then populate
// -----------------------------
var data = new google.visualization.DataTable();
  // Add columns
  data.addColumn('string', 'Employee Name');
  data.addColumn('date', 'Start Date');

  // Add empty rows
  data.addRows(6);
  data.setCell(0, 0, 'Mike');
  data.setCell(0, 1, {v:new Date(2008,1,28), f:'February 28, 2008'});
  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));

ArrayToDataTable()

這個輔助函式會使用單一呼叫建立和填入 DataTable。

優點：

• 在瀏覽器中執行簡單且容易理解的程式碼。
• 您可以明確指定每個資料欄的資料類型，或讓 Google 圖表根據傳入的資料推斷類型。
  • 如要明確指定資料欄的資料類型，請在標頭列中使用 type 屬性指定物件。
  • 如要讓 Google 圖表推論出類型，請使用字串做為資料欄標籤。

例如：

var data = google.visualization.arrayToDataTable([
       ['Employee Name', 'Salary'],
       ['Mike', {v:22500, f:'22,500'}], // Format as "22,500".
       ['Bob', 35000],
       ['Alice', 44000],
       ['Frank', 27000],
       ['Floyd', 92000],
       ['Fritz', 18500]
      ],
      false); // 'false' means that the first row contains labels, not data.

var data = google.visualization.arrayToDataTable([
       [ {label: 'Year', id: 'year'},
         {label: 'Sales', id: 'Sales', type: 'number'}, // Use object notation to explicitly specify the data type.
         {label: 'Expenses', id: 'Expenses', type: 'number'} ],
       ['2014', 1000, 400],
       ['2015', 1170, 460],
       ['2016', 660, 1120],
       ['2017', 1030, 540]]);

JavaScript 文字初始化器

您可以將 JavaScript 常值物件傳送至您的表格建構函式，定義資料表結構定義，也可以視需要選擇資料。

優點：

• 在網路伺服器上產生資料時相當實用。
• 處理速度較大型資料表 (約 1,000 個以上的儲存格) 的速度更快

缺點：

• 語法並非易用，且容易出現錯字。
• 程式碼不易閱讀。
• 和 JSON 稍微相似但不完全相同。

範例：

var data = new google.visualization.DataTable(
   {
     cols: [{id: 'task', label: 'Employee Name', type: 'string'},
            {id: 'startDate', label: 'Start Date', type: 'date'}],
     rows: [{c:[{v: 'Mike'}, {v: new Date(2008, 1, 28), f:'February 28, 2008'}]},
            {c:[{v: 'Bob'}, {v: new Date(2007, 5, 1)}]},
            {c:[{v: 'Alice'}, {v: new Date(2006, 7, 16)}]},
            {c:[{v: 'Frank'}, {v: new Date(2007, 11, 28)}]},
            {c:[{v: 'Floyd'}, {v: new Date(2005, 3, 13)}]},
            {c:[{v: 'Fritz'}, {v: new Date(2011, 6, 1)}]}
           ]
   }
)

傳送資料來源查詢

當您傳送查詢到圖表工具資料來源時，成功回覆是 DataTable 執行個體。傳回後，這個資料資料表可以複製、修改或複製到 DataView，方法和任何其他 DataTable 相同。

function drawVisualization() {
    var query = new google.visualization.Query(
        'http://spreadsheets.google.com/tq?key=pCQbetd-CptGXxxQIG7VFIQ&pub=1');

    // Apply query language statement.
    query.setQuery('SELECT A,D WHERE D > 100 ORDER BY D');
    
    // Send the query with a callback function.
    query.send(handleQueryResponse);
  }

  function handleQueryResponse(response) {
    if (response.isError()) {
      alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage());
      return;
    }

    var data = response.getDataTable();
    visualization = new google.visualization.LineChart(document.getElementById('visualization'));
    visualization.draw(data, {legend: 'bottom'});
  }

dataTableToCsv()

輔助函式 google.visualization.dataTableToCsv(data) 會傳回包含資料表資料的 CSV 字串。

這個函式的輸入內容可以是 DataTable 或 DataView。

並採用儲存格的格式化值。系統會忽略資料欄研究室。

系統使用標準 CSV 逸出規則來逸出「,」和「\n」等特殊字元。

以下程式碼會在瀏覽器的 JavaScript 控制台中顯示

Ramanujan,1729
Gauss,5050

：

<html>
  <head>
  <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
  <script type="text/javascript">
   google.charts.load("current", {packages:['corechart']});
   google.charts.setOnLoadCallback(drawChart);
   function drawChart() {
      var data = google.visualization.arrayToDataTable([
        ['Name', 'Number'],
        ['Ramanujan', 1729],
        ['Gauss', 5050]
      ]);
    var csv = google.visualization.dataTableToCsv(data);
    console.log(csv);
  }
  </script>
  </head>
</html>

更多資訊

• 查詢圖表工具的資料來源
• DataTable JavaScript 文字語法
• DataTable 參考資料
• DataView 參考資料
• arrayToDataTable() 參考資料