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

ทริกเกอร์ช่วยให้ 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 วินาที
  • ในบางสถานการณ์ ส่วนเสริมเอดิเตอร์จะเรียกใช้ onOpen(e) และ onEdit(e) ทริกเกอร์แบบง่ายในโหมดที่ไม่ได้รับอนุญาต ซึ่งจะเพิ่มความซับซ้อนบางอย่าง ดูข้อมูลเพิ่มเติมได้ในคําแนะนําเกี่ยวกับวงจรการให้สิทธิ์ส่วนเสริม
  • ทริกเกอร์แบบง่ายจะขึ้นอยู่กับขีดจํากัดโควต้าของทริกเกอร์ Apps Script

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

onOpen(e)

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

trigger/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) จะไม่ทํางานเอง เว้นแต่จะมีการเปิดไฟล์อีกครั้ง

trigger/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) ด้านล่างจะตั้งค่าความคิดเห็นในเซลล์ที่บันทึกครั้งล่าสุดที่แก้ไข

trigger/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) จะตั้งค่าพื้นหลังของเซลล์เป็นสีแดง

trigger/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)

เปลี่ยน
ชีต
การส่งแบบฟอร์ม
ชีต
ฟอร์ม
ตามเวลา (นาฬิกา)
ชีต
สไลด์
ฟอร์ม
เอกสาร
Sites
สแตนด์อโลน
ดาวน์โหลด
เว็บไซต์
แบบสแตนด์อโลน

function doGet(e)

โพสต์
เว็บไซต์
แบบสแตนด์อโลน

function doPost(e)

* กิจกรรมที่เปิดอยู่สําหรับ Google ฟอร์มไม่ได้เกิดขึ้นเมื่อผู้ใช้เปิดแบบฟอร์มเพื่อตอบกลับ แต่เมื่อผู้ใช้แก้ไขจะเปิดแบบฟอร์มเพื่อแก้ไข