Простые триггеры

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

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

onOpen(e)

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

триггеры/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

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

триггеры/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

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

триггеры/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

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

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

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

триггеры/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) и doPost(e)

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

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

Если ограничения на простые триггеры не позволяют им удовлетворить ваши потребности, вместо них может работать устанавливаемый триггер . В таблице ниже указано, какие типы триггеров доступны для каждого типа события. Например, Google Sheets, Slides, Forms и Docs поддерживают простые открытые триггеры, но только Sheets, Docs и Forms поддерживают устанавливаемые открытые триггеры.

Событие Простые триггеры Устанавливаемые триггеры
Открыть
Листы
Слайды
Формы*
Документы

function onOpen(e)

Листы
Формы*
Документы
Редактировать
Листы

function onEdit(e)

Листы
Изменение выбора
Листы

function onSelectionChange(e)

Установить
Листы
Слайды
Формы
Документы

function onInstall(e)

Изменять
Листы
Отправить форму
Листы
Формы
Управляемый временем (часы)
Листы
Слайды
Формы
Документы
Места
Автономный
Получать
Места
Автономный

function doGet(e)

Почта
Места
Автономный

function doPost(e)

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