控制項和資訊主頁

在這個頁面中，您將瞭解如何將多份圖表合併為資訊主頁，並讓使用者控管這些圖表顯示的資料。

總覽

資訊主頁可讓您輕鬆整理及管理多個共用相同基礎資料的圖表。使用本頁所述的 API 後，您就不必為了整合及協調資訊主頁中的所有圖表而煩惱。

資訊主頁是使用 google.visualization.Dashboard 類別定義。Dashboard 執行個體會收到 DataTable，其中包含以視覺化方式呈現資料，並負責繪圖，並將資料發布到資訊主頁的所有圖表。

控制項是與您互動的使用者介面小工具 (例如類別挑選器、範圍滑桿、自動完成工具...)，目的是驅動資訊主頁管理的資料，以及該資訊主頁所包含的圖表。

請使用 google.visualization.ControlWrapper 類別定義控制項。您可以將 ControlWrapper 執行個體新增至資訊主頁，這些執行個體在水管系統中的運作方式類似管道和閥。他們會收集使用者輸入內容，並使用資訊來決定要讓資訊主頁管理的圖表使用哪些資料。

請參閱下方範例，瞭解如何使用類別挑選器和範圍滑桿，以圓餅圖呈現資料。

注意：資訊主頁為互動式，請嘗試操作控制項，並即時查看圖表變化。

使用控制項和資訊主頁

以下是建立資訊主頁並嵌入頁面的主要步驟。您會看到示範以下所有步驟的程式碼片段，以及每個步驟的詳細資訊。

  1. 為資訊主頁建立 HTML 架構。 網頁必須包含所需的 HTML 元素數量，才能容納資訊主頁的每位成員。 包括資訊主頁本身及當中的所有控制項和圖表。一般而言，您會先針對每個類型使用 <div>。
  2. 載入程式庫。網頁只需要包含或載入兩種程式庫：Google AJAX API 和 Google 視覺化 controls 套件。
  3. 準備資料。您必須準備要以視覺化方式呈現的資料，包括自行在程式碼中指定資料，或向遠端網站查詢資料。
  4. 建立資訊主頁執行個體。呼叫資訊主頁的建構函式，然後傳入容納該資訊主頁的 <div> 元素參照，將資訊主頁例項化。
  5. 建立任意數量的控制選項和圖表執行個體。 建立 google.visualization.ChartWrapper 和 google.visualization.ControlWrapper 執行個體來描述資訊主頁管理的各個圖表及控管。
  6. 建立依附元件。在資訊主頁上呼叫 bind()，並傳入控制項和圖表執行個體，讓資訊主頁知道要管理的項目。將控制項與圖表繫結後，資訊主頁會更新圖表，以符合您對資料強制執行的限制。
  7. 繪製資訊主頁。在資訊主頁上呼叫 draw() 並傳入資料，即可在頁面上繪製整個資訊主頁。
  8. 繪圖後透過程式輔助方式變更。您可以選擇在初次繪圖後，透過程式輔助方式驅動資訊主頁中的控制項，並讓資訊主頁據此更新圖表。

以下是建立簡易資訊主頁的簡易範例頁面，該頁面設有範圍滑桿，可放大圓餅圖。產生的資訊主頁會顯示在程式碼片段下方。

<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) 會自動識別需要的其他套件 (例如使用度量圖表時的 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. 準備資料

載入 Visualization 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)。

每當您變更資訊主頁的組成 (例如新增控制項或圖表)，或者變更執行該資訊主頁的整體 DataTable 時，都應呼叫 draw()。

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

注意：請先監聽 ready 事件，再嘗試變更資訊主頁組合或再次繪製。

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

資訊主頁完成初始 draw() 後，就會生效，並自動回應您對其執行的任何動作 (例如變更資訊主頁中控制項滑桿的所選範圍)。

如果您需要透過程式輔助方式修改資訊主頁狀態，請直接在所屬的 ControlWrapper 和 ChartWrapper 執行個體上執行。原則上，請直接在特定 ControlWrapper (或 ChartWrapper) 執行個體上執行任何所需變更：例如，分別透過 setOption() 和 setState() 變更控制項選項或狀態，並在之後呼叫其 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 參考資料

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

資訊主頁

代表共用相同基礎資料的一組協作控制項和圖表。

建構函式

Dashboard(containerRef)
containerRef
這是頁面中有效容器元素的參照，用於保存資訊主頁內容。

方法

資訊主頁提供以下方法：

方法 傳回類型 說明
bind(controls, charts) google.visualization.Dashboard

將一或多個控制項繫結至一或多位其他資訊主頁參與者 (圖表或其他控制項)，讓前一項控制項收集到會影響資訊主頁管理資料的程式輔助或使用者互動時，所有後者都會重新繪製。傳回資訊主頁執行個體本身，以鏈結多個 bind() 呼叫。

  • controls - 可以是單一或 google.visualization.ControlWrapper 例項陣列，用來定義要繫結的控制項。
  • 圖表：可能是定義圖表的單一例項，或定義圖表所導向的google.visualization.ChartWrapper例項陣列。
draw(dataTable) 無

繪製資訊主頁。
getSelection() 物件陣列

傳回資訊主頁中所選視覺實體的陣列。在資訊主頁上呼叫 getSelection() 方法時，會傳回該圖表中所有圖表的所有選項匯總資料，讓您在使用圖表選取功能時使用單一參照。

注意： 特定事件的事件監聽器仍須附加至每個要監聽的圖表。

詳細說明

活動

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

名稱 說明 屬性
error 嘗試算繪資訊主頁時發生錯誤時觸發。資訊主頁中的一或多個控制項和圖表可能無法轉譯。 id、message
ready

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

ready 事件也會觸發：

  • 使用者或與其中一個控制項透過程式輔助互動觸發的資訊主頁重新整理後，
  • 以程式輔助方式呼叫資訊主頁任何圖表部分的 draw() 方法後。
 無

ControlWrapper

ControlWrapper 物件是圍繞著所設控制例項 JSON 表示法的包裝函式。這個類別公開便利的方法，可用於定義、繪製資訊主頁控制項，以及透過程式輔助方式變更其狀態。

建構函式

ControlWrapper(opt_spec)
opt_spec
[選用]：定義控制項的 JSON 物件，或是該物件的序列化字串版本。下表為 JSON 物件支援的屬性：如未指定，您必須使用 ControlWrapper 所公開的 set... 方法，設定所有適當的屬性。
屬性 類型 這是必填欄位 預設 說明
controlType 字串 這是必填欄位 無 控制項的類別名稱。您可以為 Google 控制項省略 google.visualization 套件名稱。範例： CategoryFilter、NumberRangeFilter。
containerId 字串 這是必填欄位 無 在網頁上代管控制項的 DOM 元素 ID。
選項 物件 選用 無 說明控制項選項的物件。您可以使用 JavaScript 常值標記法，或是提供物件的控制代碼。範例： "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state 物件 選用 無 說明控制項狀態的物件。狀態會收集使用者操作控制項可能影響的所有變數。例如，只要以滑桿佔用的低和大拇指位置來說明範圍滑桿狀態，您可以使用 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) 不限類型

傳回指定的控制項選項值

  • key - 要擷取的選項名稱。可以是合格名稱，例如 '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()。 無

ChartWrapper

請參閱圖表 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"} };

CategoryFilter

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

狀態

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

選項

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

ChartRangeFilter

疊加上兩根拇指的滑桿，用於從圖表的連續軸選取某個範圍的值。

狀態

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

選項

名稱 類型 預設 說明
filterColumnIndex 號碼 無 用於篩選的資料表中的資料欄索引。您必須提供這個選項或 filterColumnLabel。如果兩者同時出現，系統會優先採用這個選項。

請注意，指定 domain 資料欄的索引只適合放在控制項內繪製的圖表連續軸。
filterColumnLabel 字串 無 篩選器所運作資料表的資料欄標籤。您必須提供這個選項或 filterColumnIndex。如果兩者同時出現，系統會優先採用 filterColumnIndex。

請注意，只為在控制項內繪製的圖表連續軸呈現 domain 欄的標籤。
ui 物件 null 包含成員的物件，用於設定控制項 UI 的各個層面。如要指定這個物件的屬性，您可以使用物件常值標記法，如下所示： 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType 字串 組合圖 控制項中繪製的圖表類型。
可以是「面積圖」、「折線圖」、「組合圖」或「散佈圖」。
ui.chartOptions 物件 
{
 'enableInteractivity': false,
 'chartArea': {'height': '100%'},
 'legend': {'position': 'none'},
 'hAxis': {'textPosition': 'in'},
 'vAxis': {
  'textPosition': 'none',
  'gridlines': {'color': 'none'}
 }
}
控制項中繪製的圖表設定選項。允許與資訊主頁中任何圖表相同的設定層級，並符合 ChartWrapper.setOptions() 接受的格式。

您可以指定其他選項或覆寫預設選項 (請注意，系統已謹慎選擇預設值，以達到最佳外觀)。
ui.chartView 物件或字串 (序列化物件) null 檢視畫面規格，套用至在控制項內繪製圖表時使用的資料表。允許使用與資訊主頁中任何圖表相同的設定層級，並符合 ChartWrapper.setView() 接受的格式。如未指定，系統會使用資料表本身來繪製圖表。

請注意，繪製圖表的水平軸必須是「連續」，因此請務必據此指定 ui.chartView。
ui.minRangeSize 號碼 解讀為 1 像素的資料值差異 可選範圍大小的下限 (range.end - range.start)，以資料值單位的形式指定。數值軸必須是數字 (不一定是整數)。如果是日期、日期時間或時間軸，則是以毫秒為單位指定差值的整數。
ui.snapToData boolean false 如果設為 true，範圍拇指會與最近的資料點對齊。在這種情況下，getState() 傳回的範圍端點會是資料表中的值。

活動

額外 ControlWrapper 事件：

名稱 說明 屬性
statechange 與每個 ControlWrapper 記錄相同，只有額外的布林值屬性 inProgress，用於指定狀態目前是否正在變更 (可能是拇指或範圍本身正在拖曳)。 inProgress

DateRangeFilter

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

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

狀態

名稱 類型 預設 說明
lowValue 號碼 無 所選範圍的下限 (含)。
highValue 號碼 無 所選範圍的最高範圍 (包含首尾)。
lowThumbAtMinimum boolean 無 滑桿的下方拇指是否鎖定在允許的最小範圍內。如果設定，則會覆寫 lowValue。
highThumbAtMaximum boolean 無 滑桿的上方拇指是否鎖定在允許範圍內的最大數值。如果設定，則會覆寫 highValue。

選項

名稱 類型 預設 說明
filterColumnIndex 號碼 無 要用於篩選的資料表中的資料欄。您必須提供這個選項或 filterColumnLabel。如果兩者同時出現，系統會優先採用這個選項。 必須指向類型為 number 的資料欄。
filterColumnLabel 字串 無 篩選依據的資料欄標籤。您必須提供這個選項或 filterColumnIndex。如果兩者同時出現，系統會優先採用 filterColumnIndex。必須指向類型為 number 的資料欄。
minValue 日期 自動 範圍下限允許的值。如果未定義，系統就會從控制項管理的 DataTable 的內容推論值。
maxValue 日期 自動 範圍更高範圍允許的最大值。如果未定義，系統就會從控制項管理的 DataTable 的內容推論值。
ui 物件 null 包含成員的物件，用於設定控制項 UI 的各個層面。如要指定這個物件的屬性，您可以使用物件常值標記法，如下所示： 
{label: 'Age', labelSeparator: ':'}
ui.format 物件 無 以字串表示日期的方式。接受任何有效的 日期格式 。
ui.step 字串 天 拖曳滑桿時可能發生的最低變化：可以是任何時間單位 (最高可到「天」)。 (尚未支援「月」和「年」)。
ui.ticks 號碼 自動 滑桿可佔據的刻點數量 (範圍列中的固定位置)。
ui.unitIncrement 字串 「1」 範圍範圍中單位遞增的金額。單位遞增等同於使用方向鍵移動滑桿指標。
ui.blockIncrement 號碼 10 範圍範圍的區塊遞增量。區塊遞增等同於使用 pgUp 和 pgDown 鍵來移動滑桿的拇指。
ui.showRangeValues boolean true 是否在滑桿旁邊加上標籤，即可顯示所選範圍的範圍。
ui.orientation 字串 「Horizontal」 滑桿方向。'horizontal' 或 'vertical'。
ui.label 字串 自動 滑桿旁邊的標籤。如未指定，系統會使用控制項進行作業的資料欄標籤。
ui.labelSeparator 字串 無 附加至標籤的分隔符字串，以視覺方式將標籤和滑桿分開。
ui.labelStacking 字串 「Horizontal」 標籤應顯示在滑桿上方 (垂直堆疊) 或旁邊 (水平堆疊)。請使用 'vertical' 或 'horizontal'。
ui.cssClass 字串 'google-visualization-controls-rangefilter' 指派給控制項的 CSS 類別，用於自訂樣式。

NumberRangeFilter

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

狀態

名稱 類型 預設 說明
lowValue 號碼 無 所選範圍的下限 (含)。
highValue 號碼 無 所選範圍的最高範圍 (包含首尾)。
lowThumbAtMinimum boolean 無 滑桿的下方拇指是否鎖定在允許的最小範圍內。如果設定，則會覆寫 lowValue。
highThumbAtMaximum boolean 無 滑桿的上方拇指是否鎖定在允許範圍內的最大數值。如果設定，則會覆寫 highValue。

選項

名稱 類型 預設 說明
filterColumnIndex 號碼 無 要用於篩選的資料表中的資料欄。您必須提供這個選項或 filterColumnLabel。如果兩者同時出現，系統會優先採用這個選項。 必須指向類型為 number 的資料欄。
filterColumnLabel 字串 無 篩選依據的資料欄標籤。您必須提供這個選項或 filterColumnIndex。如果兩者同時出現，系統會優先採用 filterColumnIndex。必須指向類型為 number 的資料欄。
minValue 號碼 自動 範圍下限允許的值。如果未定義，系統就會從控制項管理的 DataTable 的內容推論值。
maxValue 號碼 自動 範圍更高範圍允許的最大值。如果未定義，系統就會從控制項管理的 DataTable 的內容推論值。
ui 物件 null 包含成員的物件，用於設定控制項 UI 的各個層面。如要指定這個物件的屬性，您可以使用物件常值標記法，如下所示： 
{label: 'Age', labelSeparator: ':'}
ui.format 物件 無 如何將數字表示為字串。接受任何有效的 數字格式 。
ui.step 號碼 1，或是從 ticks 計算 (如有定義) 拖曳滑桿時可能出現的最小可能變化。
ui.ticks 號碼 自動 滑桿可佔據的刻點數量 (範圍列中的固定位置)。
ui.unitIncrement 號碼 1 範圍範圍中單位遞增的金額。單位遞增等同於使用方向鍵移動滑桿指標。
ui.blockIncrement 號碼 10 範圍範圍的區塊遞增量。區塊遞增等同於使用 pgUp 和 pgDown 鍵來移動滑桿的拇指。
ui.showRangeValues boolean true 是否在滑桿旁邊加上標籤，即可顯示所選範圍的範圍。
ui.orientation 字串 「Horizontal」 滑桿方向。'horizontal' 或 'vertical'。
ui.label 字串 自動 滑桿旁邊的標籤。如未指定，系統會使用控制項進行作業的資料欄標籤。
ui.labelSeparator 字串 無 附加至標籤的分隔符字串，以視覺方式將標籤和滑桿分開。
ui.labelStacking 字串 「Horizontal」 標籤應顯示在滑桿上方 (垂直堆疊) 或旁邊 (水平堆疊)。請使用 'vertical' 或 'horizontal'。
ui.cssClass 字串 'google-visualization-controls-rangefilter' 指派給控制項的 CSS 類別，用於自訂樣式。

StringFilter

簡單的文字輸入欄位，可讓您透過字串比對篩選資料。每次按下按鍵後，系統都會更新：請嘗試輸入 j，將下表的範圍限定為 John 和 Jessica。

狀態

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

選項

名稱 類型 預設 說明
filterColumnIndex 號碼 無 要用於篩選的資料表中的資料欄。您必須提供這個選項或 filterColumnLabel。如果兩者同時出現，系統會優先採用這個選項。
filterColumnLabel 字串 無 篩選依據的資料欄標籤。您必須提供這個選項或 filterColumnIndex。如果兩者同時出現，系統會優先採用 filterColumnIndex。
matchType 字串 「prefix」 控制項是否應僅比對完全相符的值 ('exact')、從值開頭 ('prefix') 開頭的前置字串，或任何子字串 ('any')。
caseSensitive boolean false 比對是否區分大小寫。
useFormattedValue boolean false 控制項是否應與儲存格格式的值比對，或再次與實際值相符。
ui 物件 null 包含成員的物件，用於設定控制項 UI 的各個層面。如要指定這個物件的屬性，您可以使用物件常值標記法，如下所示： 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true 每當有人按下按鍵，還是只在輸入欄位「changes」時 (聚焦於焦點或按下 Enter 鍵)，控制項都必須符合。
ui.label 字串 自動 顯示在輸入欄位旁邊的標籤。如未指定，系統會使用控制項操作的資料欄標籤。
ui.labelSeparator 字串 無 附加至標籤的分隔符字串，以視覺方式將標籤和輸入欄位分開。
ui.labelStacking 字串 「Horizontal」 標籤是否應顯示在輸入欄位上方 (垂直堆疊) 或旁邊 (水平堆疊)。請使用 'vertical' 或 'horizontal'。
ui.cssClass 字串 'google-visualization-controls-stringfilter' 指派給控制項的 CSS 類別，用於自訂樣式。