יצירת כרטיסים אינטראקטיביים

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

הוספת פעולות לווידג'טים

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

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

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

דוגמה

בדוגמה הבאה מוגדר לחצן שמוצגת בו התראה למשתמש אחרי הלחיצה עליו. הקליק מפעיל את פונקציית הקריאה החוזרת 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!
  }

עיצוב אינטראקציות אפקטיביות

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

• בדרך כלל, כדי להגדיר את ההתנהגות של ווידג'טים אינטראקטיביים, צריך לפחות שיטת טיפול אחת.

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

• כשמשתמשים בפונקציות הטיפול בווידג'טים setOpenLink() או setOnClickOpenLinkAction(), צריך לספק אובייקט OpenLink כדי להגדיר איזו כתובת URL לפתוח. אפשר גם להשתמש באובייקט הזה כדי לציין את התנהגות הפתיחה והסגירה באמצעות הממשקים של OpenAs ו-OnClose.

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

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

• אם סטטוס הנתונים בקצה העורפי של צד שלישי משתנה כתוצאה מאינטראקציה של משתמש עם ממשק המשתמש של התוסף, מומלץ שהתוסף יגדיר את הביט 'הסטטוס השתנה' ל-true כדי לנקות את המטמון הקיים בצד הלקוח. פרטים נוספים זמינים בתיאור השיטה ActionResponseBuilder.setStateChanged().