Активация событий

Ваша визуализация может запускать события, на получение которых может зарегистрироваться хост-страница. События могут запускаться действиями пользователя: например, пользователь щелкает диаграмму, или могут быть внутренними: например, запуск события каждые 10 секунд. Вы можете зарегистрировать метод Javascript, который будет вызываться всякий раз, когда запускаются определенные события, возможно, с данными, специфичными для этого события.

Каждая визуализация определяет свои собственные события, и документация для этой визуализации должна описывать, когда запускается каждое событие, что оно означает и какую информацию оно отправляет обработчику событий (например, см . визуализацию организационной диаграммы ). На этой странице описывается, как создатель визуализации может запускать события. Чтобы узнать, как клиенты могут зарегистрироваться для получения событий, см. страницу « Обработка событий ».

Существует одно событие, которое должна активировать любая выбираемая визуализация: событие выбора. Однако поведение и значение этого события определяются каждой визуализацией.

Если визуализация не готова к взаимодействию сразу после того, как метод draw возвращает управление пользователю, визуализация должна сработать: событие готовности. Точное поведение и значение этого события определены в разделе «Событие готовности ».

Важно отметить, что события API визуализации отделены от стандартных событий DOM.

Содержание

  1. Запуск события
  2. Выбранное событие
  3. Готовое событие
  4. Дополнительная информация

Запуск события

Чтобы вызвать событие из вашей визуализации, вызовите google.visualization.events.trigger() . Функция ожидает следующие параметры:

  1. Исходная визуализация (обычно это значение this ).
  2. Название события (строка).
  3. Детали события (Объект). Необязательная карта (имя/значение) конкретных сведений о событии.

В следующем примере показано, как визуализация вызывает событие select:

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', {});
};

Страницы хостинга могут зарегистрироваться для получения ваших событий, вызвав google.visualization.events.addListener() или google.visualization.events.addOneTimeListener() . Обязательно тщательно документируйте все запускаемые вами события.

Выбранное событие

Событие «выбрать» — это стандартное событие, вызываемое многими визуализациями в ответ на щелчок мыши пользователя. Если вы решите запускать событие в ответ на щелчки мыши, вы должны реализовать событие «выбрать» стандартным способом, описанным здесь:

  1. Инициировать событие с именем «выбрать», когда пользователь выбирает некоторые данные в визуализации. Событие не отправляет никаких аргументов прослушивающим функциям.
  2. Предоставьте метод getSelection() , как описано в разделе связанного документа. Этот метод должен возвращать индексы элементов данных , выбранных пользователем.
  3. Предоставьте метод setSelection() , как описано в справочном разделе. Также см. страницу обработки событий , чтобы узнать, как обрабатывать события.

Готовое событие

Любая визуализация должна запускать событие «готово», которое работает стандартным образом, чтобы сообщить разработчику, когда визуализация готова для обработки вызываемых методов. (Однако нет абсолютного требования , чтобы визуализация вел себя именно так; проверьте документацию по вашей визуализации).

Как правило, визуализации, отображающие событие «готово», разрабатываются со следующими характеристиками:

  • Событие ready не передает обработчику никаких свойств (ваш обработчик функции не должен ожидать, что ему будут переданы какие-либо параметры).
  • Визуализация должна запускать событие готовности после того, как визуализация готова к взаимодействию. Если отрисовка визуализации является асинхронной, важно, чтобы событие запускалось, когда методы взаимодействия действительно могут быть вызваны, а не только после завершения метода draw .
  • Добавление слушателя к этому событию должно быть сделано до вызова метода draw , потому что в противном случае событие может быть запущено до того, как слушатель настроен, и вы его не перехватите.
  • Вызывая методы взаимодействия до того, как сработает событие готовности, вы рискуете тем, что эти методы не будут работать должным образом.

Соглашение заключается в том, что визуализации, которые не запускают событие «готово», готовы к взаимодействию сразу после завершения метода draw и возврата управления пользователю.

Дополнительная информация