配信イベント

ビジュアリゼーションでは、ホストページで受信できるイベントを登録できます。イベントは、ユーザー アクションによって発生する場合があります。たとえば、ユーザーがグラフをクリックした場合や、ユーザーが 10 秒ごとにイベントを配信するなど、内部でトリガーされる場合があります。特定のイベントが発生するたびに呼び出される JavaScript メソッドを登録して、場合によってはそのイベントに固有のデータを持つことができます。

すべてのビジュアリゼーションは独自のイベントを定義します。各ビジュアリゼーションのドキュメントでは、各イベントが発生したタイミング、その意味、イベント ハンドラに送信される情報について説明します（たとえば、orgchart のビジュアリゼーションをご覧ください）。このページでは、可視化を行うクリエイターがイベントを発生させる方法について説明します。クライアントがイベントを受信する登録方法については、イベントの処理ページをご覧ください。

選択可能なビジュアリゼーションが呼び出すイベントには、select イベントがあります。 ただし、このイベントの動作と意味は各ビジュアリゼーションによって定義されます。

draw メソッドがユーザーに制御を返す直後に、ビジュアリゼーションの準備ができていない場合、ビジュアリゼーションは Ready イベントを呼び出します。 このイベントの正確な動作と意味については、Ready イベントをご覧ください。

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

目次

  1. イベントを呼び出す
  2. イベントを選択
  3. Ready イベント
  4. 詳細情報

イベントを呼び出す

ビジュアリゼーションからイベントを呼び出すには、google.visualization.events.trigger() 関数を呼び出します。関数には次のパラメータが必要です。

  1. ソースの可視化（通常は this の値）。
  2. イベント名（文字列）。
  3. イベントの詳細（オブジェクト）。特定のイベントの詳細のマップ（名前/値）。

次の例は、ビジュアリゼーションが選択イベントをスローする方法を示しています。

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() を呼び出して、イベントを受信するように登録できます。発生したイベントはすべて記録する必要があります。

イベントを選択

「選択」イベントは、ユーザーのマウスクリックに応じて多くのビジュアリゼーションによってスローされる標準的なイベントです。マウスのクリックに応じてイベントを呼び出す場合は、以下の標準的な方法で「選択」イベントを実装する必要があります。

  1. ユーザーがビジュアリゼーション内のデータを選択すると、「select」という名前のイベントが発生します。イベントでは、リッスン関数に引数は送信されません。
  2. リンク先のドキュメントのセクションの説明に沿って getSelection() メソッドを公開します。このメソッドは、ユーザーが選択したデータ要素のインデックスを返します。
  3. リファレンス セクションで説明されているように、setSelection() メソッドを公開します。イベントの処理方法について、イベントの処理ページもご覧ください。

Ready イベント

すべてのビジュアリゼーションは、メソッドと呼ばれるビジュアリゼーションを処理する準備が整ったことをデベロッパーに知らせるために、標準的な方法で機能する「ready」イベントを呼び出します。（ただし、ビジュアリゼーションがこのように動作するという絶対的な要件はありません）。ビジュアリゼーションのドキュメントを確認してください。

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

  • ready イベントはハンドラにプロパティを渡しません（関数ハンドラはパラメータを渡すことを期待できません）。
  • ビジュアリゼーションは、操作の準備が整った後に Ready イベントを呼び出す必要があります。ビジュアリゼーションの描画が非同期の場合は、draw メソッドが終了したときだけでなく、操作メソッドを実際に呼び出せるときにもイベントが発生します。
  • このイベントにリスナーを追加することは、draw メソッドを呼び出す前に行う必要があります。そうしないと、リスナーの設定前にイベントが発生してリスナーをキャッチできないためです。
  • ready イベントが発生する前に操作メソッドを呼び出すと、このメソッドが正常に機能しないリスクがあります。

慣例では、「準備完了」イベントを起動しない可視化は、draw メソッドが終了した直後に操作の準備が整い、ユーザーに制御を返します。

詳細情報