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.
Tiện ích bổ sung của Google Workspace có thể cung cấp các giao diện tuỳ chỉnh khi người dùng đang sử dụng Google Drive. Điều này cho phép bạn cung cấp cho người dùng thông tin bổ sung có liên quan, tự động hoá các tác vụ và kết nối các hệ thống của bên thứ ba với Google Drive.
Truy cập vào giao diện người dùng của tiện ích bổ sung
Bạn có thể mở một tiện ích bổ sung của Google Workspace trong Google Drive nếu biểu tượng của tiện ích đó xuất hiện trong cột biểu tượng ở bên phải giao diện người dùng Drive. Tiện ích bổ sung của Google Workspace có thể xác định giao diện trang chủ, giao diện chọn mục hoặc cả hai:
Nếu người dùng nhấp vào biểu tượng tiện ích bổ sung khi đang ở trong Google Drive, tiện ích bổ sung sẽ thực thi hàm drive.homepageTrigger tương ứng (nếu có). Hàm này tạo và trả về một thẻ trang chủ cho Google Drive để hiển thị. Nếu không có hàm drive.homepageTrigger nào được xác định, thì một thẻ trang chủ chung sẽ xuất hiện.
Nếu người dùng chọn một hoặc nhiều mục trong Google Drive rồi nhấp vào biểu tượng tiện ích bổ sung hoặc chọn các mục trong khi tiện ích bổ sung đang mở, thì tiện ích bổ sung sẽ thực thi hàm theo ngữ cảnh drive.onItemsSelectedTrigger tương ứng (nếu có). Hàm này tạo giao diện "các mục đã chọn" theo ngữ cảnh trên Google Drive của tiện ích bổ sung và trả về giao diện đó cho Google Drive để hiển thị.
Xây dựng giao diện tiện ích bổ sung cho Drive
Bạn có thể tạo các giao diện mở rộng Google Drive bằng cách làm theo các bước chung sau:
Quyết định xem bạn có muốn tiện ích bổ sung của mình có một trang chủ dành riêng cho Drive hay không.
Ngoài ra, hãy quyết định xem bạn có muốn cung cấp giao diện theo ngữ cảnh khi người dùng chọn các mục trên Drive hay không.
Triển khai các hàm gọi lại được liên kết cần thiết để phản hồi các hoạt động tương tác của người dùng với giao diện người dùng, chẳng hạn như lượt nhấp vào nút.
Trang chủ của Drive
Google Drive hỗ trợ hiển thị trang chủ của tiện ích bổ sung Google Workspace.
Để hiển thị trang chủ chung của tiện ích bổ sung trong Google Drive, bạn chỉ cần đảm bảo rằng có trường addOns.drive trong tệp kê khai của tiện ích bổ sung.
Hoặc thêm drive.homepageTrigger vào tệp kê khai tiện ích bổ sung để cung cấp một trang chủ dành riêng cho Drive.
Trong cả hai trường hợp, bạn phải cung cấp tên của một hàm kích hoạt trang chủ trong dự án tập lệnh của tiện ích bổ sung. Hàm này được gọi tự động để tạo trang chủ Drive khi cần. Bạn phải triển khai hàm này để tạo và trả về một Card duy nhất hoặc một mảng các đối tượng Card tạo nên trang chủ. Hàm kích hoạt trang chủ được truyền một đối tượng sự kiện làm tham số chứa một số thông tin chung, chẳng hạn như nền tảng của ứng dụng. Bạn có thể sử dụng dữ liệu đối tượng sự kiện để điều chỉnh cấu trúc của trang chủ.
Giao diện theo bối cảnh của Drive cho các mục đã chọn
Google Drive dựa vào một điều kiện kích hoạt theo bối cảnh để xác định giao diện (nếu có) sẽ hiển thị khi người dùng chọn một hoặc nhiều mục trên Google Drive. Khi sự kiện kích hoạt xảy ra, sự kiện này sẽ thực thi hàm kích hoạt theo bối cảnh do trường drive.onItemsSelectedTrigger.runFunction chỉ định trong tệp kê khai tiện ích bổ sung.
Để tạo giao diện chọn mục theo bối cảnh cho Drive, bạn phải làm như sau:
Đảm bảo tệp kê khai của tiện ích bổ sung có https://www.googleapis.com/auth/drive.addons.metadata.readonlyscope
Giống như mọi thẻ, bạn phải triển khai mọi hàm gọi lại được dùng để cung cấp tính tương tác của tiện ích cho giao diện. Ví dụ: nếu bạn đưa một nút vào giao diện, thì nút đó phải có một Action được đính kèm và một hàm gọi lại đã triển khai chạy khi người dùng nhấp vào nút.
Đối tượng sự kiện
Một đối tượng sự kiện được tạo và truyền đến hàm kích hoạt drive.homepageTrigger hoặc drive.onItemsSelectedTrigger khi các hàm đó được gọi. Hàm kích hoạt có thể sử dụng thông tin trong đối tượng sự kiện này để xác định cách tạo thẻ bổ sung hoặc kiểm soát hành vi của tiện ích bổ sung.
Cấu trúc đầy đủ của các đối tượng sự kiện được mô tả trong phần Đối tượng sự kiện.
Khi Drive là ứng dụng lưu trữ đang hoạt động của tiện ích bổ sung, các đối tượng sự kiện theo bối cảnh sẽ bao gồm trường đối tượng sự kiện Drive mang thông tin cụ thể về ứng dụng Drive.
Các đối tượng sự kiện theo ngữ cảnh của Drive cho các điều kiện kích hoạt lựa chọn mục bao gồm thông tin về các mục mà người dùng đã chọn khi điều kiện kích hoạt hoạt động. Khi người dùng chọn nhiều mục trong Drive, một trong các mục đó sẽ được coi là một trong những mục mà người dùng quan tâm nhất; mục này được gọi là mục con trỏ đang hoạt động.
[[["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\u003eGoogle Workspace add-ons extend Google Drive functionality by offering custom interfaces for automation, insights, and third-party integrations.\u003c/p\u003e\n"],["\u003cp\u003eAdd-ons can provide a homepage within Google Drive and a contextual interface that appears when Drive items are selected.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers build these interfaces using Apps Script, defining triggers and functions in the add-on's manifest file.\u003c/p\u003e\n"],["\u003cp\u003eAdd-ons utilize event objects, including Drive-specific data, to tailor their behavior based on user interactions and selected items.\u003c/p\u003e\n"],["\u003cp\u003eWhen multiple items are selected in Google Drive, add-ons can access both the active cursor item and the full list of selected items for context.\u003c/p\u003e\n"]]],["Google Workspace add-ons enhance Google Drive with custom interfaces, triggered by user actions. Add-ons can display a homepage when the icon is clicked or a contextual interface upon item selection. Developers define these interfaces by implementing `homepageTrigger` or `onItemsSelectedTrigger` functions in the add-on's manifest. These functions build and return card-based UIs. Contextual triggers utilize event objects containing information about selected items, including an active cursor item for single-item interactions, to tailor the add-on's behavior.\n"],null,["# Building Google Drive interfaces\n\nGoogle Workspace add-ons can provide customized\ninterfaces when the user is using Google Drive. This lets you provide the user\nwith additional relevant information, automate tasks, and connect third-party\nsystems to Google Drive.\n\nAccessing the add-on UI\n-----------------------\n\nYou can open a Google Workspace add-on in\nGoogle Drive if its icon appears in the\nicon column on the right side of the Drive user interface. A\nGoogle Workspace add-on can\ndefine a homepage interface, an item select interface, or both:\n\n- If a user clicks the add-on icon while in Google Drive, the add-on executes the corresponding [`drive.homepageTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.homepageTrigger) function (if present). This function builds and returns a [homepage card](/workspace/add-ons/concepts/homepages) to Google Drive for display. If no [`drive.homepageTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.homepageTrigger) function is defined, a generic homepage card is displayed instead.\n- If the user selects one or more items in Google Drive and then clicks the add-on icon, or selects items while the add-on is open, the add-on executes the corresponding [`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger) contextual function (if present). This function builds the add-on's Google Drive [contextual \"items selected\" interface](#drive_contextual_interface_for_items_selected) and returns it to Google Drive for display.\n\nBuilding the add-on Drive interface\n-----------------------------------\n\nYou can build interfaces that extend Google Drive by following these general\nsteps:\n\n1. Decide whether you want your add-on to have a Drive-specific [homepage](/workspace/add-ons/concepts/homepages). Also decide if you want to provide a contextual interface for when the user selects Drive items.\n2. Add the appropriate [`addOns.common`](/apps-script/manifest/addons#AddOns.FIELDS.common) and [`addOns.drive`](/apps-script/manifest/addons#AddOns.FIELDS.drive) fields to the add-on script project [manifest](/workspace/add-ons/concepts/workspace-manifests), including any [Drive scopes](/workspace/add-ons/concepts/workspace-scopes#drive_scopes) required.\n3. If you are providing a [Drive-specific homepage](#drive_homepages), implement the [`drive.homepageTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.homepageTrigger) function to build this interface. You can also choose to use the [`common.homepageTrigger`](/apps-script/manifest/addons#Common.FIELDS.homepageTrigger) interface for multiple Google Workspace hosts.\n4. If you are providing a Drive contextual item selection interface, you must implement a [`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger) contextual trigger function to build this interface. See [Drive contextual interface for items selected](#drive_contextual_interface_for_items_selected)) for details.\n5. Implement the associated callback functions needed to respond to the user's UI interactions, such as button clicks.\n\n### Drive homepages\n\nGoogle Drive supports displaying Google Workspace add-on\n[homepages](/workspace/add-ons/concepts/homepages).\nTo show your add-on's common homepage in Google Drive simply make sure there\nis a [`addOns.drive`](/apps-script/manifest/addons#AddOns.FIELDS.drive) field\nin the add-on's manifest.\n\nAlternatively, add a\n[`drive.homepageTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.homepageTrigger)\nto the add-on manifest to provide a Drive-specific homepage.\n\nIn either case, you must provide the name of a homepage trigger function in your\nadd-on's script project. This function is automatically called to build the\nDrive homepage when it is needed. You must implement this function to build and\nreturn a single\n[`Card`](/apps-script/reference/card-service/card) or an array of\n[`Card`](/apps-script/reference/card-service/card)\nobjects that make up the homepage. The homepage trigger function is passed an\n[event object](/workspace/add-ons/concepts/event-objects)\nas a parameter that contains some general information such as the client's\nplatform. You can use the event object data to tailor the construction of the\nhomepage.\n\n### Drive contextual interface for items selected\n\nGoogle Drive relies on a contextual trigger to determine what interface\n(if any) to display when the user selects one or more Google Drive items. When the\ntrigger fires, it executes the contextual trigger function specified by the\n[`drive.onItemsSelectedTrigger.runFunction`](/apps-script/manifest/drive-addons#OnItemsSelectedTrigger.FIELDS.runFunction)\nfield in the add-on [manifest](/workspace/add-ons/concepts/workspace-manifests).\n\nTo create a contextual item selection interface for Drive, you must do the\nfollowing:\n\n1. Ensure the add-on's manifest includes the\n `https://www.googleapis.com/auth/drive.addons.metadata.readonly`\n [scope](/workspace/add-ons/concepts/workspace-scopes#drive_scopes)\n\n2. Ensure the manifest includes a\n [`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger)\n section.\n\n3. Implement the function named in the\n [`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger)\n field.\n This function accepts an [event object](#event_objects) as an argument\n and must return either a single\n [`Card`](/apps-script/reference/card-service/card) object or an array of\n [`Card`](/apps-script/reference/card-service/card) objects.\n\n4. As with any card, you must implement any callback functions used to provide\n widget interactivity for the interface. For example, if you include a button\n in the interface, it should have an attached\n [Action](/apps-script/reference/card-service/action)\n and an implemented callback function that run when the button is clicked.\n\n### Event objects\n\nAn [event object](/workspace/add-ons/concepts/event-objects) is created and passed\nto the [`drive.homepageTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.homepageTrigger)\nor [`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger)\ntrigger function when those functions are called. The trigger function can use\nthe information in this event object to determine how to construct add-on cards\nor otherwise control the add-on behavior.\n\nThe full structure of event objects is described in\n[Event objects](/workspace/add-ons/concepts/event-objects).\nWhen Drive is the acting host app of the add-on, contextual event objects\ninclude the\n[Drive event object](/workspace/add-ons/concepts/event-objects#drive_event_object)\nfield that carries Drive-specific client information.\n\nContextual Drive event objects for item selection triggers include information\nabout the items the user has selected when the trigger fires. When a user\nselects more than one item in Drive, one of the items is deemed to be one of\nprimary interest; this item is referred to as the *active cursor item*.\n| **Note:** If the add-on's behavior is meant to apply to multiple selected items, use the information provided in the [`drive.selectedItems`](/workspace/add-ons/concepts/event-objects#drive_event_object) array in the event object to identify them all. \n|\n| When an add-on's behavior should only be applied to a single selected item, use the information provided in the [`drive.activeCursorItem`](/workspace/add-ons/concepts/event-objects#drive_event_object) field of the event object to identify the item out of the full selection. Don't attempt to infer which item to use from the [`drive.selectedItems`](/workspace/add-ons/concepts/event-objects#drive_event_object) array.\n\nThe following example shows a\n[Drive event object](/workspace/add-ons/concepts/event-objects#drive_event_object)\nthat is passed to a\n[`drive.onItemsSelectedTrigger`](/apps-script/manifest/drive-addons#Drive.FIELDS.onItemsSelectedTrigger)\nfunction: \n\n {\n \"commonEventObject\": { ... },\n \"drive\": {\n \"activeCursorItem\":{\n \"addonHasFileScopePermission\": true,\n \"id\":\"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl\",\n \"iconUrl\": \"https://drive-thirdparty.googleusercontent.com...\",\n \"mimeType\":\"application/pdf\",\n \"title\":\"How to get started with Drive\"\n },\n \"selectedItems\": [\n {\n \"addonHasFileScopePermission\": true,\n \"id\":\"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl\",\n \"iconUrl\":\"https://drive-thirdparty.googleusercontent.com...\",\n \"mimeType\":\"application/pdf\",\n \"title\":\"How to get started with Drive\"\n },\n ...\n ]\n },\n ...\n }"]]
