DataTables 和 DataView

本頁面討論圖表使用的內部資料表示法、用於將資料傳遞至圖表的 DataTable 和 DataView 類別，以及例項化和填入 DataTable 的各種方法。

目錄

1. 圖表資料的呈現方式
2. 我的圖表使用哪種表格架構？
3. 資料表和 DataView
4. 建立並填入資料表
   1. 建立新的資料表，然後呼叫 addColumn()/addRows()/addRow()/setCell()
   2. arrayToDataTable()
   3. JavaScript 常值初始化器
   4. 傳送資料來源查詢
5. dataTableToCsv()
6. 更多資訊

資料在圖表中的呈現方式

所有圖表都會以資料表儲存資料。以下是已填入兩欄資料的表格示意圖：

index：0 type: string label: 'Task'	索引：1 類型：數字 標籤：「每天營業時間」
公司	11
用餐	2
「通勤」	2
「看電視」	2
睡眠	7

資料會儲存在參照為 (「資料列」、「資料欄」) 的儲存格中，其中「資料列」是從零開始的資料列索引，而「資料欄」是從零開始的資料欄索引，或您可以指定的唯一 ID。

下表包含更完整的表格支援元素和屬性清單，詳情請參閱「建構函式 JavaScript 常值參數格式」一節：

• 表格 - 資料欄和資料列陣列，以及可指派的任意名稱/值組合的選用對應。圖表目前沒有使用表格層級的屬性。
• 資料欄 - 每個資料欄都支援必要資料類型，以及選用的字串標籤、ID、模式，以及任意名稱/值屬性的對應。標籤是一種容易在圖表中顯示的字串，可以用這個 ID 取代欄索引。資料欄可以在程式碼中由 0 開始的索引參照，或由選用 ID 參照。如需支援的資料類型清單，請參閱 DataTable.addColumn()。
• 列 - 列是儲存格陣列，以及可指派任意名稱/值組合的選用對應。
• 儲存格 - 每個儲存格都是一個物件，內含欄類型的實際值，以及選填的字串格式版本。舉例來說，數值欄的值可能是 7，格式化值則為「seven」。 如果提供格式化值，圖表會使用實際值進行計算和算繪，但也可能在適當的情況下顯示格式化值，例如使用者將遊標懸停在某個點上時。每個儲存格中也有可選的任意名稱/值組合對應選項。

我的圖表使用哪種表格架構？

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

DataTables 和 DataView

圖表資料表是以 DataTable 物件或 DataView 物件表示，以 JavaScript 表示。在某些情況下，您可能會看到 DataTable 的 JavaScript 常值或 JSON 版本。舉例來說，當資料是由圖表工具的資料來源透過網際網路傳送時，或可能是 ChartWrapper 可能的輸入值。

DataTable 是用來建立原始資料表。DataView 是一種便利類別，可提供 DataTable 的唯讀檢視畫面，並具備快速隱藏或重新排序列或資料欄的方法，而不必修改連結的原始資料。 以下是這兩個類別的簡要比較：

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

建立並填入資料表

建立及填入資料表的方法有很多種：

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

Empty 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 執行個體。 這些傳回的 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。

它會使用儲存格的格式化值。會忽略欄標籤。

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

下列程式碼將會在瀏覽器的 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>

更多資訊

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