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

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

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

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

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

1. יוצרים אובייקט Action, שמציין את פונקציית הקריאה החוזרת שאמורה לפעול יחד עם הפרמטרים הנדרשים.
2. כדי לקשר את הווידג'ט ל-Action, שולחים קריאה לפונקציית ה-handler המתאימה של הווידג'טים.
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!
  }

תכנון אינטראקציות יעילות

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

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

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

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

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

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

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