בניית ממשקי עריכה ב-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, שמכילים מידע על הלקוח.

אם לתוסף אין הרשאת היקף 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"
  },
  ...
}