コントロールとダッシュボード

このページでは、複数のグラフをダッシュボードに結合し、表示するデータをユーザーが操作できるようにする方法について説明します。

概要

ダッシュボードを使用すると、同じ基盤となるデータを共有する複数のグラフをまとめて整理、管理できます。このページで説明する API を使用すると、ダッシュボード内のすべてのグラフを連携して調整する負担から解放されます。

ダッシュボードは、google.visualization.Dashboard クラスを使用して定義されます。Dashboard インスタンスは、可視化するデータを含む DataTable を受け取り、ダッシュボードに含まれるすべてのグラフへのデータの描画と配布を行います。

コントロールは、ダッシュボードおよびその構成要素であるグラフによって管理されるデータを操作するために操作する、ユーザー インターフェース ウィジェット（カテゴリ選択ツール、範囲スライダー、予測入力ツールなど）です。

コントロールは google.visualization.ControlWrapper クラスを使用して定義します。 ControlWrapper インスタンスをダッシュボードに追加すると、配管システムの配管やバルブのように動作します。ユーザー入力を収集し、その情報を使用して、ダッシュボードが管理しているデータを、その中のグラフで使用可能にする必要があるかどうかを決定します。

次の例をご覧ください。カテゴリ選択ツールと範囲スライダーを使用して、円グラフで可視化されたデータを示しています。

注: ダッシュボードはインタラクティブです。コントロールを操作して、グラフの変化をリアルタイムで確認してみてください。

コントロールとダッシュボードの使用

ダッシュボードを作成してページに埋め込む主な手順は次のとおりです。以下に、これらのすべてのステップを示すコード スニペットと、各ステップの詳細情報を示します。

  1. ダッシュボードの HTML スケルトンを作成する。ページには、ダッシュボードのすべてのメンバーを保持するために必要な数の HTML 要素が必要です。これには、ダッシュボード自体と、ダッシュボードに含まれるすべてのコントロールとグラフが含まれます。通常は、それぞれに <div> を使用します。
  2. ライブラリを読み込みます。ダッシュボードでは、Google AJAX API と GoogleVisualization controls パッケージの 2 つのライブラリのみをページに含めるか読み込む必要があります。
  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 と GoogleVisualization controls パッケージの 2 つのライブラリをページに含めるか読み込むだけで済みます。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. ダッシュボード インスタンスを作成する

データを作成したら、ダッシュボード オブジェクトをインスタンス化できます。ダッシュボード コンストラクタは、1 つのパラメータ（ダッシュボードを描画する 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}
  });

  • ダッシュボードを構成するすべてのグラフは、データを準備するステップで準備した同じ基盤となる dataTable を共有します。ただし、多くの場合、グラフを正しく表示するには、特定の列の配置が必要になります。たとえば、円グラフでは、ラベルを表す文字列の列と、値を表す数値列が必要です。

    次の例のように、view オプションを使用して、各 ChartWrapper インスタンスを構成するときに、グラフに関連する列を宣言します。

      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);

1 対 1、1 対多、多対 1、多対多など、さまざまな設定でコントロールとグラフをバインドできます。複数のコントロールがグラフにバインドされている場合、ダッシュボードでは、バインドされているすべてのコントロールによって適用される結合された制約に一致するようにグラフが更新されます。同時に、1 つのコントロールで複数のグラフを同時に実行できます。複数のバインディングを同時に指定するには、単一のインスタンスではなく配列を 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() メソッドは、1 つのパラメータ（ダッシュボードを強化する 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 API と Dashboards API によって公開されるオブジェクトと、すべてのコントロールで公開される標準メソッドについて説明します。

ダッシュボード

同じ基盤となるデータを共有する、コラボレーションしているコントロールとグラフのコレクションを表します。

コンストラクタ

Dashboard(containerRef)
containerRef
ダッシュボード コンテンツを保持するページ上の有効なコンテナ要素への参照。

メソッド

ダッシュボードは以下のメソッドを公開します。

メソッド 戻り値の型 説明
bind(controls, charts) google.visualization.Dashboard

1 つ以上のコントロールを 1 つ以上の他のダッシュボード参加者（グラフまたは他のコントロール）にバインドします。これにより、ダッシュボードで管理されているデータに影響するプログラムまたはユーザー操作が収集されるたびに、後者のすべてのコントロールが再描画されます。複数の bind() 呼び出しをチェーンでつなぐダッシュボード インスタンス自体を返します。

  • controls - 単一の 1 つ、またはバインドするコントロールを定義する google.visualization.ControlWrapper インスタンスの配列。
  • charts - 単一のインスタンス、またはコントロールによって駆動されるグラフを定義する google.visualization.ChartWrapper インスタンスの配列。
draw(dataTable) なし

ダッシュボードを描画します。
getSelection() オブジェクトの配列

ダッシュボード内のグラフで選択された、視覚的なエンティティの配列を返します。getSelection() メソッドは、ダッシュボードで呼び出されると、その中のすべてのグラフで行われたすべての選択の集計を返します。これにより、グラフの選択を操作するときに 1 つの参照を使用できます。

注: リッスンする各グラフに、select イベントのイベント リスナーをアタッチする必要があります。

詳細な説明

イベント

Dashboard オブジェクトは、以下のイベントをスローします。イベントがスローされる前に Dashboard.draw() を呼び出す必要があるので注意してください。

名前 説明 プロパティ
error ダッシュボードのレンダリング中にエラーが発生したときに呼び出されます。ダッシュボードの一部である 1 つ以上のコントロールとグラフのレンダリングに失敗した可能性があります。 id、message
ready

ダッシュボードの描画が完了し、変更を受け入れる準備ができました。ダッシュボードを構成するすべてのコントロールとグラフは、外部メソッド呼び出しとユーザー操作に対応しています。描画後にダッシュボード（またはダッシュボードに表示されるデータ）を変更する場合は、draw メソッドを呼び出す前にこのイベントのリスナーを設定し、イベントが発生した後にのみ変更を適用する必要があります。

ready イベントも発生します。

  • ユーザーまたはプログラムによるいずれかのコントロールの操作によってダッシュボードの更新が完了した後
  • ダッシュボードのグラフ部分の draw() メソッドをプログラムで呼び出した後。
 なし

ControlWrapper

ControlWrapper オブジェクトは、構成されたコントロール インスタンスの JSON 表現のラッパーです。このクラスは、ダッシュボード コントロールを定義して描画し、プログラムによって状態を変更するための便利なメソッドを公開します。

コンストラクタ

ControlWrapper(opt_spec)
opt_spec
（省略可）- コントロールを定義する JSON オブジェクトか、そのオブジェクトのシリアル化文字列バージョン。次の表に、JSON オブジェクトでサポートされているプロパティを示します。指定しない場合、ControlWrapper によって公開される set... メソッドを使用して、適切なすべてのプロパティを設定する必要があります。
プロパティ タイプ 必須 デフォルト 説明
controlType 文字列 必須 none コントロールのクラス名。Google コントロールの場合、google.visualization パッケージ名は省略できます。例: CategoryFilter、NumberRangeFilter。
containerId 文字列 必須 none コントロールをホストするページ上の DOM 要素の ID です。
オプション オブジェクト 任意 none コントロールのオプションを記述するオブジェクト。JavaScript のリテラル表記を使用するか、オブジェクトへのハンドルを指定できます。例: "options": {"filterColumnLabel": "Age", "minValue": 10, "maxValue": 80}
state オブジェクト 任意 none コントロールの状態を記述するオブジェクト。この状態では、コントロールを操作するユーザーが影響を及ぼす可能性があるすべての変数が収集されます。たとえば、範囲スライダーの状態は、スライダーの「低」と「高」の親指が占める位置で表すことができます。JavaScript のリテラル表記を使用するか、オブジェクトへのハンドルを指定できます。例: "state": {"lowValue": 20, "highValue": 50}

メソッド

ControlWrapper は以下の追加のメソッドを公開します。

メソッド 戻り値の型 説明
draw() なし

コントロールを描画します。通常、コントロールを保持しているダッシュボードが描画を処理します。オプションや状態など、他の設定を変更した後は、draw() を呼び出してコントロールをプログラムで再描画する必要があります。
toJSON() 文字列 コントロールの JSON 表現の文字列バージョンを返します。
clone() ControlWrapper コントロール ラッパーのディープコピーを返します。
getControlType() 文字列 コントロールのクラス名。これが Google コントロールの場合、名前は google.visualization で修飾されません。たとえば、これが CategoryFilter コントロールの場合は、「google.visualization.CategoryFilter」ではなく「CategoryFilter」を返します。
getControlName() 文字列 setControlName() によって割り当てられたコントロール名を返します。
getControl() コントロール オブジェクト参照 この ControlWrapper によって作成されたコントロールへの参照を返します。これは、ControlWrapper オブジェクト（またはそれを保持しているダッシュボード）で draw() を呼び出し、Ready イベントをスローするまで null を返します。返されるオブジェクトでは、メソッド 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

定義済みの値のセットから 1 つ以上を選択するための選択ツール。

状態

名前 タイプ デフォルト 説明
selectedValues オブジェクトまたはプリミティブ型の配列 none 現在選択されている値のセット。選択する値は、values オプションで定義された選択可能な全体のセットである必要があります（余分な値は無視されます）。CategoryFilter で多肢選択式が許可されない場合は、配列の最初の値のみが保持されます。

オプション

名前 タイプ デフォルト 説明
filterColumnIndex 数値 none フィルタが操作されるデータテーブルの列。このオプションまたは filterColumnLabel を指定する必要があります。両方が指定されている場合、このオプションが優先されます。
filterColumnLabel string none フィルタを操作する列のラベル。このオプションまたは filterColumnIndex を指定する必要があります。両方が指定されている場合、filterColumnIndex が優先されます。
values 配列 自動 選択可能な値のリスト。オブジェクトの配列を使用する場合は、ユーザーへの表示に適した toString() 表現にする必要があります。null または未定義の場合、このコントロールが操作する DataTable 列にある値から値のリストが自動的に計算されます。
useFormattedValue boolean false 選択可能な値のリストを DataTable 列から自動的に入力する場合、実際のセル値を使用するか、書式設定された値を使用するかを、このフィルタで操作します。
ui オブジェクト null コントロールの UI のさまざまな要素を構成するメンバーを持つオブジェクト。このオブジェクトのプロパティを指定するには、次に示すようにオブジェクト リテラル表記を使用できます。 
{label: 'Metric', labelSeparator: ':'}
ui.caption string '値を選択...' 項目が選択されていないときに値選択ツール ウィジェット内に表示されるキャプション。
ui.sortValues boolean true 選択する値を並べ替えるかどうかを指定します。
ui.selectedValuesLayout string '脇に' 複数の選択が可能な場合に、選択した値を表示する方法。有効な値は次のとおりです。
  • 'aside': 選択した値は、値選択ツールウィジェットの横に 1 行のテキストで表示されます。
  • 'below': 選択した値は、ウィジェットの下に 1 行のテキストで表示されます。
  • 'belowWrapping': below と同様ですが、選択ツールに収まらないエントリは新しい行に折り返します。
  • 'belowStacked': 選択した値は、ウィジェットの下の列に表示されます。
ui.allowNone boolean true ユーザーが値を選択できないようにするかどうか。false の場合、ユーザーは使用可能な値から少なくとも 1 つを選択する必要があります。コントロールの初期化時に、このオプションが false に設定され、selectedValues 状態が指定されていない場合、使用可能な値から最初の値が自動的に選択されます。
ui.allowMultiple boolean true 1 つだけでなく、複数の値を選択できるかどうかを指定します。
ui.allowTyping boolean true ユーザーがテキスト フィールドに入力して（予測入力ツールを使用して）候補のリストを絞り込むことができるかどうか。
ui.label string 自動 カテゴリ選択ツールの横に表示するラベル。指定しない場合、コントロールが操作する列のラベルが使用されます。
ui.labelSeparator string none カテゴリ選択ツールとラベルを視覚的に区別するためにラベルに追加される区切り文字。
ui.labelStacking string 「横向き」 カテゴリ選択ツールの上にラベルを表示するか（縦に重ねて）、横に並べるか（横に重ねて）表示するか。'vertical' または 'horizontal' を使用します。
ui.cssClass string 'google-visualization-controls-categoryfilter' カスタム スタイル設定のために、コントロールに割り当てる CSS クラス。

ChartRangeFilter

グラフに 2 本の親指が重なって配置されたスライダー。グラフの連続軸から値の範囲を選択します。

状態

名前 タイプ デフォルト 説明
range.start number、date、datetime、または timeofday 範囲の開始値 選択された範囲の始点（両端を含む）。
range.end number、date、datetime、または timeofday 範囲の終了値 選択した範囲の終端（両端を含む）。

オプション

名前 タイプ デフォルト 説明
filterColumnIndex 数値 none フィルタが操作するデータテーブル内の列のインデックス。このオプションまたは filterColumnLabel を指定する必要があります。両方が存在する場合、このオプションが優先されます。

コントロール内に描画されたグラフの連続軸に具現化されているドメイン列のインデックスを指定することが意味があるので注意してください。
filterColumnLabel string none フィルタが適用されるデータテーブルの列のラベル。このオプションまたは filterColumnIndex を指定する必要があります。両方が指定されている場合、filterColumnIndex が優先されます。

コントロール内に描画されたグラフの連続軸に組み込まれるドメイン列のラベルを指定することが意味があるので注意してください。
ui オブジェクト null コントロールの UI のさまざまな要素を構成するメンバーを持つオブジェクト。このオブジェクトのプロパティを指定するには、次に示すようにオブジェクト リテラル表記を使用できます。 
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chartType string 「ComboChart」 コントロール内に描画されるグラフの種類。
「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 オブジェクトまたは文字列（シリアル化されたオブジェクト） null コントロール内にグラフを描画するために使用されるデータ表に適用するビューの仕様。ダッシュボード内のグラフと同じレベルの構成を許可し、ChartWrapper.setView() で受け入れられる形式と同じ形式にします。指定しない場合は、データテーブル自体がグラフの描画に使用されます。

描画されるグラフの横軸は連続している必要があるので、それに応じて ui.chartView を指定するように注意してください。
ui.minRangeSize 数値 データ値の差を 1 ピクセルとして解釈 選択可能な範囲の最小サイズ（range.end - range.start）。データ値の単位で指定します。数値軸の場合は数値になります（整数である必要はありません）。日付、日時、timeofday の軸の場合は、差をミリ秒単位で指定する整数です。
ui.snapToData boolean false true の場合、範囲のつまみは最も近いデータポイントにスナップされます。この場合、getState() によって返される範囲の終点は、必ずデータテーブル内の値です。

イベント

ControlWrapper イベントへの追加は次のとおりです。

名前 説明 プロパティ
statechange すべての ControlWrapper のドキュメントと同様に、追加のブール値プロパティ inProgress のみがあります。このプロパティは、状態が現在変更されているか（つまみまたは範囲自体がドラッグされているか）を指定します。 inProgress

DateRangeFilter

期間を選択するための 2 つの値スライダー。

スライダーを動かして、下の表に表示される行を変更してみてください。

状態

名前 タイプ デフォルト 説明
lowValue 数値 none 選択範囲の下限（両端を含む）。
highValue 数値 none 選択範囲の高い範囲（両端を含む）。
lowThumbAtMinimum boolean none スライダーの下親指を最小許容範囲にロックするかどうか。設定すると、lowValue がオーバーライドされます。
highThumbAtMaximum boolean none スライダーの上の親指が最大許容範囲でロックされるかどうか。設定すると、highValue がオーバーライドされます。

オプション

名前 タイプ デフォルト 説明
filterColumnIndex 数値 none フィルタが操作されるデータテーブルの列。このオプションまたは filterColumnLabel を指定する必要があります。両方が指定されている場合、このオプションが優先されます。 number 型の列を指す必要があります。
filterColumnLabel string none フィルタを操作する列のラベル。このオプションまたは filterColumnIndex を指定する必要があります。両方が指定されている場合、filterColumnIndex が優先されます。number 型の列を指す必要があります。
minValue 日付 自動 範囲の下位の範囲の最小値。未定義の場合、値はコントロールによって管理される DataTable の内容から推定されます。
maxValue 日付 自動 範囲のより高い範囲の最大許容値。未定義の場合、値はコントロールによって管理される DataTable の内容から推定されます。
ui オブジェクト null コントロールの UI のさまざまな要素を構成するメンバーを持つオブジェクト。このオブジェクトのプロパティを指定するには、次に示すようにオブジェクト リテラル表記を使用できます。 
{label: 'Age', labelSeparator: ':'}
ui.format オブジェクト none 日付を文字列として表す方法。有効な 日付形式 を使用できます。
ui.step string 日 スライダーのつまみをドラッグするときに可能な変更の最小単位: 「日」までの任意の時間単位を指定できます。 （「month」と「year」はまだサポートされていません）。
ui.ticks 数値 自動 スライダーのつまみが占有できる目盛りの数（範囲バー内の固定位置）。
ui.unitIncrement string '1' 範囲の範囲を単位単位で増分する量。単位の増分は、矢印キーを使用してスライダーのつまみを動かすことと同等です。
ui.blockIncrement 数値 10 範囲の範囲のブロック インクリメントで増分する量。ブロック インクリメントは、pgUp キーと pgDown キーを使用してスライダーのつまみを動かすことと同等です。
ui.showRangeValues boolean true 選択した範囲の範囲を表示するスライダーの横に、ラベルを表示するかどうかを指定します。
ui.orientation string 「横向き」 スライダーの向き。'horizontal' または 'vertical' のいずれか。
ui.label string 自動 スライダーの横に表示するラベル。指定しない場合、コントロールを操作する列のラベルが使用されます。
ui.labelSeparator string none スライダーとラベルを視覚的に区切るためにラベルに追加される区切り文字。
ui.labelStacking string 「横向き」 ラベルをスライダーの上（縦方向のスタック）または横（横方向のスタック）に表示するかどうかを指定します。'vertical' または 'horizontal' を使用します。
ui.cssClass string 'google-visualization-controls-rangefilter' カスタム スタイル設定のために、コントロールに割り当てる CSS クラス。

NumberRangeFilter

数値の範囲を選択するための 2 つの値スライダー。

状態

名前 タイプ デフォルト 説明
lowValue 数値 none 選択範囲の下限（両端を含む）。
highValue 数値 none 選択範囲の高い範囲（両端を含む）。
lowThumbAtMinimum boolean none スライダーの下親指を最小許容範囲にロックするかどうか。設定すると、lowValue がオーバーライドされます。
highThumbAtMaximum boolean none スライダーの上の親指が最大許容範囲でロックされるかどうか。設定すると、highValue がオーバーライドされます。

オプション

名前 タイプ デフォルト 説明
filterColumnIndex 数値 none フィルタが操作されるデータテーブルの列。このオプションまたは filterColumnLabel を指定する必要があります。両方が指定されている場合、このオプションが優先されます。 number 型の列を指す必要があります。
filterColumnLabel string none フィルタを操作する列のラベル。このオプションまたは filterColumnIndex を指定する必要があります。両方が指定されている場合、filterColumnIndex が優先されます。number 型の列を指す必要があります。
minValue 数値 自動 範囲の下位の範囲の最小値。未定義の場合、値はコントロールによって管理される DataTable の内容から推定されます。
maxValue 数値 自動 範囲のより高い範囲の最大許容値。未定義の場合、値はコントロールによって管理される DataTable の内容から推定されます。
ui オブジェクト null コントロールの UI のさまざまな要素を構成するメンバーを持つオブジェクト。このオブジェクトのプロパティを指定するには、次に示すようにオブジェクト リテラル表記を使用できます。 
{label: 'Age', labelSeparator: ':'}
ui.format オブジェクト none 数値を文字列として表す方法。有効な 数値形式 を使用できます。
ui.step 数値 1、または ticks から計算されます（定義されている場合） スライダーのつまみをドラッグしたときに許可される最小の変更値です。
ui.ticks 数値 自動 スライダーのつまみが占有できる目盛りの数（範囲バー内の固定位置）。
ui.unitIncrement 数値 1 範囲の範囲を単位単位で増分する量。単位の増分は、矢印キーを使用してスライダーのつまみを動かすことと同等です。
ui.blockIncrement 数値 10 範囲の範囲のブロック インクリメントで増分する量。ブロック インクリメントは、pgUp キーと pgDown キーを使用してスライダーのつまみを動かすことと同等です。
ui.showRangeValues boolean true 選択した範囲の範囲を表示するスライダーの横に、ラベルを表示するかどうかを指定します。
ui.orientation string 「横向き」 スライダーの向き。'horizontal' または 'vertical' のいずれか。
ui.label string 自動 スライダーの横に表示するラベル。指定しない場合、コントロールを操作する列のラベルが使用されます。
ui.labelSeparator string none スライダーとラベルを視覚的に区切るためにラベルに追加される区切り文字。
ui.labelStacking string 「横向き」 ラベルをスライダーの上（縦方向のスタック）または横（横方向のスタック）に表示するかどうかを指定します。'vertical' または 'horizontal' を使用します。
ui.cssClass string 'google-visualization-controls-rangefilter' カスタム スタイル設定のために、コントロールに割り当てる CSS クラス。

StringFilter

文字列の照合でデータをフィルタできるシンプルなテキスト入力フィールド。キーが押されるたびに更新されます。「j」と入力して、下の表を「John」と「Jessica」に絞り込みます。

状態

名前 タイプ デフォルト 説明
value 文字列またはオブジェクト none コントロールの入力フィールドに現在入力されているテキスト。

オプション

名前 タイプ デフォルト 説明
filterColumnIndex 数値 none フィルタが操作されるデータテーブルの列。このオプションまたは filterColumnLabel を指定する必要があります。両方が指定されている場合、このオプションが優先されます。
filterColumnLabel string none フィルタを操作する列のラベル。このオプションまたは filterColumnIndex を指定する必要があります。両方が指定されている場合、filterColumnIndex が優先されます。
matchType string '接頭辞' コントロールが完全一致の値のみに一致させるかどうか（'exact'）、値の先頭から始まるプレフィックス（'prefix'）、任意の部分文字列（'any'）にマッチするかどうか。
caseSensitive boolean false 照合で大文字と小文字を区別するかどうか。
useFormattedValue boolean false コントロールをセル形式の値と照合するか、実際の値と比較するかを指定します。
ui オブジェクト null コントロールの UI のさまざまな要素を構成するメンバーを持つオブジェクト。このオブジェクトのプロパティを指定するには、次に示すようにオブジェクト リテラル表記を使用できます。 
{label: 'Name', labelSeparator: ':'}
ui.realtimeTrigger boolean true キーが押されたときにコントロールが一致するか、入力フィールドが変更されたとき（フォーカス喪失または Enter キーの押下）にのみ一致させるかを指定します。
ui.label string 自動 入力フィールドの横に表示するラベル。指定しない場合、コントロールが操作する列のラベルが使用されます。
ui.labelSeparator string none ラベルと入力フィールドとを視覚的に区別するためにラベルに追加される区切り文字。
ui.labelStacking string 「横向き」 ラベルを入力フィールドの上（縦に積み重ねる）または横（横に積み重ねる）に表示するかどうか。'vertical' または 'horizontal' を使用します。
ui.cssClass string 'google-visualization-controls-stringfilter' カスタム スタイル設定のために、コントロールに割り当てる CSS クラス。