イベント処理

Stay organized with collections Save and categorize content based on your preferences.

このページでは、グラフで発生したイベントをリッスンして処理する方法について説明します。

目次

概要

Google チャートでは、リッスン可能なイベントを発生させることができます。イベントは、ユーザーがグラフをクリックしたときになど、ユーザー アクションによってトリガーされます。特定のイベントが発生するたびに(場合によってはそのイベント固有のデータを使用して)呼び出される JavaScript メソッドを登録できます。

すべてのグラフは独自のイベントを定義します。そのチャートのドキュメントには、各イベントが発生したタイミング、意味、およびイベントに関連する情報を返す方法が記載されています。このページでは、グラフからイベントを受信するために登録する方法と、イベントを処理する方法について説明します。

選択可能なチャートが起動するイベントには、select イベントがあります。 ただし、このイベントの動作と意味は、各グラフで定義されます。

グラフ イベントは標準の DOM イベントとは異なるため、注意が必要です。

イベントの登録と処理

イベント ハンドラを登録するには、イベントを公開するグラフの名前、リッスンするイベントの文字列名、イベントが発生したときに呼び出す関数の名前を指定して、google.visualization.events.addListener() または addOneTimeListener() を呼び出します。関数は、発生したイベントである単一のパラメータを受け入れる必要があります。グラフのドキュメントに記載されているように、このイベントにはイベントに関するカスタム情報を含めることができます。

重要: グラフで準備完了のイベントが公開されている場合は、常に、そのイベントが発生するのを待ってから、グラフのメソッドの送信やイベントの受信を試みます。これらのグラフは Ready イベントをスローする前に動作することがありますが、この動作は保証されていません。

次のコード スニペットは、ユーザーが表の行をクリックするたびにアラート ボックスを表示する方法を示しています。

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

これは、この特定のテーブル オブジェクトのイベントをリッスンするためにのみ登録されます。特定のオブジェクトからイベントを受信することのみを登録できます。

次のように、関数定義を渡すこともできます。

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

イベント情報の取得

一般に、イベントは、2 つの方法で情報をハンドラ関数にパラメータとして渡すか、グローバル オブジェクトに情報を追加します。イベントが情報を公開するかどうか、およびどのように公開するかについては、そのグラフのドキュメントをご覧ください。両方のタイプの情報を取得する方法は次のとおりです。

ハンドラに渡されるイベント情報

グラフがパラメータとしてデータを処理する関数に渡す場合、そのデータは次のように取得されます。

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

ハンドラに渡されるパラメータには、グラフとして文書化する必要があるプロパティがあります。この方法でイベント情報を公開するグラフの例については、グラフのページイベントをご覧ください。

グローバル オブジェクトに渡されるイベント情報

一部のイベントではグローバル オブジェクトのプロパティが変更され、そのプロパティをリクエストできます。典型的な例は「select」イベントです。このイベントは、ユーザーがグラフの一部を選択すると発生します。この場合、コードでグラフの getSelection() を呼び出して、現在の選択内容を確認する必要があります。詳しくは、以下の select イベントで詳しく説明します。

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');
  

select イベント

前述のように、選択可能なグラフでは、標準的な方法で動作する「select」イベントが呼び出され、チャート内の選択されたアイテムの値が取得されます。(ただし、グラフがこのように動作するという絶対的な要件はありません。グラフのドキュメントを確認してください)。

通常、「select」イベントを公開するグラフは、次の仕様で設計されています。

  • select イベントではハンドラにプロパティやオブジェクトが渡されません(関数ハンドラではハンドラにパラメータを渡されません)。
  • グラフでは、メソッド getSelection() を公開する必要があります。このメソッドは、選択したデータ要素を記述するオブジェクトの配列を返します。これらのオブジェクトのプロパティは rowcolumn です。rowcolumn は、DataTable で選択されたアイテムの行インデックスと列インデックスです。(選択イベントは、グラフ内の HTML 要素ではなく、グラフの基となるデータを記述します)。選択したアイテムのデータを取得するには、DataTable.getValue() または getFormattedValue() を呼び出す必要があります。
    rowcolumn の両方が指定されている場合、選択された要素はセルになります。row のみが指定されている場合、選択された要素は行です。column のみが指定されている場合、選択された要素は列です。
  • グラフでは、メソッド setSelection(selection) を公開して、基になるテーブルでの選択を変更し、グラフ内の対応するデータを選択することが推奨されます。selection パラメータは getSelection() 配列に似た配列です。各要素は、プロパティ rowcolumn を含むオブジェクトです。row プロパティは DataTable の選択された行のインデックスを定義し、column プロパティは DataTable の選択された列のインデックスを定義します。このメソッドが呼び出されると、グラフには、新しい選択が視覚的に表示されるようになります。setSelection() の実装では、「選択」イベントをトリガーしないでください
    rowcolumn の両方が指定されている場合、選択された要素はセルになります。row のみが指定されている場合、選択された要素は行です。column のみが指定されている場合、選択された要素は列です。

注意点:

  • グラフでは、選択の一部が無視される場合があります。選択した行のみを表示できるテーブルでは、setSelection の実装でセル要素や列要素を無視することがあります)。
  • グラフによっては、「選択」イベントがトリガーされない場合があります。また、グラフによっては、行の選択全体または列の選択のみをサポートしている場合もあります。各グラフのドキュメントでは、サポートされるイベントとメソッドを定義しています。
  • 複数選択の扱いはグラフによって異なります(完全には許可されない場合もあります)。
  • 選択したデータを読み取るには、ハンドラで DataTable.getValue() を呼び出す必要があります。これを有効にする最も簡単な方法は、DataTable オブジェクトをグローバルにすることです。

次の例では、表グラフの要素が選択されたときに、選択した表要素を含むアラートボックスをポップアップします。

表グラフでは行選択イベントのみが呼び出されますが、コードは汎用であり、行、列、セルの選択イベントに使用できます。

この例のハンドラコードは次のとおりです。

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

Ready イベント

ほとんどのグラフは非同期でレンダリングされます。すべての Google チャートは、draw() を呼び出した後、準備完了イベントをスローします。これにより、チャートがレンダリングされたことを示します。また、プロパティを返すか、以降のメソッド呼び出しを処理する準備が整います。draw() を呼び出した後は、必ず Ready イベントをリッスンしてからメソッドを呼び出してください。

一般に、「Ready」イベントを公開するグラフは、次の仕様で設計されています。

  • 準備完了イベントではハンドラにプロパティを渡しません(関数ハンドラではパラメータを渡すことはありません)。
  • グラフは、操作の準備が整った後に Ready イベントを発生させる必要があります。グラフの描画が非同期の場合、draw メソッドの終了時だけでなく、操作メソッドが実際に呼び出されたときにイベントが呼び出されることが重要です。
  • draw() メソッドを呼び出す前に、このイベントにリスナーを追加する必要があります。そうしないと、リスナーの設定前にイベントが発生してリスナーがキャッチしない可能性があります。
  • 準備完了イベントが発生する前に操作メソッドを呼び出すと、このメソッドが正しく機能しなくなるおそれがあります。

慣例では、「準備完了」イベントを起動しないグラフは、draw メソッドが終了した直後に操作の準備ができて、ユーザーに制御を返します。グラフが準備完了イベントを発生させた場合は、次のように、メソッドを呼び出す前にスローされます。

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

Ready イベント ハンドラの構文

function myReadyHandler(){...}

準備完了のイベント ハンドラにパラメータは渡されません。

error イベント

グラフが適切に処理されるように、なんらかのエラーが発生した場合にエラーイベントをスローする必要があります。イベント ハンドラには、エラーの説明と、各グラフに固有のカスタム イベント プロパティが渡されます。グラフをインスタンス化したらすぐにこのイベントに登録して、後続のステップで発生する可能性のあるエラーをトラップしてください。

goog.visualization.errors ヘルパー関数を使用して、ユーザーにエラーを適切に表示できます。

エラーイベント ハンドラの構文

function myErrorHandler(err){...}

エラーイベント ハンドラには、次のメンバーを持つオブジェクトを渡す必要があります。

  • id(必須)- グラフを含む DOM 要素の ID。または表示できない場合は、グラフの代わりにエラー メッセージが表示される。
  • message(必須)- エラーを説明する短いメッセージ文字列。
  • detailedMessage [省略可] - エラーの詳細な説明。
  • options(省略可)- このエラーとグラフの種類に適したカスタム パラメータを含むオブジェクト。

イベント処理の例

次の例は、getSelection() と setSelection() の両方を示しています。同じデータテーブルを使用する 2 つのグラフ間で選択を同期しています。一方のグラフをクリックすると、もう一方のグラフの選択が同期されます。

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

表の行またはグラフ要素に関する以下のグラフをクリックすると、実際の選択内容を確認できます。