ทริกเกอร์อย่างง่าย

ทริกเกอร์ช่วยให้ Apps Script เรียกใช้ฟังก์ชันโดยอัตโนมัติเมื่อมีเหตุการณ์บางอย่างเกิดขึ้น เช่น การเปิดเอกสาร ทริกเกอร์ทั่วไปคือชุดฟังก์ชันที่จองไว้ซึ่งมีอยู่ใน Apps Script เช่น ฟังก์ชัน onOpen(e) ซึ่งจะทำงานเมื่อผู้ใช้เปิดไฟล์ Google เอกสาร ชีต สไลด์ หรือฟอร์ม ทริกเกอร์ที่ติดตั้งได้มอบความสามารถมากกว่าทริกเกอร์ธรรมดา แต่ต้องเปิดใช้งานก่อนใช้งาน สำหรับทริกเกอร์ทั้ง 2 ประเภท Apps Script จะส่งออบเจ็กต์เหตุการณ์ไปยังฟังก์ชันที่ทริกเกอร์ ซึ่งมีข้อมูลเกี่ยวกับบริบทที่เกิดเหตุการณ์

เริ่มต้นใช้งาน

หากต้องการใช้ทริกเกอร์แบบง่าย ให้สร้างฟังก์ชันที่ใช้ชื่อฟังก์ชันที่สงวนไว้ชื่อใดชื่อหนึ่งต่อไปนี้

  • onOpen(e) จะทำงานเมื่อผู้ใช้เปิดสเปรดชีต เอกสาร งานนำเสนอ หรือแบบฟอร์มที่ผู้ใช้มีสิทธิ์แก้ไข
  • onInstall(e) จะทำงานเมื่อผู้ใช้ติดตั้งส่วนเสริมเครื่องมือแก้ไขจากภายใน Google เอกสาร ชีต สไลด์ หรือฟอร์ม
  • onEdit(e) ทำงานเมื่อผู้ใช้เปลี่ยนค่าในสเปรดชีต
  • onSelectionChange(e) ทำงานเมื่อผู้ใช้เปลี่ยนแปลงการเลือกในสเปรดชีต
  • doGet(e) ทำงานเมื่อผู้ใช้เข้าชมเว็บแอปหรือโปรแกรมส่งคำขอ HTTP GET ไปยังเว็บแอป
  • doPost(e) ทำงานเมื่อโปรแกรมส่งคำขอ HTTP POST ไปยังเว็บแอป

พารามิเตอร์ e ในชื่อฟังก์ชันด้านบนคือออบเจ็กต์เหตุการณ์ที่ส่งไปยังฟังก์ชัน ออบเจ็กต์มีข้อมูลเกี่ยวกับบริบทที่ทำให้ทริกเกอร์เริ่มทำงาน แต่คุณจะใช้งานหรือไม่ก็ได้

ข้อจำกัด

เนื่องจากทริกเกอร์แบบง่ายจะเริ่มทำงานโดยอัตโนมัติโดยไม่ต้องขอสิทธิ์จากผู้ใช้ จึงอยู่ภายใต้ข้อจำกัดหลายประการ ดังนี้

  • สคริปต์ต้องเชื่อมโยงกับไฟล์ Google ชีต สไลด์ เอกสาร หรือฟอร์ม หรือจะเป็นส่วนเสริมที่ขยายแอปพลิเคชันรายการใดรายการหนึ่งเหล่านั้น
  • โดยจะไม่ทำงานหากเปิดไฟล์ในโหมดอ่านอย่างเดียว (ดูหรือแสดงความคิดเห็น)
  • การเรียกใช้สคริปต์และคำขอ API จะไม่ทำให้ทริกเกอร์ทำงาน เช่น การเรียกใช้ Range.setValue() เพื่อแก้ไขเซลล์ไม่ได้ทำให้ทริกเกอร์ onEdit ของสเปรดชีตทำงาน
  • แต่จะไม่สามารถเข้าถึงบริการที่ต้องมีการให้สิทธิ์ได้ เช่น ทริกเกอร์แบบง่ายไม่สามารถส่งอีเมลได้เนื่องจากบริการ Gmail ต้องการการให้สิทธิ์ แต่ทริกเกอร์แบบง่ายอาจแปลวลีด้วยบริการภาษา ซึ่งจะไม่ระบุตัวตน
  • โดยผู้ใช้จะแก้ไขไฟล์ที่ตนเองเชื่อมโยงด้วยได้ แต่จะเข้าถึงไฟล์อื่นไม่ได้เนื่องจากต้องมีการให้สิทธิ์
  • ซึ่งอาจระบุหรือไม่ระบุข้อมูลประจำตัวของผู้ใช้ปัจจุบันได้ ทั้งนี้ขึ้นอยู่กับชุดข้อจำกัดด้านความปลอดภัยที่ซับซ้อน
  • และจะทํางานได้ไม่เกิน 30 วินาที
  • ในบางสถานการณ์ ส่วนเสริม Editor จะเรียกใช้ onOpen(e) และ onEdit(e) ทริกเกอร์แบบง่ายในโหมดไม่มีการให้สิทธิ์ซึ่งจะทำให้เกิดข้อมูลแทรกเพิ่มเติม สำหรับข้อมูลเพิ่มเติม โปรดดูคำแนะนำเกี่ยวกับวงจรการให้สิทธิ์ส่วนเสริม
  • ทริกเกอร์แบบง่ายจะขึ้นอยู่กับขีดจำกัดโควต้าของทริกเกอร์ Apps Script

ข้อจำกัดเหล่านี้ไม่มีผลกับ doGet(e) หรือ doPost(e)

onOpen(e)

ทริกเกอร์ onOpen(e) จะทำงานโดยอัตโนมัติเมื่อผู้ใช้เปิดสเปรดชีต เอกสาร งานนำเสนอ หรือแบบฟอร์มที่ผู้ใช้มีสิทธิ์แก้ไข (ทริกเกอร์จะไม่ทำงานเมื่อตอบแบบฟอร์ม แต่ทริกเกอร์เฉพาะเมื่อเปิดแบบฟอร์มเพื่อแก้ไขเท่านั้น) onOpen(e) มีการใช้บ่อยที่สุดในการเพิ่มรายการในเมนูที่กำหนดเองไปยัง Google ชีต สไลด์ เอกสาร หรือฟอร์ม

triggers/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/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/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) จะทำงานโดยอัตโนมัติเมื่อผู้ใช้เปลี่ยนแปลงการเลือกในสเปรดชีต หากต้องการเปิดใช้งานทริกเกอร์นี้ คุณต้องรีเฟรชสเปรดชีต เมื่อมีการเพิ่มทริกเกอร์และทุกครั้งที่เปิดสเปรดชีต

หากการเลือกย้ายไปมาระหว่างหลายเซลล์ในช่วงเวลาสั้นๆ ระบบอาจข้ามเหตุการณ์การเปลี่ยนแปลงการเลือกบางอย่างเพื่อลดเวลาในการตอบสนอง เช่น หากมีการเปลี่ยนแปลงการเลือกหลายรายการภายใน 2 วินาทีติดต่อกัน เฉพาะการเปลี่ยนแปลงการเลือกครั้งแรกและครั้งสุดท้ายเท่านั้นที่จะเปิดใช้งานทริกเกอร์ onSelectionChange(e)

ในตัวอย่างด้านล่าง หากเลือกเซลล์ว่าง ฟังก์ชัน onSelectionChange(e) จะตั้งค่าพื้นหลังของเซลล์เป็นสีแดง

triggers/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 ฟอร์มจะไม่เกิดขึ้นเมื่อผู้ใช้เปิดแบบฟอร์มเพื่อตอบกลับ แต่จะเกิดขึ้นเมื่อผู้แก้ไขเปิดแบบฟอร์มเพื่อแก้ไข