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

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

概要

ダッシュボードは、同じ基礎データを共有する複数のグラフを 1 つのテーブルにまとめて整理する簡単な方法です。このページで説明する API を使用することで、ダッシュボードを構成するすべてのグラフを連携させ、調整する負担から解放されます。

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

コントロールは、ダッシュボードとそれらのグラフの一部であるグラフによって管理されるデータを操作するために操作するユーザー インターフェース ウィジェット(カテゴリ選択ツール、範囲スライダー、オートコンプリートなど)です。

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

カテゴリ選択ツールと範囲スライダーを使用して、円グラフで視覚化されたデータを取得する例を次に示します。

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

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

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

  1. ダッシュボードの HTML スケルトンを作成しますダッシュボードのすべてのメンバーを保持するために必要な数の HTML 要素がページに含まれている必要があります。これには、ダッシュボード自体と、ダッシュボードに含まれるすべてのコントロールとグラフが含まれます。通常は各タグに対して <div> を使用します。
  2. ライブラリを読み込む。ダッシュボードに追加または読み込む必要があるライブラリは、Google AJAX API と Google 可視化 API の 2 つのみです。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 Visualization API の 2 つのみです。controlsAPI(特に 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() がハンドラ関数を呼び出すため、必要なヘルパー メソッドとクラスがすべてデータの準備をすぐに開始できます。

ダッシュボードでは、グラフと同じように 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 パラメータを指定しないでください。ダッシュボードは、それぞれに適切なデータをフィードします。必ず必須パラメータ(チャートの場合は chartTypecontainerId、コントロールの場合は controlTypecontainerId)を指定してください。

コントロールとグラフの設定に関するヒントをいくつか紹介します。

  • すべてのコントロールに 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);

コントロールとグラフは、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() メソッドは、ダッシュボードを強化する DataTable(または DataView)の 1 つのパラメータのみを受け取ります。

ダッシュボードの構成を変更する(新しいコントロールやグラフを追加するなど)たびに draw() を呼び出すか、ダッシュボードの基となる DataTable 全体を変更するたびに呼び出す必要があります。

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
ダッシュボード コンテンツを保持するページ内の有効なコンテナ要素への参照。

Methods

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

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

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

  • controls - バインドするコントロールを定義する、1 つまたは 2 つの google.visualization.ControlWrapper インスタンスの配列。
  • チャート - コントロールによって制御されるグラフを定義する google.visualization.ChartWrapper インスタンスのいずれか 1 つまたは配列。
draw(dataTable) なし

ダッシュボードを描画します。

getSelection() オブジェクトの配列

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

注: 選択イベントのイベント リスナーは、リッスンする各グラフに添付する必要があります。

詳細説明

イベント

ダッシュボード オブジェクトは次のイベントをスローします。イベントがスローされる前に Dashboard.draw() を呼び出す必要があります。

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

ダッシュボードは描画を完了し、変更を受け入れる準備が整っています。ダッシュボードに含まれるすべてのコントロールとグラフで、外部メソッドの呼び出しとユーザーの操作が可能になります。ダッシュボード(または描画されるデータ)を変更したいときは、draw メソッドを呼び出す前に、このイベントのリスナーをセットアップし、イベントが発生した後にのみ変更を適用する必要があります。

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

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

コントロール ラッパー

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

コンストラクタ

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

Methods

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

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

コントロールを描画します。通常、コントロールを保持するダッシュボードが描画を処理します。draw() を呼び出して、オプションや状態など、他の設定を変更した後、コントロールがプログラムによって再描画されるようにする必要があります。

toJSON() String コントロールの JSON 表現の文字列バージョンを返します。
clone() ControlWrapper コントロール ラッパーのディープコピーを返します。
getControlType() String コントロールのクラス名。これが Google のコントロールである場合、名前には google.visualization は修飾されません。たとえば、CategoryFilter コントロールの場合、「google.visualization.CategoryFilter」ではなく「CategoryFilter」を返します。
getControlName() String setControlName() によって割り当てられたコントロール名を返します。
getControl() コントロール オブジェクトの参照 この ControlWrapper で作成されたコントロールへの参照を返します。ControlWrapper オブジェクト(またはそれを保持するダッシュボード)で draw() を呼び出し、Ready イベントがスローされるまで、null を返します。返されたオブジェクトは 1 つのメソッド resetControl() のみを公開します。このメソッドは、コントロールの状態を初期化された状態(HTML フォーム要素のリセットなど)にリセットします。
getContainerId() String コントロールの 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() を呼び出します。 なし

グラフのラッパー

可視化の API リファレンス セクションの google.visualization.ChartWrapper ドキュメントをご覧ください。

ダッシュボードの一部として ChartWrapper を使用する場合は、次の点に注意してください。

  • dataTablequerydataSourceUrlrefreshInterval 属性を明示的に設定しないでください。グラフを保持するダッシュボードが、必要なデータをフィードします。
  • コントロール グループとグラフ インスタンスの作成に示すように、view 属性を設定して、ダッシュボードで指定された dataTable に存在するすべての列のうち、グラフに関連する列を宣言します。

フィルタは、グラフに表示するデータをインタラクティブに選択できるグラフィック要素です。このセクションでは、Google グラフのフィルタである CategoryFilterChartRangeFilterDateRangeFilterNumberRangeFilterStringFilter について説明します。

いずれのパラメータも ControlWrapper.setControlType() のパラメータとして使用できます。

注: オプションを説明する際は、ネストされたオブジェクト属性を表すためにドット表記が使用されます。たとえば、'ui.label' という名前のオプションは、options オブジェクト内で var options = {"ui": {"label": "someLabelValue"} }; として宣言する必要があります。

カテゴリフィルタ

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

State

名前 タイプ Default 説明
selectedValues オブジェクトまたはプリミティブ型の配列 none 現在選択されている値のセット。選択した値は、values オプションで定義された選択可能な値全体のセットにする必要があります(無関係な値は無視されます)。CategoryFilter で複数選択できない場合は、配列の最初の値のみが保持されます。

オプション

名前 タイプ Default 説明
filterColumnIndex 数値 none フィルタの動作対象となるデータテーブルの列です。このオプションまたは filterColumnLabel のいずれかは必須です。両方が存在する場合は、このオプションが優先されます。
filterColumnLabel 文字列 none フィルタを適用する列のラベル。このオプションまたは filterColumnIndex のいずれかは必須です。両方が存在する場合は、filterColumnIndex が優先されます。
values 配列 自動 選択できる値のリスト。Objects の配列を使用する場合は、ユーザーに表示する適切な toString() 表現が必要です。null または未定義の場合、このコントロールが動作している DataTable 列に存在する値から値のリストが自動的に計算されます。
useFormattedValue boolean false このフィルタは、実際のセル値を使用するか、書式設定された値を使用するかにかかわらず、DataTable 列から選択可能な値のリストを自動的に入力するときに機能します。
ui オブジェクト null コントロールの UI のさまざまな面を構成するメンバーを含むオブジェクト。このオブジェクトのプロパティを指定するには、次のようにオブジェクト リテラル表記を使用します。
{label: 'Metric', labelSeparator: ':'}
UI キャプション 文字列 「値を選択...」 アイテムが選択されていないときに値選択ツール ウィジェット内に表示される字幕。
ui.sortValues boolean true 選択する値を並べ替えるかどうか。
ui.selectedValuesLayout 文字列 「サイド」 複数の選択が許可されている場合に、選択された値を表示する方法。有効な値は次のとおりです。
  • 'aside': 選択した値が、値選択ツール ウィジェットの横に 1 行で表示されます。
  • 'below': 選択した値が、ウィジェットの下に 1 行で表示されます。
  • 'belowWrapping': below に似ていますが、選択ツールに収まらないエントリは改行で改行されます。
  • 'belowStacked': 選択した値が、ウィジェットの下の列に表示されます。
ui.allowNone boolean true ユーザーに値の選択を許可しないかどうか。false の場合、ユーザーは使用可能な値の中から少なくとも 1 つの値を選択する必要があります。制御の初期化中にオプションが false に設定され、selectedValues 状態が指定されていない場合、使用可能な値の最初の値が自動的に選択されます。
ui.allowMultiple boolean true 1 個だけでなく複数の値を選択できるかどうか。
ui.allowTyping boolean true ユーザーがテキスト フィールドに入力し、(Autocompleteer を介して)可能な選択肢のリストを絞り込むことができるかどうか。
UI ラベル 文字列 自動 カテゴリ選択ツールの横に表示するラベル。指定しない場合は、コントロールの対象である列のラベルが使用されます。
ui.labelSeparator 文字列 none ラベルをカテゴリ選択ツールから視覚的に分離するラベルの区切り文字列。
ui.labelStacking 文字列 「horizontal」 ラベルをカテゴリ選択ツールの上(縦に重ねる場合)または横(横に重ねる場合)に表示するかどうか。'vertical' または 'horizontal' を使用します。
ui.cssClass 文字列 「google-visualization-controls-categoryfilter」 コントロールに割り当てる CSS クラス(カスタム スタイル設定用)

グラフの範囲フィルタ

2 つの親指が重ねられたスライダー。グラフの連続軸から値の範囲を選択します。

State

名前 タイプ Default 説明
range.start 数値、日付、日時、時刻 範囲の開始値 選択した範囲の開始値(指定した値を含む)。
range.end 数値、日付、日時、時刻 範囲の終了値 選択した範囲の終了値(指定した値を含む)。

オプション

名前 タイプ Default 説明
filterColumnIndex 数値 none フィルタが適用されるデータテーブル内の列のインデックス。このオプションまたは filterColumnLabel のいずれかは必須です。両方が存在する場合は、このオプションが優先されます。

コントロール内に描画されるグラフの連続軸で表されるドメイン列のインデックスを指定することだけは、意味があることに注意してください。

filterColumnLabel 文字列 none フィルタが適用されるデータテーブルの列のラベル。このオプションまたは filterColumnIndex のいずれかは必須です。両方が存在する場合は、filterColumnIndex が優先されます。

コントロール内に描画されるグラフの連続軸に盛り込まれた domain 列のラベルを指定することのみが適切です。

ui オブジェクト null コントロールの UI のさまざまな面を構成するメンバーを含むオブジェクト。このオブジェクトのプロパティを指定するには、次のようにオブジェクト リテラル表記を使用します。
{chartType: 'ScatterChart', chartOptions: {pointSize: 10}}
ui.chart のタイプ 文字列 「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 チャート オブジェクトまたは文字列(シリアル化されたオブジェクト) null コントロール内のグラフの描画に使用するデータテーブルに適用するビューの仕様。ダッシュボードのどのグラフと同じレベルの構成を許可し、ChartWrapper.setView() で受け入れられる形式に従います。指定しなかった場合、データテーブル自体がグラフの描画に使用されます。

描画したグラフの横軸は連続する必要があるため、それに応じて ui.chartView を指定するように注意してください。

ui.minRangeSize 数値 1 ピクセルと解釈されるデータ値の差 データ値で指定される最小選択可能範囲サイズ(range.end - range.start)。数値軸の場合、これは数値です(必ずしも整数であるとは限りません)。日付、日時、または日時の軸の場合、差をミリ秒単位で指定する整数です。
ui.snapToData boolean false true の場合、つまみは最も近いデータポイントにスナップされます。この場合、getState() によって返される範囲の終点は、必ずしもデータテーブル内の値です。

イベント

ControlWrapper イベントへの追加:

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

期間フィルタ

期間を選択するためのデュアル値のスライダー。

スライダーを動かして、下の表に表示する行を変更します。

State

名前 タイプ Default 説明
低値 数値 none 選択した範囲の下限(指定した値を含む)。
高価値 数値 none 選択した範囲の上位(両端を含む)。
LowThumbAtMinimum boolean none スライダーのつまみが最小許容範囲内にロックされているかどうか。設定すると、lowValue がオーバーライドされます。
highThumbAtMaximum boolean none スライダーの親指の高さが最大許容範囲でロックされているかどうか。設定すると、highValue がオーバーライドされます。

オプション

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

NumberRangeFilter

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

State

名前 タイプ Default 説明
低値 数値 none 選択した範囲の下限(指定した値を含む)。
高価値 数値 none 選択した範囲の上位(両端を含む)。
LowThumbAtMinimum boolean none スライダーのつまみが最小許容範囲内にロックされているかどうか。設定すると、lowValue がオーバーライドされます。
highThumbAtMaximum boolean none スライダーの親指の高さが最大許容範囲でロックされているかどうか。設定すると、highValue がオーバーライドされます。

オプション

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

文字列フィルタ

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

State

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

オプション

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