Обработка событий

На этой странице описывается, как прослушивать и обрабатывать события, создаваемые диаграммой.

Содержание

  1. Обзор
  2. Регистрация и проведение мероприятия
  3. Получение информации о событии
  4. Выбранное событие
  5. Готовое событие
  6. Событие ошибки
  7. Пример обработки событий

Обзор

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

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

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

Важно отметить, что события диаграммы отделены от стандартных событий DOM.

Регистрация и проведение мероприятия

Чтобы зарегистрировать обработчики событий, вы вызываете google.visualization.events.addListener() или addOneTimeListener() указав имя диаграммы, отображающей событие, имя строки события, которое нужно прослушивать, и имя функции, которая будет вызываться, когда это событие запускается. Ваша функция должна принимать один параметр, который является событием, которое было запущено. Это событие может содержать пользовательскую информацию о событии, как описано в документации по диаграмме.

Важно: если ваша диаграмма предоставляет событие готовности , вам всегда следует ждать, пока это событие будет запущено, прежде чем пытаться отправлять методы или получать события из диаграммы. Эти диаграммы могут работать до того, как они создадут событие готовности, но такое поведение не гарантировано.

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

// 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']);
}

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

Информация о событии передается глобальному объекту

Вместо этого некоторые события изменяют свойство глобального объекта, которое затем можно запросить. Типичным примером этого является событие «select», которое вызывается, когда пользователь выбирает часть диаграммы. В этом случае код должен вызвать getSelection() на диаграмме, чтобы узнать, какой текущий выбор. Более подробная информация о событии выбора приведена ниже.

// 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.');

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

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

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

  • Событие выбора не передает обработчику никаких свойств или объектов (обработчик функции не должен ожидать передачи ему каких-либо параметров).
  • Диаграмма должна предоставлять метод getSelection() , который возвращает массив объектов, описывающих выбранные элементы данных. Эти объекты имеют свойства row и column . row и column — это индексы строк и столбцов выбранного элемента в DataTable . (События выбора описывают базовые данные на графике, а не элементы HTML на диаграмме.) Чтобы получить данные выбранного элемента, вам придется вызвать DataTable.getValue() или getFormattedValue() .
    Если указаны и row , и column , выбранным элементом является ячейка. Если указана только row , выбранный элемент является строкой. Если указан только column , выбранный элемент является столбцом.
  • Диаграмма должна предоставлять метод setSelection(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);
}

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

Большинство диаграмм отображаются асинхронно; все диаграммы Google выдают событие готовности после вызова draw() , что указывает на то, что диаграмма визуализируется и готова возвращать свойства или обрабатывать дальнейшие вызовы методов. Вы всегда должны прослушивать событие готовности, прежде чем пытаться вызвать его методы после вызова draw() .

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

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

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

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

Синтаксис готового обработчика событий

function myReadyHandler(){...}

Обработчику события готовности не передаются никакие параметры.

Событие ошибки

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

Вы можете использовать вспомогательные функции goog.visualization.errors , чтобы корректно отображать любые ошибки пользователю.

Синтаксис обработчика событий ошибок

function myErrorHandler(err){...}

Обработчику события ошибки должен быть передан объект со следующими членами:

  • id [ Обязательный ] — идентификатор элемента DOM, содержащего диаграмму, или сообщение об ошибке, отображаемое вместо диаграммы, если ее невозможно отобразить.
  • message [ Обязательно ] — короткая строка сообщения, описывающая ошибку.
  • DetailMessage [ Необязательно ] — подробное объяснение ошибки.
  • options [ Необязательно ] — объект, содержащий пользовательские параметры, соответствующие этой ошибке и типу диаграммы.

Пример обработки событий

В следующем примере демонстрируются как getSelection(), так и setSelection(). Он синхронизирует выбор между двумя диаграммами, использующими одну и ту же таблицу данных. Нажмите на любую диаграмму, чтобы синхронизировать выбор на другой диаграмме.

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

Нажмите на диаграммы ниже в строках таблицы или на элементах диаграммы, чтобы увидеть выбор в действии: