本頁面由 Cloud Translation API 翻譯而成。

控制項和資訊主頁

本頁將說明如何將多個圖表合併至資訊主頁，並讓使用者能控管要顯示哪些資料。

簡介

資訊主頁可讓您輕鬆整理及管理使用相同基礎資料的多個圖表。使用本頁所述的 API，您可以免除接線的負擔，並協調資訊主頁中的所有圖表。

使用 google.visualization.Dashboard 類別定義資訊主頁。Dashboard 執行個體會收到一個內含資料的 DataTable，用來繪製及處理繪圖，並將資料發布至資訊主頁的所有圖表。

「控制項」是使用者介面小工具 (例如類別挑選器、範圍滑桿、自動完成器等)，與您互動時，可推動資訊主頁管理的資料及當中的圖表。

使用 google.visualization.ControlWrapper 類別定義控制項。您可在資訊主頁中加入 ControlWrapper 執行個體，其在管線系統中的行為與管道和閥子等。這類元件會收集使用者輸入內容，並運用資訊判斷資訊主頁應管理哪些資料，並提供給其中的圖表。

請看以下範例，使用類別挑選器和範圍滑桿，透過圓餅圖呈現資料。

注意：資訊主頁具有互動性，請嘗試執行控制項，並即時查看圖表變化。

使用控制項和資訊主頁

以下為建立資訊主頁並嵌入網頁的重要步驟。下方提供程式碼片段，說明下列所有步驟，並列出每個步驟的詳細資訊。

為資訊主頁建立 HTML 架構。 您網頁所需的 HTML 元素數量必須不限，才能存放資訊主頁的所有成員。包括資訊主頁本身及其中所有控制項和圖表。一般來說，您必須為每個元素使用 <div>。
載入程式庫。資訊主頁只需要在網頁中納入或載入兩個程式庫：Google AJAX API 以及 Google 視覺化 controls 套件。
準備資料。您必須準備資料以視覺化方式呈現，也就是說，您必須自行在程式碼中指定資料，或是向遠端網站查詢資料。
建立資訊主頁執行個體。呼叫其建構函式並將參照傳遞至要保留資訊主頁的 <div> 元素，藉此將資訊主頁執行個體化。
視需求建立多個控制項和圖表執行個體。建立 google.visualization.ChartWrapper 和 google.visualization.ControlWrapper 執行個體，以說明資訊主頁管理的每個圖表和控制項。
建立依附元件。在資訊主頁中呼叫 bind()，並傳入控制和圖表執行個體，讓資訊主頁知道要管理哪些項目。一旦控制項與圖表繫結在一起，資訊主頁就會更新圖表，以符合控制項對資料強制執行的限制。
繪製資訊主頁。在資訊主頁上呼叫 draw() 並傳遞資料，即可在網頁上繪製整個資訊主頁。
繪圖後進行程式輔助變更： 您可以選擇在初始繪圖後透過程式驅動資訊主頁中的控制項，並讓資訊主頁據此更新圖表。

以下網頁範例建立了簡單的資訊主頁，這個資訊主頁內含一個範圍滑桿，可代表圓餅圖。產生的資訊主頁會顯示在程式碼片段下方。

<html>
  <head>
    <!--Load the AJAX API-->
    <script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
    <script type="text/javascript">

      // Load the Visualization API and the controls package.
      google.charts.load('current', {'packages':['corechart', 'controls']});

      // Set a callback to run when the Google Visualization API is loaded.
      google.charts.setOnLoadCallback(drawDashboard);

      // Callback that creates and populates a data table,
      // instantiates a dashboard, a range slider and a pie chart,
      // passes in the data and draws it.
      function drawDashboard() {

        // Create our data table.
        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        // Create a dashboard.
        var dashboard = new google.visualization.Dashboard(
            document.getElementById('dashboard_div'));

        // Create a range slider, passing some options
        var donutRangeSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'filter_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten'
          }
        });

        // Create a pie chart, passing some options
        var pieChart = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'pieSliceText': 'value',
            'legend': 'right'
          }
        });

        // Establish dependencies, declaring that 'filter' drives 'pieChart',
        // so that the pie chart will only display entries that are let through
        // given the chosen slider range.
        dashboard.bind(donutRangeSlider, pieChart);

        // Draw the dashboard.
        dashboard.draw(data);
      }
    </script>
  </head>

  <body>
    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>
  </body>
</html>

以下是程式碼的資訊主頁。

1. 為資訊主頁建立 HTML 骨架

您的網頁必須包含太多 HTML 元素 (通常是 <div>)，才能保存資訊主頁本身以及其中所有的控制項和圖表。將資訊主頁、控制項和圖表執行個體執行個體化時，您必須將參照的元素傳遞至其元素，因此請為各個 HTML 元素指派 ID。

    <!--Div that will hold the dashboard-->
    <div id="dashboard_div">
      <!--Divs that will hold each control and chart-->
      <div id="filter_div"></div>
      <div id="chart_div"></div>
    </div>

您可以隨心所欲地放置每個 HTML 元素，

2. 載入程式庫

資訊主頁只需要在網頁中納入或載入兩個程式庫：Google AJAX API 以及 Google 視覺化 controls 套件。API (特別是 google.visualization.ChartWrapper) 會自動識別所需的其他套件 (例如使用「Guge 圖表」時，則會使用 gauge)，而且會即時載入這些套件，不需要再另行介入處理。

您必須使用 google.charts.load() 擷取控制資料庫。

<!--Load the AJAX API-->
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<script type="text/javascript">

  // Load the Visualization API and the controls package.
  // Packages for all the other charts you need will be loaded
  // automatically by the system.
  google.charts.load('current', {'packages':['corechart', 'controls']});

  // Set a callback to run when the Google Visualization API is loaded.
  google.charts.setOnLoadCallback(drawDashboard);

  function drawDashboard() {
    // Everything is loaded. Assemble your dashboard...
  }
</script>

3. 準備資料

載入視覺化 API 後，google.charts.setOnLoadCallback() 會呼叫您的處理常式函式，讓您知道所有必要的輔助方法和類別已準備就緒，可以開始準備您的資料。

資訊主頁可接受與資料表中相同的資料，

4. 建立資訊主頁執行個體

建立資料之後，您可以將資訊主頁物件執行個體化。資訊主頁建構函式會採用一個參數：參照用於繪製資訊主頁的 DOM 元素。

  var dashboard = new google.visualization.Dashboard(document.getElementById('dashboard_div'));

資訊主頁將以 JavaScript 類別的形式顯示。將資訊主頁執行個體化後，您可以執行幾個選用步驟，例如新增事件監聽器，例如在資訊主頁準備就緒時接收通知。資訊主頁處理事件的方式與圖表相同，詳情請參閱「處理視覺化事件」或「圖表顯示錯誤」一節。

5. 建立控制與圖表執行個體

定義要納入資訊主頁的每個控制項和圖表所需的執行個體數量。分別使用 google.visualization.ChartWrapper 和 google.visualization.ControlWrapper 分別定義圖表和控制項。

  // Create a range slider, passing some options
  var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten'
    }
  });

  // Create a pie chart, passing some options
  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'pieSliceText': 'label'
    }
  });

建立 ChartWrapper 和 ControlWrapper 執行個體時，請勿指定 dataTable 或 dataSourceUrl 參數。資訊主頁會透過適當的資料為每一個動態饋給提供資料。不過，請務必指定必要的參數：圖表的 chartType 和 containerId，以及控制項的 controlType 和 containerId。

設定控制項和圖表的幾個訣竅：

您必須向所有控制項提供 filterColumnIndex (或 filterColumnLabel) 來指定該控制項用於 google.visualization.DataTable 的哪個資料欄 (在上例中，控制項是在標示為「Donuts eaten」的資料欄上執行)，

第一次使用控制項時，請使用控制項上的 state 設定選項，以明確狀態初始化這些控制項。例如，您可以利用這項設定來修正範圍滑桿控制項「不喜歡」的初始位置。

  var donutRangeSlider = new google.visualization.ControlWrapper({
    'controlType': 'NumberRangeFilter',
    'containerId': 'filter_div',
    'options': {
      'filterColumnLabel': 'Donuts eaten',
      'minValue': 1,
      'maxValue': 10
    },
    // Explicitly positions the thumbs at position 3 and 8,
    // out of the possible range of 1 to 10.
    'state': {'lowValue': 3, 'highValue': 8}
  });

資訊主頁內的所有圖表都會使用您在準備資料步驟中準備的基準資料表。不過，圖表通常需要使用特定的資料欄排列方式才能正確顯示資料。舉例來說，圓餅圖需要標籤字串欄，然後再加上值的數字欄。

設定每個 ChartWrapper 執行個體時，請使用 view 選項來宣告與圖表相關的資料欄，如以下範例所示。

  var data = google.visualization.arrayToDataTable([
    ['Name', 'Gender', 'Age', 'Donuts eaten'],
    ['Michael' , 'Male', 12, 5],
    ['Elisa', 'Female', 20, 7],
    ['Robert', 'Male', 7, 3],
    ['John', 'Male', 54, 2],
    ['Jessica', 'Female', 22, 6],
    ['Aaron', 'Male', 3, 1],
    ['Margareth', 'Female', 42, 8]
  ]);

  var pieChart = new google.visualization.ChartWrapper({
    'chartType': 'PieChart',
    'containerId': 'chart_div',
    'options': {
      'width': 300,
      'height': 300,
      'title': 'Donuts eaten per person'
    },
    // The pie chart will use the columns 'Name' and 'Donuts eaten'
    // out of all the available ones.
    'view': {'columns': [0, 3]}
  });

  // The rest of dashboard configuration follows
  // ...

6. 建立依附元件

將資訊主頁以及所有即將納入資訊主頁的控制項與圖表執行個體化之後，請使用 bind() 方法告知資訊主頁，控制項與圖表之間存在相依關係。

一旦控制項與圖表繫結在一起，資訊主頁就會更新圖表，以符合控制項對資料強制執行的限制。在您正在建構的樣本資訊主頁中，範圍滑桿和圓餅圖會繫結在一起，因此每次與舊版互動時，後者都會更新以顯示符合所選範圍的資料。

  // 'pieChart' will update whenever you interact with 'donutRangeSlider'
  // to match the selected range.
  dashboard.bind(donutRangeSlider, pieChart);

您可以在多種不同設定中繫結控制項和圖表，包括一對一、一對一、多對多、多對多。只要將多個控制項繫結至圖表，資訊主頁就會更新圖表，以符合所有繫結控制項強制執行的合併限制。同時，一個控制項可同時產生多個圖表。如要同時指定多個繫結，請將陣列傳入 bind() 方法，而非單一執行個體。您也可以將多個 bind() 呼叫鏈結在一起。以下舉幾個例子說明。

  // Many-to-one binding where 'ageSelector' and 'salarySelector' concurrently
  // participate in selecting which data 'ageVsSalaryScatterPlot' visualizes.
  dashboard.bind([agePicker, salaryPicker], ageVsSalaryScatterPlot);

  // One-to-many binding where 'ageSelector' drives two charts.
  dashboard.bind(agePicker, [ageVsSalaryScatterPlot, ageBarChart]);

  // bind() chaining where each control drives its own chart.
  dashboard.bind(agePicker, ageBarChart).bind(salaryRangePicker, salaryPieChart);

若是進階用途，您也可以將控制項繫結至其他控制項，藉此建立依附元件鏈結。

  dashboard.bind(countryPicker, regionPicker).bind(regionPicker, cityPicker);

7. 繪製數字面板

呼叫資訊主頁執行個體上的 draw() 方法，以顯示整個資訊主頁。draw() 方法只接受一個參數：為資訊主頁提供支援的 DataTable (或 DataView)。

每當您變更資訊主頁的組合 (例如在資訊主頁中新增控制項或圖表) 時，都應呼叫 draw()，或者變更採用整個系統的 DataTable。

每當 draw() 終止繪製所有控制項和圖表時，資訊主頁執行個體就會啟動 ready 事件。如果有任何受到管理的控制項或圖表失敗，就會觸發 error 事件。如要進一步瞭解如何處理事件，請參閱處理事件一文。

注意：在嘗試變更資訊主頁組合或再次繪製之前，您應該先監聽 ready 事件。

8. 繪圖後的程式輔助變更

資訊主頁完成初始 draw() 後會「即時」，並自動回應您在其上執行的任何動作 (例如，變更資訊主頁中某個控制滑桿的所選範圍)。

如果需要以程式輔助方式更改資訊主頁的狀態，可以直接在其所在的 ControlWrapper 和 ChartWrapper 執行個體上運作。原則上，您需要直接對特定 ControlWrapper (或 ChartWrapper) 執行個體執行任何需要的變更，例如透過 setOption() 和 setState() 分別變更控制選項或狀態，然後呼叫其 draw() 方法。資訊主頁隨即會配合要求的變更進行更新。

以下是這類案件的範例。

google.charts.load('current', {'packages':['corechart', 'controls']});
      google.charts.setOnLoadCallback(drawStuff);

function drawStuff() {

var dashboard = new google.visualization.Dashboard(
          document.getElementById('programmatic_dashboard_div'));

// We omit "var" so that programmaticSlider is visible to changeRange.
        var programmaticSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'programmatic_control_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten',
            'ui': {'labelStacking': 'vertical'}
          }
        });

var programmaticChart  = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'programmatic_chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'legend': 'none',
            'chartArea': {'left': 15, 'top': 15, 'right': 0, 'bottom': 0},
            'pieSliceText': 'value'
          }
        });

var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

dashboard.bind(programmaticSlider, programmaticChart);
        dashboard.draw(data);

changeRange = function() {
          programmaticSlider.setState({'lowValue': 2, 'highValue': 5});
          programmaticSlider.draw();
        };

changeOptions = function() {
          programmaticChart.setOption('is3D', true);
          programmaticChart.draw();
        };
      }

完整網頁

<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', 'controls']});
      google.charts.setOnLoadCallback(drawStuff);

      function drawStuff() {

        var dashboard = new google.visualization.Dashboard(
          document.getElementById('programmatic_dashboard_div'));

        // We omit "var" so that programmaticSlider is visible to changeRange.
        var programmaticSlider = new google.visualization.ControlWrapper({
          'controlType': 'NumberRangeFilter',
          'containerId': 'programmatic_control_div',
          'options': {
            'filterColumnLabel': 'Donuts eaten',
            'ui': {'labelStacking': 'vertical'}
          }
        });

        var programmaticChart  = new google.visualization.ChartWrapper({
          'chartType': 'PieChart',
          'containerId': 'programmatic_chart_div',
          'options': {
            'width': 300,
            'height': 300,
            'legend': 'none',
            'chartArea': {'left': 15, 'top': 15, 'right': 0, 'bottom': 0},
            'pieSliceText': 'value'
          }
        });

        var data = google.visualization.arrayToDataTable([
          ['Name', 'Donuts eaten'],
          ['Michael' , 5],
          ['Elisa', 7],
          ['Robert', 3],
          ['John', 2],
          ['Jessica', 6],
          ['Aaron', 1],
          ['Margareth', 8]
        ]);

        dashboard.bind(programmaticSlider, programmaticChart);
        dashboard.draw(data);

        changeRange = function() {
          programmaticSlider.setState({'lowValue': 2, 'highValue': 5});
          programmaticSlider.draw();
        };

        changeOptions = function() {
          programmaticChart.setOption('is3D', true);
          programmaticChart.draw();
        };
      }

    </script>
  </head>
  <body>
    <div id="programmatic_dashboard_div" style="border: 1px solid #ccc">
      <table class="columns">
        <tr>
          <td>
            <div id="programmatic_control_div" style="padding-left: 2em; min-width: 250px"></div>
            <div>
              <button style="margin: 1em 1em 1em 2em" onclick="changeRange();">
                Select range [2, 5]
              </button><br />
              <button style="margin: 1em 1em 1em 2em" onclick="changeOptions();">
                Make the pie chart 3D
              </button>
            </div>
          </td>
          <td>
            <div id="programmatic_chart_div"></div>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>

API 參考資料

本節列出由 Control 和 Dashboards API 公開的物件，以及所有控制項公開的標準方法。

資訊主頁

代表能共用相同基礎資料的協同合作控制項和圖表集合。

建構函式

Dashboard(containerRef)

containerRef。
: 參照網頁中容器元素的有效容器元素。

方法

資訊主頁提供下列方法：

方法傳回類型說明

方法	傳回類型	說明
`bind(controls, charts)`	google.visualization.Dashboard	將一或多個「控制項」繫結至一或多位其他資訊主頁參與者 (圖表或其他控制項)，這樣當前任何人員收集程式輔助或使用者互動時，就會重新繪製資訊主頁管理的資料。傳回資訊主頁執行個體本身，用於將多個 `bind()` 呼叫鏈結在一起。 controls - 定義要繫結的控制項的單一或 `google.visualization.ControlWrapper` 執行個體陣列。圖表：單一圖表或 `google.visualization.ChartWrapper` 例項陣列，用於定義圖表將由控制項驅動的圖表。
`draw(dataTable)`	無	繪製資訊主頁。 dataTable - 下列任一，包括 `DataTable` 物件、`DataView` 物件、DataTable 的 JSON 表示法，或符合 google.visualization.arrayToDataTable() 語法的陣列。
`getSelection()`	物件陣列	傳回資訊主頁中圖表的選定視覺實體。透過資訊主頁呼叫 `getSelection()` 方法時，系統會針對其內所有圖表的所有選取項目傳回匯總，以便在處理圖表選項時使用單一參照。注意：所選事件的事件監聽器仍必須附加至您要監聽的每個圖表。擴充說明

bind(controls, charts)

google.visualization.Dashboard

將一或多個「控制項」繫結至一或多位其他資訊主頁參與者 (圖表或其他控制項)，這樣當前任何人員收集程式輔助或使用者互動時，就會重新繪製資訊主頁管理的資料。傳回資訊主頁執行個體本身，用於將多個 bind() 呼叫鏈結在一起。

controls - 定義要繫結的控制項的單一或 google.visualization.ControlWrapper 執行個體陣列。
圖表：單一圖表或 google.visualization.ChartWrapper 例項陣列，用於定義圖表將由控制項驅動的圖表。

draw(dataTable)

無

繪製資訊主頁。

dataTable - 下列任一，包括 DataTable 物件、DataView 物件、DataTable 的 JSON 表示法，或符合 google.visualization.arrayToDataTable() 語法的陣列。

getSelection()

物件陣列

傳回資訊主頁中圖表的選定視覺實體。透過資訊主頁呼叫 getSelection() 方法時，系統會針對其內所有圖表的所有選取項目傳回匯總，以便在處理圖表選項時使用單一參照。

注意：所選事件的事件監聽器仍必須附加至您要監聽的每個圖表。

擴充說明

活動

資訊主頁物件會擲回下列事件。請注意，您必須先呼叫 Dashboard.draw()，才能擲回任何事件。

名稱說明屬性

error 嘗試顯示資訊主頁時發生錯誤。資訊主頁中的一或多個控制項和圖表可能無法轉譯。 id、message

名稱	說明	屬性
`error`	嘗試顯示資訊主頁時發生錯誤。資訊主頁中的一或多個控制項和圖表可能無法轉譯。	id、message
`ready`	資訊主頁已完成繪圖，可開始接受變更。資訊主頁中的所有控制項和圖表都可以用於外部方法呼叫和使用者互動。如果您想在繪製資訊主頁後變更資訊主頁 (或顯示的資料)，請在呼叫 `draw` 方法「之前」先為這個事件設定事件監聽器，並且只在事件觸發後套用變更。 `ready` 事件也會觸發：使用者重新整理資訊主頁的操作後，或以程式輔助方式與其中一個控制項互動後，對程式輔助中任何圖表部分的 `draw()` 方法進行程式輔助呼叫之後。	無

ready

資訊主頁已完成繪圖，可開始接受變更。資訊主頁中的所有控制項和圖表都可以用於外部方法呼叫和使用者互動。如果您想在繪製資訊主頁後變更資訊主頁 (或顯示的資料)，請在呼叫 draw 方法「之前」先為這個事件設定事件監聽器，並且只在事件觸發後套用變更。

ready 事件也會觸發：

使用者重新整理資訊主頁的操作後，或以程式輔助方式與其中一個控制項互動後，
對程式輔助中任何圖表部分的 draw() 方法進行程式輔助呼叫之後。

無

ControlWrapper

ControlWrapper 物件是所配置控制執行個體的 JSON 表示法的包裝函式。這個類別會顯示便利的方法來定義資訊主頁的控制項、繪製控制項，並以程式輔助方式變更其狀態。

建構函式

ControlWrapper(opt_spec)

opt_spec: [選用] - 定義定義物件的 JSON 物件，或該物件的序列化字串版本。JSON 物件的支援屬性如下表所示。如未指定，您必須使用 ControlWrapper 公開的 set... 方法設定所有適用的屬性。

屬性	類型	必填	預設	說明
ControlType	字串	必填	無	控制項的類別名稱。如果是 Google 控制項，您可以省略 `google.visualization` 套件名稱。範例：`CategoryFilter`、`NumberRangeFilter`。
容器 ID	字串	必填	無	您網頁上會代管控制項的 DOM 元素 ID。
選項	物件	選用	無	說明控制項的選項的物件。您可以使用 JavaScript 文字標記法，或提供物件控制代碼。範例： `"options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}`
州	物件	選用	無	說明控制項狀態的物件。狀態會收集使用者操作控制項可能影響的所有變數。舉例來說，範圍滑桿的狀態可透過滑桿的低和高大的座標表示。您可以使用 JavaScript 常值標記法，或提供物件控制代碼。範例：`"state": {"lowValue": 20, "highValue": 50}`

方法

ControlWrapper 提供下列其他方法：

方法	傳回類型	說明
`draw()`	無	繪製控制項。一般而言，控制控制項的資訊主頁會負責繪製其。變更任何其他設定 (例如選項或狀態) 之後，您應該呼叫 `draw()` 以強制透過程式輔助重繪控制項。
`toJSON()`	字串	傳回控制項的 JSON 表示法字串版本。
`clone()`	ControlWrapper	傳回控制包裝函式的深度複本。
`getControlType()`	字串	控制項的類別名稱。如果這是 Google 控管項目，則名稱不會與 `google.visualization` 相容。舉例來說，如果這是「CategoryFilter」控制項，則會傳回「CategoryFilter」，而不是「google.visualization.CategoryFilter」。
`getControlName()`	字串	傳回 `setControlName()` 指派的控制名稱。
`getControl()`	控制物件參照	傳回此 ControlWrapper 所建立之控制項的參照。此方法會傳回空值，直到您在 ControlWrapper 物件 (或保留該物件的資訊主頁) 上呼叫 `draw()` 之後，否則會擲回就緒的事件。傳回的物件只會提供一個方法：`resetControl()`，該方法會將控制狀態重設為其初始化時 (例如重設 HTML 表單元素)。
`getContainerId()`	字串	控制項的 DOM 容器元素 ID。
`getOption(key, opt_default_val)`	不限類型	傳回指定的控制選項值鍵 - 擷取選項名稱。可以是合格名稱，例如 `'vAxis.title'`。 opt_default_value [選用]：如果指定值未定義或為空值，系統會傳回此值。
`getOptions()`	物件	傳回此控制項的選項選項物件。
`getState()`	物件	傳回控制狀態。
`setControlType(type)`	無	設定控制項類型。傳入控制項的類別名稱，以便執行個體化。如果這是 Google 控管項目，請勿以 `google.visualization` 進行說明。例如，針對數值欄的範圍滑桿，請將「NumberRangeFilter」傳入。
`setControlName(name)`	無	為控制項設定任意名稱。這個控制項不會顯示在控制項的任一處，但僅供參考。
`setContainerId(id)`	無	設定控制項包含 DOM 元素的 ID。
`setOption(key, value)`	無	設定單一控制選項值，其中 key 為選項名稱，value 則是值。如要取消設定選項，請為該值傳入 null。請注意，key 可以是合格名稱，例如 `'vAxis.title'`。
`setOptions(options_obj)`	無	為控制項設定完整的選項物件。
`setState(state_obj)`	無	設定控制狀態。狀態會收集使用者操作控制項可能影響的所有變數。例如，範圍滑桿狀態可說明滑桿的低和高所佔的位置。

活動

ControlWrapper 物件擲回下列事件。請注意，您必須呼叫 ControlWrapper.draw() (或繪製控點的資訊主頁)，才能擲回任何事件。

名稱	說明	屬性
`error`	嘗試顯示控制項時發生錯誤。	id、message
`ready`	這個控制項已可接受使用者互動以及外部方法呼叫。如果您想要與控制項互動，並在繪製後呼叫方法，則應該在呼叫 `draw` 方法之前為此事件設定監聽器，且只有在事件觸發後呼叫。或者，您可以在資訊主頁等待 `ready` 事件，且只有在事件啟動後，您才會保有控制和呼叫控制方法。	無
`statechange`	使用者與控制項互動時觸發，影響其狀態。舉例來說，只要移動範圍滑桿的 [按讚]，系統就會觸發 `statechange` 事件。如要在事件觸發後擷取更新的控制狀態，請呼叫 `ControlWrapper.getState()`。	無

圖表 Wrapper

請參閱視覺化 API 參考資料一節中的 google.visualization.ChartWrapper 說明文件。

使用 ChartWrapper 做為資訊主頁的一部分時，適用下列注意事項：

請勿明確設定 dataTable、query、dataSourceUrl 和 refreshInterval 屬性。含有圖表的資訊主頁會負責提供所需的資料。
您應設定其 view 屬性，在資訊主頁提供的 dataTable 中，宣告哪些資料欄與圖表相關，如建立控制項和圖表執行個體所示。

控制項庫

「篩選器」是圖形元素，可供使用者以互動方式選擇要在圖表上顯示的資料。本節說明 Google 圖表篩選器：CategoryFilter、ChartRangeFilter、DateRangeFilter、NumberRangeFilter 和 StringFilter。

您可以使用任何參數做為 ControlWrapper.setControlType() 的參數。

注意：在描述選項中，點標記法可用來描述巢狀物件屬性。舉例來說，應在選項物件中宣告名為 'ui.label' 的選項，並指定為 var options = {"ui": {"label": "someLabelValue"} };。

用來在一組定義值之間選擇一或多個項目的選擇器。

狀態

名稱	類型	預設	說明
所選值	物件陣列或原始類型	無	目前選取的值組合。所選值必須是一組由 `values` 選項定義的整體可選取值 (系統會忽略任何多餘的值)。如果 `CategoryFilter` 不允許複選，系統只會保留陣列的第一個值。

選項

名稱	類型	預設	說明
filterColumnIndex	數字	無	篩選器應在哪個資料表上運作。您必須提供這個選項或 `filterColumnLabel`。如果兩者同時存在，系統會優先採用這個選項。
篩選欄標籤	string	無	篩選器應執行資料欄的標籤。您必須提供這個選項或 `filterColumnIndex`。如果兩者同時存在，系統會優先採用 `filterColumnIndex`。
values	陣列	自動	提供值清單。如果使用物件陣列，則應該具備適當的 `toString()` 表示法才能向使用者顯示。如果為空值或未定義，系統會自動根據這個控制項用於資料表的 DataTable 資料欄中的值計算值清單。
useFormattedValue	布林值	否	從 DataTable 資料欄自動選取可選取值的清單時，這個篩選器會運作，無論是使用實際的儲存格值還是格式化值。
ui	物件	空值	具有成員設定物件，用於設定控制項 UI 各個層面的物件。如要指定此物件的屬性，您可以使用物件常值標記法，如下所示： {label: 'Metric', labelSeparator: ':'}
ui.caption	string	[選擇值...]	未選取任何項目時，值選擇器小工具中顯示的說明文字。
ui.sortValues	布林值	true	是否應排序所選值。
ui.selectedValuesLayout	string	「兩側」	如何顯示多個可用選項。可能的值包括： `'aside'`：所選值會顯示在值挑選器小工具旁邊的一行文字中。 `'below'`：選取的值會顯示在小工具下方的一行文字中。 `'belowWrapping'`：與 `below` 類似，但無法在挑選器中顯示的項目則換行為新的一行， `'belowStacked'`：所選值會顯示在小工具下方的資料欄中。
ui.allowNone	布林值	true	是否允許使用者選擇任何值。如果設為 `false`，使用者必須選擇可用值中的至少一個值。在控制初始化期間，如果選項設為 `false` 且未指定 `selectedValues` 狀態，則會自動選取可選取值的第一個值。
ui.allowMultiple	布林值	true	是否可選取多個值，而不只是只能選取一個值。
ui.allowTyping	布林值	true	是否允許使用者在文字欄位中輸入文字，藉此縮小可能的選項清單 (透過自動完成功能)。
ui.label	string	自動	顯示在類別挑選器旁的標籤。如未指定，系統會使用用於控制資料欄的資料欄標籤。
ui.labelSeparator	string	無	標籤之間的分隔符字串，能以視覺化方式呈現標籤與類別挑選器。
ui.labelStacking	string	水平	標籤應顯示在類別挑選器的上方 (垂直堆疊) 或旁邊 (水平堆疊)。使用 `'vertical'` 或 `'horizontal'`。
ui.cssClass	string	「google-visualization-controls-categoryfilter」	指派給自訂 CSS 的控制項。

圖表篩選器

將兩個喜歡的疊加在圖表上的滑桿，可從圖表的連續軸中選取某個範圍的值。

狀態

名稱	類型	預設	說明
range.start	數字、日期、日期或時間	範圍起始值	所選範圍的開頭 (含首尾)。
範圍	數字、日期、日期或時間	範圍結束值	所選範圍的結尾 (含首尾)。

選項

名稱	類型	預設	說明
filterColumnIndex	數字	無	資料表在所執行資料表所使用的索引。您必須提供這個選項或 `filterColumnLabel`。如果兩者同時存在，系統會優先採用這個選項。請注意，如要指定 domain 資料欄的索引，該值會納入控制項內繪製的圖表連續軸。
篩選欄標籤	string	無	篩選條件所屬資料表的資料欄標籤。您必須提供這個選項或 `filterColumnIndex`。如果兩者同時存在，系統會優先採用 `filterColumnIndex`。請注意，如要指定 domain 資料欄的標籤，該鍵會包含於控制項內繪製的圖表的連續軸上。
ui	物件	空值	具有成員設定物件，用於設定控制項 UI 各個層面的物件。如要指定此物件的屬性，您可以使用物件常值標記法，如下所示： {chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType	string	「組合圖」	在控制項中繪製的圖表類型。可以是：「AreaChart」、「LineChart」、「ComboChart」或「ScatterChart」。
ui.chartOptions	物件	{ 'enableInteractivity': false, 'chartArea': {'height': '100%'}, 'legend': {'position': 'none'}, 'hAxis': {'textPosition': 'in'}, 'vAxis': { 'textPosition': 'none', 'gridlines': {'color': 'none'} } }	在控制項中繪製的圖表設定選項。允許與資訊主頁中的任何圖表相同的設定層級，且符合 ChartWrapper.setOptions() 可接受的格式。您可以指定其他選項或覆寫預設選項 (但請注意，為確保最佳顯示效果，系統已謹慎選擇預設值)。
ui.chartView	物件或字串 (序列化物件)	空值	要在資料控管項目中繪製圖表時使用的資料表規格。允許資訊主頁設定的任何圖表層級設定，並且符合 ChartWrapper.setView() 可接受的格式。如未指定，資料表本身就會用來繪製圖表。請注意，繪圖圖表的水平軸必須「連續」，因此請據此指定 `ui.chartView`。
ui.minRangeSize	數字	資料值差異解讀為 1 像素	可選取的範圍大小 (`range.end - range.start`)，以資料值單位為單位指定。以數字軸表示，這是數字 (不一定是整數)。以日期、日期時間或時間時間軸表示的整數，以毫秒為單位表示差異。
ui.snapToData	布林值	否	如為 true，範圍「不喜歡」會貼齊最近的資料點。在這種情況下，`getState()` 傳回範圍的終點必須是資料表中的值。

活動

ControlWrapper 事件的新增功能：

名稱	說明	屬性
`statechange`	與每個 ControlWrapper 所記錄的相同，只有額外的布林屬性 `inProgress` 可指定目前變更的狀態 (姆指之一或範圍本身是拖曳的)。	進行中

日期範圍篩選器

雙值滑桿，用於選取日期範圍。

請嘗試移動滑桿來變更下表中顯示的資料列。

狀態

名稱	類型	預設	說明
低價值	數字	無	所選範圍的較低範圍 (含首尾)。
高價值	數字	無	所選範圍中較高的範圍 (含首尾)。
LowThumbAtMin	布林值	無	滑桿的較低拇指是否鎖定在允許範圍內。如有設定，則會覆寫 `lowValue`。
HighThumbAtMax	布林值	無	滑桿的較高拇指是否鎖定在允許的最大範圍內。如有設定，則會覆寫 `highValue`。

選項

名稱	類型	預設	說明
filterColumnIndex	數字	無	篩選器應在哪個資料表上運作。您必須提供這個選項或 `filterColumnLabel`。如果兩者同時存在，系統會優先採用這個選項。必須指向類型為 `number` 的資料欄。
篩選欄標籤	string	無	篩選器應執行資料欄的標籤。您必須提供這個選項或 `filterColumnIndex`。如果兩者同時存在，系統會優先採用 `filterColumnIndex`。必須指向類型為 `number` 的資料欄。
minValue (最小值)	日期	自動	範圍下限的下限值。如未定義，則會從控管的 DataTable 內容推論這個值。
最大值	日期	自動	範圍允許的最大值。如未定義，則會從控管的 DataTable 內容推論這個值。
ui	物件	空值	具有成員設定物件，用於設定控制項 UI 各個層面的物件。如要指定此物件的屬性，您可以使用物件常值標記法，如下所示： {label: 'Age', labelSeparator: ':'}
ui.format	物件	無	如何將日期表示為字串。接受任何有效的日期格式。
ui.step	string	天	拖曳滑桿的最小可能變更：可設為「日」的任何時間單位。 (尚不支援「month」和「year」)。
ui.tick	數字	自動	滑桿可能會佔用的刻點數量 (範圍列上的固定位置)。
ui.unitIncrement	string	「1」	範圍範圍內單位增量的遞增金額。單元增量相當於使用方向鍵移動滑桿。
ui.blockIncrement	數字	10	範圍範圍內區塊增加的遞增金額。區塊增量相當於使用 pgUp 和 pgDown 鍵來移動滑桿的按讚。
ui.showRangeValues	布林值	true	是否要在滑桿上顯示所選範圍的標籤。
ui.orientation	string	水平	滑桿方向。`'horizontal'` 或 `'vertical'`。
ui.label	string	自動	滑桿旁邊的標籤。如未指定，系統會使用用於控制資料欄的資料欄標籤。
ui.labelSeparator	string	無	附加至標籤的分隔符字串，可將標籤與滑桿進行視覺區隔。
ui.labelStacking	string	水平	標籤是否應顯示在滑桿的上方 (垂直堆疊) 或旁邊 (水平堆疊)。使用 `'vertical'` 或 `'horizontal'`。
ui.cssClass	string	google-visualization-controls-rangefilter	指派給自訂 CSS 的控制項。

NumberRangeFilter

雙值滑桿，用於選取數值範圍。

狀態

名稱	類型	預設	說明
低價值	數字	無	所選範圍的較低範圍 (含首尾)。
高價值	數字	無	所選範圍中較高的範圍 (含首尾)。
LowThumbAtMin	布林值	無	滑桿的較低拇指是否鎖定在允許範圍內。如有設定，則會覆寫 `lowValue`。
HighThumbAtMax	布林值	無	滑桿的較高拇指是否鎖定在允許的最大範圍內。如有設定，則會覆寫 `highValue`。

選項

名稱	類型	預設	說明
filterColumnIndex	數字	無	篩選器應在哪個資料表上運作。您必須提供這個選項或 `filterColumnLabel`。如果兩者同時存在，系統會優先採用這個選項。必須指向類型為 `number` 的資料欄。
篩選欄標籤	string	無	篩選器應執行資料欄的標籤。您必須提供這個選項或 `filterColumnIndex`。如果兩者同時存在，系統會優先採用 `filterColumnIndex`。必須指向類型為 `number` 的資料欄。
minValue (最小值)	數字	自動	範圍下限的下限值。如未定義，則會從控管的 DataTable 內容推論這個值。
最大值	數字	自動	範圍允許的最大值。如未定義，則會從控管的 DataTable 內容推論這個值。
ui	物件	空值	具有成員設定物件，用於設定控制項 UI 各個層面的物件。如要指定此物件的屬性，您可以使用物件常值標記法，如下所示： {label: 'Age', labelSeparator: ':'}
ui.format	物件	無	如何將數字表示為字串。可接受任何有效的數字格式。
ui.step	數字	1，或由 `ticks` 計算 (如已定義)	拖曳滑桿的喜歡次數下限。
ui.tick	數字	自動	滑桿可能會佔用的刻點數量 (範圍列上的固定位置)。
ui.unitIncrement	數字	1	範圍範圍內單位增量的遞增金額。單元增量相當於使用方向鍵移動滑桿。
ui.blockIncrement	數字	10	範圍範圍內區塊增加的遞增金額。區塊增量相當於使用 pgUp 和 pgDown 鍵來移動滑桿的按讚。
ui.showRangeValues	布林值	true	是否要在滑桿上顯示所選範圍的標籤。
ui.orientation	string	水平	滑桿方向。`'horizontal'` 或 `'vertical'`。
ui.label	string	自動	滑桿旁邊的標籤。如未指定，系統會使用用於控制資料欄的資料欄標籤。
ui.labelSeparator	string	無	附加至標籤的分隔符字串，可將標籤與滑桿進行視覺區隔。
ui.labelStacking	string	水平	標籤是否應顯示在滑桿的上方 (垂直堆疊) 或旁邊 (水平堆疊)。使用 `'vertical'` 或 `'horizontal'`。
ui.cssClass	string	google-visualization-controls-rangefilter	指派給自訂 CSS 的控制項。

字串篩選器

一個簡單的文字輸入欄位，可讓您透過字串比對篩選資料。每次按下按鍵後都會更新：請試著輸入 j，將下方的資料表縮小為 John 與 Jessica。

狀態

名稱	類型	預設	說明
值	字串或物件	無	目前輸入控制項輸入欄位的文字。

選項

名稱	類型	預設	說明
filterColumnIndex	數字	無	篩選器應在哪個資料表上運作。您必須提供這個選項或 `filterColumnLabel`。如果兩者同時存在，系統會優先採用這個選項。
篩選欄標籤	string	無	篩選器應執行資料欄的標籤。您必須提供這個選項或 `filterColumnIndex`。如果兩者同時存在，系統會優先採用 `filterColumnIndex`。
比對類型	string	「前置字串」	控制項是否應完全符合確切值 (`'exact'`)、從值的開頭 (`'prefix'`) 開頭的前置字串或任何子字串 (`'any'`)。
區分大小寫	布林值	否	比對是否應區分大小寫。
useFormattedValue	布林值	否	控制項是否應與儲存格格式值相符或對應實際值。
ui	物件	空值	具有成員設定物件，用於設定控制項 UI 各個層面的物件。如要指定此物件的屬性，您可以使用物件常值標記法，如下所示： {label: 'Name', labelSeparator: ':'}
ui.realtime 觸發條件	布林值	true	是否應按下按鍵，使其只有在符合輸入欄位「變更」時 (聚焦或按下 Enter 鍵) 時才會比對。
ui.label	string	自動	顯示在輸入欄位旁邊的標籤。如未指定，系統會使用用於控制資料欄的資料欄標籤。
ui.labelSeparator	string	無	附加至標籤的分隔符字串，可將標籤與輸入欄位以視覺化方式分隔。
ui.labelStacking	string	水平	標籤應顯示在輸入欄位的上方 (垂直堆疊) 或旁邊 (水平堆疊)。使用 `'vertical'` 或 `'horizontal'`。
ui.cssClass	string	'google-visualization-controls-stringfilter'	指派給自訂 CSS 的控制項。

控制項和資訊主頁

簡介

使用控制項和資訊主頁

1. 為資訊主頁建立 HTML 骨架

2. 載入程式庫

3. 準備資料

4. 建立資訊主頁執行個體

5. 建立控制與圖表執行個體

6. 建立依附元件

7. 繪製數字面板

8. 繪圖後的程式輔助變更

API 參考資料

資訊主頁

建構函式

方法

活動

ControlWrapper

建構函式

方法

活動

圖表 Wrapper

控制項庫

類別篩選器

狀態

選項

圖表篩選器

狀態

選項

活動

日期範圍篩選器

狀態

選項

NumberRangeFilter

狀態

選項

字串篩選器

狀態

選項