בעזרת תוספים ל-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 עבור העורכים, יש לפעול לפי השלבים הבאים:
- מוסיפים את השדות המתאימים
addOns.common
,addOns.docs
,addOns.sheets
וaddOns.slides
לפרויקט הסקריפט של התוסף למניפסט. - הוסיפו את כל היקפי ההרשאות הנדרשים למניפסט של פרויקט הסקריפט.
- אם אתם מספקים דף בית ספציפי לעורך, עליכם להטמיע את הפונקציה
EDITOR_NAME.homepageTrigger
כדי לבנות את הממשק. אם לא, כדאי להשתמש בממשקcommon.homepageTrigger
כדי ליצור דף בית משותף לאפליקציות המארחות. - כשמשתמשים בממשקי API ל-REST, צריך להטמיע את תהליך ההרשאה להיקף
drive.file
ואת פונקציית ההפעלהEDITOR_NAME.onFileScopeGrantedTrigger
כדי להציג ממשק ספציפי לקובץ הפתוח. מידע נוסף זמין במאמר ממשקים ל-API ל-REST. - אם מגדירים תצוגות מקדימות של קישורים משירות של צד שלישי, צריך להטמיע את תהליך ההרשאה של היקף ההרשאות
https://www.googleapis.com/auth/workspace.linkpreview
ואת הפונקציהlinkPreviewTriggers
. מידע נוסף זמין במאמר ממשקים לתצוגה מקדימה של קישורים. - מטמיעים את פונקציות הקריאה החוזרת (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
.
- יש לכלול את
EDITOR_NAME.onFileScopeGrantedTrigger
בקטע העורך המתאים במניפסט. לדוגמה, אם רוצים ליצור את הממשק הזה ב-Google Sheets, צריך להוסיף את הטריגר לקטע"sheets"
. - מטמיעים את הפונקציה שנקראת בקטע
EDITOR_NAME.onFileScopeGrantedTrigger
. הפונקציה הזו מקבלת אובייקט אירוע כארגומנט, וחייבת להחזיר אובייקטCard
יחיד או מערך שלCard
אובייקטים. - כמו בכל כרטיס, עליכם להטמיע את פונקציות הקריאה החוזרת שמשמשות כדי לספק אינטראקטיביות לווידג'טים בממשק. לדוגמה, אם כוללים לחצן בממשק, צריך לכלול בו לחצן 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" }, ... }