ทริกเกอร์สําหรับส่วนเสริมเครื่องมือแก้ไข

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

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

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

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

ประเภททริกเกอร์ของส่วนเสริมของเอดิเตอร์

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

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

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

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

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

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

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

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

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

ข้อจำกัด

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

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

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

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

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

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

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

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

  ทริกเกอร์การส่งแบบฟอร์มมี 2 เวอร์ชัน ได้แก่ เวอร์ชันสำหรับชีต (ที่เก็บรวบรวมคำตอบของแบบฟอร์ม) และเวอร์ชันสำหรับ Google ฟอร์ม ออบเจ็กต์เหตุการณ์ที่ส่งผ่านไปยังฟังก์ชันทริกเกอร์การส่งแบบฟอร์มในชีต จะง่ายขึ้นและแสดงผลค่าการตอบกลับในอาร์เรย์อย่างง่าย ออบเจ็กต์เหตุการณ์ที่ส่งไปยังฟังก์ชันทริกเกอร์การส่งแบบฟอร์มของ Forms จะให้ข้อมูลเพิ่มเติมซึ่งอยู่ในออบเจ็กต์ FormResponse

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

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

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

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

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