פיתוח ממשקים ל-Google Drive

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

גישה לממשק המשתמש של תוסף ל-Google Workspace

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

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

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

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

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

דפי הבית של Drive

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

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

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

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

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

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

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

2. צריך לוודא שהמניפסט כולל את הקטע drive.onItemsSelectedTrigger.

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

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

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

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

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

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

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

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

בדוגמה הבאה מוצג אובייקט של אירוע ב-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"
      },
      ...
    ]
  },
  ...
}