פעולות בתוספים

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

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

כדי להגדיר ווידג'ט עם Action, צריך לבצע את התהליך הכללי הבא:

1. יוצרים את האובייקט Action ומציינים את פונקציית הקריאה החוזרת שהוא צריך להפעיל, יחד עם הפרמטרים הנדרשים.
2. מפעילים את פונקציית הטיפול בווידג'ט המתאימה בווידג'ט באמצעות האובייקט Action.
3. מטמיעים את פונקציית הקריאה החוזרת כדי להפעיל את ההתנהגות הנדרשת.

הערה: חשוב להבחין בין אובייקטים של Action לבין אובייקטים של CardAction. אובייקטים מסוג CardAction הם פריטים בתפריט של כותרת הכרטיס, ואילו אובייקטים מסוג Action מגדירים תגובות לאינטראקציות של המשתמש עם ממשק המשתמש.

פונקציות לטיפול בווידג'טים

כדי לקשר ווידג'ט לAction ספציפי או להתנהגות אחרת, משתמשים בפונקציית handler של הווידג'ט. פונקציית הטיפול קובעת איזה סוג של אינטראקציה (לדוגמה, לחיצה על הווידג'ט או עריכה של שדה טקסט) מפעיל את התנהגות הפעולה. פונקציית הטיפול מגדירה גם אילו שלבים בממשק המשתמש יבוצעו, אם בכלל, אחרי השלמת הפעולה.

בטבלה הבאה מפורטים סוגי ה-handler השונים של הווידג'טים והווידג'טים שבהם הם משמשים:

פונקציית handler	מפעיל פעולה	ווידג'טים רלוונטיים	תיאור
setOnChangeAction()	הערך של הווידג'ט משתנה	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	מגדירה Action שמבצעת פונקציית Apps Script כשהווידג'ט מאבד את המיקוד, למשל כשמשתמש מזין טקסט בקלט ולוחץ על Enter. הגורם המטפל מעביר באופן אוטומטי אובייקט אירוע לפונקציה שהוא מפעיל. אם תבחרו בכך, תוכלו להוסיף פרטים של פרמטרים לאובייקט האירוע הזה.
setOnClickAction()	המשתמש לוחץ על הווידג'ט	CardAction Image ImageButton DecoratedText TextButton	מגדיר Action שמבצע פונקציה של Apps Script כשהמשתמש לוחץ על הווידג'ט. הגורם המטפל מעביר באופן אוטומטי אובייקט אירוע לפונקציה שהוא מפעיל. אפשר להוסיף לאובייקט האירוע הזה מידע על פרמטרים אופציונליים.
setComposeAction()	המשתמש לוחץ על הווידג'ט	CardAction Image ImageButton DecoratedText TextButton	ספציפי ל-Gmail. מגדיר Action שיוצר טיוטה של אימייל, ואז מציג את הטיוטה למשתמש בחלון הכתיבה בממשק המשתמש של Gmail. אתם יכולים לכתוב את הטיוטה כהודעה חדשה או כתשובה להודעה הפתוחה ב-Gmail. כשה-handler מפעיל את פונקציית הקריאה החוזרת ליצירת טיוטה, הוא מעביר אובייקט אירוע לפונקציית הקריאה החוזרת. פרטים נוספים זמינים במאמר בנושא יצירת טיוטות של הודעות.
setOnClickOpenLinkAction()	המשתמש לוחץ על הווידג'ט	CardAction Image ImageButton DecoratedText TextButton	מגדיר Action לפתיחת כתובת URL כשמשתמש לוחץ על הווידג'ט. משתמשים ב-handler הזה כשצריך ליצור את כתובת ה-URL או לבצע פעולות אחרות לפני שהקישור נפתח. אחרת, בדרך כלל פשוט יותר להשתמש ב-setOpenLink(). אפשר לפתוח את כתובת ה-URL רק בחלון חדש. אחרי שסוגרים את התוסף, אפשר לטעון אותו מחדש בממשק המשתמש.
setOpenLink()	המשתמש לוחץ על הווידג'ט	CardAction Image ImageButton DecoratedText TextButton	פתיחה ישירה של כתובת URL כשמשתמש לוחץ על הווידג'ט. משתמשים ב-handler הזה כשמכירים את כתובת ה-URL ורק רוצים לפתוח אותה. אחרת, משתמשים ב-setOnClickOpenLinkAction(). אפשר לפתוח את כתובת ה-URL בחלון חדש או בשכבת-על. כשסוגרים את התוסף, אפשר לטעון אותו מחדש בממשק המשתמש.
setSuggestionsAction()	המשתמש מזין טקסט לקלט	TextInput	מגדירה Action שמבצעת פונקציה של Apps Script כשמשתמש מזין טקסט בווידג'ט של קלט טקסט. הגורם המטפל מעביר באופן אוטומטי אובייקט אירוע לפונקציה שהוא מפעיל. פרטים נוספים זמינים במאמר בנושא הצעות להשלמה אוטומטית של קלט טקסט.

פונקציות קריאה חוזרת

פונקציות קריאה חוזרת מופעלות כשAction מופעל. מכיוון שפונקציות הקריאה החוזרת הן פונקציות של Apps Script, הן יכולות לעשות כמעט כל מה שפונקציות סקריפט אחרות יכולות לעשות.

אזהרה: שירות הכרטיסים של Apps Script מגביל את פונקציות הקריאה החוזרת לזמן ביצוע של 30 שניות לכל היותר. אם הביצוע נמשך יותר זמן, יכול להיות שממשק המשתמש של התוסף לא יעדכן את הצגת הכרטיס בתגובה ל-Action כמו שצריך.

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

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

הפעולה שניסית לבצע	פונקציית הקריאה החוזרת צריכה להחזיר
ניווט בין כרטיסים	ActionResponse
הצגת Notification	ActionResponse
פתיחת קישור באמצעות setOnClickOpenLinkAction()	ActionResponse
הצגת הצעות להשלמה אוטומטית	SuggestionResponse
שימוש בפעולה אוניברסלית	UniversalActionResponse
פעולות נוספות	כלום

פעולות לאפליקציות מארחות של Google Workspace

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

• פעולות ביומן
• פעולות ב-Chat
• פעולות שקשורות לנסיעה
• פעולות ב-Gmail
• פעולות של עורכים

הערה: כשמשתמשים במחלקות ליצירת תגובות, חשוב להפעיל את build() כדי ליצור את אובייקטי התגובה. אם לא עושים את זה, מתקבלת שגיאה.

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

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

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

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

במאמר בנושא אובייקטים של אירועים מוסבר באופן מלא על המבנה של אובייקט האירוע.

הערה: תוספים ל-Gmail השתמשו בגרסה פשוטה יותר של מבנה אובייקט האירוע הזה, שכבר לא בשימוש. כדי לשמור על תאימות לאחור, כל השדות של אובייקט האירוע בתוספים המקוריים של Gmail עדיין כלולים במבנה החדש של אובייקט האירוע (ראו מבנה אובייקט האירוע). עם זאת, אותו מידע מופיע שוב במבני המשנה של האובייקטים common event ו-Gmail event. אם משדרגים תוסף ל-Gmail לתוסף ל-Google Workspace, צריך לשנות את הקוד כדי להשתמש בשדות המעודכנים של אובייקט האירוע. בסופו של דבר, השדות המקוריים של אובייקט האירוע ב-Gmail יוסרו.