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

Các điều kiện kích hoạt Apps Script gây ra một tập lệnh được chỉ định (hàm kích hoạt) để thực thi mỗi khi xảy ra 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 trình kích hoạt và mỗi sự kiện Ứng dụng Google Workspace hỗ trợ một nhóm sự kiện khác.

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 sự kiện cấu trúc đối tượng được sắp xếp 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 thông 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 thích hợp nhằm đối phó với sự kiện. Ví dụ: trong Tiện ích bổ sung Trình chỉnh sửa, điều kiện 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 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 hướng dẫn về cách sử dụng trình kích hoạt trong người chỉnh sửa dự án tiện ích bổ sung.

Các loại trình kích hoạt Tiện ích bổ sung của 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 Apps Script trong Tiện ích bổ sung của trình chỉnh sửa, bao gồm cả các trình 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. Chiến lược phát hành đĩa đơn 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.

Bảng sau đây trình bày các loại điều kiện kích hoạt đơn giản và có thể cài đặt Tiện ích bổ sung của Trình chỉnh sửa có thể sử dụng và 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	Điều kiện kích hoạt có thể cài đặt
Mở Một tệp trình chỉnh sửa được mở ra.	Đối tượng sự kiện Tài liệu onOpen Đối tượng sự kiện onOpen trong Biểu mẫu Đối tượng sự kiện Trang tính onOpen Đối tượng sự kiện Trang trình bày onOpen	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 trên Trang tính	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 trên Trang tính		Trang tính
Gửi biểu mẫu Gửi một biểu mẫu bằng 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 hướng thời gian (đồng hồ) Trình kích hoạt sẽ kích hoạt vào thời gian hoặc khoảng thời gian được 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ở cho Google Biểu mẫu không xảy ra khi người dùng mở một biểu mẫu để phản hồ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

Điều kiện kích hoạt đơn giản sử dụng một nhóm tên hàm, 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 điều kiện 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 bằng cách triển khai một hàm bằng một trong những tên dành riêng 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 áp dụng khi phản hồi biểu mẫu). Hàm này chỉ thực thi nếu người dùng đã quyền chỉnh sửa tệp hữu quan và thông 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 là onInstall(e) vừa đượ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 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ị của ô 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ị của ô.

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ùng một quy tắc các quy định hạn chế đơn giản trong các loại dự án Apps Script khác. Lưu ý đặc biệt về những vấn đề này khi thiết kế tiện ích bổ sung:

• Các trình kích hoạt đơn giản không chạy nếu tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét). Hành vi này ngăn hệ thống điề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 trình chỉnh sửa sẽ chạy onOpen(e) và onEdit(e) trình kích hoạt đơn giản ở chế độ không cấp quyền. Chế độ này thể hiện một số chức năng khác như đượ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ể sử dụng dịch vụ hoặc nhận những hành động khác đòi hỏi uỷ quyền, ngoại trừ đượ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 lâu hơn 30 giây. Cẩn thận giảm thiểu số 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ụ thuộc vào điều kiện kích hoạt Apps Script hạn mức.

Điều kiện 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 điều kiện 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. tiện ích bổ sung Bạn không thể tạo trình kích hoạt có thể cài đặt theo cách thủ công. Không giống như các đ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ể sử dụng những dịch vụ yêu cầu uỷ quyền.

Các điều kiện kích hoạt có thể cài đặt trong tiện ích bổ sung sẽ không gửi email thông báo 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 thành xử lý lỗi thay mặt người dùng một cách linh hoạt bất cứ khi nào có thể.

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

• Các điều kiện kích hoạt Mở có thể cài đặt sẽ thực thi khi người dùng mở tài liệu, bảng tính hoặc khi biểu mẫu được mở trong trình chỉnh sửa (nhưng không mở khi phản hồi vào biểu mẫu).
• Các điều kiện 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 theo định dạng hoặc các thay đổi không làm thay đổi giá trị của ô.
• Các điều kiện kích hoạt Thay đổi 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 một bảng tính, bao gồm các chỉnh sửa định dạng và sửa đổi đối với 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 phản hồi trên Google Biểu mẫu là đã gửi.

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

Cho phép đ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 tiện ích bổ sung để sử dụng những dịch vụ mới đòi hỏi uỷ quyền bổ sung, người dùng sẽ được nhắc cấp quyền lại cho tiện ích bổ sung mỗi khi 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 thách thức ủy quyền đặc biệt. 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 số lượt gửi biểu mẫu: một biểu mẫu nhà sáng tạo có thể cho phép tiện ích bổ sung đó trong lần đầu tiên họ sử dụng rồi để 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 phải 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 thêm, người tạo biểu mẫu sẽ không bao giờ thấy hộp thoại cấp phép 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 các tiện ích bổ sung sẽ tiếp tục kích hoạt ngay cả khi cần được cấp quyền lại. Tuy nhiên, tập lệnh vẫn không thành công nếu đến một dòng mã yêu cầu uỷ quyền, 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 đã xuất bản của tiện ích bổ sung.

Dưới đây là ví dụ về cấu trúc nên dùng trong các hàm kích hoạt để để tránh cạm bẫy uỷ quyền. Hàm kích hoạt mẫu phản hồi một gửi biểu mẫu trong một tiện ích bổ sung Google Trang tính và nếu quá trình uỷ quyền lại bắt buộc, gửi cho người dùng tiện ích bổ sung một email cảnh báo 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 điều kiện kích hoạt có thể cài đặt trong tiện ích bổ sung phải tuân theo cùng quy định hạn chế quản lý các đ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, một số hạn chế áp dụng đối với thiết bị có thể cài đặt trình kích hoạt trong 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, cho mỗi tài liệu. Ví dụ: trong một bảng tính cho trước, một người dùng cụ thể chỉ có thể có một lần 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ộ 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à một 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 để theo dõi khi Google Tài liệu B được mở.
• 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ã chạy bằng điều kiện kích hoạt có thể cài đặt sẽ gửi ra một ngoại lệ. Việc kiểm tra là tuỳ thuộc vào nhà phát triển và xử lý các trường hợp không thành công một cách linh hoạt.
• 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ì điều kiện kích hoạt 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 cho 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 chúng đạt đến mã sử dụng dịch vụ trái phép mà tại thời điểm đó chúng sẽ ngừng hoạt động. Điều này chỉ đúng nếu đã phát hành tiện ích bổ sung; cùng một điều kiện kích hoạt trong 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 cần bất kỳ phần nào của tập lệnh uỷ quyền.
• Các điều kiện kích hoạt có thể cài đặt phải tuân theo điều kiện kích hoạt Apps Script hạn mức.