ทริกเกอร์สําหรับส่วนเสริมของเอดิเตอร์

ทริกเกอร์ Apps Script ทำให้ฟังก์ชันของสคริปต์ที่ระบุ (ฟังก์ชันทริกเกอร์) ทำงานทุกครั้งที่เกิดเหตุการณ์ที่ระบุ มีเพียงบางเหตุการณ์เท่านั้นที่ทำให้ทริกเกอร์เริ่มทำงาน และแอปพลิเคชัน Google Workspace แต่ละแอปจะรองรับชุดเหตุการณ์ที่แตกต่างกัน

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

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

หน้านี้มีหลักเกณฑ์เกี่ยวกับการใช้ทริกเกอร์ในโปรเจ็กต์ส่วนเสริมของตัวแก้ไข

ประเภททริกเกอร์ที่เป็นส่วนเสริมของตัวแก้ไข

คุณใช้ประเภททริกเกอร์ทั่วไปส่วนใหญ่ที่มีให้สำหรับโปรเจ็กต์ Apps Script ในส่วนเสริมของ Editor ได้ ซึ่งรวมถึงทริกเกอร์แบบง่ายและทริกเกอร์ที่ติดตั้งได้ส่วนใหญ่ ชุดประเภททริกเกอร์ที่ใช้ได้จะขึ้นอยู่กับการขยายแอปพลิเคชัน

ตารางต่อไปนี้แสดงประเภทของทริกเกอร์แบบง่ายและติดตั้งได้ซึ่งส่วนเสริมของตัวแก้ไขใช้ได้ และให้ลิงก์ไปยังออบเจ็กต์เหตุการณ์ที่เกี่ยวข้อง

กิจกรรม	ออบเจ็กต์เหตุการณ์	ทริกเกอร์แบบง่าย	ทริกเกอร์ที่ติดตั้งได้
เปิด ไฟล์ตัวแก้ไขจะเปิดขึ้น	เอกสารเมื่อเปิดออบเจ็กต์เหตุการณ์ ออบเจ็กต์เมื่อเปิดออบเจ็กต์ใน Google ฟอร์ม ชีตขณะเปิดออบเจ็กต์เหตุการณ์ ออบเจ็กต์เมื่อเปิดสไลด์	เอกสาร ฟอร์ม* ชีต สไลด์ function onOpen(e)	เอกสาร ฟอร์ม ชีต
ติดตั้ง ติดตั้งส่วนเสริมแล้ว	onInstall event object	เอกสาร ฟอร์ม ชีต สไลด์ function onInstall(e)
แก้ไข เนื้อหาของเซลล์ในสเปรดชีตมีการเปลี่ยนแปลง	ชีต onEdit ออบเจ็กต์เหตุการณ์	ชีต function onEdit(e)	ชีต
เปลี่ยน มีการแก้ไขหรือจัดรูปแบบเนื้อหาในชีต	ชีต onChange ออบเจ็กต์เหตุการณ์		ชีต
Form-submit ส่งแบบฟอร์ม Google ฟอร์ม	ออบเจ็กต์เหตุการณ์การส่งแบบฟอร์มการส่งแบบฟอร์ม ออบเจ็กต์เหตุการณ์การส่งแบบฟอร์มเพื่อส่งแบบฟอร์มของชีต		ฟอร์ม ชีต
ตามเวลา (นาฬิกา) ทริกเกอร์จะเริ่มทำงานในเวลาหรือช่วงเวลาที่ระบุ	ออบเจ็กต์เหตุการณ์ที่ขึ้นกับเวลา		เอกสาร ฟอร์ม ชีต สไลด์

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

ทริกเกอร์แบบง่ายในส่วนเสริม

ทริกเกอร์แบบง่ายจะใช้ชื่อฟังก์ชันที่สงวนไว้ ไม่สามารถใช้บริการที่ต้องมีการให้สิทธิ์ได้ และระบบจะเปิดใช้โดยอัตโนมัติเพื่อใช้งาน ในบางกรณี เหตุการณ์ทริกเกอร์แบบง่ายจะจัดการด้วยทริกเกอร์ที่ติดตั้งได้แทน

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

• onOpen(e) จะทำงานเมื่อผู้ใช้เปิดเอกสาร สเปรดชีต หรืองานนำเสนอ onOpen(e) ยังทำงานเมื่อเปิดแบบฟอร์มในตัวแก้ไขได้ด้วย (แต่ทำไม่ได้เมื่อตอบกลับแบบฟอร์ม) การดำเนินการนี้จะทำงานก็ต่อเมื่อผู้ใช้มีสิทธิ์แก้ไขไฟล์ที่เป็นปัญหาและมักจะใช้เพื่อสร้างรายการในเมนูเป็นส่วนใหญ่
• onInstall(e) จะดำเนินการเมื่อผู้ใช้ติดตั้งส่วนเสริม โดยปกติจะใช้ onInstall(e) เพื่อเรียก onOpen(e) เพื่อให้มั่นใจว่าเมนูส่วนเสริมจะปรากฏทันทีหลังจากติดตั้งโดยผู้ใช้ไม่ต้องรีเฟรชหน้า
• onEdit(e) จะดำเนินการเมื่อผู้ใช้เปลี่ยนค่าของเซลล์ในสเปรดชีต ทริกเกอร์นี้จะไม่เริ่มทำงานเพื่อตอบสนองต่อการย้ายเซลล์ การจัดรูปแบบ หรือการเปลี่ยนแปลงอื่นๆ ที่ไม่ได้เปลี่ยนแปลงค่าของเซลล์

พบข้อจำกัด

ทริกเกอร์แบบง่ายในส่วนเสริมจะมีข้อจํากัดเดียวกันซึ่งใช้บังคับกับทริกเกอร์แบบง่ายในโปรเจ็กต์ Apps Script ประเภทอื่นๆ โปรดคำนึงถึงข้อจำกัดเหล่านี้ เมื่อออกแบบส่วนเสริม

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

ทริกเกอร์ที่ติดตั้งได้ในส่วนเสริม

ส่วนเสริมจะสร้างและแก้ไขทริกเกอร์ที่ติดตั้งได้แบบเป็นโปรแกรมด้วยบริการ Apps Script Script ทริกเกอร์ส่วนเสริมที่ติดตั้งได้จะสร้างเองไม่ได้ ทริกเกอร์ที่ติดตั้งได้แตกต่างจากทริกเกอร์ทั่วไปตรงที่ใช้บริการที่ต้องมีการให้สิทธิ์ได้

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

ส่วนเสริมสามารถใช้ทริกเกอร์ที่ติดตั้งได้ต่อไปนี้

• ทริกเกอร์เปิดที่ติดตั้งได้จะทำงานเมื่อผู้ใช้เปิดเอกสาร สเปรดชีต หรือเมื่อแบบฟอร์มเปิดในตัวแก้ไข (แต่ไม่ใช่เมื่อตอบกลับแบบฟอร์ม)
• แก้ไขทริกเกอร์ที่ติดตั้งได้จะทำงานเมื่อผู้ใช้เปลี่ยนค่าของเซลล์ในสเปรดชีต ทริกเกอร์นี้จะไม่เริ่มทำงานเพื่อตอบสนองต่อการจัดรูปแบบหรือการเปลี่ยนแปลงอื่นๆ ที่ไม่ได้ปรับเปลี่ยนค่าของเซลล์
• เปลี่ยนทริกเกอร์ที่ติดตั้งได้จะทำงานเมื่อผู้ใช้ทำการเปลี่ยนแปลงในสเปรดชีต ซึ่งรวมถึงการแก้ไขการจัดรูปแบบและการแก้ไขสเปรดชีต (เช่น การเพิ่มแถว)

• ทริกเกอร์ที่ติดตั้งได้ของการส่งแบบฟอร์มจะทำงานเมื่อมีการส่งการตอบกลับ Google ฟอร์ม

• ทริกเกอร์ตามเวลา (หรือที่เรียกว่าทริกเกอร์นาฬิกา) จะเริ่มทำงานในเวลาที่เฉพาะเจาะจงหรือซ้ำๆ ในช่วงเวลาปกติ

การให้สิทธิ์ทริกเกอร์ที่ติดตั้งได้

โดยปกติแล้ว หากนักพัฒนาซอฟต์แวร์อัปเดตส่วนเสริมเพื่อใช้บริการใหม่ที่ต้องมีการให้สิทธิ์เพิ่มเติม ผู้ใช้จะได้รับข้อความแจ้งให้ให้สิทธิ์ส่วนเสริมอีกครั้งเมื่อผู้ใช้ใช้งานส่วนเสริมดังกล่าวในครั้งถัดไป

อย่างไรก็ตาม ส่วนเสริมที่ใช้ทริกเกอร์จะพบการตรวจสอบสิทธิ์พิเศษ สมมติว่าส่วนเสริมที่ใช้ทริกเกอร์เพื่อตรวจสอบการส่งแบบฟอร์ม ผู้สร้างแบบฟอร์มอาจให้สิทธิ์ส่วนเสริมในครั้งแรกที่ใช้งาน แล้วปล่อยให้ส่วนเสริมนั้นทำงานเป็นเวลาหลายเดือนหรือหลายปีโดยไม่ต้องเปิดแบบฟอร์มอีกครั้ง หากนักพัฒนาซอฟต์แวร์ส่วนเสริมต้องการอัปเดตส่วนเสริมเพื่อใช้บริการใหม่ที่ต้องมีการให้สิทธิ์เพิ่มเติม ผู้สร้างแบบฟอร์มจะไม่เห็นกล่องโต้ตอบการให้สิทธิ์อีกครั้ง เนื่องจากไม่ได้เปิดแบบฟอร์มอีกครั้งและส่วนเสริมจะหยุดทำงาน

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

ด้านล่างนี้เป็นตัวอย่างโครงสร้างที่แนะนําที่จะใช้ในฟังก์ชันทริกเกอร์เพื่อหลีกเลี่ยงข้อผิดพลาดในการให้สิทธิ์ ฟังก์ชันทริกเกอร์ตัวอย่างจะตอบสนองต่อเหตุการณ์การส่งแบบฟอร์มภายในส่วนเสริมของ Google ชีต และหากต้องมีการให้สิทธิ์อีกครั้ง ระบบจะส่งอีเมลแจ้งเตือนให้ผู้ใช้ส่วนเสริมนั้นโดยใช้ HTML ที่มีเทมเพลต

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

พบข้อจำกัด

ทริกเกอร์ที่ติดตั้งได้ในส่วนเสริมจะอยู่ภายใต้ข้อจำกัดเดียวกันกับที่ควบคุมทริกเกอร์ที่ติดตั้งได้ในโปรเจ็กต์ Apps Script ประเภทอื่นๆ

นอกเหนือจากข้อจำกัดเหล่านี้แล้ว ยังมีข้อจำกัดอีกหลายอย่างที่มีผลกับทริกเกอร์ที่ติดตั้งได้ในส่วนเสริมโดยเฉพาะ ดังนี้

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