Google Drive 인터페이스 빌드
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Google Workspace 부가기능은 사용자가 Google Drive를 사용할 때 맞춤 인터페이스를 제공할 수 있습니다. 이를 통해 사용자에게 관련 정보를 추가로 제공하고, 작업을 자동화하고, 서드 파티 시스템을 Google Drive에 연결할 수 있습니다.
부가기능 UI 액세스
Google Drive 사용자 인터페이스의 오른쪽에 있는 아이콘 열에 아이콘이 표시되면 Google Drive에서 Google Workspace 부가기능을 열 수 있습니다. Google Workspace 부가기능은 홈페이지 인터페이스, 항목 선택 인터페이스 또는 둘 다를 정의할 수 있습니다.
부가기능 Drive 인터페이스 빌드
다음 일반적인 단계에 따라 Google Drive를 확장하는 인터페이스를 빌드할 수 있습니다.
- 부가기능에 Drive 전용 홈페이지를 사용할지 결정합니다.
사용자가 Drive 항목을 선택할 때 상황별 인터페이스를 제공할지 여부도 결정합니다.
- 필요한 Drive 범위를 포함하여 적절한
addOns.common 및 addOns.drive 필드를 부가기능 스크립트 프로젝트 매니페스트에 추가합니다.
- 드라이브 전용 홈페이지를 제공하는 경우
drive.homepageTrigger 함수를 구현하여 이 인터페이스를 빌드합니다. 여러 Google Workspace 호스트에 common.homepageTrigger 인터페이스를 사용할 수도 있습니다.
- Drive 컨텍스트 항목 선택 인터페이스를 제공하는 경우
drive.onItemsSelectedTrigger 컨텍스트 트리거 함수를 구현하여 이 인터페이스를 빌드해야 합니다.
자세한 내용은 선택한 항목의 드라이브 컨텍스트 인터페이스를 참고하세요.
- 버튼 클릭과 같은 사용자의 UI 상호작용에 응답하는 데 필요한 연결된 콜백 함수를 구현합니다.
Drive 홈페이지
Google Drive는 Google Workspace 부가기능 홈페이지 표시를 지원합니다.
Google Drive에 부가기능의 공통 홈페이지를 표시하려면 부가기능의 매니페스트에 addOns.drive 필드가 있는지 확인하세요.
또는 부가기능 매니페스트에 drive.homepageTrigger를 추가하여 Drive 전용 홈페이지를 제공할 수 있습니다.
어떤 경우든 부가기능의 스크립트 프로젝트에 홈페이지 트리거 함수의 이름을 제공해야 합니다. 이 함수는 필요할 때 Drive 홈페이지를 빌드하기 위해 자동으로 호출됩니다. 이 함수를 구현하여 홈페이지를 구성하는 단일 Card 또는 Card 객체 배열을 빌드하고 반환해야 합니다. 홈페이지 트리거 함수에는 클라이언트의 플랫폼과 같은 일반적인 정보가 포함된 이벤트 객체가 매개변수로 전달됩니다. 이벤트 객체 데이터를 사용하여 홈페이지의 구성을 맞춤설정할 수 있습니다.
선택한 항목의 Drive 컨텍스트 인터페이스
Google Drive는 상황별 트리거를 사용하여 사용자가 하나 이상의 Google Drive 항목을 선택할 때 표시할 인터페이스(있는 경우)를 결정합니다. 트리거가 실행되면 부가기능 매니페스트의 drive.onItemsSelectedTrigger.runFunction 필드에 지정된 컨텍스트 트리거 함수가 실행됩니다.
Drive의 컨텍스트 항목 선택 인터페이스를 만들려면 다음을 실행해야 합니다.
애드온의 매니페스트에 https://www.googleapis.com/auth/drive.addons.metadata.readonly
범위가 포함되어 있는지 확인합니다.
매니페스트에 drive.onItemsSelectedTrigger 섹션이 포함되어 있는지 확인합니다.
drive.onItemsSelectedTrigger 필드에 지정된 함수를 구현합니다.
이 함수는 이벤트 객체를 인수로 허용하며 단일 Card 객체 또는 Card 객체의 배열을 반환해야 합니다.
다른 카드와 마찬가지로 인터페이스의 위젯 상호작용을 제공하는 데 사용되는 콜백 함수를 구현해야 합니다. 예를 들어 인터페이스에 버튼을 포함하는 경우 버튼이 클릭될 때 실행되는 작업이 연결되어 있고 콜백 함수가 구현되어 있어야 합니다.
이벤트 객체
이벤트 객체는 함수가 호출될 때 생성되어 drive.homepageTrigger 또는 drive.onItemsSelectedTrigger 트리거 함수에 전달됩니다. 트리거 함수는 이 이벤트 객체의 정보를 사용하여 부가기능 카드를 구성하는 방법이나 부가기능 동작을 제어하는 방법을 결정할 수 있습니다.
이벤트 객체의 전체 구조는 이벤트 객체에 설명되어 있습니다.
Drive가 부가기능의 호스트 앱으로 작동하는 경우 컨텍스트 이벤트 객체에는 Drive 관련 클라이언트 정보를 전달하는 Drive 이벤트 객체 필드가 포함됩니다.
항목 선택 트리거의 컨텍스트 Drive 이벤트 객체에는 트리거가 실행될 때 사용자가 선택한 항목에 관한 정보가 포함됩니다. 사용자가 Drive에서 두 개 이상의 항목을 선택하면 항목 중 하나가 기본 관심 항목으로 간주됩니다. 이 항목을 활성 커서 항목이라고 합니다.
다음 예시는 drive.onItemsSelectedTrigger 함수에 전달되는 Drive 이벤트 객체를 보여줍니다.
{
"commonEventObject": { ... },
"drive": {
"activeCursorItem":{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl": "https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
"selectedItems": [
{
"addonHasFileScopePermission": true,
"id":"0B_sX1fXRRU6Ac3RhcnRlcl9maWxl",
"iconUrl":"https://drive-thirdparty.googleusercontent.com...",
"mimeType":"application/pdf",
"title":"How to get started with Drive"
},
...
]
},
...
}
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-07-31(UTC)
[null,null,["최종 업데이트: 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 }"]]
