このページでは、グラフで発生したイベントをリッスンして処理する方法について説明します。
目次
概要
Google グラフでは、リッスン可能なイベントを発生させることができます。イベントは、ユーザーがグラフをクリックしたときになど、ユーザー アクションによってトリガーできます。特定のイベントが発生するたびに呼び出される JavaScript メソッドを登録し、場合によってはそのイベントに固有のデータを持つようにします。
すべてのグラフは独自のイベントを定義します。そのグラフのドキュメントには、各イベントが発生したタイミング、意味、イベントに関連付けられた情報の取得方法が記載されています。このページでは、グラフからイベントを受信する登録方法と、イベントの処理方法について説明します。
選択可能なグラフは、必ず 1 つのイベントで選択します。 ただし、このイベントの動作と意味は各グラフによって定義されます。
グラフのイベントは標準の 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()); });
イベント情報の取得
イベントは、一般的に、パラメータとしてハンドラ関数に情報を渡すか、グローバル オブジェクトに情報を追加します。イベントが情報を公開するかどうかと、その方法については、そのグラフのドキュメントをご覧ください。両方のタイプの情報を取得する方法は、次のとおりです。
ハンドラに渡されるイベント情報
グラフがパラメータとしてデータを処理関数に渡す場合は、次のように取得されます。
// 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']); }
ハンドラに渡されるパラメータには、グラフについて記述するプロパティがあります。このようにイベント情報を公開するグラフの例については、Table グラフのページイベントをご覧ください。
グローバル オブジェクトに渡されるイベント情報
イベントによっては、代わりにグローバル オブジェクトのプロパティを変更することで、そのプロパティをリクエストできます。その一般的な例は、ユーザーがグラフの一部を選択したときに呼び出される「選択」イベントです。この場合、チャートで 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()
の実装では、「選択」イベントをトリガーしてはなりません。row
とcolumn
を両方とも指定した場合、選択した要素がセルになります。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()
メソッドを呼び出す前に行う必要があります。そうしないと、リスナーの設定前にイベントが発生してリスナーをキャッチできないためです。 - ready イベントが発生する前に操作メソッドを呼び出すと、これらのメソッドが正常に機能しないおそれがあります。
慣例では、「準備完了」イベントを起動しないグラフは、draw
メソッドが終了した直後に操作の準備が整い、ユーザーに制御を戻します。グラフが準備完了イベントを発生させた場合は、次のように、このメソッドが呼び出されるまでメソッドを呼び出す必要があります。
google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);
Ready イベント ハンドラの構文
function myReadyHandler(){...}
ready イベント ハンドラにパラメータは渡されません。
error イベント
なんらかのエラーが発生した場合は、グラフを適切に処理できるようにエラーイベントをスローします。イベント ハンドラには、エラーの説明に加えて、各グラフに固有のカスタム イベント プロパティが渡されます。後でインスタンスで発生する可能性があるエラーをトラップするには、グラフをインスタンス化した直後にこのイベントに登録してください。
goog.visualization.errors
ヘルパー関数を使用して、エラーをユーザーに対して適切に表示できます。
エラーイベント ハンドラの構文
function myErrorHandler(err){...}
エラーイベント ハンドラには、次のメンバーを持つオブジェクトを渡す必要があります。
- id [必須] - グラフを含む DOM 要素の ID、またはグラフを表示できない場合にグラフの代わりにエラー メッセージを表示する。
- message [必須] - エラーを説明する短いメッセージ文字列。
- detailedMessage [省略可] - エラーの詳細な説明。
- オプション [省略可]- このエラーとグラフの種類に適したカスタム パラメータを含むオブジェクト。
イベント処理の例
次の例では、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()); });