פיתוח ממשקים של Google Editor

בעזרת התוספים של Google Workspace, אפשר לספק ממשקים מותאמים אישית בכלי העריכה, כולל Google Docs‏, Sheets ו-Slides. כך תוכלו לספק למשתמש מידע רלוונטי, לבצע משימות באופן אוטומטי ולחבר מערכות של צד שלישי לכלי העריכה.

גישה לממשק המשתמש של התוסף

אפשר לפתוח תוסף של Google Workspace ב-Editors אם הסמל שלו מופיע בחלונית הצדדית של Google Workspace לגישה מהירה, שמשמאל לממשקי המשתמש של Docs, ‏ Sheets ו-Slides.

תוסף ל-Google Workspace יכול להציג את הממשקים הבאים:

• ממשקי דף הבית: אם המניפסט של התוסף כולל את הטריגר EDITOR_NAME.homepageTrigger ל-Editor שבו המשתמש פותח את התוסף, התוסף יוצר ומחזיר כרטיס דף בית במיוחד ל-Editor הזה. אם המניפסט של התוסף לא כולל את הערך EDITOR_NAME.homepageTrigger ל-Editor שבו המשתמש פותח אותו, יוצג במקום זאת כרטיס גנרי של דף הבית.

• ממשקי API ל-REST: אם התוסף משתמש ב-API ל-REST, אפשר לכלול טריגרים שמבקשים גישה למסמך לפי קובץ באמצעות ההיקף drive.file. לאחר ההרשאה, מופעל טריגר נוסף בשם EDITOR_NAME.onFileScopeGrantedTrigger ומתקבל ממשק ספציפי לקובץ.

• ממשקי תצוגה מקדימה של קישורים: אם התוסף שלכם משולב עם שירות של צד שלישי, תוכלו ליצור כרטיסים עם תצוגה מקדימה של תוכן מכתובות ה-URL של השירות.

פיתוח ממשקים לתוספים של עורך Google

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

1. מוסיפים את השדות המתאימים addOns.common,‏ addOns.docs,‏ addOns.sheets ו-addOns.slides למניפסט של פרויקט הסקריפט של התוסף.
2. מוסיפים את כל היקפי העריכה הנדרשים למניפסט של פרויקט הסקריפט.
3. אם אתם מספקים דף בית ספציפי לעורכים, צריך להטמיע את הפונקציה EDITOR_NAME.homepageTrigger כדי ליצור את הממשק. אם לא, תוכלו להשתמש בממשק common.homepageTrigger כדי ליצור דף בית משותף לאפליקציות המארחות.
4. אם אתם משתמשים ב-API ל-REST, כדאי להטמיע את תהליך ההרשאה ברמת ההיקף drive.file ואת פונקציית הטריגר EDITOR_NAME.onFileScopeGrantedTrigger כדי להציג ממשק ספציפי לקובץ הפתוח. למידע נוסף, ראו ממשקי API ל-REST.
5. אם מגדירים תצוגות מקדימות של קישורים משירות צד שלישי, צריך להטמיע את התהליך של הרשאת ההיקף https://www.googleapis.com/auth/workspace.linkpreview ואת הפונקציה linkPreviewTriggers. מידע נוסף זמין במאמר ממשקי תצוגה מקדימה של קישורים.
6. מטמיעים את פונקציות הקריאה החוזרת המשויכות שנדרשות כדי להגיב לאינטראקציות של המשתמש בממשק המשתמש, כמו קליקים על לחצנים.

דפי הבית של עורכי תוכן

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

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

אתם יכולים להציג דף בית משותף או דף בית ספציפי לכלי העריכה שבו המשתמש פותח את התוסף.

הצגת דף הבית המשותף

כדי להציג את דף הבית המשותף של התוסף בכל אחד מהעורכים, צריך לכלול את השדות המתאימים של העורכים, כמו addOns.docs,‏ addOns.sheets או addOns.slides, במניפסט של התוסף.

בדוגמה הבאה מוצג החלק addons במניפסט של תוסף ל-Google Workspace. התוסף מרחיב את Docs,‏ Sheets ו-Slides, ומציג את דף הבית המשותף בכל אפליקציית מארח.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

הצגת דף בית ספציפי לעורכים

כדי להציג דף בית ספציפי לעורך, מוסיפים את EDITOR_NAME.homepageTrigger למניפסט של התוסף.

בדוגמה הבאה מוצג החלק addons במניפסט של תוסף ל-Google Workspace. התוסף מופעל ב-Docs, ב-Sheets וב-Slides. הוא מציג את דף הבית המשותף ב-Docs וב-Slides, ודף בית ייחודי ב-Sheets. פונקציית ה-callback‏ onSheetsHomepage יוצרת את הכרטיס בדף הבית שספציפי ל-Sheets.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

ממשקי API ל-REST

אם התוסף משתמש בממשקי API מסוג REST, כמו Google Sheets API, תוכלו להשתמש בפונקציה onFileScopeGrantedTrigger כדי להציג ממשק חדש שספציפי לקובץ הפתוח באפליקציית המארח של ה-Editor.

כדי להשתמש בפונקציה onFileScopeGrantedTrigger, צריך לכלול את תהליך ההרשאה ברמת ההיקף drive.file. במאמר בקשת גישה לקובץ של המסמך הנוכחי מוסבר איך לבקש את ההיקף drive.file.

כשמשתמש מעניק את ההיקף drive.file, האירוע EDITOR_NAME.onFileScopeGrantedTrigger.runFunction מופעל. כשהטריגר מופעל, הוא מפעיל את פונקציית הטריגר לפי הקשר שצוינה בשדה EDITOR_NAME.onFileScopeGrantedTrigger.runFunction במניפסט של התוסף.

כדי ליצור ממשק API ל-REST לאחד מהעורכים, פועלים לפי השלבים הבאים. מחליפים את EDITOR_NAME באפליקציית המארח של Editor שבה רוצים להשתמש, לדוגמה sheets.onFileScopeGrantedTrigger.

1. מוסיפים את EDITOR_NAME.onFileScopeGrantedTrigger בקטע המתאים של עורך הקוד במניפסט. לדוגמה, אם רוצים ליצור את הממשק הזה ב-Google Sheets, מוסיפים את הטריגר לקטע "sheets".
2. מטמיעים את הפונקציה שצוינה בקטע EDITOR_NAME.onFileScopeGrantedTrigger. הפונקציה הזו מקבלת אובייקט אירוע כארגומנט, והיא חייבת להחזיר אובייקט Card יחיד או מערך של אובייקטים מסוג Card.
3. כמו בכל כרטיס, צריך להטמיע את פונקציות הקריאה החוזרת שמשמשות לספק אינטראקטיביות של ווידג'ט לממשק. לדוגמה, אם אתם כוללים לחצן בממשק, צריך לצרף לו פעולה ופונקציית קריאה חוזרת (callback) שמופעל כשלוחצים על הלחצן.

בדוגמה הבאה מוצג החלק addons במניפסט של תוסף ל-Google Workspace. התוסף משתמש ב-API ל-REST, ולכן onFileScopeGrantedTrigger כלול ב-Google Sheets. כשמשתמש מעניק את ההיקף drive.file, פונקציית הקריאה החוזרת onFileScopeGrantedSheets יוצרת ממשק ספציפי לקובץ.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

ממשקי תצוגה מקדימה של קישורים לשירותי צד שלישי

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

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

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

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

המבנה המלא של אובייקטי האירועים מתואר בקטע אובייקטי אירועים.

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

אם לתוסף אין הרשאת היקף drive.file למשתמש או למסמך הנוכחיים, אובייקט האירוע מכיל רק את השדה docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission או slides.addonHasFileScopePermission. אם לתוסף יש הרשאה, אובייקט האירוע מכיל את כל השדות של אובייקט האירוע ב-Editor.

בדוגמה הבאה מוצג אובייקט אירוע של עורך שמוענק לפונקציה sheets.onFileScopeGrantedTrigger. כאן, לתוסף יש הרשאת היקף drive.file למסמך הנוכחי:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }