עיצוב כרטיס אינטראקטיבי או תיבת דו-שיח

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

---

עצב כרטיסים והצג תצוגה מקדימה שלהם באמצעות הכלי ליצירת כרטיסים.

לפתיחת הכלי ליצירת כרטיסים

---

דרישות מוקדמות

חשבון Google Workspace עם גישה ל-Google Chat.

אפליקציה שפורסמה ב-Chat. כדי ליצור אפליקציה ל-Chat, תוכלו להיעזר בquickstart.

הוספת לחצן

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

• פותחים היפר-קישור עם OpenLink כדי לספק למשתמשים מידע נוסף.
• מריצים action עם פונקציה בהתאמה אישית, כמו קריאה ל-API.

הלחצנים תומכים בטקסט חלופי.

הוספה של לחצן שמפעיל פונקציה מותאמת אישית

בהמשך מופיע כרטיס שמכיל ווידג'ט של ButtonList עם שני לחצנים. לחיצה על לחצן אחד תפתח את המסמכים למפתחים של Google Chat בכרטיסייה חדשה. הלחצן השני מפעיל פונקציה מותאמת אישית בשם goToView() ומעביר את הפרמטר viewType="BIRD EYE VIEW".

הוספת לחצן בצבע מותאם אישית ובלחצן מושבת

אפשר להגדיר "disabled": "true" כדי למנוע ממשתמשים ללחוץ על לחצן.

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

הוספת לחצן עם סמל

למטה מוצג כרטיס שמכיל ווידג'ט של ButtonList עם שני ווידג'טים של Button. בלחיצה על לחצן אחד השדה knownIcon מוצג סמל האימייל המובנה של Google Chat. הלחצן השני משתמש בשדה iconUrl כדי להציג ווידג'ט של סמל מותאם אישית.

הוספת לחצן עם סמל וטקסט

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

הוספת רכיבים שניתן לבחור בממשק המשתמש

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

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

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

בקטע הזה מובאות דוגמאות לכרטיסים שבהם נעשה שימוש בווידג'ט SelectionInput. בדוגמאות נעשה שימוש בסוגים שונים של קלט קטעים:

• שאלות עם תיבות סימון (יש להן יותר מתשובה אחת)
• לחצני בחירה
• מתגים
• תפריט נפתח
• תפריט בחירה מרובה

הוספת תיבת סימון

למטה מוצגת תיבת דו-שיח שבה המשתמשים מתבקשים לציין אם איש הקשר הוא מקצועי, אישי או שניהם, עם ווידג'ט SelectionInput עם תיבות סימון:

הוספת לחצן בחירה

למטה מוצגת תיבת דו-שיח שבה המשתמש מתבקש לציין אם איש קשר הוא מקצועי או אישי, בווידג'ט SelectionInput שמשתמש בלחצני בחירה:

הוספת מתג

למטה מוצגת תיבת דו-שיח שבה המשתמשים מתבקשים לציין אם איש הקשר הוא מקצועי, אישי או שניהם עם ווידג'ט SelectionInput שמשתמש במתגים:

הוספת תפריט נפתח

למטה מוצגת תיבת דו-שיח שבה מוצגת למשתמש בקשה לציין אם איש קשר הוא מקצועי או אישי, בווידג'ט SelectionInput שמשתמש בתפריט נפתח:

הוספת תפריט לבחירה מרובה

למטה מוצגת תיבת דו-שיח שבה המשתמשים מתבקשים לבחור אנשי קשר מתפריט בחירה מרובה:

שימוש במקורות נתונים לתפריטים של בחירה מרובה

בקטע הבא מוסבר איך להשתמש בתפריטים של בחירה מרובה כדי לאכלס נתונים ממקורות דינמיים, כמו אפליקציה של Google Workspace או מקור נתונים חיצוני.

מקורות נתונים מ-Google Workspace

אתם יכולים לאכלס פריטים בתפריט של בחירה מרובה ממקורות הנתונים הבאים ב-Google Workspace:

• משתמשי Google Workspace: אפשר לאכלס רק משתמשים באותו ארגון ב-Google Workspace.
• מרחבי Chat: המשתמשים שמזינים פריטים בתפריט הבחירה מרובה יכולים להציג ולבחור רק מרחבים משותפים שהם שייכים לארגון שלהם ב-Google Workspace.

כדי להשתמש במקורות נתונים של Google Workspace, צריך לציין את השדה platformDataSource. בניגוד לסוגים אחרים של קלט בחירה, משמיטים את האובייקטים SectionItem כי הפריטים שנבחרו מגיעים באופן דינמי מ-Google Workspace.

הקוד הבא מציג תפריט לבחירה מרובה של משתמשי Google Workspace. כדי לאכלס משתמשים, קלט הבחירה מגדיר את commonDataSource לערך USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

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

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

מקורות נתונים מחוץ ל-Google Workspace

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

כדי להשתמש במקור נתונים חיצוני, צריך להשתמש בשדה externalDataSource כדי לציין פונקציה שמחזירה פריטים ממקור הנתונים.

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

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

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 2,
    "externalDataSource": {
      "function": "getContacts"
    },
    "items": [
      {
        "text": "Contact 3",
        "value": "contact-3",
        "startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
        "bottomText": "Contact three description",
        "selected": false
      }
    ]
  }
}

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

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

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

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

Apps Script

apps-script/selection-input/on-widget-update.gs

הצגת הקוד ב-GitHub

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

Node.js

node/selection-input/on-widget-update.js

הצגת הקוד ב-GitHub

/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          items: [
            {
              value: "contact-1",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 1",
              bottomText: "Contact one description",
              selected: false
            },
            {
              value: "contact-2",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 2",
              bottomText: "Contact two description",
              selected: false
            },
            {
              value: "contact-3",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 3",
              bottomText: "Contact three description",
              selected: false
            },
            {
              value: "contact-4",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 4",
              bottomText: "Contact four description",
              selected: false
            },
            {
              value: "contact-5",
              startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
              text: "Contact 5",
              bottomText: "Contact five description",
              selected: false
            },
          ]
        }
      }
    }
  };
}

הוספת שדה שבו המשתמש יכול להזין טקסט

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

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

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

זהו כרטיס שמכיל ווידג'ט של TextInput:

המשתמש יכול לבחור תאריך ושעה

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

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

למטה מוצג כרטיס שמורכב משלושה סוגים שונים של ווידג'טים מסוג DateTimePicker:

פתרון בעיות

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

יכול להיות שהודעת השגיאה לא תוצג בממשק המשתמש של Chat, אבל יש הודעות שגיאה תיאוריות ונתוני יומן שיכולים לעזור לכם לתקן שגיאות כשמפעילים רישום שגיאות באפליקציות של Chat. לקבלת עזרה בהצגה, בניפוי באגים ובתיקון שגיאות, אפשר להיעזר במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.

נושאים קשורים

• ButtonList
• Button
• Color
• knownIcon
• SelectionInput
• TextInput
• הווידג'ט DateTimePicker