ビジュアリゼーションでは、ホストページで受信できるイベントを登録できます。イベントは、ユーザー アクションによって発生する場合があります。たとえば、ユーザーがグラフをクリックした場合や、ユーザーが 10 秒ごとにイベントを配信するなど、内部でトリガーされる場合があります。特定のイベントが発生するたびに呼び出される JavaScript メソッドを登録して、場合によってはそのイベントに固有のデータを持つことができます。
すべてのビジュアリゼーションは独自のイベントを定義します。各ビジュアリゼーションのドキュメントでは、各イベントが発生したタイミング、その意味、イベント ハンドラに送信される情報について説明します(たとえば、orgchart のビジュアリゼーションをご覧ください)。このページでは、可視化を行うクリエイターがイベントを発生させる方法について説明します。クライアントがイベントを受信する登録方法については、イベントの処理ページをご覧ください。
選択可能なビジュアリゼーションが呼び出すイベントには、select イベントがあります。 ただし、このイベントの動作と意味は各ビジュアリゼーションによって定義されます。
draw
メソッドがユーザーに制御を返す直後に、ビジュアリゼーションの準備ができていない場合、ビジュアリゼーションは Ready イベントを呼び出します。
このイベントの正確な動作と意味については、Ready イベントをご覧ください。
Visualization API イベントは、標準の DOM イベントとは異なることに注意してください。
目次
イベントを呼び出す
ビジュアリゼーションからイベントを呼び出すには、google.visualization.events.trigger()
関数を呼び出します。関数には次のパラメータが必要です。
- ソースの可視化(通常は
this
の値)。 - イベント名(文字列)。
- イベントの詳細(オブジェクト)。特定のイベントの詳細のマップ(名前/値)。
次の例は、ビジュアリゼーションが選択イベントをスローする方法を示しています。
MyVisualization.prototype.onclick = function(rowIndex) { this.highlightRow(this.selectedRow, false); // Clear previous selection this.highlightRow(rowIndex, true); // Highlight new selection // Save the selected row index in case getSelection is called. this.selectedRow = rowIndex; // Fire a select event. google.visualization.events.trigger(this, 'select', {}); };
Hosting ページは、google.visualization.events.addListener()
または google.visualization.events.addOneTimeListener()
を呼び出して、イベントを受信するように登録できます。発生したイベントはすべて記録する必要があります。
イベントを選択
「選択」イベントは、ユーザーのマウスクリックに応じて多くのビジュアリゼーションによってスローされる標準的なイベントです。マウスのクリックに応じてイベントを呼び出す場合は、以下の標準的な方法で「選択」イベントを実装する必要があります。
- ユーザーがビジュアリゼーション内のデータを選択すると、「select」という名前のイベントが発生します。イベントでは、リッスン関数に引数は送信されません。
- リンク先のドキュメントのセクションの説明に沿って
getSelection()
メソッドを公開します。このメソッドは、ユーザーが選択したデータ要素のインデックスを返します。
- リファレンス セクションで説明されているように、
setSelection()
メソッドを公開します。イベントの処理方法について、イベントの処理ページもご覧ください。
Ready イベント
すべてのビジュアリゼーションは、メソッドと呼ばれるビジュアリゼーションを処理する準備が整ったことをデベロッパーに知らせるために、標準的な方法で機能する「ready」イベントを呼び出します。(ただし、ビジュアリゼーションがこのように動作するという絶対的な要件はありません)。ビジュアリゼーションのドキュメントを確認してください。
一般に、「ready」イベントを公開する可視化は、次の仕様で設計されています。
- ready イベントはハンドラにプロパティを渡しません(関数ハンドラはパラメータを渡すことを期待できません)。
- ビジュアリゼーションは、操作の準備が整った後に Ready イベントを呼び出す必要があります。ビジュアリゼーションの描画が非同期の場合は、
draw
メソッドが終了したときだけでなく、操作メソッドを実際に呼び出せるときにもイベントが発生します。 - このイベントにリスナーを追加することは、
draw
メソッドを呼び出す前に行う必要があります。そうしないと、リスナーの設定前にイベントが発生してリスナーをキャッチできないためです。 - ready イベントが発生する前に操作メソッドを呼び出すと、このメソッドが正常に機能しないリスクがあります。
慣例では、「準備完了」イベントを起動しない可視化は、draw
メソッドが終了した直後に操作の準備が整い、ユーザーに制御を返します。