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

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

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

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

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

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

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

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

בניית ממשקים לתוספים לעורכים

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

1. מוסיפים את השדות המתאימים addOns.common,‏ addOns.docs,‏ addOns.sheets ו-addOns.slides אל המניפסט של פרויקט הסקריפט של התוסף.
2. מוסיפים את כל ההיקפים של הרשאות העריכה הנדרשים למניפסט של פרויקט הסקריפט.
3. אם אתם מספקים דף בית ספציפי לעורך, צריך להטמיע את הפונקציה EDITOR_NAME.homepageTrigger כדי לבנות את הממשק. אם לא, אפשר להשתמש בממשק common.homepageTrigger כדי ליצור דף בית משותף לאפליקציות המארחות.
4. אם משתמשים בממשקי REST API, צריך להטמיע את תהליך ההרשאה של היקף drive.file ואת פונקציית הטריגר EDITOR_NAME.onFileScopeGrantedTrigger כדי להציג ממשק שספציפי לקובץ הפתוח. מידע נוסף זמין במאמר ממשקי REST API.
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. פונקציית הקריאה החוזרת 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

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

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

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

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

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

בדוגמה הבאה מוצג החלק addons במניפסט של תוסף ל-Google Workspace. התוסף משתמש בממשקי REST API, ולכן 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"
          },
          ...
        }