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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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