פעולות בתוסף

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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