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

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

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

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

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

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

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

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

פונקציית טיפול הפעולה שמופעל עליה הטריגר ווידג'טים רלוונטיים תיאור
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 כשהמשתמש לוחץ על הווידג'ט. צריך להשתמש במטפל הזה כשצריך ליצור את כתובת ה-URL או כשצריך לבצע פעולות אחרות לפני פתיחת הקישור. אחרת, בדרך כלל קל יותר להשתמש ב-setOpenLink(). אפשר לפתוח את כתובת ה-URL רק בחלון חדש. כשהתוסף סגור, אפשר לגרום לממשק המשתמש לטעון מחדש את התוסף.
setOpenLink() המשתמש לוחץ על הווידג'ט CardAction
Image
ImageButton
DecoratedText
TextButton 		כתובת ה-URL נפתחת ישירות כשהמשתמש לוחץ על הווידג'ט. משתמשים במטפל הזה כשידוע לכם מה כתובת ה-URL ואתם צריכים רק לפתוח אותה. אחרת, משתמשים ב-setOnClickOpenLinkAction(). אפשר לפתוח את כתובת ה-URL בחלון חדש או בשכבת-על. כשהתוסף סגור, אפשר לגרום לממשק המשתמש לטעון מחדש את התוסף.
setSuggestionsAction() המשתמש מזין טקסט בקלט TextInput מגדיר Action שמפעיל פונקציה של Apps Script כשהמשתמש מזין טקסט לווידג'ט של קלט טקסט. הגורם המטפל מעביר באופן אוטומטי אובייקט אירוע לפונקציה שהוא קורא לה. לפרטים נוספים, ראו הצעות להשלמה אוטומטית של קלט טקסט.

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

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

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

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

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

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

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

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

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

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