קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
תוספים ל-Google Workspace יכולים לספק ממשקים מותאמים אישית כשמשתמשים ב-Google Drive. כך תוכלו לספק למשתמש מידע רלוונטי נוסף, להפוך משימות לאוטומטיות ולחבר מערכות של צד שלישי ל-Google Drive.
גישה לממשק המשתמש של התוסף
אפשר לפתוח תוסף ל-Google Workspace ב-Google Drive אם הסמל שלו מופיע בעמודת הסמלים בצד שמאל של ממשק המשתמש של Drive. תוסף ל-Google Workspace יכול להגדיר ממשק של דף בית, ממשק לבחירת פריטים או את שניהם:
אם משתמש לוחץ על סמל התוסף ב-Google Drive, התוסף מפעיל את הפונקציה התואמת drive.homepageTrigger (אם היא קיימת). הפונקציה הזו יוצרת כרטיס לדף הבית ומחזירה אותו ל-Google Drive לתצוגה. אם לא מוגדרת פונקציה של drive.homepageTrigger, מוצג במקומה כרטיס גנרי של דף הבית.
אם המשתמש בוחר פריט אחד או יותר ב-Google Drive ואז לוחץ על סמל התוסף, או בוחר פריטים כשהתוסף פתוח, התוסף מפעיל את הפונקציה ההקשרית המתאימה drive.onItemsSelectedTrigger (אם היא קיימת). הפונקציה הזו יוצרת את ממשק 'הפריטים שנבחרו' ההקשרי של Google Drive לתוסף ומחזירה אותו ל-Google Drive להצגה.
פיתוח הממשק של התוסף ל-Drive
כדי ליצור ממשקים שמרחיבים את Google Drive, צריך לבצע את השלבים הכלליים הבאים:
מחליטים אם רוצים שלתוסף יהיה דף בית ספציפי ל-Drive.
כדאי גם להחליט אם רוצים לספק ממשק לפי הקשר כשמשתמש בוחר פריטים ב-Drive.
מטמיעים את פונקציות הקריאה החוזרת שנדרשות כדי להגיב לאינטראקציות של המשתמש עם ממשק המשתמש, כמו לחיצות על כפתורים.
דפי הבית של 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 היא אפליקציית המארח של התוסף, אובייקטים של אירועים הקשריים כוללים את השדה Drive event object שמכיל מידע ספציפי ללקוח של Drive.
אובייקטים של אירועים ב-Drive בהקשר של טריגרים לבחירת פריטים כוללים מידע על הפריטים שהמשתמש בחר כשהטריגר מופעל. כשמשתמש בוחר יותר מפריט אחד ב-Drive, אחד מהפריטים נחשב לפריט העיקרי שמעניין אותו. הפריט הזה נקרא פריט הסמן הפעיל.
[[["התוכן קל להבנה","easyToUnderstand","thumb-up"],["התוכן עזר לי לפתור בעיה","solvedMyProblem","thumb-up"],["סיבה אחרת","otherUp","thumb-up"]],[["חסרים לי מידע או פרטים","missingTheInformationINeed","thumb-down"],["התוכן מורכב מדי או עם יותר מדי שלבים","tooComplicatedTooManySteps","thumb-down"],["התוכן לא עדכני","outOfDate","thumb-down"],["בעיה בתרגום","translationIssue","thumb-down"],["בעיה בדוגמאות/בקוד","samplesCodeIssue","thumb-down"],["סיבה אחרת","otherDown","thumb-down"]],["עדכון אחרון: 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 }"]]
