פעולות של תוספים מספקות התנהגות אינטראקטיבית של הווידג'טים. על ידי יצירת פעולה, אתה מגדיר מה קורה כאשר המשתמש בוחר או מעדכן ווידג'ט.
ברוב המקרים אפשר להגדיר פעולות של תוספים באמצעות האובייקטים Action
שמסופקים על ידי שירות הכרטיס של Apps Script.
כל Action
משויך לפונקציית קריאה חוזרת כשיוצרים אותו. מטמיעים את פונקציית הקריאה החוזרת כדי לבצע את הפעולות הרצויות כשהמשתמש יוצר אינטראקציה עם הווידג'ט. בנוסף, צריך לקשר את Action
לווידג'ט באמצעות פונקציית ה-handler המתאימה של הווידג'טים, שמגדירה איזה סוג של אינטראקציה מפעיל את הקריאה החוזרת של Action
.
מגדירים ווידג'ט באמצעות Action
באמצעות התהליך הכללי הבא:
- יוצרים את האובייקט
Action
ומציינים את פונקציית הקריאה החוזרת שהוא צריך להפעיל יחד עם הפרמטרים הנדרשים. - קוראים לפונקציית ה-handler המתאימה של הווידג'ט בווידג'ט באמצעות האובייקט
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 קורא לפונקציית הקריאה החוזרת של גרסת הטיוטה, הוא מעביר אובייקט אירוע לפונקציית הקריאה החוזרת.
למידע נוסף, אפשר לקרוא את המאמר כתיבת טיוטות של הודעות. |
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 מעביר באופן אוטומטי אובייקט אירוע לפונקציה שהוא קורא לפונקציה.
למידע נוסף, אפשר לעיין בהצעות להשלמה אוטומטית של קלט טקסט. |
פונקציות קריאה חוזרת (callback)
פונקציות קריאה חוזרת מופעלות כשהטריגרים של Action
מופעלים. פונקציית קריאה חוזרת (callback) היא פונקציות של Apps Script, ולכן הן יכולות לבצע כמעט כל פעולה שפונקציית סקריפט אחרת יכולה לבצע.
לפעמים פונקציית קריאה חוזרת מחזירה אובייקט תגובה ספציפי. תגובות מהסוג הזה מצביעות על פעולות נוספות שצריך לבצע אחרי שמסיימים לבצע קריאה חוזרת, כמו הצגת כרטיס חדש או הצגת הצעות להשלמה אוטומטית. כשפונקציית הקריאה החוזרת חייבת להחזיר אובייקט תשובה ספציפי, צריך להשתמש במחלקה של builder בשירות הכרטיס כדי ליצור את האובייקט.
בטבלה הבאה אפשר לראות מתי פונקציות הקריאה החוזרת צריכות להחזיר אובייקט תגובה ספציפי לפעולות ספציפיות. כל הפעולות האלה לא תלויות באפליקציה המארחת הספציפית שהתוסף מרחיב:
בוצע ניסיון לפעולה | פונקציית הקריאה החוזרת אמורה לחזור |
---|---|
ניווט בין כרטיסים | ActionResponse |
להציג Notification |
ActionResponse |
פתיחת קישור באמצעות setOnClickOpenLinkAction() |
ActionResponse |
הצגת הצעות להשלמה אוטומטית | SuggestionResponse |
שימוש בפעולה אוניברסלית | UniversalActionResponse |
פעולות נוספות | Nothing |
בנוסף לפעולות האלה, לכל אפליקציה מארחת יש קבוצת פעולות משלה שאפשר לבצע רק במארח הזה. לפרטים נוספים, אפשר להיעזר במדריכים הבאים:
אובייקטים של אירוע פעולה
כשהתוסף מפעיל Action
, ממשק המשתמש בונה באופן אוטומטי אובייקט אירוע בפורמט JSON ומעביר אותו כארגומנט לפונקציית הקריאה החוזרת Action
. אובייקט האירוע הזה מכיל מידע על ההקשר הנוכחי של המשתמש בצד הלקוח, כמו הערכים הנוכחיים של כל הווידג'טים האינטראקטיביים בכרטיס שמוצג.
לאובייקטים של אירועי פעולה יש מבנה JSON ספציפי שמארגן את המידע שהם מכילים. אותו מבנה משמש כאשר טריגר של דף הבית מופעל כדי ליצור דף בית, או כאשר מופעל טריגר לפי הקשר כדי לעדכן את מסך התוסף.
הסבר מלא על מבנה אובייקט האירוע מופיע בקטע אובייקטי אירוע.