Trang này được dịch bởi Cloud Translation API.

Đ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 gọi lại 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 sự 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 sự 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 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	Điều kiện 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.	đố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 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ồ) Sự kiện kích hoạt sẽ diễn ra 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 để trả lời, mà xảy ra khi người chỉnh sửa mở biểu mẫu để sửa đổi.

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 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 một 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 chỉ cần triển khai một hàm có một trong các tên dành riêng sau đây:

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 phải khi trả lờ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 nhất để tạo mục trong trình đơn.
onInstall(e) sẽ 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 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(e) sẽ thực thi khi người dùng thay đổi giá trị của một ô trong bảng tính. Sự kiện kích hoạt này không hoạt động khi có các thao tá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ác quy định hạn chế tương tự 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 đặc biệt lưu ý đến 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 một tệp được mở ở chế độ chỉ đọc (xem hoặc nhận xét). Hành vi này sẽ 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(e) và onEdit(e) ở chế độ không uỷ quyền. Chế độ này có một số điểm phức tạp khác 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 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. Hãy chú ý giảm thiểu lượng dữ liệu được xử lý 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 của 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 họ 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 linh hoạt 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. Sự kiện 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).
Các trình kích hoạt có thể cài đặt Form-submit sẽ thực thi khi một câu trả lời trên Google Biểu mẫu được gửi.

Lưu ý: Có hai phiên bản của trình 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 trình 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 đồ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.

Uỷ quyền cho các 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 uỷ quyền, 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 tiện ích đó.

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 sử dụng một trình 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ể uỷ quyền cho tiện ích bổ sung vào lần đầu tiên 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 không thành công 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, 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 những cạm bẫy về việc uỷ quyền. Hàm kích hoạt mẫu phản hồi một sự kiện form-submit 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 dựa trên mẫu.

Code.gs

triggers/form/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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.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 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ự điều chỉnh 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ế cụ thể á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 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 dựa trên 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.
Điều kiện 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, 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ụ 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 xuất bản; cùng một điều kiện 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 giới hạn hạn mức của điều kiện kích hoạt Apps Script.

Điều kiện kích hoạt cho tiện ích bổ sung dành cho Trình chỉnh sửa Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

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

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

Quy định hạn chế

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

Uỷ quyền cho các trình kích hoạt có thể cài đặt

Code.gs

authorizationemail.html

Quy định hạn chế

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