このページは Cloud Translation API によって翻訳されました。

イベントを処理する

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

概要

Google グラフでは、リッスン可能なイベントを生成できます。イベントは、ユーザーによるグラフのクリックなどのユーザー操作によってトリガーされます。JavaScript メソッドを登録して、特定のイベントが発生するたびに（場合によっては、そのイベントに固有のデータとともに）呼び出すことができます。

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

選択可能なグラフを起動するには、select イベントが必要です。ただし、このイベントの動作と意味はグラフごとに定義されます。

グラフイベントは、標準の DOM イベントとは異なることに注意してください。

イベントの登録と処理

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

重要: グラフで ready イベントが公開されている場合は、必ずそのイベントが発生するのを待ってから、メソッドの送信やグラフからのイベントの受信を試みてください。これらのグラフは、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」イベントを公開するグラフは、以下の仕様に合わせて設計されています。

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

注意点:

グラフでは選択の一部が無視される場合があります。たとえば、選択した行のみを表示できるテーブルでは、setSelection の実装でセル要素や列要素を無視できます）。
グラフによっては、「select」イベントがトリガーされない場合もあります。また、グラフによっては、行全体または列全体の選択のみをサポートしている場合もあります。各グラフのドキュメントでは、グラフでサポートされるイベントとメソッドが定義されています。
複数選択の処理は、グラフによって方法が異なります（許可していないグラフもあります）。
選択したデータを読み取るには、ハンドラで 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() を呼び出すと ready イベントがスローされます。これは、グラフがレンダリングされ、プロパティを返したり、以降のメソッド呼び出しを処理したりできることを示します。draw() を呼び出した後にメソッドを呼び出そうとする前に、Ready イベントを常にリッスンする必要があります。

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

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

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

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

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

function myReadyHandler(){...}

ready イベントハンドラにはパラメータが渡されません。

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

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