פיתוח ממשקים ל-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"
      },
      ...
    ]
  },
  ...
}