Cards v2

קלפים

ממשק של כרטיס שמוצג בהודעה ב-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"
                             }
                           ]
                         }
                       }
                     }
                   ]
                 }
               }
             ]
           }
         ]
       }
    }
  ]
}
ייצוג JSON
{
  "header": {
    object (CardHeader)
  },
  "sections": [
    {
      object (Section)
    }
  ],
  "sectionDividerStyle": enum (DividerStyle),
  "cardActions": [
    {
      object (CardAction)
    }
  ],
  "name": string,
  "fixedFooter": {
    object (CardFixedFooter)
  },
  "displayStyle": enum (DisplayStyle),
  "peekCardHeader": {
    object (CardHeader)
  }
}
שדות
header

object (CardHeader)

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

sections[]

object (Section)

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

sectionDividerStyle

enum (DividerStyle)

סגנון ההפרדה בין הקטעים.

cardActions[]

object (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.

displayStyle

enum (DisplayStyle)

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

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

peekCardHeader

object (CardHeader)

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

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

CardHeader

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

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

ייצוג ב-JSON
{
  "title": string,
  "subtitle": string,
  "imageType": enum (ImageType),
  "imageUrl": string,
  "imageAltText": string
}
שדות
title

string

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

subtitle

string

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

imageType

enum (ImageType)

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

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

imageUrl

string

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

imageAltText

string

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

ImageType

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

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

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

קטע

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

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

ייצוג ב-JSON
{
  "header": string,
  "widgets": [
    {
      object (Widget)
    }
  ],
  "collapsible": boolean,
  "uncollapsibleWidgetsCount": integer,
  "collapseControl": {
    object (CollapseControl)
  }
}
שדות
header

string

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

widgets[]

object (Widget)

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

collapsible

boolean

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

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

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

uncollapsibleWidgetsCount

integer

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

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

collapseControl

object (CollapseControl)

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

ווידג'ט

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

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

ייצוג JSON
{
  "horizontalAlignment": enum (HorizontalAlignment),

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "image": {
    object (Image)
  },
  "decoratedText": {
    object (DecoratedText)
  },
  "buttonList": {
    object (ButtonList)
  },
  "textInput": {
    object (TextInput)
  },
  "selectionInput": {
    object (SelectionInput)
  },
  "dateTimePicker": {
    object (DateTimePicker)
  },
  "divider": {
    object (Divider)
  },
  "grid": {
    object (Grid)
  },
  "columns": {
    object (Columns)
  },
  "chipList": {
    object (ChipList)
  }
  // End of list of possible types for union field data.
}
שדות
horizontalAlignment

enum (HorizontalAlignment)

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

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

object (TextParagraph)

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

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

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

object (Image)

מציגה תמונה.

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

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

object (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

object (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

object (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

object (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

object (DateTimePicker)

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

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

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

object (Divider)

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

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

"divider": {
}
grid

object (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

object (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

object (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.

TextParagraph

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

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

ייצוג ב-JSON
{
  "text": string,
  "maxLines": integer
}
שדות
text

string

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

maxLines

integer

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

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

תמונה

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

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

ייצוג ב-JSON
{
  "imageUrl": string,
  "onClick": {
    object (OnClick)
  },
  "altText": string
}
שדות
imageUrl

string

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

לדוגמה:

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

object (OnClick)

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

altText

string

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

OnClick

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

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

ייצוג ב-JSON
{

  // Union field data can be only one of the following:
  "action": {
    object (Action)
  },
  "openLink": {
    object (OpenLink)
  },
  "openDynamicLinkAction": {
    object (Action)
  },
  "card": {
    object (Card)
  },
  "overflowMenu": {
    object (OverflowMenu)
  }
  // End of list of possible types for union field data.
}
שדות

שדה איחוד data

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

action

object (Action)

אם צוין, פעולה תופעל על ידי onClick

card

object (Card)

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

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

overflowMenu

object (OverflowMenu)

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

פעולה

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

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

ייצוג ב-JSON
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction),
  "requiredWidgets": [
    string
  ],
  "allWidgetsAreRequired": boolean
}
שדות
function

string

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

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

parameters[]

object (ActionParameter)

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

loadIndicator

enum (LoadIndicator)

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

persistValues

boolean

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

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

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

interaction

enum (Interaction)

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

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

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

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

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

requiredWidgets[]

string

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

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

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

allWidgetsAreRequired

boolean

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

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

ActionParameter

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

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

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

ייצוג ב-JSON
{
  "key": string,
  "value": string
}
שדות
key

string

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

value

string

הערך של הפרמטר.

LoadIndicator

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

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

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

אינטראקציה

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

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

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

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

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

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

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

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

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

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

OpenAs

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

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

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

OnClose

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

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

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

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

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

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

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

OverflowMenu

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

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

ייצוג JSON
{
  "items": [
    {
      object (OverflowMenuItem)
    }
  ]
}
שדות
items[]

object (OverflowMenuItem)

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

OverflowMenuItem

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

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

ייצוג JSON
{
  "startIcon": {
    object (Icon)
  },
  "text": string,
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean
}
שדות
startIcon

object (Icon)

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

text

string

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

onClick

object (OnClick)

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

disabled

boolean

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

סמל

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

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

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

ייצוג ב-JSON
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string,
  "materialIcon": {
    object (MaterialIcon)
  }
  // End of list of possible types for union field icons.
}
שדות
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

enum (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

object (MaterialIcon)

הצגה של אחד סמלי החומר של Google.

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

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

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

MaterialIcon

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

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

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

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

ייצוג JSON
{
  "name": string,
  "fill": boolean,
  "weight": integer,
  "grade": integer
}
שדות
name

string

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

fill

boolean

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

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

weight

integer

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

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

grade

integer

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

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

DecoratedText

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

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

ייצוג ב-JSON
{
  "icon": {
    object (Icon)
  },
  "startIcon": {
    object (Icon)
  },
  "topLabel": string,
  "text": string,
  "wrapText": boolean,
  "bottomLabel": string,
  "onClick": {
    object (OnClick)
  },

  // Union field control can be only one of the following:
  "button": {
    object (Button)
  },
  "switchControl": {
    object (SwitchControl)
  },
  "endIcon": {
    object (Icon)
  }
  // End of list of possible types for union field control.
}
שדות
icon
(deprecated)

object (Icon)

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

startIcon

object (Icon)

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

topLabel

string

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

text

string

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

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

wrapText

boolean

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

חל רק על text, לא topLabel וגם bottomLabel.

bottomLabel

string

הטקסט שמופיע למטה text תמיד עוטף.

onClick

object (OnClick)

הפעולה הזו מופעלת כשמשתמשים לוחצים על topLabel או bottomLabel.

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

object (Button)

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

switchControl

object (SwitchControl)

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

endIcon

object (Icon)

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

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

לחצן

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

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

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

ייצוג ב-JSON
{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string,
  "type": enum (Type)
}
שדות
text

string

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

icon

object (Icon)

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

color

object (Color)

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

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

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

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

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

onClick

object (OnClick)

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

disabled

boolean

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

altText

string

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

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

type

enum (Type)

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

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

צבע

מייצג צבע במרחב הצבעים RGBA. הייצוג הזה נועד לאפשר פשטות המרה אל ומתוך ייצוגי צבע בשפות שונות, על-פני קומפקטיות. לדוגמה, ניתן לספק את השדות של הייצוג הזה באופן טריוויאלי ל-constructor של java.awt.Color ב-Java; אפשר לספק אותו גם באופן טריוויאלי +colorWithRed:green:blue:alpha method ב-iOS; ובמאמץ קטן, אפשר לעצב אותו בקלות rgba() ב-JavaScript.

בדף העזר הזה אין מידע על מרחב הצבעים המוחלט שצריך להשתמש בו כדי לפרש את ערך ה-RGB – לדוגמה, sRGB, Adobe RGB, DCI-P3 ו-BT.2020. כברירת מחדל, האפליקציות צריכות להשתמש במרחב הצבעים sRGB.

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

דוגמה (Java):

 import com.google.type.Color;

 // ...
 public static java.awt.Color fromProto(Color protocolor) {
   float alpha = protocolor.hasAlpha()
       ? protocolor.getAlpha().getValue()
       : 1.0;

   return new java.awt.Color(
       protocolor.getRed(),
       protocolor.getGreen(),
       protocolor.getBlue(),
       alpha);
 }

 public static Color toProto(java.awt.Color color) {
   float red = (float) color.getRed();
   float green = (float) color.getGreen();
   float blue = (float) color.getBlue();
   float denominator = 255.0;
   Color.Builder resultBuilder =
       Color
           .newBuilder()
           .setRed(red / denominator)
           .setGreen(green / denominator)
           .setBlue(blue / denominator);
   int alpha = color.getAlpha();
   if (alpha != 255) {
     result.setAlpha(
         FloatValue
             .newBuilder()
             .setValue(((float) alpha) / denominator)
             .build());
   }
   return resultBuilder.build();
 }
 // ...

דוגמה (iOS / Obj-C):

 // ...
 static UIColor* fromProto(Color* protocolor) {
    float red = [protocolor red];
    float green = [protocolor green];
    float blue = [protocolor blue];
    FloatValue* alpha_wrapper = [protocolor alpha];
    float alpha = 1.0;
    if (alpha_wrapper != nil) {
      alpha = [alpha_wrapper value];
    }
    return [UIColor colorWithRed:red green:green blue:blue alpha:alpha];
 }

 static Color* toProto(UIColor* color) {
     CGFloat red, green, blue, alpha;
     if (![color getRed:&red green:&green blue:&blue alpha:&alpha]) {
       return nil;
     }
     Color* result = [[Color alloc] init];
     [result setRed:red];
     [result setGreen:green];
     [result setBlue:blue];
     if (alpha <= 0.9999) {
       [result setAlpha:floatWrapperWithValue(alpha)];
     }
     [result autorelease];
     return result;
}
// ...

דוגמה (JavaScript):

// ...

var protoToCssColor = function(rgb_color) {
   var redFrac = rgb_color.red || 0.0;
   var greenFrac = rgb_color.green || 0.0;
   var blueFrac = rgb_color.blue || 0.0;
   var red = Math.floor(redFrac * 255);
   var green = Math.floor(greenFrac * 255);
   var blue = Math.floor(blueFrac * 255);

   if (!('alpha' in rgb_color)) {
      return rgbToCssColor(red, green, blue);
   }

   var alphaFrac = rgb_color.alpha.value || 0.0;
   var rgbParams = [red, green, blue].join(',');
   return ['rgba(', rgbParams, ',', alphaFrac, ')'].join('');
};

var rgbToCssColor = function(red, green, blue) {
  var rgbNumber = new Number((red << 16) | (green << 8) | blue);
  var hexString = rgbNumber.toString(16);
  var missingZeros = 6 - hexString.length;
  var resultBuilder = ['#'];
  for (var i = 0; i < missingZeros; i++) {
     resultBuilder.push('0');
  }
  resultBuilder.push(hexString);
  return resultBuilder.join('');
};

// ...
ייצוג JSON
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
שדות
red

number

כמות הצבע האדום כערך במרווח הזמן [0, 1].

green

number

כמות הצבע הירוק כערך במרווחים [0, 1].

blue

number

כמות הכחול בצבע כערך בטווח [0, 1].

alpha

number

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

pixel color = alpha * (this color) + (1.0 - alpha) * (background color)

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

סוג

זה שינוי אופציונלי. type בלחיצה אחת. אם המיקום color מוגדר, type נאלץ FILLED.

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

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

SwitchControl

מתג בסגנון מתג או תיבת סימון decoratedText לווידג'ט הזה.

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

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

ייצוג JSON
{
  "name": string,
  "value": string,
  "selected": boolean,
  "onChangeAction": {
    object (Action)
  },
  "controlType": enum (ControlType)
}
שדות
name

string

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

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

value

string

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

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

selected

boolean

מתי true, המתג נבחר.

onChangeAction

object (Action)

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

controlType

enum (ControlType)

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

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

ControlType

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

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

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

ButtonList

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

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

ייצוג ב-JSON
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
שדות
buttons[]

object (Button)

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

TextInput

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

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

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

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

ייצוג ב-JSON
{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  },
  "validation": {
    object (Validation)
  },
  "placeholderText": string
}
שדות
name

string

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

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

label

string

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

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

נדרש אם hintText לא צוינה. אחרת, אופציונלי.

hintText

string

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

נדרש אם label לא צוינה. אחרת, אופציונלי.

value

string

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

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

type

enum (Type)

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

onChangeAction

object (Action)

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

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

initialSuggestions

object (Suggestions)

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

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

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

כשמצוין, TextInput.type הוא תמיד SINGLE_LINE, גם אם הוא מוגדר MULTIPLE_LINE.

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

autoCompleteAction

object (Action)

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

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

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

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

validation

object (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 לשדה הקלט של הטקסט יש גובה קבוע של כמה שורות.

RenderActions

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

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

שדות
action

Action

פעולה

שדות
navigations[]

Navigation

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

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

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

navigations: {
  pushCard: CARD
}

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

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

navigations: {
  updateCard: CARD
}

הצעות

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

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

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

כשמצוין, TextInput.type הוא תמיד SINGLE_LINE, גם אם הוא מוגדר MULTIPLE_LINE.

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

ייצוג ב-JSON
{
  "items": [
    {
      object (SuggestionItem)
    }
  ]
}
שדות
items[]

object (SuggestionItem)

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

SuggestionItem

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

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

ייצוג ב-JSON
{

  // Union field content can be only one of the following:
  "text": string
  // End of list of possible types for union field content.
}
שדות

שדה איחוד content

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

text

string

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

אימות

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

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

ייצוג ב-JSON
{
  "characterLimit": integer,
  "inputType": enum (InputType)
}
שדות
characterLimit

integer

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

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

inputType

enum (InputType)

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

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

InputType

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

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

SelectionInput

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

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

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

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

ייצוג ב-JSON
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,
  "validation": {
    object (Validation)
  },

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
שדות
name

string

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

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

label

string

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

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

type

enum (SelectionType)

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

items[]

object (SelectionItem)

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

onChangeAction

object (Action)

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

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

multiSelectMaxSelectedItems

integer

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

multiSelectMinQueryLength

integer

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

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

validation

object (Validation)

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

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

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

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

externalDataSource

object (Action)

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

platformDataSource

object (PlatformDataSource)

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

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.

SelectionItem

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

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

ייצוג ב-JSON
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
שדות
text

string

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

value

string

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

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

selected

boolean

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

startIconUri

string

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

bottomText

string

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

PlatformDataSource

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

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

ייצוג JSON
{

  // Union field data_source can be only one of the following:
  "commonDataSource": enum (CommonDataSource),
  "hostAppDataSource": {
    object (HostAppDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
שדות
שדה האיחוד data_source. מקור הנתונים. data_source יכול להיות רק אחת מהאפשרויות הבאות:
commonDataSource

enum (CommonDataSource)

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

hostAppDataSource

object (HostAppDataSourceMarkup)

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

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

CommonDataSource

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

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

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

HostAppDataSourceMarkup

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

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

ייצוג JSON
{

  // Union field data_source can be only one of the following:
  "chatDataSource": {
    object (ChatClientDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
שדות
שדה איחוד data_source אפליקציית Google Workspace שמאכלסת פריטים בתפריט לבחירה מרובה. data_source יכול להיות רק אחת מהאפשרויות הבאות:
chatDataSource

object (ChatClientDataSourceMarkup)

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

ChatClientDataSourceMarkup

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

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

ייצוג JSON
{

  // Union field source can be only one of the following:
  "spaceDataSource": {
    object (SpaceDataSource)
  }
  // End of list of possible types for union field source.
}
שדות
שדה איחוד source מקור הנתונים של Google Chat. source יכול להיות רק אחד מהערכים הבאים:
spaceDataSource

object (SpaceDataSource)

מרחבים ב-Google Chat שהמשתמש חבר בהם.

SpaceDataSource

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

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

ייצוג JSON
{
  "defaultToCurrentSpace": boolean
}
שדות
defaultToCurrentSpace

boolean

אם מוגדר true, בתפריט הבחירה מרובה, המרחב המשותף הנוכחי ב-Google Chat ייבחר כברירת מחדל.

DateTimePicker

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

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

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

ייצוג ב-JSON
{
  "name": string,
  "label": string,
  "type": enum (DateTimePickerType),
  "valueMsEpoch": string,
  "timezoneOffsetDate": integer,
  "onChangeAction": {
    object (Action)
  },
  "validation": {
    object (Validation)
  }
}
שדות
name

string

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

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

label

string

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

type

enum (DateTimePickerType)

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

valueMsEpoch

string (int64 format)

ערך ברירת המחדל שמוצג בווידג'ט, באלפיות השנייה מאז ראשית זמן יוניקס (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

integer

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

onChangeAction

object (Action)

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

validation

object (Validation)

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

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

DateTimePickerType

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

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

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

קו מפריד

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

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

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

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

"divider": {}

תצוגת רשת

תצוגת רשת עם אוסף של פריטים. הפריטים יכולים לכלול רק טקסט או תמונות. לעמודות רספונסיביות, או כדי לכלול יותר מטקסט או תמונות, משתמשים 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"
    }
  }
}
ייצוג JSON
{
  "title": string,
  "items": [
    {
      object (GridItem)
    }
  ],
  "borderStyle": {
    object (BorderStyle)
  },
  "columnCount": integer,
  "onClick": {
    object (OnClick)
  }
}
שדות
title

string

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

items[]

object (GridItem)

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

borderStyle

object (BorderStyle)

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

columnCount

integer

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

onClick

object (OnClick)

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

GridItem

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

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

ייצוג ב-JSON
{
  "id": string,
  "image": {
    object (ImageComponent)
  },
  "title": string,
  "subtitle": string,
  "layout": enum (GridItemLayout)
}
שדות
id

string

מזהה שהמשתמש מציין לפריט הזה בתצוגת הרשת. המזהה הזה מוחזר בפרמטר ה-callback‏ onClick של רשת ההורה.

image

object (ImageComponent)

התמונה שמופיעה בפריט.

title

string

שם הפריט ברשת.

subtitle

string

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

layout

enum (GridItemLayout)

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

ImageComponent

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

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

ייצוג ב-JSON
{
  "imageUri": string,
  "altText": string,
  "cropStyle": {
    object (ImageCropStyle)
  },
  "borderStyle": {
    object (BorderStyle)
  }
}
שדות
imageUri

string

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

altText

string

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

cropStyle

object (ImageCropStyle)

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

borderStyle

object (BorderStyle)

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

ImageCropStyle

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

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

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

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}
ייצוג JSON
{
  "type": enum (ImageCropType),
  "aspectRatio": number
}
שדות
type

enum (ImageCropType)

סוג החיתוך.

aspectRatio

number

יחס הגובה-רוחב שבו יש להשתמש אם סוג החיתוך הוא 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.

BorderStyle

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

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

ייצוג ב-JSON
{
  "type": enum (BorderType),
  "strokeColor": {
    object (Color)
  },
  "cornerRadius": integer
}
שדות
type

enum (BorderType)

סוג הגבולות.

strokeColor

object (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

integer

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

BorderType

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

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

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

GridItemLayout

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

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

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

עמודות

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

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

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

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

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

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

  • תיבת הדו-שיח שמוצגת כשמשתמשים פותחים את התוסף מטיוטה של אימייל.
  • תיבת הדו-שיח שמוצגת כשמשתמשים פותחים את התוסף מהתפריט הוספת קובץ באירוע ביומן Google.
ייצוג JSON
{
  "columnItems": [
    {
      object (Column)
    }
  ]
}
שדות
columnItems[]

object (Column)

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

עמודה

עמודה.

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

ייצוג JSON
{
  "horizontalSizeStyle": enum (HorizontalSizeStyle),
  "horizontalAlignment": enum (HorizontalAlignment),
  "verticalAlignment": enum (VerticalAlignment),
  "widgets": [
    {
      object (Widgets)
    }
  ]
}
שדות
horizontalSizeStyle

enum (HorizontalSizeStyle)

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

horizontalAlignment

enum (HorizontalAlignment)

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

verticalAlignment

enum (VerticalAlignment)

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

widgets[]

object (Widgets)

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

HorizontalSizeStyle

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

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

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

HorizontalAlignment

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

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

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

VerticalAlignment

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

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

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

ווידג'טים

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

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

ייצוג JSON
{

  // Union field data can be only one of the following:
  "textParagraph": {
    object (TextParagraph)
  },
  "image": {
    object (Image)
  },
  "decoratedText": {
    object (DecoratedText)
  },
  "buttonList": {
    object (ButtonList)
  },
  "textInput": {
    object (TextInput)
  },
  "selectionInput": {
    object (SelectionInput)
  },
  "dateTimePicker": {
    object (DateTimePicker)
  },
  "chipList": {
    object (ChipList)
  }
  // End of list of possible types for union field data.
}
שדות

שדה איחוד data

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

textParagraph

object (TextParagraph)

ווידג'ט TextParagraph.

image

object (Image)

ווידג'ט Image.

decoratedText

object (DecoratedText)

DecoratedText לווידג'ט הזה.

buttonList

object (ButtonList)

ButtonList לווידג'ט הזה.

textInput

object (TextInput)

ווידג'ט TextInput.

selectionInput

object (SelectionInput)

SelectionInput לווידג'ט הזה.

dateTimePicker

object (DateTimePicker)

DateTimePicker לווידג'ט הזה.

chipList

object (ChipList)

ווידג'ט ChipList. ההגדרה הזו זמינה באפליקציות ל-Google Chat ולא זמינה לתוספים ל-Google Workspace.

ChipList

רשימה של צ'יפים בפריסה לרוחב, שאפשר לגלול לרוחב או לגלול לשורה הבאה.

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

ייצוג JSON
{
  "layout": enum (Layout),
  "chips": [
    {
      object (Chip)
    }
  ]
}
שדות
layout

enum (Layout)

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

chips[]

object (Chip)

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

פריסה

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

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

צ'יפ

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

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

ייצוג JSON
{
  "icon": {
    object (Icon)
  },
  "label": string,
  "onClick": {
    object (OnClick)
  },
  "enabled": boolean,
  "disabled": boolean,
  "altText": string
}
שדות
icon

object (Icon)

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

label

string

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

onClick

object (OnClick)

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

enabled
(deprecated)

boolean

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

disabled

boolean

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

altText

string

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

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

CollapseControl

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

ייצוג JSON
{
  "horizontalAlignment": enum (HorizontalAlignment),
  "expandButton": {
    object (Button)
  },
  "collapseButton": {
    object (Button)
  }
}
שדות
horizontalAlignment

enum (HorizontalAlignment)

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

expandButton

object (Button)

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

collapseButton

object (Button)

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

DividerStyle

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

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

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

CardAction

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

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

ייצוג JSON
{
  "actionLabel": string,
  "onClick": {
    object (OnClick)
  }
}
שדות
actionLabel

string

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

onClick

object (OnClick)

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

CardFixedFooter

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

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

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

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

ייצוג ב-JSON
{
  "primaryButton": {
    object (Button)
  },
  "secondaryButton": {
    object (Button)
  }
}
שדות
primaryButton

object (Button)

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

secondaryButton

object (Button)

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

DisplayStyle

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

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

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