רוב התוספים, בנוסף להצגת נתונים, מחייבים את המשתמש להזין מידע. כשמפתחים תוסף מבוסס-כרטיסים, אפשר ווידג'טים אינטראקטיביים כמו לחצנים, פריטים בתפריט סרגל הכלים או תיבות סימון כדי לבקש מהמשתמש לקבל נתונים שהתוסף שלך לצרכים שלכם או מספקים אמצעי בקרה אחרים לאינטראקציה.
הוספת פעולות לווידג'טים
בדרך כלל אפשר להפוך את הווידג'טים לאינטראקטיביים על ידי קישור שלהם פעולות ספציפיות והטמעה של ההתנהגות הנדרשת בקריאה חוזרת מותאמת אישית. פרטים נוספים זמינים בקטע פעולות לגבי תוספים.
ברוב המקרים, אפשר לבצע את התהליך הכללי הזה כדי להגדיר ווידג'ט מבצעים פעולה ספציפית אחרי שבוחרים או מעדכנים אותם:
- יוצרים אובייקט
Action
, ציון פונקציית הקריאה החוזרת שאמורה לפעול, יחד עם כל הפרמטרים הנדרשים. - יש לקשר את הווידג'ט אל
Action
באמצעות קריאה פונקציית ה-handler של הווידג'טים. - הטמעה של פונקציית הקריאה החוזרת כדי לבצע את ההתנהגות הנדרשת.
דוגמה
בדוגמה הבאה מוגדר לחצן שמציג התראה למשתמש
לאחר הלחיצה. הקליק מפעיל את פונקציית הקריאה החוזרת notifyUser()
עם ארגומנט שמציין את טקסט ההתראה. החזרת מבנה
ActionResponse
בתוצאות תוצג התראה.
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification())
.setText(notificationText)
.build(); // Don't forget to build the response!
}
תכנון אינטראקציות יעילות
כשמעצבים כרטיסים אינטראקטיביים, חשוב לזכור את הנקודות הבאות:
לווידג'טים אינטראקטיביים בדרך כלל צריך להגדיר לפחות שיטת handler אחת או התנהגות המשתמשים.
שימוש בווידג'ט
setOpenLink()
handler כשיש לכם כתובת URL ואתם רק רוצים לפתוח אותה בכרטיסייה. כך לא תצטרכו להגדיר אובייקטAction
וקריאה חוזרת (callback) מותאמת אישית. אם צריך קודם לבנות את כתובת ה-URL, או להשתמש בכל סוג אחר של לפני פתיחת כתובת האתר, מגדיריםAction
ומשתמשיםsetOnClickOpenLinkAction()
במקום זאת.כשמשתמשים ב
setOpenLink()
אוsetOnClickOpenLinkAction()
בפונקציות המטפל בווידג'טים, צריך לספקOpenLink
כדי להגדיר את כתובת ה-URL שצריך לפתוח. אפשר גם להשתמש באובייקט הזה כדי לציין התנהגות פתיחה וסגירה באמצעותOpenAs
ו-OnClose
טיפוסים בני מנייה (enum).יכול להיות שיותר מווידג'ט אחד יכול להשתמש באותו ווידג'ט אובייקט
Action
. אבל צריך להגדירAction
אובייקטים אם רוצים כדי לספק לפונקציית הקריאה החוזרת פרמטרים שונים.מומלץ להשתמש בפונקציות קריאה חוזרת (callback) פשוטות. כדי שהתוספים יישארו רספונסיביות, שירות הכרטיסים מגביל את פונקציות הקריאה החוזרת (callback) ל-30 שניות לכל היותר בזמן הביצוע. אם הביצוע נמשך יותר זמן, יכול להיות שממשק המשתמש של התוסף לא תעדכן את תצוגת הכרטיס שלו כמו שצריך בתגובה
Action
אם סטטוס הנתונים בקצה עורפי של צד שלישי משתנה כתוצאה ממשתמש עם ממשק המשתמש של התוסף, מומלץ 'מצב השתנה' ביט אל
true
, כך שכל מטמון קיים בצד הלקוח בוצע ניקוי. לצפייהActionResponseBuilder.setStateChanged()
לתיאור ה-method לקבלת פרטים נוספים.