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.

ActionParameter

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

מידע נוסף זמין בכתובת CommonEventObject.

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

שדות
key

string

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

value

string

ערך הפרמטר.

אינטראקציה

אפשרות. חובה כשפותחים תיבת דו-שיח.

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

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

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

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

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

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

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

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

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

LoadIndicator

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

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

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

BorderStyle

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

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

שדות
type

BorderType

סוג הגבול.

strokeColor

Color

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

cornerRadius

int32

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

BorderType

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

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

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

לחצן

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

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

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

שדות
text

string

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

icon

Icon

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

color

Color

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

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

עבור אדום, ירוק וכחול, הערך של כל שדה הוא מספר float ש ניתן לבטא בשתי דרכים: כמספר בין 0 ל-255 לחלק ל-255 (153/255), או כערך בין 0 ל-1 (0.6). הערך 0 מציין שאין צבע ו-1 או 255/255 מייצג את הנוכחות המלאה של הצבע הזה בסולם ה-RGB.

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

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

עבור alpha, הערך 1 מייצג צבע אחיד, והערך 0 מייצג צבע שקוף לחלוטין.

לדוגמה, הצבע הבא מייצג חצי אדום שקוף:

"color": {
   "red": 1,
   "green": 0,
   "blue": 0,
   "alpha": 0.5
}
onClick

OnClick

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

disabled

bool

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

altText

string

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

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

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/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

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

זמין לתוספים ל-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.

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

DividerStyle

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

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

טיפוסים בני מנייה (enums)
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.

עמודות

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

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

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

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

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

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

שדות
columnItems[]

Column

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

עמודה

עמודה.

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

שדות
horizontalSizeStyle

HorizontalSizeStyle

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

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

horizontalAlignment

HorizontalAlignment

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

verticalAlignment

VerticalAlignment

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

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

widgets[]

Widgets

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

HorizontalSizeStyle

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

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

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

VerticalAlignment

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

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

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

ווידג'טים

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

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

שדות

שדה איחוד data.

data יכול להיות רק אחד מהבאים:

textParagraph

TextParagraph

ווידג'ט ‏TextParagraph.

image

Image

ווידג'ט ‏Image.

decoratedText

DecoratedText

ווידג'ט ‏DecoratedText.

buttonList

ButtonList

ווידג'ט ‏ButtonList.

textInput

TextInput

ווידג'ט ‏TextInput.

selectionInput

SelectionInput

ווידג'ט ‏SelectionInput.

dateTimePicker

DateTimePicker

ווידג'ט ‏DateTimePicker.

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.

DateTimePickerType

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

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

טיפוסים בני מנייה (enums)
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.

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

קו מפריד

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

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

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

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

"divider": {}

EndNavigation

פעולת זרימה בתיבת דו-שיח.

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

שדות
action

Action

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

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

פעולה

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

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

טיפוסים בני מנייה (enums)
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

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

מזהה GRid

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

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

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

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

"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

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

GridItem

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

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

שדות
id

string

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

image

ImageComponent

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

title

string

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

subtitle

string

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

layout

GridItemLayout

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

GridItemLayout

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

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

טיפוסים בני מנייה (enums)
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/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/chat/images/quickstart-app-avatar.png"

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

תמונה

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

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

שדות
imageUrl

string

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

למשל:

https://developers.google.com/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.

טיפוסים בני מנייה (enums)
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.

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

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

למשל:

1) הוספת כרטיס חדש לערימה (ניווט קדימה).

 navigations : {
    pushCard : CARD
  }

2) מעדכנים את הכרטיס בחלק העליון של הערימה (בעדכון).

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

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

  navigations : {
    popCard : true,
  }

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

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

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

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

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

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

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

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

8) החליפו את הכרטיס העליון בכרטיס חדש.

  navigations : {
    updateCard : CARD
  }
שדות

שדה איחוד navigate_action.

navigate_action יכול להיות רק אחד מהבאים:

popToRoot

bool

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

pop

bool

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

popToCard

string

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

pushCard

Card

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

updateCard

Card

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

endNavigation

EndNavigation

פעולת הניווט בתהליך של תיבת הדו-שיח שנעשה בה שימוש ב-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.

OnClose

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

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

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

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

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

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

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

OpenAs

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

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

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

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

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

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

שדה איחוד 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.

CommonDataSource

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

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

טיפוסים בני מנייה (enums)
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/chat/images/quickstart-app-avatar.png.

bottomText

string

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

SelectionType

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

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

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

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

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

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

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

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

זמין באפליקציות 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

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

הצעות

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

לדוגמה, שדה להזנת טקסט לשפת התכנות עשוי להציע את 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.

placeholderText

string

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

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

סוג

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

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

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

TextParagraph

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

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

שדות
text

string

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

ווידג'ט

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

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

שדות
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/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,
        "alpha": 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 הבא יוצר רשת של שתי עמודות עם פריט אחד:

"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"
          }
        }
      ]
    }
  ]
}

HorizontalAlignment

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

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

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

ImageType

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

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

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