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

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

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

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

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

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 אחת או התנהגות המשתמשים.

• שימוש בווידג'ט 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 לקבלת פרטים נוספים.