控件和信息中心

在本页中，您将了解如何将多个图表合并到信息中心，并让用户控制其显示的数据。

概览

信息中心是组织整理和管理共享相同基础数据的多个图表的简单方法。通过使用本页介绍的 API，您无需再费心进行连接和协调属于信息中心的所有图表。

信息中心是使用 google.visualization.Dashboard 类定义的。Dashboard 实例会收到 DataTable，其中包含要直观呈现的数据，并负责绘制数据并将其分布到信息中心内的所有图表。

控件是您可以与之互动的界面 widget（例如类别选择器、范围滑块、自动补全器等），以便驱动由信息中心及其中包含的图表管理的数据。

控件使用 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. 准备数据

加载可视化 API 后，google.charts.setOnLoadCallback() 将调用您的处理程序函数，这样您就可以知道所有必需的辅助方法和类都已准备就绪，可以开始准备数据。

信息中心接受 DataTable 中的数据，与图表一样。

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 的哪一列（在上面的示例中，控件在标记为吃甜甜圈的列上运行），

  • 对控件使用 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}
  });

  • 属于信息中心的所有图表都共用您在准备数据步骤中准备的相同基础 dataTable。但是，图表通常需要特定的列排列方式才能正确显示：例如，饼图需要一个字符串列作为标签，后跟一个数字列作为值。

    配置每个 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 and Dashboards API 提供的对象，以及所有控件公开的标准方法。

信息中心

表示一组共享相同基础数据的协作控件和图表。

构造函数

Dashboard(containerRef)
containerRef
对网页上用于存放信息中心内容的有效容器元素的引用。

方法

信息中心提供以下方法：

方法 返回值类型 说明
bind(controls, charts) google.visualization.Dashboard

将一个或多个控件绑定到一个或多个信息中心参与者（图表或其他控件），这样一来，每当任何控件会收集影响信息中心所管理数据的程序化互动或用户互动时，系统会重新绘制所有控件。返回信息中心实例本身，用于将多个 bind() 调用链接在一起。

  • controls - 单个或 google.visualization.ControlWrapper 实例的数组，用于定义要绑定的控件。
  • charts - 单个或 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 创建的控件的引用。这会返回 null，直到您对 ControlWrapper 对象（或在包含该对象的信息中心）调用 draw()，并且该方法会抛出 ready 事件。返回的对象仅公开一个方法：resetControl()，该方法会将控件状态重置为初始化时的状态（如重置 HTML 表单元素）。
getContainerId() 字符串 控件的 DOM 容器元素的 ID。
getOption(key, opt_default_val) 任何类型

返回指定的控件选项值

  • key - 要检索的选项的名称。可以是限定名称，例如 'vAxis.title'。
  • opt_default_value [可选] - 如果指定的值未定义或为 null，系统将返回此值。
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 number 无 对过滤器执行操作的数据表列。必须提供此选项或 filterColumnLabel。如果两者都存在，则此选项优先。
filterColumnLabel string 无 要对过滤器执行运算的列的标签。必须提供此选项或 filterColumnIndex。如果两者都存在，则 filterColumnIndex 优先。
值 数组 自动 可供选择的值的列表。如果使用对象数组，则这些对象应具有合适的 toString() 表示法以向用户显示。如果为 null 或 undefined，系统将根据执行此控件的 DataTable 列中显示的值自动计算值列表。
useFormattedValue boolean false 从 DataTable 列中自动填充可选值列表时，此过滤条件会作运算用，无论是使用实际单元格值还是使用其格式的值。
ui 对象 null 一个对象，包含用于配置控件界面各个方面的成员。 如需指定此对象的属性，您可以使用对象字面量表示法，如下所示： 
{label: 'Metric', labelSeparator: ':'}
ui.caption string “选择一个值...” 未选择任何项时要在值选择器 widget 中显示的说明。
ui.sortValues boolean true 是否应对可供选择的值进行排序。
ui.selectedValuesLayout string “aside” 在允许多项选择的情况下，如何显示所选值。可能的
    值如下：
  • 'aside'：所选值将显示在值选择器 widget 旁边的单个文本行中。
  • 'below'：选定值将显示在 widget 下方的单个文本行中，
  • 'belowWrapping'：与 below 类似，但不适合选择器的条目将另起一行。
  • 'belowStacked'：选定值将显示在 widget 下方的列中。
ui.allowNone boolean true 是否允许用户选择任何值。如果为 false，则用户必须从可用值中至少选择一个值。在控件初始化期间，如果选项设为 false 且未指定 selectedValues 状态，系统会自动选择可用值中的第一个值。
ui.allowMultiple boolean true 是否可以选择多个值，而不是只选择一个值。
ui.allowTyping boolean true 是否允许用户在文本字段中输入内容以缩小可能选项列表的范围（通过自动补全功能）。
ui.label string 自动 要在类别选择器旁边显示的标签。如果未指定，将使用执行控件操作的列的标签。
ui.labelSeparator string 无 附加到标签的分隔符字符串，用于直观地将标签与类别选择器分开。
ui.labelStacking string “水平” 标签应该显示在类别选择器上方（垂直堆叠）还是旁边（水平堆叠）。请使用 'vertical' 或 'horizontal'。
ui.cssClass string 'google-visualization-controls-categoryfilter' 要分配给控件的 CSS 类，用于自定义样式。

ChartRangeFilter

一个滑块，上面叠加在图表上有两个拇指，用于从图表的连续轴中选择一系列值。

状态

名称 类型 默认 说明
range.start 数字、日期、日期时间或时间 范围起始值 所选范围的起始值（含边界值）。
range.end 数字、日期、日期时间或时间 范围结束值 所选范围（含边界值）的末尾。

选项

名称 类型 默认 说明
filterColumnIndex number 无 对过滤器执行操作的数据表中列的索引。 必须提供此选项或 filterColumnLabel。如果两者同时存在，则此选项优先。

请注意，指定 domain 列的索引才有意义，且该索引体现在控件内绘制的图表的连续轴上。

filterColumnLabel string 无 对过滤器执行操作的数据表列的标签。必须提供此选项或 filterColumnIndex。如果两者同时存在，则 filterColumnIndex 优先。

请注意，指定 domain 列的标签才有意义，该标签体现在控件内绘制的图表的连续轴上。

ui 对象 null 一个对象，包含用于配置控件界面各个方面的成员。 如需指定此对象的属性，您可以使用对象字面量表示法，如下所示： 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType string “组合图表” 在控件内绘制的图表类型。
可以是以下项之一：“面积图”、“折线图”、“组合图表”或“散点图”。
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 number 系统会将数据值差异解读为 1 个像素 可选范围大小下限 (range.end - range.start)，以数据值单位指定。对于数字轴，该值为数字（不一定是整数）。 对于日期、日期时间或时间轴，它是一个整数，用于指定以毫秒为单位的差值。
ui.snapToData boolean false 如果为 true，范围滑块会贴靠到最近的数据点。 在这种情况下，getState() 返回的范围的端点必须是数据表中的值。

活动

添加了 ControlWrapper 事件：

名称 说明 属性
statechange 与每个 ControlWrapper 的说明一样，只有一个额外的布尔值属性 inProgress，用于指定当前是否正在更改状态（正在更改其中一个滑块或拖动范围本身）。 inProgress

DateRangeFilter

用于选择日期范围的双值滑块。

尝试移动滑块以更改下表中显示的行。

状态

名称 类型 默认 说明
lowValue number 无 所选范围的下限（含边界值）。
highValue number 无 所选范围的更高范围（含边界值）。
lowThumbAtMinimum boolean 无 滑块的下拇指是否锁定在允许的最小范围内。如果设置了此字段，则会替换 lowValue。
highThumbAtMaximum boolean 无 滑块的上拇指是否锁定在允许的最大范围内。如果设置了此字段，则会替换 highValue。

选项

名称 类型 默认 说明
filterColumnIndex number 无 对过滤器执行操作的数据表列。必须提供此选项或 filterColumnLabel。如果两者都存在，则此选项优先。 必须指向类型为 number 的列。
filterColumnLabel string 无 要对过滤器执行运算的列的标签。必须提供此选项或 filterColumnIndex。如果两者都存在，则以 filterColumnIndex 为准。必须指向类型为 number 的列。
minValue 日期 自动 范围较小的允许的最小值。如果未定义，系统将根据由控件管理的 DataTable 的内容推断出该值。
maxValue 日期 自动 范围较大允许的最大值。如果未定义，系统将根据由控件管理的 DataTable 的内容推断出该值。
ui 对象 null 一个对象，包含用于配置控件界面各个方面的成员。 如需指定此对象的属性，您可以使用对象字面量表示法，如下所示： 
{label: 'Age', labelSeparator: ':'}
ui.format 对象 无 如何以字符串表示日期。接受任何有效的 日期格式 。
ui.step string 天 拖动滑块时可能发生的最小变化：可以是任何时间单位，最长为“天”。 （尚不支持“month”和“year”）。
ui.ticks number 自动 滑块滑块可以占据的刻度线数量（范围栏中的固定位置）。
ui.unitIncrement string “1” 范围范围的单位增量要增加的量。单位增量相当于使用箭头键来移动滑块。
ui.blockIncrement number 10 要针对范围范围的块增量增加的量。块增量相当于使用 pgUp 和 pgDown 键来移动滑块的滑块。
ui.showRangeValues boolean 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

用于选择数值范围的双值滑块。

状态

名称 类型 默认 说明
lowValue number 无 所选范围的下限（含边界值）。
highValue number 无 所选范围的更高范围（含边界值）。
lowThumbAtMinimum boolean 无 滑块的下拇指是否锁定在允许的最小范围内。如果设置了此字段，则会替换 lowValue。
highThumbAtMaximum boolean 无 滑块的上拇指是否锁定在允许的最大范围内。如果设置了此字段，则会替换 highValue。

选项

名称 类型 默认 说明
filterColumnIndex number 无 对过滤器执行操作的数据表列。必须提供此选项或 filterColumnLabel。如果两者都存在，则此选项优先。 必须指向类型为 number 的列。
filterColumnLabel string 无 要对过滤器执行运算的列的标签。必须提供此选项或 filterColumnIndex。如果两者都存在，则以 filterColumnIndex 为准。必须指向类型为 number 的列。
minValue number 自动 范围较小的允许的最小值。如果未定义，系统将根据由控件管理的 DataTable 的内容推断出该值。
maxValue number 自动 范围较大允许的最大值。如果未定义，系统将根据由控件管理的 DataTable 的内容推断出该值。
ui 对象 null 一个对象，包含用于配置控件界面各个方面的成员。 如需指定此对象的属性，您可以使用对象字面量表示法，如下所示： 
{label: 'Age', labelSeparator: ':'}
ui.format 对象 无 如何将数字表示为字符串。接受任何有效的 数字格式 。
ui.step number 1，或通过 ticks 计算得出（如果已定义） 拖动滑块时可能发生的最小变化。
ui.ticks number 自动 滑块滑块可以占据的刻度线数量（范围栏中的固定位置）。
ui.unitIncrement number 1 范围范围的单位增量要增加的量。单位增量相当于使用箭头键来移动滑块。
ui.blockIncrement number 10 要针对范围范围的块增量增加的量。块增量相当于使用 pgUp 和 pgDown 键来移动滑块的滑块。
ui.showRangeValues boolean 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 类，用于自定义样式。

StringFilter

一个简单的文本输入字段，可让您通过字符串匹配来过滤数据。它会在每次按键后更新：请尝试输入 j，将下表范围缩小为 John 和 Jessica。

状态

名称 类型 默认 说明
值 字符串或对象 无 控件输入字段中当前输入的文本。

选项

名称 类型 默认 说明
filterColumnIndex number 无 对过滤器执行操作的数据表列。必须提供此选项或 filterColumnLabel。如果两者都存在，则此选项优先。
filterColumnLabel string 无 要对过滤器执行运算的列的标签。必须提供此选项或 filterColumnIndex。如果两者都存在，则 filterColumnIndex 优先。
matchType string “prefix” 控件是否应仅匹配确切值 ('exact')、从值开头开始的前缀 ('prefix') 或任何子字符串 ('any')。
caseSensitive boolean false 匹配是否区分大小写。
useFormattedValue boolean false 控件是与单元格格式的值匹配还是与实际值匹配。
ui 对象 null 一个对象，包含用于配置控件界面各个方面的成员。 如需指定此对象的属性，您可以使用对象字面量表示法，如下所示： 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true 该控件是在任何时候按下某个键时应匹配，还是仅在输入字段“更改”（失去焦点或按 Enter 键）时匹配。
ui.label string 自动 要在输入字段旁边显示的标签。如果未指定，将使用执行控件操作的列的标签。
ui.labelSeparator string 无 附加到标签的分隔符字符串，用于直观地将标签与输入字段分隔开来。
ui.labelStacking string “水平” 标签应该显示在输入字段上方（垂直堆叠）还是旁边（水平堆叠）。请使用 'vertical' 或 'horizontal'。
ui.cssClass string 'google-visualization-controls-stringfilter' 要分配给控件的 CSS 类，用于自定义样式。