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