Простые триггеры (original) (raw)

Триггеры позволяют Apps Script автоматически запускать функцию при наступлении определённого события, например, при открытии документа. Простые триггеры — это набор зарезервированных функций, встроенных в Apps Script, например, функция onOpen(e) , которая выполняется при открытии пользователем файла Google Docs, Sheets, Slides или Forms. Устанавливаемые триггеры предлагают больше возможностей, чем простые, но их необходимо активировать перед использованием. Для обоих типов триггеров Apps Script передаёт вызываемой функции объект события , содержащий информацию о контексте, в котором произошло событие.

Начиная

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

• onOpen(e) запускается, когда пользователь открывает электронную таблицу, документ, презентацию или форму, которые пользователь имеет разрешение редактировать.
• onInstall(e) запускается, когда пользователь устанавливает надстройку редактора из Google Docs, Sheets, Slides или Forms.
• onEdit(e) запускается, когда пользователь изменяет значение в электронной таблице.
• onSelectionChange(e) запускается, когда пользователь изменяет выбор в электронной таблице.
• doGet(e) запускается, когда пользователь посещает веб-приложение или программа отправляет HTTP-запрос GET веб-приложению.
• doPost(e) запускается, когда программа отправляет HTTP-запрос POST веб-приложению.

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

Ограничения

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

• Скрипт должен быть привязан к файлу Google Sheets, Slides, Docs или Forms или же представлять собой надстройку , расширяющую одно из этих приложений.
• Они не запускаются, если файл открыт в режиме только для чтения (просмотра или комментирования).
• Выполнение скриптов и запросы API не приводят к срабатыванию триггеров. Например, вызов Range.setValue() для редактирования ячейки не приводит к срабатыванию триггера onEdit электронной таблицы.
• Они не могут получить доступ к сервисам, требующим авторизации . Например, простой триггер не может отправить электронное письмо, поскольку сервис Gmail требует авторизации, но может перевести фразу с помощью сервиса Language , который является анонимным.
• Они могут изменять файл, к которому привязаны, но не могут получить доступ к другим файлам, поскольку для этого требуется авторизация.
• Они могут иметь или не иметь возможность определить личность текущего пользователя в зависимости от сложного набора ограничений безопасности .
• Они не могут работать дольше 30 секунд.
• В определённых обстоятельствах надстройки редактора запускают свои простые триггеры onOpen(e) и onEdit(e) в режиме без авторизации, что создаёт некоторые дополнительные сложности. Подробнее см. в руководстве по жизненному циклу авторизации надстроек .
• На простые триггеры распространяются ограничения квоты триггеров Apps Script.

Эти ограничения не распространяются на doGet(e) или doPost(e) .

onOpen(e)

Триггер onOpen(e) запускается автоматически, когда пользователь открывает электронную таблицу, документ, презентацию или форму, на редактирование которых у него есть разрешение. (Триггер не запускается при ответе на форму, а только при открытии формы для редактирования.) onOpen(e) чаще всего используется для добавления пользовательских пунктов меню в Google Таблицы, Презентации, Документы или Формы.

onInstall(e)

Триггер onInstall(e) запускается автоматически, когда пользователь устанавливает надстройку редактора из Google Docs, Sheets, Slides или Forms. Он не сработает, если пользователь установит надстройку с сайта Google Workspace Marketplace . Обратите внимание, что существуют определённые ограничения на действия onInstall(e) . Подробнее об авторизации читайте здесь. Чаще всего onInstall(e) используется для простого вызова onOpen(e) для добавления пользовательских меню. Ведь после установки надстройки файл уже открыт, и, следовательно, onOpen(e) не запустится самостоятельно, пока файл не будет открыт повторно.

onEdit(e)

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

onSelectionChange(e)

Триггер onSelectionChange(e) срабатывает автоматически, когда пользователь изменяет выбор в таблице. Для активации этого триггера необходимо обновлять таблицу после добавления триггера и каждый раз при её открытии.

Если выделение перемещается между несколькими ячейками за короткое время, некоторые события изменения выделения могут быть пропущены для сокращения задержки. Например, если несколько изменений выделения производятся с интервалом в две секунды, только первое и последнее изменение выделения активируют триггер onSelectionChange(e) .

В приведенном ниже примере, если выбрана пустая ячейка, функция onSelectionChange(e) устанавливает фон ячейки на красный.

doGet(e) и doPost(e)

Триггер doGet(e) срабатывает автоматически, когда пользователь посещает веб-приложение или программа отправляет HTTP-запрос GET веб-приложению. doPost(e) срабатывает, когда программа отправляет HTTP-запрос POST веб-приложению. Подробнее об этих триггерах рассказано в руководствах по веб-приложениям , HTML-сервисам и Content-сервисам . Обратите внимание, что doGet(e) и doPost(e) не распространяются перечисленные выше ограничения.

Доступные типы триггеров

Если ограничения простых триггеров не позволяют вам использовать их, устанавливаемый триггер может подойти. В таблице ниже перечислены типы триггеров, доступные для каждого типа событий. Например, простые триггеры открытия поддерживаются Google Таблицами, Презентациями, Формами и Документами, но устанавливаемые триггеры открытия поддерживаются только в Таблицах, Документах и ​​Формах.

Событие	Простые триггеры	Устанавливаемые триггеры
Открыть	Листы Слайды Формы* Документы function onOpen(e)	Листы Формы* Документы
Редактировать	Листы function onEdit(e)	Листы
Изменение выбора	Листы function onSelectionChange(e)
Установить	Листы Слайды Формы Документы function onInstall(e)
Изменять	Листы
Форма отправлена	Листы Формы
Управляемый временем (часы)	Листы Слайды Формы Документы Автономный
Получать	Автономный function doGet(e)
Почта	Автономный function doPost(e)

* Событие открытия для Google Forms происходит не тогда, когда пользователь открывает форму для ответа, а когда редактор открывает форму для ее изменения.