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

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

Начиная

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

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

Эти ограничения не распространяются на 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. Триггер не сработает, когда пользователь установит надстройку с веб-сайта 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 Таблицы, Слайды, Формы и Документы поддерживают простые триггеры открытия, но только Таблицы, Документы и Формы поддерживают устанавливаемые триггеры открытия.

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

function onOpen(e)

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

function onEdit(e)

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

function onSelectionChange(e)

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

function onInstall(e)

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

function doGet(e)

Почта
Автономный

function doPost(e)

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