בניית ממשקי עריכה ב-Google

בעזרת תוספים ל-Google Workspace, אתם יכולים לספק ממשקים מותאמים אישית בתוך כלי העריכה, כולל Google Docs,‏ Google Sheets ו-Google 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 עבור כלי העריכה, פועלים לפי השלבים הבאים:

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

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

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

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

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

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

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

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

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

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

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

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

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