Proste aktywatory

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Aktywatory pozwalają na automatyczne uruchamianie funkcji Apps Script po wystąpieniu określonego zdarzenia, takiego jak otwarcie dokumentu. Proste aktywatory to zestaw zarezerwowanych funkcji wbudowanych w Apps Script, takich jak funkcja onOpen(e), która uruchamia się, gdy użytkownik otworzy plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Reguły możliwe do zainstalowania mają większe możliwości niż proste reguły, ale muszą zostać aktywowane przed użyciem. W przypadku obu typów aktywatorów Apps Script przekazuje aktywowaną funkcję obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Pierwsze kroki

Aby użyć prostego aktywatora, wystarczy utworzyć funkcję, która będzie używać jednej z tych zarezerwowanych nazw:

  • onOpen(e) działa, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, które ma uprawnienia do edycji.
  • onInstall(e) działa, gdy użytkownik zainstaluje dodatek do Edytora z Dokumentów, Arkuszy, Prezentacji lub Formularzy Google.
  • onEdit(e) uruchamia się, gdy użytkownik zmieni wartość w arkuszu kalkulacyjnym.
  • onSelectionChange(e) działa, gdy użytkownik zmieni zaznaczenie w arkuszu kalkulacyjnym.
  • doGet(e) działa, gdy użytkownik odwiedza aplikację internetową lub program wysyła żądanie HTTP GET do aplikacji internetowej.
  • doPost(e) działa, gdy program wysyła żądanie HTTP POST do aplikacji internetowej.

Parametr e w nazwach funkcji to obiekt zdarzenia przekazywany do tej funkcji. Obiekt zawiera informacje o kontekście, które spowodowało jego uruchomienie, ale używanie go jest opcjonalne.

Ograniczenia

Proste reguły uruchamiają się automatycznie bez pytania użytkownika o zgodę na stosowanie. Dlatego podlegają pewnym ograniczeniom:

  • Skrypt musi być powiązany z plikiem Arkuszy, Prezentacji, Dokumentów lub Formularzy Google albo musi być dodatkiem rozszerzającym jedną z tych aplikacji.
  • Nie są one uruchamiane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie).
  • Wykonywanie skryptów i żądania API nie powodują uruchomienia aktywatorów. Na przykład wywołanie Range.setValue() do edycji komórki nie powoduje uruchomienia aktywatora arkusza kalkulacyjnegoonEdit.
  • Nie ma on dostępu do usług, które wymagają autoryzacji. Na przykład prosta reguła nie może wysłać e-maila, ponieważ usługa Gmail wymaga autoryzacji, a prosta reguła może przetłumaczyć wyrażenie anonimowe w usłudze językowej.
  • Mogą też modyfikować plik, z którym są powiązani, ale nie mają dostępu do innych plików, co wymagałoby autoryzacji.
  • Może on nie być w stanie określić tożsamości bieżącego użytkownika w zależności od złożonego zestawu ograniczeń.
  • Nie mogą trwać dłużej niż 30 sekund.
  • W niektórych przypadkach dodatki do edycji uruchamiają proste aktywatory onOpen(e) i onEdit(e) w trybie bez autoryzacji, co stwarza pewne utrudnienia. Więcej informacji znajdziesz w przewodniku po cyklu życia dodatku do autoryzacji.
  • Proste aktywatory podlegają limitom limitu wyzwalaczy Apps Script.

Te ograniczenia nie dotyczą stron doGet(e) i doPost(e).

onOpen(e)

Reguła onOpen(e) działa automatycznie, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, które może edytować. Reguła nie będzie uruchamiana podczas odpowiadania na formularz tylko podczas jego otwierania i edytowania. Najczęściej onOpen(e) dodaje się elementy menu do Arkuszy, Prezentacji, Dokumentów lub Formularzy Google.

aktywatory/aktywatory.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)

Reguła onInstall(e) działa automatycznie, gdy użytkownik zainstaluje dodatek do Edytora z Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Aktywator nie będzie działać, gdy użytkownik zainstaluje dodatek ze strony Google Workspace Marketplace. Istnieją pewne ograniczenia możliwości onInstall(e), dowiedz się więcej o autoryzacji. Najpopularniejszym sposobem użycia właściwości onInstall(e) jest samo wywołanie opcji onOpen(e) w celu dodania niestandardowych menu. Gdy dodatek jest już zainstalowany, plik jest już otwarty, dzięki czemu onOpen(e) nie może działać samodzielnie, chyba że plik zostanie ponownie otwarty.

aktywatory/aktywatory.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)

Reguła onEdit(e) jest uruchamiana automatycznie, gdy użytkownik zmieni wartość dowolnej komórki w arkuszu kalkulacyjnym. Większość reguł onEdit(e) używa odpowiednich informacji z obiektu zdarzenia do odpowiedniego reagowania. Na przykład ta funkcja onEdit(e) ustawia komentarz w komórce, który rejestruje ostatnią zmianę.

aktywatory/aktywatory.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)

Reguła onSelectionChange(e) działa automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować regułę, musisz ją odświeżyć po dodaniu i za każdym razem, gdy arkusz zostanie otwarty.

Jeśli w krótkim czasie zaznaczenie zostanie przeniesione między kilkoma komórkami, niektóre zdarzenia zmiany wyboru mogą zostać pominięte, aby skrócić czas oczekiwania. Jeśli na przykład wiele zmian wyboru zostanie wprowadzonych w ciągu dwóch sekund, tylko pierwsza i ostatnia zmiana będą aktywować regułę onSelectionChange(e).

W poniższym przykładzie po wybraniu pustej komórki funkcja onSelectionChange(e) ustawia tło komórki na czerwony.

aktywatory/aktywatory.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)

Reguła doGet(e) działa automatycznie, gdy użytkownik odwiedza aplikację internetową lub program wysyła żądanie HTTP GET do aplikacji internetowej. doPost(e) uruchamia się, gdy program wysyła żądanie HTTP POST do aplikacji internetowej. Te reguły są przedstawione w przewodnikach dotyczących aplikacji internetowych, usługi HTML i usługi treści. doGet(e) i doPost(e) nie podlegają ograniczeniom opisanym powyżej.

Dostępne typy reguł

Jeśli ograniczenia prostych reguł nie pozwalają im sprostać Twoim potrzebom, może okazać się, że można zainstalować regułę. W tabeli poniżej znajdziesz typy reguł, które są dostępne w przypadku poszczególnych typów zdarzeń. Na przykład Arkusze Google, Prezentacje, Formularze i Dokumenty obsługują aktywatory proste, ale tylko Arkusze, Dokumenty i Formularze obsługują aktywalne otwarte reguły, które można zainstalować.

Zdarzenie Proste aktywatory Reguły do zainstalowania
Otwórz
Arkusze
Prezentacje
Formularze*
Dokumenty

function onOpen(e)

Arkusze
Formularze*
Dokumenty
Edytuj
Arkusze

function onEdit(e)

Arkusze
Zmiana wyboru
Arkusze

function onSelectionChange(e)

Zainstaluj
Arkusze
Prezentacje
Formularze
Dokumenty

function onInstall(e)

Zmień
Arkusze
Przesłanie formularza
Arkusze
Formularze
Na podstawie czasu (zegar)
Arkusze
Prezentacje
Formularze
Dokumenty
Witryny
Samodzielne
Pobierz
Witryny
Samodzielne

function doGet(e)

Post
Witryny
Samodzielne

function doPost(e)

* Zdarzenie otwarte w Formularzach Google nie występuje, gdy użytkownik otwiera formularz i chce go zmienić, ale tylko aby edytować formularz.