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

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

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

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

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

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

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