דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

יוצרים את האובייקט Action, ציון של פונקציית הקריאה החוזרת מופעל עם הפרמטרים הנדרשים.
קריאה לפונקציית המטפל בווידג'טים המתאימה בווידג'ט בעזרת 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, ולכן אפשר להשתמש בהן לעשות כמעט כל דבר שפונקציית סקריפט אחרת יכולה לעשות.

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

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

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

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

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

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

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

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

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