בניית ממשקי Google Editor

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

איך ניגשים לממשק המשתמש של התוסף

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

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

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

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

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

יצירת ממשקים לתוספי עריכה

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

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. מטמיעים את פונקציות הקריאה החוזרת (callback) המשויכות הנדרשות כדי להגיב לאינטראקציות של ממשק המשתמש, כמו לחיצות על לחצנים.

דפי הבית של Editor

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

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

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

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

כדי להציג ב'עורכי Docs' את דף הבית המשותף של התוסף, צריך לכלול במניפסט של התוסף את שדות ה-Editor המתאימים, כמו 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

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

בדוגמה הבאה מוצג החלק addons במניפסט של תוסף Google Workspace. התוסף מופעל ב-Docs , Sheets ו-Slides. הוא מציג את דף הבית המשותף ב-Docs וב-Slides, ודף בית ייחודי ב-Sheets. פונקציית הקריאה החוזרת 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. כמו בכל כרטיס, עליכם להטמיע את פונקציות הקריאה החוזרת שמשמשות כדי לספק אינטראקטיביות לווידג'טים בממשק. לדוגמה, אם כוללים לחצן בממשק, צריך לכלול בו לחצן Action (פעולה) שמצורף אליו ופונקציית קריאה חוזרת (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. פונקציית הטריגר משתמשת במידע שבאובייקט האירוע כדי לקבוע איך ליצור כרטיסי תוספים או כדי לשלוט בדרך אחרת בהתנהגות של התוספים.

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

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

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

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

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