Триггеры сценариев приложений вызывают выполнение указанной функции сценария ( функции триггера ) при каждом возникновении указанного события. Только определенные события могут вызвать срабатывание триггеров, и каждое приложение Google Workspace поддерживает свой набор событий.
При срабатывании триггера создается объект события . Эта структура JSON содержит сведения о произошедшем событии. Информация в структуре объекта события организована по-разному в зависимости от типа триггера.
После создания объекта события Apps Script передает его в качестве параметра триггерной функции. Триггерная функция — это функция обратного вызова, которую вы должны реализовать самостоятельно, чтобы предпринять необходимые действия для реагирования на событие. Например, в надстройке редактора триггер используется для создания пунктов меню надстройки при открытии документа. В этом случае вы реализуете триггерную функцию onOpen(e)
для создания пунктов меню, необходимых надстройке, возможно, используя данные в объекте события.
На этой странице представлены рекомендации по использованию триггеров в проектах надстроек редактора.
Типы триггеров надстроек редактора
Вы можете использовать большинство универсальных типов триггеров, доступных для проектов Apps Script в надстройках редактора, включая простые триггеры и большинство устанавливаемых триггеров . Точный набор доступных типов триггеров зависит от расширяемого приложения.
В следующей таблице показаны типы простых и устанавливаемых триггеров, которые могут использовать надстройки редактора, и приведены ссылки на соответствующие объекты событий:
Событие | Объект события | Простые триггеры | Устанавливаемые триггеры |
---|---|---|---|
Открыть Открывается файл редактора. | Объект события onOpen Документов Объект события onOpen форм Объект события Sheets onOpen Объект события Slides onOpen | ![]() ![]() ![]() ![]() | ![]() ![]() ![]() |
Установить Дополнение установлено. | объект события onInstall | ![]() ![]() ![]() ![]() | |
Редактировать Содержимое ячейки электронной таблицы изменено. | Объект события onEdit Таблиц | ![]() | ![]() |
Изменять Содержимое листа редактируется или форматируется. | Объект события Sheets onChange | ![]() | |
Отправка формы Отправлена форма Google. | Объект события формы-отправки форм Объект события отправки формы в Таблицах | ![]() ![]() | |
Управляемый временем (часы) Триггер срабатывает в указанное время или интервал. | Объект события, управляемого временем | ![]() ![]() ![]() ![]() |
* Событие открытия для Google Forms происходит не тогда, когда пользователь открывает форму для ответа, а когда редактор открывает форму, чтобы изменить ее.
Простые триггеры в дополнениях
Простые триггеры используют набор зарезервированных имен функций, не могут использовать службы, требующие авторизации, и автоматически включаются для использования. В некоторых случаях вместо этого простое событие триггера может обрабатываться устанавливаемым триггером .
Вы можете добавить простой триггер в надстройку, просто реализовав функцию с одним из следующих зарезервированных имен:
-
onOpen(e)
выполняется, когда пользователь открывает документ, электронную таблицу или презентацию.onOpen(e)
также может выполняться при открытии формы в редакторе (но не при ответе на форму). Он выполняется только в том случае, если у пользователя есть разрешение на редактирование рассматриваемого файла, и чаще всего используется для создания пунктов меню . -
onInstall(e)
выполняется, когда пользователь устанавливает надстройку. ОбычноonInstall(e)
используется только для вызоваonOpen(e)
; это гарантирует, что дополнительные меню появятся сразу после установки, не требуя от пользователя обновления страницы. -
onEdit(e)
выполняется, когда пользователь изменяет значение ячейки в электронной таблице. Этот триггер не срабатывает в ответ на перемещение ячеек, форматирование или другие изменения, которые не меняют значений ячеек.
Ограничения
На простые триггеры в надстройках распространяются те же ограничения , что и на простые триггеры в других проектах Apps Script. Обратите особое внимание на эти ограничения при разработке надстроек:
- Простые триггеры не запускаются, если файл открыт в режиме только для чтения (просмотр или комментарий). Такое поведение предотвращает заполнение дополнительных меню.
- В определенных обстоятельствах надстройки редактора запускают простые триггеры
onOpen(e)
иonEdit(e)
в режиме без авторизации. Этот режим представляет некоторые дополнительные сложности, описанные в модели авторизации надстроек . - Простые триггеры не могут использовать сервисы или выполнять другие действия, требующие авторизации , за исключением случаев, описанных в модели авторизации надстройки .
- Простые триггеры не могут работать дольше 30 секунд. Позаботьтесь о том, чтобы минимизировать объем обработки, выполняемой в простой триггерной функции.
- На простые триггеры распространяются ограничения квоты триггеров Apps Script.
Устанавливаемые триггеры в дополнениях
Надстройки могут программно создавать и изменять устанавливаемые триггеры с помощью службы Apps Script Script
. Дополнительные устанавливаемые триггеры невозможно создать вручную. В отличие от простых триггеров, устанавливаемые триггеры могут использовать сервисы, требующие авторизации.
Устанавливаемые триггеры в надстройках не отправляют пользователю электронные письма об ошибках , когда они сталкиваются с ошибками, поскольку в большинстве случаев пользователь не может решить проблему. По этой причине вам следует спроектировать надстройку так, чтобы она корректно обрабатывала ошибки от имени пользователя, когда это возможно.
Дополнения могут использовать следующие устанавливаемые триггеры:
- Открытые устанавливаемые триггеры выполняются, когда пользователь открывает документ, электронную таблицу или форму в редакторе (но не при ответе на форму).
- Устанавливаемые триггеры редактирования выполняются, когда пользователь изменяет значение ячейки в электронной таблице. Этот триггер не срабатывает в ответ на форматирование или другие изменения, которые не меняют значения ячеек.
- Устанавливаемые триггеры изменений срабатывают, когда пользователь вносит какие-либо изменения в электронную таблицу, включая изменения форматирования и изменения самой электронной таблицы (например, добавление строки).
Устанавливаемые триггеры отправки формы срабатывают при отправке ответа формы Google.
Триггеры, управляемые временем (также называемые триггерами часов), срабатывают в определенное время или неоднократно через регулярный интервал времени.
Авторизация устанавливаемых триггеров
Обычно, если разработчик обновляет надстройку для использования новых сервисов, требующих дополнительной авторизации, пользователям предлагается повторно авторизовать надстройку при следующем ее использовании.
Однако надстройки, использующие триггеры, сталкиваются с особыми проблемами авторизации. Представьте себе надстройку, которая использует триггер для мониторинга отправки форм: создатель формы может авторизовать надстройку при первом ее использовании, а затем оставить ее работать на месяцы или годы, даже не открывая форму повторно. Если разработчик дополнения обновит дополнение для использования новых сервисов, требующих дополнительной авторизации, создатель формы никогда не увидит диалоговое окно повторной авторизации, поскольку он никогда не откроет форму повторно, и дополнение перестанет работать.
В отличие от триггеров в обычных проектах Apps Script, триггеры в надстройках продолжают срабатывать, даже если им требуется повторная авторизация. Однако сценарий по-прежнему завершается сбоем, если он попадает в строку кода, требующую авторизации, которой у сценария нет. Чтобы избежать этой ситуации, разработчики могут использовать метод ScriptApp.getAuthorizationInfo()
для ограничения доступа к частям кода, которые изменились между опубликованными версиями дополнения.
Ниже приведен пример рекомендуемой структуры для использования в триггерных функциях, чтобы избежать ошибок авторизации. Пример триггерной функции реагирует на событие отправки формы в надстройке Google Sheets и, если требуется повторная авторизация, отправляет пользователю надстройки электронное письмо с предупреждением, используя шаблонный HTML.
Код.gs
авторизацияemail.html
Ограничения
На устанавливаемые триггеры в надстройках распространяются те же ограничения , что и на устанавливаемые триггеры в других проектах Apps Script.
Помимо этих ограничений, к устанавливаемым триггерам в надстройках применяется несколько ограничений:
- Каждая надстройка может иметь только один триггер каждого типа для каждого пользователя и для каждого документа. Например, в данной электронной таблице у данного пользователя может быть только один триггер редактирования, хотя у пользователя также может быть триггер отправки формы или триггер, управляемый временем, в той же электронной таблице. Другой пользователь, имеющий доступ к той же электронной таблице, может иметь свой собственный набор триггеров.
- Дополнения могут создавать триггеры только для файла, в котором используется дополнение. То есть надстройка, используемая в Google Doc A, не может создать триггер для отслеживания открытия Google Doc B.
- Триггеры, управляемые временем, не могут запускаться чаще одного раза в час.
- Надстройки не отправляют пользователю электронное письмо автоматически, когда код, запускаемый устанавливаемым триггером, выдает исключение. Разработчик должен правильно проверять и обрабатывать случаи сбоев.
- Триггеры надстроек перестают срабатывать в любой из следующих ситуаций:
- Если надстройка удалена пользователем,
- Если надстройка отключена в документе (при повторном включении триггер снова становится работоспособным), или
- Если разработчик отменяет публикацию дополнения или отправляет неработающую версию в магазин дополнений.
- Дополнительные триггерные функции выполняются до тех пор, пока не достигнут кода, использующего неавторизованную службу, после чего они останавливаются. Это верно только в том случае, если надстройка опубликована; тот же триггер в обычном проекте Apps Script или неопубликованной надстройке вообще не выполняется, если какая-либо часть сценария требует авторизации.
- На устанавливаемые триггеры распространяются ограничения квоты триггеров Apps Script.