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

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

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

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

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

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

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

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

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

פונקציית Handler	מפעיל פעולה	ווידג'טים רלוונטיים	תיאור
setOnChangeAction()	הערך של הווידג'ט משתנה	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	הגדרה של Action שמפעילה פונקציית Apps Script כשהווידג'ט מאבד את המיקוד, למשל למשל, כשהמשתמש מזין טקסט בקלט ומקיש על Enter. handler מעביר באופן אוטומטי אובייקט event של הפונקציה שהוא קורא לפונקציה. אפשר להוסיף עוד מידע על הפרמטר באובייקט האירוע הזה אם יש צורך.
setOnClickAction()	המשתמש לוחץ על הווידג'ט	CardAction Image ImageButton DecoratedText TextButton	הגדרה של Action שמפעילה פונקציית Apps Script כשהמשתמש לוחץ על הווידג'ט. handler מעביר באופן אוטומטי אובייקט event של הפונקציה שהוא קורא לפונקציה. אפשר להוסיף פרטי פרמטרים אופציונליים לאובייקט האירוע הזה.
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 כשהמשתמש מזין טקסט לווידג'ט של קלט הטקסט. ה-handler מעביר באופן אוטומטי אובייקט event של הפונקציה שהוא קורא לפונקציה. צפייה הצעות להשלמה אוטומטית לקבלת פרטים נוספים.

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

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

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

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

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

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

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

• פעולות ביומן
• עידוד פעולות
• פעולות ב-Gmail
• פעולות עריכה

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

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

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

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

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

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

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