Pemicu Sederhana

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Pemicu memungkinkan Apps Script menjalankan fungsi secara otomatis saat peristiwa tertentu, seperti membuka dokumen, terjadi. Pemicu sederhana adalah sekumpulan fungsi yang dicadangkan dan terintegrasi ke dalam Apps Script, seperti fungsi onOpen(e), yang dijalankan saat pengguna membuka file Google Dokumen, Spreadsheet, Slide, atau Formulir. Pemicu yang dapat diinstal menawarkan lebih banyak kemampuan daripada pemicu sederhana, tetapi harus diaktifkan sebelum digunakan. Untuk kedua jenis pemicu, Apps Script meneruskan objek peristiwa yang dipicu pada fungsi yang berisi informasi tentang konteks tempat peristiwa terjadi.

Memulai

Untuk menggunakan pemicu sederhana, cukup buat fungsi yang menggunakan salah satu nama fungsi yang dicadangkan ini:

  • onOpen(e) berjalan saat pengguna membuka spreadsheet, dokumen, presentasi, atau formulir yang dapat diedit oleh pengguna.
  • onInstall(e) berjalan saat pengguna menginstal add-on Editor dari dalam Google Dokumen, Spreadsheet, Slide, atau Formulir.
  • onEdit(e) berjalan saat pengguna mengubah nilai dalam spreadsheet.
  • onSelectionChange(e) berjalan saat pengguna mengubah pilihan dalam spreadsheet.
  • doGet(e) berjalan saat pengguna mengunjungi aplikasi web atau program mengirimkan permintaan GET HTTP ke aplikasi web.
  • doPost(e) berjalan saat program mengirimkan permintaan POST HTTP ke aplikasi web.

Parameter e pada nama fungsi di atas adalah objek peristiwa yang diteruskan ke fungsi. Objek ini berisi informasi tentang konteks yang menyebabkan pemicu diaktifkan, tetapi penggunaannya bersifat opsional.

Batasan

Karena pemicu sederhana diaktifkan secara otomatis, tanpa meminta otorisasi dari pengguna, pemicu akan tunduk pada beberapa batasan:

  • Skrip harus terikat ke file Google Spreadsheet, Slide, Dokumen, atau Formulir, atau berupa add-on yang memperluas salah satu aplikasi tersebut.
  • Penginstalan file tidak akan berjalan jika file dibuka dalam mode hanya baca (lihat atau komentar).
  • Eksekusi skrip dan permintaan API tidak menyebabkan pemicu dijalankan. Misalnya, memanggil Range.setValue() untuk mengedit sel tidak akan memicu pemicu onEdit spreadsheet.
  • Mereka tidak dapat mengakses layanan yang memerlukan otorisasi. Misalnya, pemicu sederhana tidak dapat mengirim email karena layanan Gmail memerlukan otorisasi, tetapi pemicu sederhana dapat menerjemahkan frasa dengan Layanan bahasa yang bersifat anonim.
  • Mereka dapat mengubah file yang terikat, tetapi tidak dapat mengakses file lain karena hal itu akan memerlukan otorisasi.
  • Pengguna mungkin dapat atau tidak dapat menentukan identitas pengguna saat ini, bergantung pada rangkaian pembatasan keamanan yang kompleks.
  • Iklan tersebut tidak dapat berjalan lebih dari 30 detik.
  • Dalam keadaan tertentu, add-on editor menjalankan pemicu sederhana onOpen(e) dan onEdit(e) dalam mode tanpa otorisasi yang menyajikan beberapa detail tambahan. Untuk informasi selengkapnya, lihat panduan siklus proses otorisasi add-on.
  • Pemicu sederhana akan tunduk pada batas kuota pemicu Apps Script.

Batasan ini tidak berlaku untuk doGet(e) atau doPost(e).

onOpen(e)

Pemicu onOpen(e) berjalan secara otomatis saat pengguna membuka spreadsheet, dokumen, presentasi, atau formulir yang dapat mereka edit. (Pemicu tidak berjalan saat merespons formulir, hanya saat membuka formulir untuk mengeditnya.) onOpen(e) paling sering digunakan untuk menambahkan item menu kustom ke Google Spreadsheet, Slide, Dokumen, atau Formulir.

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

Pemicu onInstall(e) berjalan secara otomatis saat pengguna menginstal add-on Editor dari dalam Google Dokumen, Spreadsheet, Slide, atau Formulir. Pemicu tidak akan berjalan saat pengguna menginstal add-on dari situs Google Workspace Marketplace. Perlu diperhatikan bahwa ada batasan tertentu tentang apa yang dapat dilakukan onInstall(e), pelajari otorisasi lebih lanjut. Penggunaan onInstall(e) yang paling umum adalah dengan memanggil onOpen(e) untuk menambahkan menu kustom. Lagi pula, saat add-on diinstal, file tersebut sudah terbuka, sehingga onOpen(e) tidak berjalan sendiri kecuali file dibuka kembali.

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

Pemicu onEdit(e) berjalan secara otomatis saat pengguna mengubah nilai sel dalam spreadsheet. Sebagian besar pemicu onEdit(e) menggunakan informasi di objek peristiwa untuk merespons dengan tepat. Misalnya, fungsi onEdit(e) di bawah ini menetapkan komentar pada sel yang mencatat kapan terakhir kali komentar diedit.

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

Pemicu onSelectionChange(e) berjalan secara otomatis saat pengguna mengubah pilihan dalam spreadsheet. Untuk mengaktifkan pemicu ini, Anda harus memuat ulang spreadsheet setelah pemicu ditambahkan dan setiap kali spreadsheet dibuka.

Jika pemilihan berpindah di antara beberapa sel dalam waktu singkat, beberapa peristiwa perubahan pilihan mungkin dilewati untuk mengurangi latensi. Misalnya, jika banyak perubahan pilihan dilakukan dalam waktu dua detik satu sama lain, hanya perubahan pemilihan pertama dan terakhir yang akan mengaktifkan pemicu onSelectionChange(e).

Pada contoh di bawah, jika sel kosong dipilih, fungsi onSelectionChange(e) akan menetapkan latar belakang sel menjadi merah.

pemicu/pemicu.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) dan doPost(e)

Pemicu doGet(e) berjalan secara otomatis saat pengguna mengunjungi aplikasi web atau program mengirimkan permintaan GET HTTP ke aplikasi web. doPost(e) berjalan saat program mengirimkan permintaan HTTP POST ke aplikasi web. Pemicu ini ditunjukkan lebih banyak dalam panduan untuk aplikasi web, layanan HTML, dan Layanan konten. Perhatikan bahwa doGet(e) dan doPost(e) tidak tunduk pada pembatasan yang tercantum di atas.

Jenis pemicu yang tersedia

Jika batasan pada pemicu sederhana mencegahnya memenuhi kebutuhan Anda, pemicu yang dapat diinstal mungkin akan berfungsi. Tabel di bawah ini meringkas jenis pemicu yang tersedia untuk setiap jenis peristiwa. Misalnya, Google Spreadsheet, Slide, Formulir, dan Dokumen mendukung semua pemicu terbuka sederhana, tetapi hanya Spreadsheet, Dokumen, dan Formulir yang mendukung pemicu terbuka yang dapat diinstal.

Peristiwa Pemicu sederhana Pemicu yang dapat diinstal
Buka
Spreadsheet
Slide
Formulir*
Dokumen

function onOpen(e)

Spreadsheet
Formulir*
Dokumen
Edit
Spreadsheet

function onEdit(e)

Spreadsheet
Perubahan pilihan
Spreadsheet

function onSelectionChange(e)

Instal
Spreadsheet
Slide
Formulir
Dokumen

function onInstall(e)

Ubah
Spreadsheet
Pengiriman formulir
Spreadsheet
Formulir
Berdasarkan waktu (jam)
Spreadsheet
Slide
Formulir
Dokumen
Situs
Mandiri
Dapatkan
Situs
Mandiri

function doGet(e)

Posting
Situs
Mandiri

function doPost(e)

* Peristiwa terbuka untuk Google Formulir tidak terjadi saat pengguna membuka formulir untuk merespons, tetapi lebih ketika editor membuka formulir untuk mengubahnya.