Đ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 sẽ 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 khác nhau.

Khi một điều kiện kích hoạt được 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 khác nhau dựa trên loại trình kích hoạt.

Sau khi tạo đối tượng sự kiện, Apps Script sẽ truyền đối tượng đó dưới dạng tham số đến hàm kích hoạt. Hàm kích hoạt là một hàm gọi lại mà bạn phải tự triển khai để thực hiện mọi hành động 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, trình kích hoạt được dùng để tạo các mục trình đơn tiện ích bổ sung khi mở một tài liệu. Trong trường hợp này, bạn triển khai trên 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 nguyên tắc 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 điều kiện 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 của 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.

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à các 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ở 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.	Đố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 được 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 Gửi biểu mẫu trên Google.	Đối tượng sự kiện gửi biểu mẫu của Biểu mẫu Đối tượng sự kiện gửi biểu mẫu của Trang tính		Biểu mẫu Trang tính
Điều khiển 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 điểm hoặc khoảng thời gian cụ thể.	Đối tượng sự kiện do thời gian điều khiển		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 để trả lời, mà là 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

Trình kích hoạt đơn giản sử dụng một tập hợp tên hàm được đặt trước, không thể sử dụng các dịch vụ yêu cầu uỷ quyền và được tự động 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 được đặt trước sau đây:

• onOpen(e) 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 phải khi phản hồi biểu mẫu). Phương thức này chỉ thực thi nếu người dùng có quyền chỉnh sửa tệp có liên quan và thường được dùng để tạo mục trong trình đơn.
• onInstall(e) thực thi khi người dùng cài đặt mộ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 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. Điều kiện 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 trình kích hoạt đơn giản trong tiện ích bổ sung phải tuân theo cùng một quy định hạn chế chi phối các trình kích hoạt đơn giản trong các loại dự án Apps Script khác. Hãy lưu ý đặc biệt đến các hạn chế sau 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 tệp được mở ở chế độ chỉ có thể đọc (xem hoặc bình luận). Hành vi này sẽ ngăn 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, các tiện ích bổ sung của Trình chỉnh sửa sẽ chạy trình kích hoạt đơn giản onOpen(e) và onEdit(e) ở chế độ không uỷ quyền. Chế độ này hiển thị một số chức năng bổ sung như được nêu trong mô hình uỷ quyền tiện ích bổ sung.
• 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 cần 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.
• Trình kích hoạt đơn giản không thể chạy lâu hơn 30 giây. Hãy cẩn thận để 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.
• Trình kích hoạt đơn giản phải tuân theo giới hạn hạn mức của 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 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 của tiện ích bổ sung theo cách thủ công. Không giống như 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 họ gặp lỗi, vì trong hầu hết các trường hợp, người dùng không thể tự 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ý linh hoạt các lỗi 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:

• Trình kích hoạt có thể cài đặt 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).
• Trình kích hoạt có thể cài đặt Chỉnh sửa sẽ thực thi khi người dùng thay đổi giá trị ô 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ị ô.
• Điều kiện kích hoạt có thể cài đặt Thay đổi 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 Gửi biểu mẫu sẽ thực thi khi một câu trả lời trên Google Biểu mẫu được gửi.

• Trình kích hoạt theo thời gian (còn gọi là trình kích hoạt đồng hồ) 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.

Uỷ quyền cho 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 một tiện ích bổ sung để sử dụng các dịch vụ mới yêu cầu thêm quyền, thì người dùng sẽ được nhắc cấp lại quyền cho 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 trình kích hoạt sẽ gặp phải các vấn đề đặc biệt về việc uỷ quyền. Hãy tưởng tượng một tiện ích bổ sung sử dụng trình kích hoạt để theo dõi lượt gửi biểu mẫu: trình tạo biểu mẫu có thể uỷ quyền cho tiện ích bổ sung trong lần đầu tiên sử dụng, sau đó để tiện ích đó 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 cập nhật tiện ích bổ sung để sử dụng các dịch vụ mới yêu cầu cấp thêm quyền, thì trình 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 sẽ 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 không thành công nếu gặp phải một dòng mã yêu cầu quyền mà tập lệnh không có. Để tránh trường hợp này, nhà phát triển có thể sử dụng phương thức ScriptApp.getAuthorizationInfo() để kiểm soát 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 nhằm tránh các lỗi uỷ quyền. Hàm điều kiện kích hoạt mẫu phản hồi một 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 cấp lại quyền, sẽ gửi cho người dùng tiện ích bổ sung một email cảnh báo bằng HTML 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ùng một quy định hạn chế điều chỉnh các 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 quy định hạn chế này, một số quy định hạn chế cụ thể sẽ áp dụng cho các trình 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 của 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ó một bộ điều kiện 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. Tức là tiện ích bổ sung được dùng trong Google Tài liệu A không thể tạo điều kiện kích hoạt để giám sát thời điểm mở Google Tài liệu B.
• 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ã chạy bằng một trình kích hoạt có thể cài đặt gửi một ngoại lệ. Nhà phát triển có thể kiểm tra và xử lý các trường hợp lỗi một cách linh hoạt.
• Điều kiện kích hoạt của 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, 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ị lỗi đế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 gặp 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. Điều này chỉ đúng nếu tiện ích bổ sung được phát hành; cùng một điều kiện kích hoạt trong dự án Apps Script thông thường hoặc tiện ích bổ sung chưa phát hành 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.
• Trình kích hoạt có thể cài đặt phải tuân theo giới hạn hạn mức của trình kích hoạt Apps Script.