ממשקים של Google Drive

כשמשתמשים בתוספים ל-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 בממשק "items selected" לפי הקשר של התוסף, ומחזירה אותו לתצוגה ב-Google Drive.

יצירת הממשק של התוסף ל-Drive

כדי ליצור ממשקים שמרחיבים את Google Drive, צריך לבצע את השלבים הכלליים הבאים:

  1. מחליטים אם רוצים שלתוסף יהיה דף בית ספציפי ל-Drive. כדאי גם להחליט אם לספק ממשק תלוי הקשר שבו המשתמשים בוחרים פריטים ב-Drive.
  2. מוסיפים את השדות addOns.common ו-addOns.drive המתאימים למניפסט של פרויקט הסקריפט של התוסף, כולל כל היקף ההרשאות שנדרש ב-Drive.
  3. אם אתם מספקים דף בית ספציפי ל-Drive, צריך להטמיע את הפונקציה drive.homepageTrigger כדי לבנות את הממשק. אפשר גם להשתמש בממשק common.homepageTrigger לכמה מארחים של Google Workspace.
  4. אם אתם משתמשים בממשק לבחירת פריטים לפי הקשר ב-Drive, כדי לבנות את הממשק הזה, עליכם להטמיע פונקציית הפעלה לפי הקשר drive.onItemsSelectedTrigger. לפרטים נוספים, ראו ממשק הקשרי של Drive לפריטים שנבחרו.
  5. מטמיעים את פונקציות הקריאה החוזרת (callback) המשויכות הנדרשות כדי להגיב לאינטראקציות של ממשק המשתמש, כמו לחיצות על לחצנים.

הגדלה של דפי הבית

Google Drive תומך בהצגת דפי בית של תוספי Google Workspace. כדי להציג את דף הבית המשותף של התוסף ב-Google Drive, צריך רק לוודא שיש שדה addOns.drive במניפסט של התוסף.

לחלופין, אפשר להוסיף drive.homepageTrigger למניפסט של התוסף כדי לספק דף בית ספציפי ל-Drive.

בכל מקרה, עליכם לציין את השם של פונקציית הטריגר של דף הבית בפרויקט הסקריפט של התוסף. הפונקציה מופעלת באופן אוטומטי כדי ליצור את דף הבית של Drive כשיש צורך בכך. צריך להטמיע את הפונקציה הזו כדי ליצור ולהחזיר Card או מערך של אובייקטים מסוג Card שמהם מורכב דף הבית. אובייקט אירוע מועבר לפונקציה של הטריגר בדף הבית, בתור פרמטר שמכיל מידע כללי כלשהו, כמו הפלטפורמה של הלקוח. ניתן להשתמש בנתונים של אובייקט האירוע כדי להתאים אישית את המבנה של דף הבית.

ממשק הקשרי של Drive לפריטים שנבחרו

Google Drive מסתמך על טריגר לפי הקשר כדי לקבוע איזה ממשק (אם בכלל) יוצג כשהמשתמש בוחר פריט אחד או יותר ב-Google Drive. כשהטריגר מופעל, הוא מריץ את פונקציית הטריגר לפי הקשר שצוינה בשדה drive.onItemsSelectedTrigger.runFunction במניפסט של התוסף.

כדי ליצור ממשק לבחירת פריטים לפי הקשר ב-Drive:

  1. בדיקה שהמניפסט של התוסף כולל את ההיקף https://www.googleapis.com/auth/drive.addons.metadata.readonly

  2. מוודאים שהמניפסט כולל קטע drive.onItemsSelectedTrigger.

  3. מטמיעים את הפונקציה שנקראת בשדה drive.onItemsSelectedTrigger. הפונקציה הזו מקבלת אובייקט אירוע כארגומנט, וחייבת להחזיר אובייקט Card יחיד או מערך של אובייקטים Card.

  4. כמו בכל כרטיס, עליכם להטמיע את פונקציות הקריאה החוזרות (callback) שמשמשות כדי לספק אינטראקטיביות לווידג'טים בממשק. לדוגמה, אם כוללים לחצן בממשק, צריך לצרף לו לחצן Action (פעולה) ופונקציית קריאה חוזרת שמוטמעת בכל לחיצה על הלחצן.

אובייקטים של אירוע

אובייקט אירוע נוצר ומועבר לפונקציה drive.homepageTrigger או לפונקציית הטריגר drive.onItemsSelectedTrigger כשהפונקציות האלה מופעלות. פונקציית הטריגר יכולה להשתמש במידע שבאובייקט האירוע כדי לקבוע איך ליצור כרטיסי תוספים או כדי לשלוט באופן אחר בהתנהגות של התוספים.

המבנה המלא של אובייקטים מסוג אירוע מתואר בקטע אובייקטים של אירוע. כש-Drive היא האפליקציה המארחת המשחקת של התוסף, אובייקטים של אירועים לפי הקשר כוללים את השדה אובייקט אירוע ב-Drive, שמכיל את פרטי הלקוח הספציפיים ל-Drive.

אובייקטים לפי הקשר של אירועים ב-Drive לטריגרים של בחירת פריטים כוללים מידע על הפריטים שהמשתמש בחר כשהטריגר מופעל. כשמשתמש בוחר יותר מפריט אחד ב-Drive, אחד מהפריטים נחשב לאחד מתחומי העניין העיקריים, והפריט הזה נקרא פריט הסמן הפעיל.

בדוגמה הבאה מוצג אובייקט של אירוע ב-Drive שמועבר לפונקציה drive.onItemsSelectedTrigger:

    {
      "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"
          },
          ...
        ]
      },
      ...
    }