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

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

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

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

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

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

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

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

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

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

1. הוספת ההקשר המתאים addOns.common addOns.docs, addOns.sheets, וגם addOns.slides למניפסט של פרויקט הסקריפט של התוסף.
2. מוסיפים את כל היקפי ההרשאות הנדרשים של Editor אל את המניפסט של פרויקט הסקריפט.
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 שמרכיבים את דף הבית של התוסף.

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

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

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

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

עליך לכלול את תהליך ההרשאה להיקף של drive.file כדי להשתמש onFileScopeGrantedTrigger. כדי לדעת איך לבקש את 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) שמשמשות כדי לספק האינטראקטיביות של הווידג'ט לממשק. לדוגמה, אם כוללים לחצן בממשק, צריכה להיות לו פונקציית 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"
     }
   }

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

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

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

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

אובייקט אירוע נוצר ומוענק כדי להפעיל פונקציות, כמו 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"
          },
          ...
        }