Package google.apps.card.v1

אינדקס

פעולה

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
function

string

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

לדוגמה שימוש, אפשר לעיין במאמר קריאת נתוני טפסים.
parameters[]

ActionParameter

רשימת פרמטרים של פעולות.
loadIndicator

LoadIndicator

מציינת את אינדיקטור הטעינה שמוצג בזמן ביצוע הקריאה לפעולה.
persistValues

bool

מציין אם ערכי הטופס נשארים אחרי הפעולה. ערך ברירת המחדל הוא false.

אם הערך הוא true, ערכי הטופס נשארים אחרי הפעלת הפעולה. כדי לאפשר למשתמש לבצע שינויים בזמן העיבוד של הפעולה, מגדירים את LoadIndicator לערך NONE. בהודעות בכרטיס באפליקציות Chat, צריך גם להגדיר את ResponseType של הפעולה ל-UPDATE_MESSAGE ולהשתמש באותו card_id מהכרטיס שהכיל את הפעולה.

אם הערך שלו הוא false, ערכי הטופס נמחקים כשהפעולה מופעלת. כדי למנוע מהמשתמש לבצע שינויים בזמן העיבוד של הפעולה, מגדירים את LoadIndicator לערך SPINNER.
interaction

Interaction

זה שינוי אופציונלי. חובה כשפותחים תיבת דו-שיח.

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

אם לא מציינים אירוע, האפליקציה מגיבה על ידי ביצוע אירוע action – כמו פתיחת קישור או הפעלת פונקציה – כרגיל.

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

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.
requiredWidgets[]

string

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

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.
allWidgetsAreRequired

bool

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

ActionParameter

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

מידע נוסף זמין במאמר CommonEventObject.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
key

string

שם הפרמטר של סקריפט הפעולה.
value

string

ערך הפרמטר.

אינטראקציה

זה שינוי אופציונלי. חובה כשפותחים תיבת דו-שיח.

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

אם לא מציינים אירוע, האפליקציה מגיבה על ידי ביצוע אירוע action – כמו פתיחת קישור או הפעלת פונקציה – כרגיל.

כשמציינים interaction, האפליקציה יכולה להגיב בדרכים אינטראקטיביות מיוחדות. לדוגמה, אם מגדירים את interaction לערך OPEN_DIALOG, האפליקציה יכולה לפתוח תיבת דו-שיח.

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

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

טיפוסים בני מנייה (enum)
INTERACTION_UNSPECIFIED ערך ברירת המחדל. הפקודה action פועלת כרגיל.
OPEN_DIALOG

פתיחת תיבת דו-שיח – ממשק מבוסס-כרטיסים בחלון, שבו אפליקציות Chat משתמשות כדי לקיים אינטראקציה עם משתמשים.

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

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

LoadIndicator

מציינת את אינדיקטור הטעינה שמוצג בזמן ביצוע הקריאה לפעולה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
SPINNER הצגת סמל ספינר כדי לציין שהתוכן נטען.
NONE לא מוצגת כלום.

BorderStyle

אפשרויות הסגנון של גבול הכרטיס או הווידג'ט, כולל סוג הגבול והצבע שלו.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
type

BorderType

סוג הגבול.
strokeColor

Color

הצבעים שבהם צריך להשתמש כשהסוג הוא BORDER_TYPE_STROKE.

כדי להגדיר את צבע הקו, מציינים ערך בשדות red,‏ green ו-blue. הערך חייב להיות מספר שרירותי (float) בין 0 ל-1 על סמך ערך הצבע RGB, כאשר 0 (0/255) מייצג את היעדר הצבע ו-1 (255/255) מייצג את העוצמה המקסימלית של הצבע.

לדוגמה, הקוד הבא מגדיר את הצבע לאדום בעוצמה המקסימלית שלו:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
}

השדה alpha לא זמין לצבע קו. אם השדה הזה צוין, המערכת תתעלם ממנו.
cornerRadius

int32

רדיוס הפינות של הגבול.

BorderType

מייצג את סוגי הגבולות שהוחלו על ווידג'טים.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
BORDER_TYPE_UNSPECIFIED אין להשתמש בו. לא צוין.
NO_BORDER ערך ברירת המחדל. ללא שוליים.
STROKE קווי מתאר.

לחצן

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

כדי להפוך תמונה ללחצן שניתן ללחוץ עליו, מציינים Image (לא ImageComponent) ומגדירים פעולה onClick.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
text

string

הטקסט שמוצג בתוך הלחצן.
icon

Icon

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

Color

זה שינוי אופציונלי. הצבע של הלחצן. אם ההגדרה מוגדרת, הלחצן type מוגדר ל-FILLED והצבע של השדות text ו-icon מוגדר לצבע מנוגד לשיפור הקריאוּת. לדוגמה, אם צבע הלחצן מוגדר ככחול, כל הטקסט או הסמלים בלחצן מוגדרים כלבנים.

כדי להגדיר את צבע הלחצן, צריך לציין ערך בשדות red, green ו-blue. הערך חייב להיות מספר שרירותי (float) בין 0 ל-1 על סמך ערך הצבע RGB, כאשר 0 (0/255) מייצג את היעדר הצבע ו-1 (255/255) מייצג את העוצמה המקסימלית של הצבע.

לדוגמה, הדוגמה הבאה מגדירה את הצבע לאדום בעוצמה המקסימלית:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
}

השדה alpha אינו זמין עבור צבע הלחצן. אם השדה הזה מוגדר, המערכת תתעלם ממנו.
onClick

OnClick

חובה. הפעולה שתתבצע כשמשתמש לוחץ על הלחצן, למשל פתיחת היפר-קישור או הפעלת פונקציה מותאמת אישית.
disabled

bool

אם הערך שלו הוא true, הלחצן מוצג במצב לא פעיל ולא מגיב לפעולות המשתמש.
altText

string

הטקסט החלופי המשמש לנגישות.

מגדירים טקסט תיאורי שמאפשר למשתמשים לדעת מה הלחצן עושה. לדוגמה, אם לחיצה על לחצן פותחת היפר-קישור, אפשר לכתוב: "הלחצן פותח כרטיסייה חדשה בדפדפן ומנווט למסמכי התיעוד למפתחים של Google Chat בכתובת https://developers.google.com/workspace/chat".
type

Type

זה שינוי אופציונלי. סוג הלחצן. אם לא תגדירו את סוג הלחצן, ברירת המחדל שלו תהיה OUTLINED. אם השדה color מוגדר, סוג הלחצן מחויב להיות FILLED והמערכת מתעלמת מכל ערך שהוגדר לשדה הזה.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

סוג

זה שינוי אופציונלי. סוג הלחצן. אם השדה color מוגדר, השדה type מוגדר באופן אוטומטי ל-FILLED.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

טיפוסים בני מנייה (enum)
TYPE_UNSPECIFIED אין להשתמש בו. לא צוין.
OUTLINED לחצנים קוויים הם לחצנים עם הדגשה בינונית. בדרך כלל הן מכילות פעולות חשובות, אבל לא את הפעולה הראשית באפליקציית Chat או בתוסף.
FILLED לחצן מלא כולל מאגר בצבע אחיד. היא הכי בולטת מבחינה חזותית, ומומלצת לפעולה החשובה והראשית באפליקציית Chat או בתוסף.
FILLED_TONAL לחצן מלא בגוון הוא דרך חלופית להגיע לאיזון בין לחצנים מלאים ללחצנים עם קו מתאר. הם שימושיים בהקשרים שבהם לחצן עם עדיפות נמוכה יותר דורש הדגשה קצת יותר חזקה מזו של לחצן עם קו מתאר.
BORDERLESS לחצן לא מכיל מאגר בלתי נראה במצב ברירת המחדל שלו. הוא משמש לרוב לפעולות עם העדיפות הנמוכה ביותר, במיוחד כשמוצגות כמה אפשרויות.

ButtonList

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
buttons[]

Button

מערך של לחצנים.

קלפים

ממשק של כרטיס שמוצג בהודעה ב-Google Chat או בתוסף של Google Workspace.

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

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

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

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

לדוגמה: הודעה בכרטיס לאפליקציית Google Chat

דוגמה לכרטיס של איש קשר

כדי ליצור את הודעת הכרטיס לדוגמה ב-Google Chat, משתמשים ב-JSON הבא:

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
           "title": "Sasha",
           "subtitle": "Software Engineer",
           "imageUrl":
           "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png",
           "imageType": "CIRCLE",
           "imageAltText": "Avatar for Sasha"
         },
         "sections": [
           {
             "header": "Contact Info",
             "collapsible": true,
             "uncollapsibleWidgetsCount": 1,
             "widgets": [
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "EMAIL"
                   },
                   "text": "sasha@example.com"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PERSON"
                   },
                   "text": "<font color=\"#80e27e\">Online</font>"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PHONE"
                   },
                   "text": "+1 (555) 555-1234"
                 }
               },
               {
                 "buttonList": {
                   "buttons": [
                     {
                       "text": "Share",
                       "onClick": {
                        "openLink": {
                           "url": "https://example.com/share"
                         }
                       }
                     },
                     {
                       "text": "Edit",
                       "onClick": {
                         "action": {
                           "function": "goToView",
                           "parameters": [
                             {
                               "key": "viewType",
                               "value": "EDIT"
                             }
                           ]
                         }
                       }
                     }
                   ]
                 }
               }
             ]
           }
         ]
       }
    }
  ]
}
שדות
header

CardHeader

כותרת הכרטיס. בדרך כלל הכותרת מכילה תמונה מובילה וכותרת. כותרות תמיד מופיעות בחלק העליון של הכרטיס.
sections[]

Section

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

DividerStyle

סגנון המחיצה בין הכותרת, הקטעים והכותרת התחתונה.
cardActions[]

CardAction

הפעולות של הכרטיס. הפעולות מתווספות לתפריט של סרגל הכלים של הכרטיס.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

לדוגמה, קובץ ה-JSON הבא יוצר תפריט פעולות בכרטיס עם האפשרויות Settings ו-Send Feedback:

"cardActions": [
  {
    "actionLabel": "Settings",
    "onClick": {
      "action": {
        "functionName": "goToView",
        "parameters": [
          {
            "key": "viewType",
            "value": "SETTING"
         }
        ],
        "loadIndicator": "LoadIndicator.SPINNER"
      }
    }
  },
  {
    "actionLabel": "Send Feedback",
    "onClick": {
      "openLink": {
        "url": "https://example.com/feedback"
      }
    }
  }
]
name

string

שם הכרטיס. משמש כמזהה כרטיס בניווט בכרטיסים.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.
fixedFooter

CardFixedFooter

הכותרת התחתונה הקבועה מוצגת בתחתית הכרטיס הזה.

הגדרה של fixedFooter בלי לציין primaryButton או secondaryButton גורמת לשגיאה. באפליקציות Chat, אפשר להשתמש בכותרות תחתונות קבועות בתיבות דו-שיח, אבל לא בהודעות בכרטיסים.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.
displayStyle

DisplayStyle

בתוספים ל-Google Workspace, המדיניות הזו מגדירה את מאפייני התצוגה של peekCardHeader.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.
peekCardHeader

CardHeader

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

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

CardAction

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

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

שדות
actionLabel

string

התווית שמוצגת כאפשרות בתפריט הפעולות.
onClick

OnClick

הפעולה onClick בפעולה הזו לביצוע.

CardFixedFooter

כותרת תחתונה קבועה שמופיעה בתחתית הכרטיס.

הגדרה של fixedFooter בלי לציין primaryButton או secondaryButton גורמת לשגיאה.

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
primaryButton

Button

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

Button

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

CardHeader

מייצגת כותרת של כרטיס. מידע נוסף על אפליקציות ב-Google Chat מופיע במאמר הוספת כותרת.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
title

string

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

string

כותרת המשנה של כותרת הכרטיס. אם הפרמטר הזה מוגדר, הוא יופיע בשורה נפרדת מתחת ל-title.
imageType

ImageType

הצורה שמשמשת לחיתוך התמונה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.
imageUrl

string

כתובת ה-URL מסוג HTTPS של התמונה בכותרת הכרטיס.
imageAltText

string

הטקסט החלופי של התמונה הזו המשמש לנגישות.

DisplayStyle

בתוספים ל-Google Workspace, קובע איך הכרטיס יוצג.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

טיפוסים בני מנייה (enum)
DISPLAY_STYLE_UNSPECIFIED אין להשתמש בו. לא צוין.
PEEK הכותרת של הכרטיס מופיעה בתחתית סרגל הצד, ומכסה חלקית את הכרטיס העליון הנוכחי בערימה. לחיצה על הכותרת קופצת את הכרטיס לערימת הכרטיסים. אם לכרטיס אין כותרת, המערכת תשתמש בכותרת שנוצרה.
REPLACE ערך ברירת המחדל. כדי להציג את הכרטיס, החלפת התצוגה של הכרטיס העליון בערימת הכרטיסים.

DividerStyle

סגנון המחיצה של כרטיס. משמש כרגע רק למחיצות בין קטעי כרטיסים.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
DIVIDER_STYLE_UNSPECIFIED אין להשתמש בו. לא צוין.
SOLID_DIVIDER אפשרות ברירת מחדל. יוצרים קו מפריד אחיד.
NO_DIVIDER אם המדיניות מוגדרת, לא יוצג קו מפריד. הסגנון הזה מסיר לחלוטין את המחיצה מהפריסה. התוצאה זהה לזו שמתקבלת אם לא מוסיפים מפריד בכלל.

קטע

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
header

string

טקסט שמופיע בחלק העליון של קטע. יש תמיכה בטקסט פשוט בפורמט HTML. למידע נוסף על עיצוב טקסט, תוכלו לקרוא את המאמרים עיצוב טקסט באפליקציות ב-Google Chat ועיצוב טקסט בתוספים ל-Google Workspace.
widgets[]

Widget

כל הווידג'טים בקטע. חייבת להכיל ווידג'ט אחד לפחות.
collapsible

bool

מציין אם ניתן לכווץ את הקטע הזה.

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

כדי לקבוע אילו ווידג'טים מוסתרים, צריך לציין uncollapsibleWidgetsCount.
uncollapsibleWidgetsCount

int32

מספר הווידג'טים שאינם ניתנים לכיווץ שנשארים גלויים גם כשקטע מסוים מכווץ.

לדוגמה, אם קטע מכיל חמישה ווידג'טים והערך של uncollapsibleWidgetsCount מוגדר כ-2, שני הווידג'טים הראשונים מוצגים תמיד והשלושה האחרונים מכווצים כברירת מחדל. הערך של uncollapsibleWidgetsCount נלקח בחשבון רק כאשר הערך של collapsible הוא true.
collapseControl

CollapseControl

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

צ'יפ

צ'יפ של טקסט, סמל או טקסט וסמל שהמשתמשים יכולים ללחוץ עליו.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
icon

Icon

תמונת הסמל. אם גם icon וגם text מוגדרים, הסמל מופיע לפני הטקסט.
label

string

הטקסט שמוצג בתוך הצ'יפ.
onClick

OnClick

זה שינוי אופציונלי. הפעולה שתתבצע כשמשתמש לוחץ על הצ'יפ, למשל פתיחת היפר-קישור או הפעלת פונקציה מותאמת אישית.
enabled
(deprecated)

bool

האם הצ'יפ במצב פעיל ומגיב לפעולות של המשתמש. ברירת המחדל היא true. הוצא משימוש. במקום זאת, אתם צריכים להשתמש ב-disabled.
disabled

bool

האם הצ'יפ במצב לא פעיל ומתעלם מפעולות של משתמש. ברירת המחדל היא false.
altText

string

הטקסט החלופי המשמש לנגישות.

מגדירים טקסט תיאורי שמאפשר למשתמשים לדעת מהו תפקיד הצ'יפ. לדוגמה, אם צ'יפ פותח היפר-קישור, כותבים: "פתיחה של כרטיסייה חדשה בדפדפן ומעבר למסמכי התיעוד למפתחים של Google Chat בכתובת https://developers.google.com/workspace/chat&quot;.

ChipList

רשימה של צ'יפים שממוקמים באופן אופקי, ואפשר לגלול בה אופקית או להעביר את הצ'יפים לשורה הבאה.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
layout

Layout

הפריסה של רשימת הצ'יפים שצוינה.
chips[]

Chip

מערך של צ'יפים.

פריסה

הפריסה של רשימת הצ'יפים.

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

CollapseControl

מייצגים פקדים להרחבה ולכיווץ. זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
horizontalAlignment

HorizontalAlignment

היישור האופקי של לחצן ההרחבה והכיווץ.
expandButton

Button

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

Button

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

עמודות

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

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

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

  • באינטרנט, העמודה השנייה מתבצעת אם רוחב המסך הוא 480 פיקסלים או פחות.
  • במכשירי iOS, העמודה השנייה גולשת אם רוחב המסך קטן מ-300 נק' או שווה לו.
  • במכשירי Android, העמודה השנייה גולשת אם רוחב המסך קטן מ-320dp או שווה לו.

כדי לכלול יותר משתי עמודות או כדי להשתמש בשורות, צריך להשתמש בווידג'ט Grid.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace. ממשקי המשתמש של התוספים שתומכים בעמודות כוללים:

  • תיבת הדו-שיח שמוצגת כשמשתמשים פותחים את התוסף מתבנית של אימייל.
  • תיבת הדו-שיח שמוצגת כשמשתמשים פותחים את התוסף מהתפריט הוספת קובץ באירוע ביומן Google.
שדות
columnItems[]

Column

מערך של עמודות. אפשר לכלול עד 2 עמודות בכרטיס או בתיבת דו-שיח.

עמודה

עמודה.

תוספים ל-Google Workspace ואפליקציות של Chat

שדות
horizontalSizeStyle

HorizontalSizeStyle

מציינת איך עמודה ממלאת את רוחב הכרטיס.
horizontalAlignment

HorizontalAlignment

קובע אם הווידג'טים ייטו לצד ימין, לצד שמאל או למרכז העמודה.
verticalAlignment

VerticalAlignment

קובעת אם הווידג'טים מיושרים לחלק העליון, התחתון או למרכז של עמודה.
widgets[]

Widgets

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

HorizontalSizeStyle

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

תוספים ל-Google Workspace ואפליקציות ל-Chat

טיפוסים בני מנייה (enum)
HORIZONTAL_SIZE_STYLE_UNSPECIFIED אין להשתמש בו. לא צוין.
FILL_AVAILABLE_SPACE ערך ברירת המחדל. עמודה ממלאת את השטח הזמין, עד 70% מרוחב הכרטיס. אם שתי העמודות מוגדרות ל-FILL_AVAILABLE_SPACE, כל עמודה ממלאת 50% מהמרחב.
FILL_MINIMUM_SPACE העמודה ממלאת את שטח המסך במינימום האפשרי, ולא יותר מ-30% מרוחב הכרטיס.

VerticalAlignment

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

תוספים ל-Google Workspace ואפליקציות של Chat

טיפוסים בני מנייה (enum)
VERTICAL_ALIGNMENT_UNSPECIFIED אין להשתמש בו. לא צוין.
CENTER ערך ברירת המחדל. התאמת הווידג'טים למרכז העמודה.
TOP יישור ווידג'טים לחלק העליון של עמודה.
BOTTOM התאמת הווידג'טים לתחתית העמודה.

ווידג'טים

הווידג'טים הנתמכים שאפשר לכלול בעמודה.

תוספים ל-Google Workspace ואפליקציות של Chat

שדות

שדה איחוד data.

הערך של data יכול להיות רק אחת מהאפשרויות הבאות:
textParagraph

TextParagraph

ווידג'ט ‏TextParagraph.
image

Image

ווידג'ט ‏Image.
decoratedText

DecoratedText

ווידג'ט ‏DecoratedText.
buttonList

ButtonList

ווידג'ט ‏ButtonList.
textInput

TextInput

ווידג'ט ‏TextInput.
selectionInput

SelectionInput

ווידג'ט ‏SelectionInput.
dateTimePicker

DateTimePicker

ווידג'ט ‏DateTimePicker.
chipList

ChipList

ווידג'ט ‏ChipList. זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

DateTimePicker

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

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
name

string

השם שבו מזוהה השדה DateTimePicker באירוע של קלט בטופס.

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

string

הטקסט שמופיע כדי לבקש מהמשתמשים להזין תאריך, שעה או תאריך ושעה. לדוגמה, אם המשתמשים מתזמנים פגישה, אפשר להשתמש בתווית כמו Appointment date או Appointment date and time.
type

DateTimePickerType

האם הווידג'ט תומך בהזנת תאריך, שעה או תאריך ושעה.
valueMsEpoch

int64

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

מציינים את הערך בהתאם לסוג הבורר (DateTimePickerType):

  • DATE_AND_TIME: תאריך ושעה קלנדריים לפי שעון UTC. לדוגמה, כדי לייצג את התאריך 1 בינואר 2023 בשעה 12:00 לפי שעון UTC, משתמשים ב-1672574400000.
  • DATE_ONLY: תאריך קלנדרי בשעה 00:00:00 (שעון UTC). לדוגמה, כדי לייצג את התאריך 1 בינואר 2023, משתמשים ב-1672531200000.
  • TIME_ONLY: השעה לפי שעון UTC. לדוגמה, כדי לייצג את השעה 12:00, השתמשו ב-43200000 (או ב-12 * 60 * 60 * 1000).
timezoneOffsetDate

int32

המספר שמייצג את הפרש אזור הזמן משעון UTC, בדקות. אם השדה מוגדר, הערך של value_ms_epoch יוצג באזור הזמן שצוין. אם הוא לא מוגדר, ברירת המחדל תהיה לפי אזור הזמן של המשתמש.
onChangeAction

Action

האירוע מופעל כשהמשתמש לוחץ על שמירה או על ניקוי בממשק DateTimePicker.
validation

Validation

זה שינוי אופציונלי. מציינים את תהליך האימות הנדרש לבורר התאריכים והשעה הזה.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

DateTimePickerType

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
DATE_AND_TIME המשתמשים מזינים תאריך ושעה.
DATE_ONLY משתמשים מזינים תאריך.
TIME_ONLY המשתמשים מזינים שעה.

DecoratedText

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
icon
(deprecated)

Icon

הוצאו משימוש לטובת startIcon.
startIcon

Icon

הסמל שמוצג לפני הטקסט.
topLabel

string

הטקסט שמופיע מעל text. תמיד חותכים.
text

string

חובה. הטקסט הראשי.

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

bool

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

ההגדרה חלה רק על text, ולא על topLabel ו-bottomLabel.
bottomLabel

string

הטקסט שמופיע מתחת ל-text. תמיד מתבצעת גלישת פסקה.
onClick

OnClick

הפעולה הזו מופעלת כשמשתמשים לוחצים על topLabel או על bottomLabel.
שדה איחוד control. לחצן, מתג, תיבת סימון או תמונה שמופיעים בצד ימין של הטקסט בווידג'ט decoratedText. הערך של control יכול להיות רק אחת מהאפשרויות הבאות:
button

Button

לחצן שמשתמשים יכולים ללחוץ עליו כדי להפעיל פעולה.
switchControl

SwitchControl

ווידג'ט של מתג שהמשתמשים יכולים ללחוץ עליו כדי לשנות את המצב שלו ולהפעיל פעולה.
endIcon

Icon

סמל שמוצג אחרי הטקסט.

תמיכה בסמלים מובנים ומותאמים אישית.

SwitchControl

מתג בסגנון החלפת מצב או תיבת סימון בתוך הווידג'ט decoratedText.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

התכונה נתמכת רק בווידג'ט decoratedText.

שדות
name

string

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

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

string

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

מידע נוסף על עבודה עם קלט טפסים זמין במאמר קבלת נתוני טפסים.
selected

bool

כשהמתג true נבחר.
onChangeAction

Action

הפעולה שצריך לבצע כשמצב המתג משתנה, למשל איזו פונקציה לרוץ.
controlType

ControlType

איך המתג מופיע בממשק המשתמש.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

ControlType

איך המתג מופיע בממשק המשתמש.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
SWITCH מתג בסגנון החלפת מצב.
CHECKBOX הוצא משימוש לטובת CHECK_BOX.
CHECK_BOX תיבת סימון.

קו מפריד

אין שדות לסוג הזה.

מציג קו מפריד בין ווידג'טים כקו אופקי. דוגמה לאפליקציות ב-Google Chat מופיעה במאמר הוספת קו מפריד אופקי בין ווידג'טים.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

לדוגמה, הקוד הבא יוצר מפריד:

"divider": {}

EndNavigation

פעולה בתהליך תיבת הדו-שיח.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
action

Action

פעולת העיבוד של הלקוח כדי לסיים תהליך של תיבת דו-שיח.

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

פעולה

סוגי פעולות הרינדור של הלקוח לסיום תהליך של תיבת דו-שיח.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

טיפוסים בני מנייה (enum)
ACTION_UNSPECIFIED הפעולה לא צוינה.
CLOSE_DIALOG סגירת תהליך הדו-שיח.
CLOSE_DIALOG_AND_EXECUTE סוגרים את תהליך הדו-שיח ומרעננים את הכרטיס שפתח את תהליך הדו-שיח.

GetAutocompletionResponse

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

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat. לדוגמה:

{
  "autoComplete": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
שדות
autoComplete

Suggestions
schema

string

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

תצוגת רשת

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

אפשר להוסיף לרשת כל מספר של עמודות ופריטים. מספר השורות נקבע לפי חלוקת הפריטים במספר העמודות. לרשת עם 10 פריטים ו-2 עמודות יש 5 שורות. ברשת עם 11 פריטים ו-2 עמודות יש 6 שורות.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

לדוגמה, ה-JSON הבא יוצר רשת של 2 עמודות עם פריט אחד:

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}
שדות
title

string

הטקסט שמוצג בכותרת של הרשת.
items[]

GridItem

הפריטים שיוצגו בתצוגת הרשת.
borderStyle

BorderStyle

סגנון המסגרת שיחול על כל פריט ברשת.
columnCount

int32

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

OnClick

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

GridItem

מייצג פריט בפריסת רשת. פריטים יכולים להכיל טקסט, תמונה, או גם טקסט וגם תמונה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
id

string

מזהה שהמשתמש מציין לפריט הזה בתצוגת הרשת. המזהה הזה מוחזר בפרמטרים של קריאה חוזרת (callback) onClick של רשת ההורה.
image

ImageComponent

התמונה שמוצגת בפריט הרשת.
title

string

שם הפריט ברשימה.
subtitle

string

כותרת המשנה של הפריט ברשת.
layout

GridItemLayout

הפריסה שבה יש להשתמש בפריט הרשת.

GridItemLayout

מייצג את אפשרויות הפריסה השונות שזמינות לפריט ברשת.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
GRID_ITEM_LAYOUT_UNSPECIFIED אין להשתמש בו. לא צוין.
TEXT_BELOW הכותרת וכותרת המשנה מוצגות מתחת לתמונה של הפריט ברשת.
TEXT_ABOVE הכותרת והכותרת המשנה מוצגות מעל לתמונה של פריט התצוגה.

סמל

סמל שמוצג בווידג'ט בכרטיס. לדוגמה, ב-Google Chat, אפשר לעיין במאמר הוספת סמל.

יש תמיכה בסמלים מובְנים ובסמלים מותאמים אישית.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
altText

string

זה שינוי אופציונלי. תיאור הסמל המשמש לנגישות. אם לא צוין ערך, צוין ערך ברירת המחדל Button. מומלץ להגדיר תיאור מועיל לגבי מה שהסמל מוצג, והסבר לגבי מה שהוא עושה במקרים רלוונטיים. לדוגמה, A user's account portrait או Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/workspace/chat.

אם הסמל מוגדר ב-Button, ה-altText מופיע כטקסט עזרה כשהמשתמש מעביר את העכבר מעל הלחצן. עם זאת, אם הלחצן מגדיר גם את text, המערכת מתעלמת מה-altText של הסמל.
imageType

ImageType

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

string

הצגת אחד מהסמלים המובנים ש-Google Workspace מספקת.

לדוגמה, כדי להציג סמל של מטוס, מציינים AIRPLANE. לאוטובוס, צריך לציין BUS.

סמלים מובנים – רשימה מלאה של הסמלים הנתמכים.
iconUrl

string

הצגת סמל מותאם אישית שמתארח בכתובת URL מסוג HTTPS.

לדוגמה:

"iconUrl":
"https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png"

סוגי הקבצים הנתמכים כוללים .png ו-.jpg.
materialIcon

MaterialIcon

להציג אחד מסמלי Google לעיצוב חדשני תלת-ממדי.

לדוגמה, כדי להציג סמל תיבת סימון, משתמשים ב-

"materialIcon": {
  "name": "check_box"
}

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

תמונה

תמונה שמוגדרת באמצעות כתובת URL ושיכולה לכלול בה פעולת onClick. לדוגמה, ראו הוספת תמונה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
imageUrl

string

כתובת ה-URL מסוג HTTPS שמארחת את התמונה.

לדוגמה:

https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png
onClick

OnClick

כשמשתמש לוחץ על התמונה, הקליק מפעיל את הפעולה הזאת.
altText

string

הטקסט החלופי של התמונה, שמשמש לצורכי נגישות.

ImageComponent

התמונה מייצגת תמונה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
imageUri

string

כתובת ה-URL של התמונה.
altText

string

תווית הנגישות של התמונה.
cropStyle

ImageCropStyle

סגנון החיתוך שיחול על התמונה.
borderStyle

BorderStyle

סגנון הגבול שיש להחיל על התמונה.

ImageCropStyle

מייצג את סגנון החיתוך שהוחל על תמונה.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

לדוגמה, כך מגדירים יחס גובה-רוחב של 16:9:

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}
שדות
type

ImageCropType

סוג החיתוך.
aspectRatio

double

יחס הגובה-רוחב שבו יש להשתמש אם סוג החיתוך הוא RECTANGLE_CUSTOM.

לדוגמה, כך מחילים יחס גובה-רוחב של 16:9:

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}

ImageCropType

מייצג את סגנון החיתוך שהוחל על תמונה.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
IMAGE_CROP_TYPE_UNSPECIFIED אין להשתמש בו. לא צוין.
SQUARE ערך ברירת המחדל. החלת חיתוך ריבוע.
CIRCLE החלת חיתוך מעגלי.
RECTANGLE_CUSTOM המערכת תחיל חיתוך מלבני עם יחס גובה-רוחב מותאם אישית. מגדירים את יחס הגובה-רוחב המותאם אישית באמצעות aspectRatio.
RECTANGLE_4_3 המערכת משתמשת בחיתוך מלבני עם יחס גובה-רוחב של 4:3.

LinkPreview

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

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

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

{
  "action": {
    "linkPreview": {
      "title": "Smart chip title",
      "linkPreviewTitle": "Link preview title",
      "previewCard": {
        "header": {
          "title": "Preview card header",
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Description of the link."
                }
              }
            ]
          }
        ]
      }
    }
  }
}

הדוגמה מחזירה את התצוגה המקדימה הבאה של הקישור:

תצוגה מקדימה של קישור לדוגמה

שדות
previewCard

Card

כרטיס שמציג מידע על קישור משירות צד שלישי.
title

string

הכותרת שמופיעה בצ'יפ החכם בתצוגה המקדימה של הקישור. אם לא מגדירים את השדה, הצ'יפ החכם יציג את הכותרת של preview_card.
linkPreviewTitle

string

הכותרת שמוצגת בתצוגה המקדימה של הקישור. אם המדיניות לא מוגדרת, בתצוגה המקדימה של הקישור תוצג הכותרת של preview_card.

MaterialIcon

סמל של חומר לימוד של Google, שכולל יותר מ-2,500 אפשרויות.

לדוגמה, כדי להציג סמל תיבת סימון עם משקל ומתן ציון מותאמים אישית, כותבים את הטקסט הבא:

{
  "name": "check_box",
  "fill": true,
  "weight": 300,
  "grade": -25
}

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
name

string

שם הסמל שמוגדר בסמל החומר של Google, לדוגמה, check_box. שמות לא חוקיים יימחקו ויוחלפו במחרוזת ריקה, וכתוצאה מכך לא ניתן יהיה להציג את הסמל.
fill

bool

האם הסמל מוצג כמלא. ערך ברירת המחדל הוא False.

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

int32

עובי הקו של הסמל. אפשר לבחור מבין האפשרויות {100, 200, 300, 400, 500, 600, 700}. אם השדה חסר, ערך ברירת המחדל הוא 400. אם תציינו ערך אחר, נשתמש בערך ברירת המחדל.

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

int32

משקל ודרגה משפיעים על העובי של הסמל. התאמות בציון מפורטות יותר מאשר התאמות במשקל, שיש להן השפעה קטנה על גודל הסמל. בוחרים מתוך {-25, 0, 200}. אם הערך חסר, ערך ברירת המחדל הוא 0. אם תציינו ערך אחר, נשתמש בערך ברירת המחדל.

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

פעולה בכרטיס שמבצעת מניפולציה בערימת הכרטיסים.

לדוגמה:

1) מוסיפים כרטיס חדש למקבץ (מנווטים קדימה). באפליקציות של Chat, התכונה זמינה רק בדף הבית של האפליקציה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

 navigations : {
    pushCard : CARD
  }

2) מעדכנים את הכרטיס מעל הערימה (כלומר מעדכנים את הכרטיס).

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

  navigations : {
    popCard : true,
  }, {
    pushCard : CARD
  }

3) חוזרים אחורה שלב אחד בלי לעדכן.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

  navigations : {
    popCard : true,
  }

4) חוזרים כמה שלבים אחורה ומעדכנים את הכרטיס.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

  navigations : {
    popCard : true,
  }, ... {
    pushCard : CARD
  }

5) חוזרים כמה שלבים אל CARD_NAME מוגדר.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

  navigations : {
    popToCardName : CARD_NAME,
  }, {
    pushCard : CARD
  }

6) חוזרים לשורש ומעדכנים את הכרטיס הזה.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

  navigations : {
    popToRoot : true
  }, {
    pushCard : CARD
  }

7) קופצים אל הכרטיס שצוין ומפוצצים גם את הכרטיס הזה.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

navigations : { popToCardName : CARD_NAME }, { popCard : true, }

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

  navigations : {
    updateCard : CARD
  }
שדות

שדה איחוד navigate_action.

navigate_action יכול להיות רק אחת מהאפשרויות הבאות:
popToRoot

bool

ערימת הכרטיסים מקפיצה את כל הכרטיסים מלבד כרטיס הבסיס.
pop

bool

ערימת הקלפים קופצת כרטיס אחד כבוי.
popToCard

string

ערימת הכרטיסים גורמת להקפצת כל הכרטיסים מעל לכרטיס שצוין עם שם הכרטיס הרצוי.
pushCard

Card

ערימת הכרטיסים דוחפת כרטיס לערימת הכרטיסים.
updateCard

Card

כשמשתמשים ב-Card stack, הכרטיס העליון מתעדכן בכרטיס חדש, והערכים בשדות הטופס המלאים נשמרים. בשדה לא שווה ערך, מושמט.
endNavigation

EndNavigation

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

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

התראה

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

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

שדות
text

string

טקסט פשוט להצגה בהתראה, ללא תגי HTML.

OnClick

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות

שדה איחוד data.

data יכול להיות רק אחת מהאפשרויות הבאות:
action

Action

אם השדה הזה מוגדר, פעולה תופעל על ידי onClick.
openDynamicLinkAction

Action

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

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.
card

Card

כרטיס חדש נדחף לערימה אחרי לחיצה, אם צוין כך.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.
overflowMenu

OverflowMenu

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

OnClose

מה הלקוח עושה כשקישור שנפתח על ידי פעולת OnClick נסגר.

ההטמעה תלויה ביכולות של פלטפורמת הלקוח. לדוגמה, דפדפן אינטרנט עשוי לפתוח קישור בחלון קופץ עם טיפול OnClose.

אם מוגדרים גם הטיפולים OnOpen וגם OnClose, ופלטפורמת הלקוח לא יכולה לתמוך בשני הערכים, הערך OnClose מקבל עדיפות.

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat.

טיפוסים בני מנייה (enum)
NOTHING ערך ברירת המחדל. הכרטיס לא נטען מחדש, לא קורה כלום.
RELOAD

הכרטיס ייטען מחדש אחרי שחלון הצאצא ייסגר.

אם משתמשים בו בשילוב עם OpenAs.OVERLAY, חלון הצאצא משמש כתיבת דו-שיח של חלון וכרטיס ההורה ייחסם עד שחלון הצאצא נסגר.

OpenAs

כשפעולת OnClick פותחת קישור, הלקוח יכול לפתוח אותו כחלון בגודל מלא (אם זו המסגרת שבה הלקוח משתמש) או כשכבת-על (כמו חלון קופץ). ההטמעה תלויה ביכולות של פלטפורמת הלקוח, ויכול להיות שהמערכת תתעלם מהערך שנבחר אם הלקוח לא תומך בו. כל הלקוחות תומכים ב-FULL_SIZE.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.

טיפוסים בני מנייה (enum)
FULL_SIZE הקישור ייפתח כחלון בגודל מלא (אם זו המסגרת שבה הלקוח משתמש).
OVERLAY הקישור נפתח כשכבת-על, למשל חלון קופץ.

OverflowMenu

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

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

שדות
items[]

OverflowMenuItem

חובה. רשימת האפשרויות בתפריט.

OverflowMenuItem

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

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

שדות
startIcon

Icon

הסמל שמוצג לפני הטקסט.
text

string

חובה. הטקסט שמזהה או מתאר את הפריט למשתמשים.
onClick

OnClick

חובה. הפעולה שמופעלת כשבוחרים אפשרות בתפריט. השדה OnClick לא יכול להכיל OverflowMenu, הערכים שצוינו בשדה OverflowMenu מושמטים והאפשרות בתפריט מושבתת.
disabled

bool

האם האפשרות בתפריט מושבתת. ברירת המחדל היא False.

RenderActions

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
action

Action
hostAppAction

HostAppActionMarkup

פעולות שמטופלות על ידי אפליקציות מארח ספציפיות.
schema

string

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

פעולה

שדות
navigations[]

Navigation

דוחפים, קופצים או מעדכנים את הכרטיסים המוצגים.
notification

Notification

הצגת התראה למשתמש הקצה.
linkPreview

LinkPreview

הצגת תצוגה מקדימה של קישור למשתמש הקצה.

SelectionInput

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

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

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
name

string

חובה. השם שמשמש לזיהוי קלט הבחירה באירוע של קלט טופס.

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

string

הטקסט שמופיע מעל שדה הקלט של הבחירה בממשק המשתמש.

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

SelectionType

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

SelectionItem

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

Action

אם צוין, הטופס יישלח כשהבחירה תשתנה. אם לא צוין, צריך לציין לחצן נפרד לשליחת הטופס.

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

int32

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

int32

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

אם לא צוין ערך, ערך ברירת המחדל הוא 0 תווים למקורות נתונים סטטיים ו-3 תווים למקורות נתונים חיצוניים.
validation

Validation

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

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

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace. הערך של multi_select_data_source יכול להיות רק אחת מהאפשרויות הבאות:
externalDataSource

Action

מקור נתונים חיצוני, כמו מסד נתונים יחסי.
platformDataSource

PlatformDataSource

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

PlatformDataSource

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

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

שדות
שדה איחוד data_source. מקור הנתונים. data_source יכול להיות רק אחת מהאפשרויות הבאות:
commonDataSource

CommonDataSource

מקור נתונים שמשותף לכל האפליקציות של Google Workspace, כמו משתמשים בארגון ב-Google Workspace.
hostAppDataSource

HostAppDataSourceMarkup

מקור נתונים ייחודי לאפליקציית מארח ב-Google Workspace, כמו מרחבים משותפים ב-Google Chat.

השדה הזה תומך בספריות הלקוח של Google API, אבל הוא לא זמין בספריות הלקוח ב-Cloud. מידע נוסף זמין במאמר התקנה של ספריות הלקוח.

CommonDataSource

מקור נתונים שמשותף לכל האפליקציות של Google Workspace.

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
UNKNOWN ערך ברירת המחדל. אין להשתמש בו.
USER משתמשי Google Workspace המשתמש יכול להציג ולבחור משתמשים רק מהארגון שלו ב-Google Workspace.

SelectionItem

פריט שהמשתמשים יכולים לבחור באפשרות להזנת בחירה, כמו תיבת סימון או מתג.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
text

string

הטקסט שמזהה או מתאר את הפריט למשתמשים.
value

string

הערך שמשויך לפריט הזה. הלקוח צריך להשתמש בו כערך קלט בטופס.

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

bool

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

string

בתפריטים עם אפשרות לבחירת מספר פריטים, כתובת ה-URL של הסמל שמוצג לצד השדה text של הפריט. המערכת תומכת בקובצי PNG ו-JPEG. חייבת להיות כתובת URL מסוג HTTPS. לדוגמה, https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png.
bottomText

string

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

SelectionType

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

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
CHECK_BOX קבוצה של תיבות סימון. המשתמשים יכולים לסמן תיבת סימון אחת או יותר.
RADIO_BUTTON קבוצה של לחצני בחירה. המשתמשים יכולים לבחור רק לחצן בחירה אחד.
SWITCH קבוצת מתגים. המשתמשים יכולים להפעיל מתג אחד או יותר.
DROPDOWN תפריט נפתח. המשתמשים יכולים לבחור פריט אחד מהתפריט.
MULTI_SELECT

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

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

  • נתונים סטטיים: הפריטים מצוינים כאובייקטים מסוג SelectionItem בווידג'ט. עד 100 פריטים.
  • נתונים מ-Google Workspace: הפריטים מאוכלסים באמצעות נתונים מ-Google Workspace, כמו משתמשי Google Workspace או מרחבים משותפים ב-Google Chat.
  • נתונים חיצוניים: הפריטים מאוכלסים ממקור נתונים חיצוני מחוץ ל-Google Workspace.

במאמר הוספה של תפריט עם אפשרויות בחירה מרובות מופיעות דוגמאות לאופן השימוש בתפריטים עם ריבוי בחירה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

SubmitFormResponse

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

זמין לתוספים ל-Google Workspace ולא זמין לאפליקציות ל-Google Chat. לדוגמה:

{
  "renderActions": {
    "action": {
      "notification": {
        "text": "Email address is added: salam.heba@example.com"
      }
    },
    "hostAppAction": {
      "gmailAction": {
        "openCreatedDraftAction": {
          "draftId": "msg-a:r-79766936926021702",
          "threadServerPermId": "thread-f:15700999851086004"
        }
      }
    }
  }
}
שדות
renderActions

RenderActions

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

bool

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

string

זהו שדה סכימת no-op שעשוי להופיע בסימני ה-Markup לצורך בדיקת תחביר.

הצעות

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

לדוגמה, שדה להזנת טקסט של שפת תכנות עשוי להציע את השפות Java‏, JavaScript‏, Python ו-C++‎. כשמשתמשים מתחילים להקליד Jav, רשימת ההצעות מסוננת כך שיוצגו Java ו-JavaScript.

הצעות לערכים עוזרות למשתמשים להזין ערכים שהאפליקציה שלכם יכולה להבין. בהתייחס ל-JavaScript, חלק מהמשתמשים עשויים להזין javascript ואחרים java script. הצעת JavaScript יכולה להתאים את אופן האינטראקציה של המשתמשים עם האפליקציה שלך.

כשמציינים את הערך, TextInput.type הוא תמיד SINGLE_LINE, גם אם הוא מוגדר כ-MULTIPLE_LINE.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
items[]

SuggestionItem

רשימת הצעות להשלמה אוטומטית של המלצות בשדות להזנת טקסט.

SuggestionItem

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות

שדה איחוד content.

content יכול להיות רק אחת מהאפשרויות הבאות:
text

string

הערך של הצעת קלט לשדה קלט טקסט. הערך הזה זהה למה שהמשתמשים מזינים בעצמם.

TextInput

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

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

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

שדות
name

string

השם שלפיו קלט הטקסט מזוהה באירוע של קלט הטופס.

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

string

הטקסט שמופיע מעל השדה להזנת טקסט בממשק המשתמש.

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

חובה אם לא צוין hintText. אחרת, אופציונלי.
hintText

string

טקסט שמופיע מתחת לשדה להזנת טקסט שנועד לעזור למשתמשים להזין ערך מסוים. הטקסט הזה תמיד גלוי.

חובה אם לא צוין label. אחרת, אופציונלי.
value

string

הערך שהמשתמש הזין, שהוחזר כחלק מאירוע של קלט טופס.

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

Type

האופן שבו מופיע שדה של קלט טקסט בממשק המשתמש. לדוגמה, אם השדה הוא שורה אחת או כמה שורות.
onChangeAction

Action

מה לעשות כשמתרחש שינוי בשדה של קלט הטקסט. לדוגמה, משתמש שמוסיף לשדה או מוחק טקסט.

דוגמאות לפעולות שאפשר לבצע הן הפעלת פונקציה מותאמת אישית או פתיחת תיבת דו-שיח ב-Google Chat.
initialSuggestions

Suggestions

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

לדוגמה, בשדה קלט טקסט של שפת תכנות יכולות להופיע הצעות לשפות Java,‏ JavaScript,‏ Python ו-C++‎. כשהמשתמשים מתחילים להקליד Jav, רשימת ההצעות מסוננת כך שתוצג רק Java ו-JavaScript.

ההצעות לערכים עוזרות להנחות את המשתמשים להזין ערכים שהאפליקציה יכולה להבין. כשמדברים על JavaScript, חלק מהמשתמשים עשויים להזין javascript וחלקם java script. הצעת JavaScript יכולה לסטנדרטיזציה את אופן האינטראקציה של המשתמשים עם האפליקציה.

כשמציינים את הערך, TextInput.type הוא תמיד SINGLE_LINE, גם אם הוא מוגדר כ-MULTIPLE_LINE.

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.
autoCompleteAction

Action

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

אם לא צוין אחרת, ההצעות מוגדרות על ידי initialSuggestions והלקוח יטפל בהן.

אם צוין, האפליקציה תנקוט את הפעולה שצוינה כאן, כמו הפעלת פונקציה מותאמת אישית.

התכונה זמינה בתוספים של Google Workspace ולא זמינה באפליקציות של Google Chat.
validation

Validation

מציינים את סוג האימות הנדרש לשדה הזה להזנת טקסט.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.
placeholderText

string

טקסט שמופיע בשדה להזנת טקסט כשהשדה ריק. משתמשים בטקסט הזה כדי לבקש מהמשתמשים להזין ערך. לדוגמה, Enter a number from 0 to 100.

זמין באפליקציות ל-Google Chat ולא זמין לתוספים ל-Google Workspace.

סוג

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
SINGLE_LINE לשדה הקלט של הטקסט יש גובה קבוע של שורה אחת.
MULTIPLE_LINE לשדה הקלט של הטקסט יש גובה קבוע של כמה שורות.

TextParagraph

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

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
text

string

הטקסט שמוצג בווידג'ט.
maxLines

int32

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

ערך ברירת המחדל הוא 0, ובמקרה כזה כל ההקשר מוצג. המערכת מתעלמת מערכים שליליים. זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

אימות

מייצג את הנתונים הנחוצים לאימות הווידג'ט שאליו הוא מצורף.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

שדות
characterLimit

int32

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

זמין לאפליקציות ל-Google Chat ולתוספים ל-Google Workspace.
inputType

InputType

לציין את הסוג של ווידג'טים לקלט.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

InputType

הסוג של ווידג'ט הקלט.

טיפוסים בני מנייה (enum)
INPUT_TYPE_UNSPECIFIED סוג לא צוין. אין להשתמש בו.
TEXT טקסט רגיל שמקבל את כל התווים.
INTEGER ערך של מספר שלם.
FLOAT ערך מסוג מספר ממשי (float).
EMAIL כתובת אימייל.
EMOJI_PICKER אמוג'י שנבחר מתוך הכלי לבחירת אמוג'י שסופק על ידי המערכת.

ווידג'ט

כל כרטיס מורכב מווידג'טים.

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

שדות
horizontalAlignment

HorizontalAlignment

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

TextParagraph

הצגת פסקה של טקסט. תומכת בטקסט פשוט בפורמט HTML. למידע נוסף על עיצוב טקסט, תוכלו לקרוא את המאמרים עיצוב טקסט באפליקציות ב-Google Chat ועיצוב טקסט בתוספים ל-Google Workspace.

לדוגמה, קובץ ה-JSON הבא יוצר טקסט מודגש:

"textParagraph": {
  "text": "  <b>bold text</b>"
}
image

Image

הצגת תמונה.

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

"image": {
  "imageUrl":
  "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png",
  "altText": "Chat app avatar"
}
decoratedText

DecoratedText

הצגת פריט טקסט מעוטר.

לדוגמה, הקוד הבא ב-JSON יוצר ווידג'ט טקסט מעוטר שמוצגת בו כתובת אימייל:

"decoratedText": {
  "icon": {
    "knownIcon": "EMAIL"
  },
  "topLabel": "Email Address",
  "text": "sasha@example.com",
  "bottomLabel": "This is a new Email address!",
  "switchControl": {
    "name": "has_send_welcome_email_to_sasha",
    "selected": false,
    "controlType": "CHECKBOX"
  }
}
buttonList

ButtonList

רשימת לחצנים.

לדוגמה, הקוד הבא ב-JSON יוצר שני לחצנים. הראשון הוא לחצן טקסט כחול והשני הוא לחצן תמונה שפותח קישור:

"buttonList": {
  "buttons": [
    {
      "text": "Edit",
      "color": {
        "red": 0,
        "green": 0,
        "blue": 1,
      },
      "disabled": true,
    },
    {
      "icon": {
        "knownIcon": "INVITE",
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    }
  ]
}
textInput

TextInput

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

לדוגמה, ה-JSON הבא יוצר קלט טקסט לכתובת אימייל:

"textInput": {
  "name": "mailing_address",
  "label": "Mailing Address"
}

דוגמה נוספת: קובץ ה-JSON הבא יוצר קלט טקסט לשפת תכנות עם הצעות סטטיות:

"textInput": {
  "name": "preferred_programing_language",
  "label": "Preferred Language",
  "initialSuggestions": {
    "items": [
      {
        "text": "C++"
      },
      {
        "text": "Java"
      },
      {
        "text": "JavaScript"
      },
      {
        "text": "Python"
      }
    ]
  }
}
selectionInput

SelectionInput

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

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

"selectionInput": {
  "name": "size",
  "label": "Size"
  "type": "DROPDOWN",
  "items": [
    {
      "text": "S",
      "value": "small",
      "selected": false
    },
    {
      "text": "M",
      "value": "medium",
      "selected": true
    },
    {
      "text": "L",
      "value": "large",
      "selected": false
    },
    {
      "text": "XL",
      "value": "extra_large",
      "selected": false
    }
  ]
}
dateTimePicker

DateTimePicker

הצגת ווידג'ט שמאפשר למשתמשים להזין תאריך, שעה או תאריך ושעה.

לדוגמה, הקוד הבא ב-JSON יוצר בורר תאריך ושעה לקביעת פגישה:

"dateTimePicker": {
  "name": "appointment_time",
  "label": "Book your appointment at:",
  "type": "DATE_AND_TIME",
  "valueMsEpoch": "796435200000"
}
divider

Divider

מציג קו אופקי בין ווידג'טים.

לדוגמה, קובץ ה-JSON הבא יוצר מחיצה:

"divider": {
}
grid

Grid

הצגת רשת עם אוסף פריטים.

רשת תומכת בכל מספר של עמודות ופריטים. מספר השורות נקבע לפי המגבלה העליונה של מספר הפריטים חלקי מספר העמודות. ברשת עם 10 פריטים ו-2 עמודות יש 5 שורות. ברשת עם 11 פריטים ו-2 עמודות יש 6 שורות.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

לדוגמה, קובץ ה-JSON הבא יוצר רשת של 2 עמודות עם פריט אחד:

"grid": {
  "title": "A fine collection of items",
  "columnCount": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4
  },
  "items": [
    {
      "image": {
        "imageUri": "https://www.example.com/image.png",
        "cropStyle": {
          "type": "SQUARE"
        },
        "borderStyle": {
          "type": "STROKE"
        }
      },
      "title": "An item",
      "textAlignment": "CENTER"
    }
  ],
  "onClick": {
    "openLink": {
      "url": "https://www.example.com"
    }
  }
}
columns

Columns

מוצגות עד 2 עמודות.

כדי לכלול יותר מ-2 עמודות, או כדי להשתמש בשורות, צריך להשתמש בווידג'ט Grid.

לדוגמה, בקובץ ה-JSON הבא נוצר 2 עמודות שכל אחת מהן מכילה פסקאות טקסט:

"columns": {
  "columnItems": [
    {
      "horizontalSizeStyle": "FILL_AVAILABLE_SPACE",
      "horizontalAlignment": "CENTER",
      "verticalAlignment": "CENTER",
      "widgets": [
        {
          "textParagraph": {
            "text": "First column text paragraph"
          }
        }
      ]
    },
    {
      "horizontalSizeStyle": "FILL_AVAILABLE_SPACE",
      "horizontalAlignment": "CENTER",
      "verticalAlignment": "CENTER",
      "widgets": [
        {
          "textParagraph": {
            "text": "Second column text paragraph"
          }
        }
      ]
    }
  ]
}
chipList

ChipList

רשימת צ'יפים.

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

"chipList": {
  "chips": [
    {
      "text": "Edit",
      "disabled": true,
    },
    {
      "icon": {
        "knownIcon": "INVITE",
        "altText": "check calendar"
      },
      "onClick": {
        "openLink": {
          "url": "https://example.com/calendar"
        }
      }
    }
  ]
}

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

HorizontalAlignment

קובע אם הווידג'טים ייטו לצד ימין, לצד שמאל או למרכז העמודה.

זמין באפליקציות של Google Chat ולא זמין בתוספים של Google Workspace.

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

ImageType

הצורה שבה התמונה חתוכה.

התכונה זמינה באפליקציות של Google Chat ובתוספים ל-Google Workspace.

טיפוסים בני מנייה (enum)
SQUARE ערך ברירת המחדל. החלת מסכה ריבועית על התמונה. לדוגמה, תמונה בגודל 4x3 הופכת ל-3x3.
CIRCLE החלת מסכה עגולה על התמונה. לדוגמה, תמונה בגודל 4x3 הופכת לעיגול בקוטר 3.