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

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

Содержание

Обзор

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

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

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

Важно отметить, что события диаграммы отделены и отличаются от стандартных событий 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']);
}

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

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

Вместо этого некоторые события изменяют свойство глобального объекта, которое затем можно запросить. Типичным примером этого является событие select, которое запускается, когда пользователь выбирает часть диаграммы. В этом случае код должен вызвать 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 не передает обработчику никаких свойств или объектов (ваш обработчик функции не должен ожидать, что ему будут переданы какие-либо параметры).
  • Диаграмма должна предоставлять метод 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() .

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

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

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

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

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

function myReadyHandler(){...}

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

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

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

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

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

function myErrorHandler(err){...}

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

  • id [ Обязательный ] — идентификатор элемента DOM, содержащего диаграмму, или сообщение об ошибке, отображаемое вместо диаграммы, если она не может быть отображена.
  • message [ Обязательный ] — короткая строка сообщения, описывающая ошибку.
  • подробное сообщение [ Необязательный ] — Подробное объяснение ошибки.
  • 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());
});

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