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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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