Điều kiện kích hoạt cho tiện ích bổ sung dành cho Trình chỉnh sửa

Trình kích hoạt Apps Script khiến một hàm tập lệnh được chỉ định (hàm kích hoạt) thực thi bất cứ khi nào một sự kiện được chỉ định xảy ra. Chỉ một số sự kiện nhất định mới có thể kích hoạt điều kiện kích hoạt và mỗi ứng dụng Google Workspace hỗ trợ một nhóm sự kiện riêng.

Khi một điều kiện kích hoạt kích hoạt, một đối tượng sự kiện sẽ được tạo. Cấu trúc JSON này chứa thông tin chi tiết về sự kiện đã xảy ra. Thông tin trong cấu trúc đối tượng sự kiện được sắp xếp theo cách khác nhau dựa trên loại điều kiện kích hoạt.

Sau khi đối tượng sự kiện được tạo, Apps Script sẽ truyền đối tượng đó dưới dạng một tham số đến hàm kích hoạt. Hàm kích hoạt là một hàm callback mà bạn phải tự triển khai để thực hiện bất kỳ hành động nào phù hợp nhằm phản hồi sự kiện. Ví dụ: trong một tiện ích bổ sung của Trình chỉnh sửa, một trình kích hoạt được dùng để tạo các mục trong trình đơn tiện ích bổ sung khi một tài liệu được mở. Trong trường hợp này, bạn triển khai hàm kích hoạt onOpen(e) để tạo các mục trong trình đơn mà tiện ích bổ sung cần, có thể sử dụng dữ liệu trong đối tượng sự kiện.

Trang này cung cấp hướng dẫn về cách sử dụng trình kích hoạt trong các dự án tiện ích bổ sung của trình chỉnh sửa.

Các loại trình kích hoạt tiện ích bổ sung dành cho trình chỉnh sửa

Bạn có thể sử dụng hầu hết các loại điều kiện kích hoạt chung có sẵn cho các dự án Google Apps Script trong tiện ích bổ sung của Editor, bao gồm cả điều kiện kích hoạt đơn giản và hầu hết điều kiện kích hoạt có thể cài đặt. Tập hợp chính xác các loại điều kiện kích hoạt có sẵn phụ thuộc vào ứng dụng đang được mở rộng.

Không giống như tiện ích bổ sung của Trình chỉnh sửa, tiện ích bổ sung của Google Workspace không thể sử dụng các trình kích hoạt đơn giản hoặc có thể cài đặt chung của Apps Script. Thay vào đó, các tiện ích bổ sung này sử dụng các điều kiện kích hoạt được thiết kế riêng cho tiện ích bổ sung của Google Workspace. Để biết thêm thông tin, hãy xem phần Trình kích hoạt tiện ích bổ sung của Google Workspace.

Bảng sau đây cho biết các loại trình kích hoạt đơn giản và có thể cài đặt mà tiện ích bổ sung của Trình chỉnh sửa có thể sử dụng, đồng thời cung cấp đường liên kết đến các đối tượng sự kiện tương ứng:

Sự kiện	Đối tượng sự kiện	Điều kiện kích hoạt đơn giản	Trình kích hoạt có thể cài đặt
Mở Một tệp trình chỉnh sửa sẽ mở ra.	Đối tượng sự kiện onOpen của Tài liệu Đối tượng sự kiện onOpen của Biểu mẫu Đối tượng sự kiện onOpen của Trang tính Đối tượng sự kiện onOpen của Trang trình bày	Tài liệu Biểu mẫu* Trang tính Trang trình bày function onOpen(e)	Tài liệu Biểu mẫu Trang tính
Cài đặt Tiện ích bổ sung đã được cài đặt.	onInstall event object	Tài liệu Biểu mẫu Trang tính Trang trình bày function onInstall(e)
Chỉnh sửa Nội dung ô trong bảng tính bị thay đổi.	Đối tượng sự kiện onEdit của Trang tính	Trang tính function onEdit(e)	Trang tính
Thay đổi Nội dung trong trang tính được chỉnh sửa hoặc định dạng.	Đối tượng sự kiện onChange của Trang tính		Trang tính
Form-submit Một biểu mẫu trên Google Biểu mẫu được gửi.	Đối tượng sự kiện form-submit của Biểu mẫu Đối tượng sự kiện form-submit của Trang tính		Biểu mẫu Trang tính
Theo thời gian (đồng hồ) Điều kiện kích hoạt sẽ kích hoạt vào một thời gian hoặc khoảng thời gian cụ thể.	Đối tượng sự kiện dựa trên thời gian	Tài liệu Biểu mẫu Trang tính Trang trình bày

Sự kiện mở cho Google Biểu mẫu không xảy ra khi người dùng mở biểu mẫu để phản hồi, mà xảy ra khi người chỉnh sửa mở biểu mẫu để sửa đổi.

Điều kiện kích hoạt đơn giản trong tiện ích bổ sung

Trình kích hoạt đơn giản sử dụng một tập hợp tên hàm dành riêng, không thể sử dụng các dịch vụ yêu cầu uỷ quyền và tự động được bật để sử dụng. Trong một số trường hợp, một sự kiện kích hoạt đơn giản có thể được xử lý bằng trình kích hoạt có thể cài đặt.

Bạn có thể thêm một trình kích hoạt đơn giản vào một tiện ích bổ sung bằng cách triển khai một hàm có một trong các tên dành riêng sau đây:

• onOpen sẽ thực thi khi người dùng mở một tài liệu, bảng tính hoặc bản trình bày. onOpen cũng có thể thực thi khi biểu mẫu được mở trong trình chỉnh sửa (nhưng không phải khi phản hồi biểu mẫu). Thao tác này chỉ thực thi nếu người dùng có quyền chỉnh sửa tệp liên quan và thường được dùng để tạo mục trong trình đơn.
• onInstall sẽ thực thi khi người dùng cài đặt một tiện ích bổ sung. Thông thường, onInstall chỉ được dùng để gọi onOpen; điều này đảm bảo rằng các trình đơn bổ sung sẽ xuất hiện ngay sau khi cài đặt mà không yêu cầu người dùng làm mới trang.
• onEdit sẽ thực thi khi người dùng thay đổi giá trị của một ô trong bảng tính. Điều kiện kích hoạt này không hoạt động để phản hồi các thao tác di chuyển ô, định dạng hoặc những thay đổi khác không làm thay đổi giá trị ô.

Quy định hạn chế

Các điều kiện kích hoạt đơn giản trong tiện ích bổ sung phải tuân theo các quy định hạn chế tương tự chi phối các điều kiện kích hoạt đơn giản trong các loại dự án Apps Script khác. Hãy đặc biệt lưu ý những hạn chế này khi thiết kế tiện ích bổ sung:

• Trình kích hoạt đơn giản sẽ không chạy nếu một tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét). Hành vi này ngăn các trình đơn tiện ích bổ sung của bạn được điền sẵn.
• Trong một số trường hợp nhất định, các tiện ích bổ sung của Trình chỉnh sửa sẽ chạy các trình kích hoạt đơn giản onOpen và onEdit ở chế độ không uỷ quyền. Chế độ này trình bày các chức năng như mô tả trong mô hình uỷ quyền tiện ích bổ sung.
• Các trình kích hoạt đơn giản không thể sử dụng dịch vụ hoặc thực hiện các hành động khác yêu cầu uỷ quyền, ngoại trừ những hành động được nêu trong mô hình uỷ quyền tiện ích bổ sung.
• Các trình kích hoạt đơn giản không thể chạy quá 30 giây. Giảm thiểu lượng xử lý được thực hiện trong một hàm kích hoạt đơn giản.
• Các trình kích hoạt đơn giản phải tuân theo hạn mức trình kích hoạt Apps Script.

Trình kích hoạt có thể cài đặt trong tiện ích bổ sung

Tiện ích bổ sung có thể tạo và sửa đổi các trình kích hoạt có thể cài đặt theo phương thức lập trình bằng dịch vụ Script của Apps Script. Bạn không thể tạo trình kích hoạt có thể cài đặt tiện ích bổ sung theo cách thủ công. Không giống như các trình kích hoạt đơn giản, trình kích hoạt có thể cài đặt có thể sử dụng các dịch vụ yêu cầu uỷ quyền.

Trình kích hoạt có thể cài đặt trong tiện ích bổ sung không gửi email lỗi cho người dùng khi gặp lỗi, vì trong hầu hết các trường hợp, người dùng không thể giải quyết vấn đề. Do đó, bạn nên thiết kế tiện ích bổ sung để xử lý lỗi thay cho người dùng một cách hiệu quả bất cứ khi nào có thể.

Tiện ích bổ sung có thể sử dụng các trình kích hoạt có thể cài đặt sau đây:

• Mở các trình kích hoạt có thể cài đặt sẽ thực thi khi người dùng mở một tài liệu, bảng tính hoặc khi một biểu mẫu được mở trong trình chỉnh sửa (nhưng không phải khi phản hồi biểu mẫu).
• Chỉnh sửa các trình kích hoạt có thể cài đặt sẽ thực thi khi người dùng thay đổi giá trị của một ô trong bảng tính. Điều kiện kích hoạt này không kích hoạt để phản hồi việc định dạng hoặc các thay đổi khác không làm thay đổi giá trị ô.
• Thay đổi: Trình kích hoạt có thể cài đặt sẽ thực thi khi người dùng thực hiện bất kỳ thay đổi nào trong bảng tính, bao gồm cả việc chỉnh sửa định dạng và sửa đổi chính bảng tính (chẳng hạn như thêm một hàng).

• Form-submit (Gửi biểu mẫu) là các trình kích hoạt có thể cài đặt sẽ thực thi khi một câu trả lời trên Google Biểu mẫu được gửi.

  Có hai phiên bản của điều kiện kích hoạt gửi biểu mẫu: một cho Trang tính (nơi thu thập câu trả lời của biểu mẫu) và một cho Google Biểu mẫu. Đối tượng sự kiện được truyền đến một hàm điều kiện kích hoạt gửi biểu mẫu của Trang tính đơn giản hơn và trả về các giá trị phản hồi trong các mảng đơn giản. Đối tượng sự kiện được truyền đến một hàm kích hoạt gửi biểu mẫu của Biểu mẫu cung cấp thêm thông tin, có trong đối tượng FormResponse.

• Điều kiện kích hoạt dựa trên thời gian (còn gọi là điều kiện kích hoạt theo đồng hồ) sẽ kích hoạt vào một thời điểm cụ thể hoặc lặp lại theo một khoảng thời gian đều đặn.

Cho phép các điều kiện kích hoạt có thể cài đặt

Thông thường, nếu nhà phát triển cập nhật một tiện ích bổ sung để sử dụng các dịch vụ mới yêu cầu uỷ quyền bổ sung, thì người dùng sẽ được nhắc uỷ quyền lại cho tiện ích bổ sung vào lần tiếp theo họ sử dụng.

Tuy nhiên, những tiện ích bổ sung sử dụng điều kiện kích hoạt sẽ gặp phải các thách thức đặc biệt về việc uỷ quyền. Hãy tưởng tượng một tiện ích bổ sung dùng một điều kiện kích hoạt để theo dõi lượt gửi biểu mẫu: người tạo biểu mẫu có thể uỷ quyền cho tiện ích bổ sung vào lần đầu tiên họ sử dụng, sau đó để tiện ích bổ sung chạy trong nhiều tháng hoặc nhiều năm mà không cần mở lại biểu mẫu. Nếu nhà phát triển tiện ích bổ sung cập nhật tiện ích bổ sung để sử dụng các dịch vụ mới yêu cầu uỷ quyền bổ sung, thì người tạo biểu mẫu sẽ không bao giờ thấy hộp thoại uỷ quyền lại vì họ không bao giờ mở lại biểu mẫu và tiện ích bổ sung sẽ ngừng hoạt động.

Không giống như các trình kích hoạt trong dự án Apps Script thông thường, các trình kích hoạt trong tiện ích bổ sung vẫn tiếp tục kích hoạt ngay cả khi cần được uỷ quyền lại. Tuy nhiên, tập lệnh vẫn sẽ gặp lỗi nếu gặp phải một dòng mã yêu cầu uỷ quyền mà tập lệnh không có. Để tránh trường hợp này, hãy dùng ScriptApp.getAuthorizationInfo để kiểm soát quyền truy cập vào những phần mã đã thay đổi giữa các phiên bản của tiện ích bổ sung.

Các ví dụ sau đây cho thấy cấu trúc nên dùng trong các hàm kích hoạt để tránh những cạm bẫy về việc uỷ quyền. Hàm kích hoạt ví dụ này phản hồi sự kiện gửi biểu mẫu trong một tiện ích bổ sung của Google Trang tính và nếu cần uỷ quyền lại, hàm này sẽ gửi cho người dùng tiện ích bổ sung một email cảnh báo bằng cách sử dụng HTML theo mẫu.

/**
 * 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>

Quy định hạn chế

Các trình kích hoạt có thể cài đặt trong tiện ích bổ sung phải tuân theo các quy định hạn chế tương tự như các quy định hạn chế chi phối trình kích hoạt có thể cài đặt trong các loại dự án Apps Script khác.

Ngoài những hạn chế này, có một số hạn chế áp dụng riêng cho các điều kiện kích hoạt có thể cài đặt trong tiện ích bổ sung:

• Mỗi tiện ích bổ sung chỉ có thể có một trình kích hoạt thuộc mỗi loại, cho mỗi người dùng, cho mỗi tài liệu. Ví dụ: trong một bảng tính nhất định, một người dùng nhất định chỉ có thể có một trình kích hoạt chỉnh sửa, mặc dù người dùng đó cũng có thể có trình kích hoạt gửi biểu mẫu hoặc trình kích hoạt theo thời gian trong cùng một bảng tính. Một người dùng khác có quyền truy cập vào cùng một bảng tính có thể có bộ trình kích hoạt riêng.
• Tiện ích bổ sung chỉ có thể tạo điều kiện kích hoạt cho tệp mà tiện ích bổ sung đó được dùng. Tức là một tiện ích bổ sung được dùng trong Google Tài liệu A không thể tạo một điều kiện kích hoạt để theo dõi thời điểm Google Tài liệu B được mở.
• Trình kích hoạt dựa trên thời gian không thể chạy thường xuyên hơn một lần mỗi giờ.
• Tiện ích bổ sung không tự động gửi email cho người dùng khi mã do một trình kích hoạt có thể cài đặt chạy sẽ tạo ra một ngoại lệ. Nhà phát triển có trách nhiệm kiểm tra và xử lý các trường hợp lỗi một cách thích hợp.
• Bộ kích hoạt bổ sung sẽ ngừng kích hoạt trong bất kỳ trường hợp nào sau đây:
  • Nếu người dùng gỡ cài đặt tiện ích bổ sung,
  • Nếu tiện ích bổ sung bị vô hiệu hoá trong một tài liệu (nếu được bật lại, thì trình kích hoạt sẽ hoạt động trở lại), hoặc
  • Nếu nhà phát triển huỷ xuất bản tiện ích bổ sung hoặc gửi một phiên bản bị lỗi đến cửa hàng tiện ích bổ sung.
• Các hàm kích hoạt của tiện ích bổ sung sẽ thực thi cho đến khi đạt đến mã sử dụng một dịch vụ không được uỷ quyền, tại thời điểm đó, các hàm này sẽ dừng. Điều này chỉ đúng nếu tiện ích bổ sung được xuất bản; cùng một trình kích hoạt trong một dự án Apps Script thông thường hoặc một tiện ích bổ sung chưa xuất bản sẽ không thực thi nếu bất kỳ phần nào của tập lệnh cần được uỷ quyền.
• Các điều kiện kích hoạt có thể cài đặt phải tuân theo hạn mức điều kiện kích hoạt của Apps Script.