Trình kích hoạt cho Tiện ích bổ sung dành cho trình chỉnh sửa

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

Khi một trình kích hoạt kích hoạt, hệ thống sẽ tạo một đối tượng sự kiện. 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 khác nhau dựa trên loại trình 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 thông số cho hàm của trình kích hoạt. Hàm kích hoạt là hàm callback mà bạn phải tự triển khai để thực hiện bất kỳ hành động nào thích hợp nhằm phản hồi sự kiện đó. Ví dụ: trong Tiện ích bổ sung dành cho trình chỉnh sửa, 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ài liệu. 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 dành cho 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 trình kích hoạt chung có sẵn cho các dự án Apps Script trong Tiện ích bổ sung trình chỉnh sửa, bao gồm cả trình kích hoạt đơn giản và hầu hết trình kích hoạt có thể cài đặt. Tập hợp chính xác các loại trình kích hoạt có sẵn phụ thuộc vào ứng dụng đang được mở rộng.

Lưu ý: Không giống như Tiện ích bổ sung dành cho Trình chỉnh sửa, các Tiện ích bổ sung của Google Workspace hiện không thể sử dụng các trình kích hoạt Apps Script chung đơn giản hoặc có thể cài đặt. Thay vào đó, chúng 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 bài viết Điều kiện kích hoạt tiện ích bổ sung của Google Workspace.

Bảng sau đây cho thấy 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 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 trong trình chỉnh sửa đang mở.	Tài liệu trên đối tượng sự kiện Open Biểu mẫu trên đối tượng sự kiện Open Trang tính trên đối tượng sự kiện Open Trang trình bày trên đối tượng sự kiệnOpen	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.	Đối tượng sự kiện onInstall	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 đã thay đổi.	Trang tính có tính năng onEdit đối tượng sự kiện	Trang tính function onEdit(e)	Trang tính
Thay đổi Nội dung trong một trang tính được chỉnh sửa hoặc định dạng.	Đối tượng sự kiện onChange trong Trang tính		Trang tính
Gửi biểu mẫu Bạn đã gửi một biểu mẫu qua Google Biểu mẫu.	Đối tượng sự kiện gửi biểu mẫu trên Biểu mẫu Đối tượng sự kiện gửi biểu mẫu trên Trang tính		Biểu mẫu Trang tính
Theo thời gian (đồng hồ) Trình kích hoạt sẽ kích hoạt tại một thời điểm hoặc khoảng thời gian chỉ định.	Đối tượng sự kiện theo thời gian		Tài liệu Biểu mẫu Trang tính Trang trình bày

* Sự kiện mở đối với 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 biểu mẫu.

Trình kích hoạt đơn giản trong tiện ích bổ sung

Điều kiện kích hoạt đơn giản sử dụng một 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, 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 điều kiện kích hoạt đơn giản vào tiện ích bổ sung đơn giản bằng cách triển khai hàm với một trong các tên dành riêng sau:

• onOpen(e) 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(e) cũng có thể thực thi khi một biểu mẫu được mở trong trình chỉnh sửa (nhưng không thực thi khi phản hồi biểu mẫu). Lệnh này chỉ thực thi nếu người dùng có quyền chỉnh sửa tệp được đề cập và thường được dùng nhất để tạo các mục trong trình đơn.
• onInstall(e) thực thi khi người dùng cài đặt tiện ích bổ sung. Thông thường, onInstall(e) chỉ được dùng để gọi onOpen(e); điều này đảm bảo rằng các trình đơn tiện ích 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(e) thực thi khi người dùng thay đổi giá trị ô trong bảng tính. Trình kích hoạt này không kích hoạt để phản hồi việc di chuyển ô, định dạng hoặc các 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 các tiện ích bổ sung phải tuân theo cùng các hạn chế 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 lưu ý cụ thể những hạn chế này khi thiết kế tiện ích bổ sung:

• Các trình kích hoạt đơn giản sẽ không chạy nếu bạn mở tệp ở chế độ chỉ có thể đọc (xem hoặc nhận xét). Hành vi này ngăn việc điền sẵn các trình đơn tiện ích bổ sung của bạn.
• Trong một số trường hợp nhất định, Tiện ích bổ sung dành cho trình chỉnh sửa sẽ chạy các trình kích hoạt đơn giản onOpen(e) và onEdit(e) ở chế độ không uỷ quyền. Chế độ này trình bày một số chức năng bổ sung như đã nêu trong mô hình uỷ quyền tiện ích bổ sung.
• Điều kiện kích hoạt đơn giản không thể dùng dịch vụ hoặc thực hiện các thao tác khác cần có uỷ quyền, ngoại trừ trường hợp đã 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 lâu hơn 30 giây. Hãy chú ý giảm thiểu khối lượng quá trình xử lý được thực hiện trong một hàm kích hoạt đơn giản.
• Các điều kiện kích hoạt đơn giản phải tuân theo hạn mức 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 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ụ Apps Script Script. Bạn không thể tạo trình kích hoạt có thể cài đặt bổ sung theo cách thủ công. Không giống như điều kiện kích hoạt đơn giản, điều kiện kích hoạt có thể cài đặt có thể dùng dịch vụ cần được uỷ quyền.

Các điều kiện kích hoạt có thể cài đặt trong tiện ích bổ sung không gửi email báo lỗi cho người dùng khi họ gặp lỗi, vì trong hầu hết 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 để thay mặt người dùng xử lý lỗi nhanh chóng bất cứ khi nào có thể.

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

• Các trình kích hoạt có thể cài đặt Open (Mở) 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).
• Các trình kích hoạt có thể cài đặt Edit (Chỉnh sửa) sẽ thực thi khi người dùng thay đổi giá trị ô trong bảng tính. Trình 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 điều kiện 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).

• Trình kích hoạt có thể cài đặt Form-submit sẽ thực thi khi một phản hồi trên Google Biểu mẫu được gửi.

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

• Điều kiện kích hoạt theo thời gian (còn gọi là điều kiện kích hoạt đồng hồ) kích hoạt tại một thời điểm cụ thể hoặc lặp lại trong một khoảng thời gian thông thường.

Cho phép trình kích hoạt có thể cài đặt

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

Tuy nhiên, các tiện ích bổ sung sử dụng điều kiện kích hoạt gặp phải một số thách thức đặc biệt về ủy quyền. Hãy tưởng tượng một tiện ích bổ sung sử dụng điều kiện kích hoạt để theo dõi việc gửi biểu mẫu: người tạo biểu mẫu có thể cho phép 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 bao giờ mở lại biểu mẫu. Nếu nhà phát triển tiện ích bổ sung phải cập nhật tiện ích bổ sung để sử dụng các dịch vụ mới cần được 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ư điều kiện kích hoạt trong các dự án Apps Script thông thường, các điều kiện kích hoạt trong tiện ích bổ sung sẽ tiếp tục kích hoạt ngay cả khi chúng cần được uỷ quyền lại. Tuy nhiên, tập lệnh vẫn không thành công nếu gặp một dòng mã yêu cầu sự uỷ quyền mà tập lệnh không có. Để tránh trường hợp này, các nhà phát triển có thể sử dụng phương thức ScriptApp.getAuthorizationInfo() để cổng quyền truy cập vào các phần mã đã thay đổi giữa các phiên bản đã phát hành của tiện ích bổ sung.

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

Mã.gs

trình kích hoạt/biểu mẫu/Code.gs

Xem trên GitHub

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

validationemail.html

kích hoạt/biểu mẫu/Uỷ quyềnEmail.html

Xem trên GitHub

<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 điều kiện kích hoạt có thể cài đặt trong các tiện ích bổ sung phải tuân theo cùng các hạn chế quản lý điều kiện 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òn có một số hạn chế áp dụng cho các trình kích hoạt có thể cài đặt trong các tiện ích bổ sung cụ thể:

• Mỗi tiện ích bổ sung chỉ có thể có một trình kích hoạt cho mỗi loại, cho mỗi người dùng và trên 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 điều kiện kích hoạt chỉnh sửa, mặc dù người dùng cũng có thể có một điều kiện kích hoạt gửi biểu mẫu hoặc một điều kiện 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 sử dụng. Điều này nghĩa là một tiện ích bổ sung được dùng trong Google Tài liệu A không thể tạo trình kích hoạt để theo dõi khi Google Tài liệu B được mở.
• Các trình kích hoạt theo 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 điều kiện kích hoạt có thể cài đặt chạy trả về một ngoại lệ. Nhà phát triển có quyền quyết định việc kiểm tra và xử lý các trường hợp lỗi một cách linh hoạt.
• Các trình kích hoạt tiện ích 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ị tắt 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ỷ phát hành tiện ích bổ sung hoặc gửi một phiên bản bị hỏng lên cửa hàng tiện ích bổ sung.
• Các hàm kích hoạt tiện ích bổ sung sẽ thực thi cho đến khi đạt đến mã sử dụng một dịch vụ trái phép. Tại thời điểm đó, các hàm này sẽ dừng lại. Điều này chỉ đúng nếu tiện ích bổ sung được xuất bản; trình kích hoạt tương tự trong dự án Apps Script thông thường hoặc một tiện ích bổ sung chưa phát hành hoàn toàn 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 trình kích hoạt có thể cài đặt phải tuân theo các giới hạn của trình kích hoạt Apps Script.