Điều kiện kích hoạt cho tiện ích bổ sung của Google Workspace
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.
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 Google Workspace mở rộng Gmail, bạn có thể xác định một điều kiện kích hoạt để tạo giao diện thẻ mới khi người dùng mở một chuỗi thư. Trong trường hợp này, bạn sẽ triển khai một hàm gọi lại theo bối cảnh để tạo các thẻ tạo nên giao diện người dùng mới bằng cách sử dụng dữ liệu được truyền trong đối tượng sự kiện.
Trang này cung cấp hướng dẫn về cách sử dụng các điều kiện kích hoạt trong dự án tiện ích bổ sung Google Workspace.
Trình kích hoạt tệp kê khai
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 hiện không thể sử dụng trình kích hoạt đơn giản của Apps Script. Thay vào đó, các tiện ích này sử dụng trình kích hoạt được thiết kế riêng cho tiện ích bổ sung của Google Workspace: trình kích hoạt tệp kê khai.
Các điều kiện kích hoạt tệp kê khai được xác định hoàn toàn trong tệp kê khai của tiện ích bổ sung Google Workspace. Sau đây là một số ví dụ về các điều kiện kích hoạt tệp kê khai:
Trình kích hoạt trang chủ tạo và hiển thị trang chủ của tiện ích bổ sung.
Sự kiện trên lịchMở các điều kiện kích hoạt hiển thị thẻ mới hoặc thực hiện các hành động khác khi một sự kiện trên Lịch được mở.
Sự kiện trên lịchKích hoạt sự kiện cập nhật hiển thị thẻ mới hoặc thực hiện các hành động khác khi người dùng chỉnh sửa và lưu một sự kiện trên Lịch.
Trình kích hoạt Drive onItemsSelected hiển thị một thẻ mới hoặc thực hiện các hành động khác khi người dùng chọn một hoặc nhiều tệp hoặc thư mục trong Drive.
Trình kích hoạt soạn thư trong Gmail sẽ hiển thị thẻ tiện ích bổ sung khi người dùng mở tiện ích bổ sung trong cửa sổ soạn thư của Gmail.
Trình kích hoạt theo bối cảnh của Gmail sẽ hiển thị một thẻ mới hoặc thực hiện các hành động khác khi người dùng mở một thư trong Gmail.
Editor onFileScopeGranted triggers hiển thị một thẻ mới khi người dùng cấp quyền uỷ quyền cho phạm vi OAuth drive.file trong tài liệu Editor hiện tại.
Trong danh sách trên, chỉ có trình kích hoạt trang chủ là không theo bối cảnh; các trình kích hoạt còn lại là trình kích hoạt theo bối cảnh. Hãy xem Tệp kê khai để biết thêm thông tin về các định nghĩa về điều kiện kích hoạt tệp kê khai.
Ngoài các trình kích hoạt tệp kê khai, các tiện ích bổ sung của Google Workspace cũng có thể sử dụng trình kích hoạt có thể cài đặt của Apps Script.
Quy định hạn chế
Các điều kiện kích hoạt trong tệp kê khai có một số hạn chế khi sử dụng.
Các trình kích hoạt này chỉ được dùng trong các dự án tiện ích bổ sung của Google Workspace; chúng không có mục đích nào trong bất kỳ ứng dụng nào khác.
Vì được xác định trong tệp kê khai tiện ích bổ sung chứ không phải trong mã của tiện ích bổ sung, nên bạn không thể sử dụng dịch vụ Script Apps Script để tạo hoặc sửa đổi các trình kích hoạt này.
Hiện tại, các điều kiện kích hoạt theo bối cảnh của Gmail chỉ có thể có tiêu chí unconditional.
Điều này có nghĩa là các điều kiện kích hoạt theo ngữ cảnh sẽ kích hoạt cho mọi thư email, bất kể nội dung.
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.
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 2025-07-31 UTC."],[[["\u003cp\u003eApps Script triggers execute a specific function when a defined event occurs within a Google Workspace application.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Workspace add-ons utilize manifest triggers, defined in the add-on's manifest, to respond to events like opening a document or composing an email.\u003c/p\u003e\n"],["\u003cp\u003eManifest triggers can be contextual, reacting to specific user actions within a document or application, or non-contextual, like those that build the add-on's homepage.\u003c/p\u003e\n"],["\u003cp\u003eWhile manifest triggers offer event-driven functionality, they have limitations, including restrictions on their use and creation methods.\u003c/p\u003e\n"]]],["Apps Script triggers initiate a script function when specific events occur, creating an event object with event details. This object is then passed to a user-implemented trigger function, enabling actions based on the event. Google Workspace add-ons use manifest triggers, defined in the add-on's manifest, to trigger actions like displaying cards on homepage, when opening/updating Calendar events, selecting Drive items, or opening a message in Gmail. Contextual triggers and installable triggers are also supported but with some restrictions.\n"],null,["# Triggers for Google Workspace add-ons\n\n[Apps Script triggers](/apps-script/guides/triggers) cause a specified script\nfunction (the *trigger function*) to execute whenever a specified event\noccurs. Only certain events can cause triggers to fire, and each\nGoogle Workspace application supports a different set of events.\n\nWhen a trigger fires, an *event object* is created. This JSON structure\ncontains details about the event that occurred. The information in the event\nobject structure is organized differently based on the trigger type.\n\nOnce the event object is created, Apps Script passes it as a parameter to the\ntrigger function. The trigger function is a callback function that you must\nimplement yourself, to take whatever actions are appropriate to respond to the\nevent. For example, in a\nGoogle Workspace add-on that extends Gmail, you can\ndefine a trigger that creates a new card interface when the user opens a message\nthread. In this case, you implement a contextual callback function to create\nthe cards making up the new UI using the data passed in the\n[event object](/workspace/add-ons/concepts/event-objects).\n\nThis page provides guidelines on using triggers in\nGoogle Workspace\nadd-on projects.\n\nManifest triggers\n-----------------\n\nUnlike Editor add-ons, Google Workspace add-ons\ncurrently can't use Apps Script [simple triggers](/apps-script/guides/triggers)\nInstead, they use triggers designed specifically for\nGoogle Workspace add-ons: *manifest triggers*.\n\nManifest triggers are defined completely in the\nGoogle Workspace add-on's\n[manifest](/workspace/add-ons/concepts/workspace-manifests). Examples of manifest triggers include the\nfollowing:\n\n- **Homepage triggers** that build and display the add-on homepage.\n- **Calendar eventOpen triggers** that display a new card or take other actions when a Calendar event is opened.\n- **Calendar eventUpdate triggers** that display a new card or take other actions when a user edits and saves a Calendar event.\n- **Drive onItemsSelected triggers** that display a new card or take other actions when a user selects one or more files or folders in Drive.\n- **Gmail compose triggers** that display an add-on card when the user opens the add-on in the Gmail compose window.\n- **Gmail contextual triggers** that display a new card or take other actions when the user opens a Gmail message.\n- **Editor onFileScopeGranted triggers** that display a new card when users grant authorization for the `drive.file` OAuth scope in the current Editor document.\n\nIn the above list, only homepage triggers are non-contextual; the rest are\ncontextual triggers. See [Manifest](/workspace/add-ons/concepts/workspace-manifests)\nfor more information about manifest trigger definitions.\n\nIn addition to manifest triggers, Google Workspace\nadd-ons can also use Apps Script\n[installable triggers](/apps-script/guides/triggers/installable).\n\n### Restrictions\n\nManifest triggers have certain restrictions to their use.\n\n- These triggers are only used in Google Workspace add-on projects; they have no purpose in any other application.\n- Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script [`Script`](/apps-script/reference/script) service to create or modify these triggers.\n- Gmail contextual triggers currently can only have an `unconditional` criteria. This means contextual triggers fire for every email message, regardless of content.\n- Each add-on can only have one trigger of each type, per user, per document."]]
