Cards v2

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

بطاقة

وتدعم البطاقات التصميم المحدّد وعناصر واجهة المستخدم التفاعلية مثل الأزرار والوسائط المتعددة التفاعلية، مثل الصور. يمكنك استخدام البطاقات لتقديم معلومات مفصّلة وجمع المعلومات من المستخدمين وإرشاد المستخدمين لاتخاذ الخطوة التالية.

في 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",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}
تمثيل JSON
{
  "header": {
    object (CardHeader)
  },
  "sections": [
    {
      object (Section)
    }
  ],
  "cardActions": [
    {
      object (CardAction)
    }
  ],
  "name": string,
  "fixedFooter": {
    object (CardFixedFooter)
  },
  "displayStyle": enum (DisplayStyle),
  "peekCardHeader": {
    object (CardHeader)
  }
}
الحقول
header

object ( CardHeader )

عنوان البطاقة. وعادةً ما يحتوي العنوان على صورة رئيسية وعنوان. تظهر العناوين دائمًا في أعلى البطاقة.

sections[]

object ( Section )

يحتوي على مجموعة من الأدوات. لكل قسم عنوان اختياري خاص به. يُفصل بين الأقسام مرئيًا فاصل أسطر.

cardActions[]

object ( CardAction )

إجراءات البطاقة تتم إضافة الإجراءات إلى قائمة شريط أدوات البطاقة.

بما أنّ بطاقات تطبيقات Chat لا تحتوي على شريط أدوات، لا تتوفر تطبيقات cardActions[] في Chat.

على سبيل المثال، تنشئ JSON التالية قائمة إجراءات بطاقة باستخدام الخيارات "إعدادات" و"إرسال تعليقات":

"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

اسم البطاقة يُستخدَم كمعرّف بطاقة في التنقّل في البطاقات.

يتجاهل المستخدمون هذا الحقل لأنّ تطبيقات Chat لا تتيح التنقّل في البطاقة.

displayStyle

enum ( DisplayStyle )

في إضافات Google Workspace، يتم ضبط خصائص العرض peekCardHeader .

غير متاحة من خلال تطبيقات Chat

peekCardHeader

object ( CardHeader )

عند عرض محتوى سياقي، يعمل عنوان بطاقة النظرة السريعة كعنصر نائب حتى يتمكّن المستخدم من الانتقال بين بطاقات الصفحة الرئيسية وبطاقات السياق.

غير متاحة من خلال تطبيقات Chat

عنوان البطاقة

يمثل عنوان البطاقة.

تمثيل JSON
{
  "title": string,
  "subtitle": string,
  "imageType": enum (ImageType),
  "imageUrl": string,
  "imageAltText": string
}
الحقول
title

string

مطلوبة. عنوان رأس البطاقة. ارتفاع العنوان الثابت: إذا تم تحديد كل من العنوان والعنوان الفرعي، سيحصل كل منهما على سطر واحد. إذا تم تحديد العنوان فقط، سيشغل كلا السطرين.

subtitle

string

العنوان الفرعي لرأس البطاقة. وإذا تم تحديد هذه العلامة، ستظهر في السطر الخاص بها أسفل title .

imageType

enum ( ImageType )

الشكل المستخدم لاقتصاص الصورة.

imageUrl

string

عنوان URL الذي يستخدم HTTPS للصورة في عنوان البطاقة.

imageAltText

string

النص البديل لهذه الصورة الذي يُستخدم لتسهيل الاستخدام.

نوع الصورة

الشكل المستخدم لاقتصاص الصورة.

عمليات التعداد
SQUARE القيمة التلقائية لإضافة قناع مربّع إلى الصورة على سبيل المثال، يصبح حجم الصورة 4 × 3 3 × 3.
CIRCLE لإضافة قناع دائري إلى الصورة. على سبيل المثال، تصبح صورة 4 × 3 دائرة قطرها 3.

القسم

يحتوي القسم على مجموعة من الأدوات التي يتم عرضها عموديًا بالترتيب الذي تم تحديدها به.

تمثيل JSON
{
  "header": string,
  "widgets": [
    {
      object (Widget)
    }
  ],
  "collapsible": boolean,
  "uncollapsibleWidgetsCount": integer
}
الحقول
header

string

النص الذي يظهر في أعلى القسم. متوافق مع النص البسيط بتنسيق HTML .

widgets[]

object ( Widget )

كل الأدوات في هذا القسم. يجب أن يحتوي على أداة واحدة على الأقل.

collapsible

boolean

تشير هذه السمة إلى ما إذا كان هذا القسم قابلاً للتصغير.

تخفي الأقسام القابلة للطي بعض الأدوات أو جميعها، ولكن يمكن للمستخدمين توسيع القسم للكشف عن الأدوات المصغّرة من خلال النقر على عرض المزيد . ويمكن للمستخدمين إخفاء الأدوات مرة أخرى من خلال النقر على عرض أقل .

لتحديد الأدوات المخفية، حدِّد uncollapsibleWidgetsCount .

uncollapsibleWidgetsCount

integer

عدد الأدوات القابلة للتصغير التي تظل مرئية حتى عند تصغير قسم.

على سبيل المثال، عندما يحتوي قسم على خمس أدوات وتم ضبط uncollapsibleWidgetsCount على 2 ، يتم دائمًا عرض أول أداتَين ويتم تصغير الأدوات الثلاث تلقائيًا. تتم مراعاة uncollapsibleWidgetsCount فقط عندما يكون collapsible true .

أداة

وتتألف كل بطاقة من التطبيقات المصغّرة.

الأداة هي كائن مُركّب يمكن أن يمثل نصًا وصورًا وأزرارًا وأنواعًا أخرى من العناصر.

تمثيل 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)
  },
  "divider": {
    object (Divider)
  },
  "grid": {
    object (Grid)
  }
  // End of list of possible types for union field data.
}
الحقول
حقل الاتحاد data . يمكن أن تحتوي الأداة على عنصر واحد فقط من العناصر التالية. يمكنك استخدام حقول أدوات متعددة لعرض المزيد من العناصر. data يمكن أن تكون واحدة مما يلي:
textParagraph

object ( TextParagraph )

يعرض فقرة نصية. متوافق مع النص البسيط بتنسيق HTML .

على سبيل المثال، ينشئ JSON التالي نصًا غامقًا:

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

object ( Image )

تعرِض صورة.

على سبيل المثال، ينشئ JSON التالي صورة بنص بديل:

"image": {
  "imageUrl":
  "https://developers.google.com/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!",
  "switchWidget": {
    "name": "has_send_welcome_email_to_sasha",
    "selected": false,
    "controlType": "ControlType.CHECKBOX"
  }
}
buttonList

object ( ButtonList )

قائمة بالأزرار.

على سبيل المثال، ينشئ JSON التالي زرين. الأول هو زر نص أزرق، والزر الثاني هو زر صورة يفتح رابطًا:

"buttonList": {
  "buttons": [
    "button": {
      "text": "Edit",
      "color": {
        "red": 0,
        "green": 0,
        "blue": 1,
        "alpha": 1
       }
      "disabled": true
    },
    "button": {
      "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": "SelectionType.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 )

تعرِض أداة اختيار/إدخال للتاريخ أو الوقت أو التاريخ والوقت.

غير متاحة من خلال تطبيقات Chat سيتم توفير الدعم من خلال تطبيقات Chat قريبًا.

على سبيل المثال، ينشئ JSON التالي أداة اختيار التاريخ والوقت لجدولة موعد:

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

object ( Divider )

تعرِض أداة تقسيم الخط الأفقي بين الأدوات.

على سبيل المثال، ينشئ JSON التالي أداة تقسيم:

"divider": {
}
grid

object ( Grid )

يتم عرض شبكة تضم مجموعة من العناصر.

تدعم الشبكة أي عدد من الأعمدة والعناصر. ويتم تحديد عدد الصفوف من خلال الحدود العليا لعناصر الرقم مقسومًا على عدد الأعمدة. شبكة تحتوي على 10 عناصر وعمودين بها 5 صفوف. تحتوي الشبكة التي تتضمّن 11 عنصرًا وعمودين على 6 صفوف.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

على سبيل المثال، ينشئ JSON التالي شبكة من عمودين مع عنصر واحد:

"grid": {
  "title": "A fine collection of items",
  "numColumns": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4.0
  },
  "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
{
  "text": string
}
الحقول
text

string

النص الذي يظهر في الأداة

صورة

صورة يتم تحديدها من خلال عنوان URL ويمكن أن تحتوي على إجراء onClick .

تمثيل JSON
{
  "imageUrl": string,
  "onClick": {
    object (OnClick)
  },
  "altText": string
}
الحقول
imageUrl

string

تمثّل هذه السمة عنوان URL الذي يستضيف الصورة. https

مثلاً:

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

object ( OnClick )

عندما ينقر المستخدم على الصورة، يؤدي النقر على هذا الإجراء إلى تشغيلها.

altText

string

النص البديل لهذه الصورة، ويُستخدم لتسهيل الاستخدام.

OnOn

يمثل كيفية الاستجابة عندما ينقر المستخدمون على عنصر تفاعلي على بطاقة، مثل زر.

تمثيل JSON
{

  // Union field data can be only one of the following:
  "action": {
    object (Action)
  },
  "openLink": {
    object (OpenLink)
  },
  "openDynamicLinkAction": {
    object (Action)
  },
  "card": {
    object (Card)
  }
  // End of list of possible types for union field data.
}
الحقول

حقل الاتحاد data .

data يمكن أن تكون واحدة مما يلي:

action

object ( Action )

وفي حال تحديد ذلك، يتم تشغيل إجراء من خلال onClick .

card

object ( Card )

يتم إرسال بطاقة جديدة إلى حزمة البطاقات بعد النقر عليها إذا كانت محددة.

متوافقة مع إضافات Google Workspace، ولكنها غير متوافقة مع تطبيقات Chat.

الإجراء

إجراء يصف السلوك عند إرسال النموذج. على سبيل المثال، يمكن استدعاء "برمجة التطبيقات" للتعامل مع النموذج.

تمثيل JSON
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction)
}
الحقول
function

string

دالة مخصّصة لاستدعاء عند النقر على العنصر الذي يحتوي عليها أو تفعيلها بطريقة أخرى.

على سبيل المثال، يمكنك الاطّلاع على إنشاء بطاقات تفاعلية .

parameters[]

object ( ActionParameter )

قائمة معلّمات الإجراءات

loadIndicator

enum ( LoadIndicator )

تحدِّد هذه العلامة مؤشر التحميل الذي يُظهِر الإجراء أثناء إجراء عبارة الحث على اتخاذ إجراء.

persistValues

boolean

تشير هذه الخاصية إلى ما إذا كانت قيم النموذج تستمر بعد الإجراء. القيمة التلقائية هي false .

إذا true ، ستظل قيم النموذج بعد تشغيل الإجراء. عند استخدام LoadIndicator.NONE للإجراءات، ننصح باستخدام السمة persistValues = true لأنها تضمن عدم إرسال أي تغييرات يجريها المستخدم بعد النموذج أو على إجراءات التغيير إلى الخادم.

إذا false ، يتم محو قيم النموذج عند تنفيذ الإجراء. عند ضبط persistValues على false ، ننصح بشدة باستخدام البطاقة LoadIndicator.SPINNER لجميع الإجراءات، لأنّ ذلك يؤدي إلى قفل واجهة المستخدم لضمان عدم إجراء أي تغييرات من قِبل المستخدم أثناء معالجة الإجراء.

غير متاحة من خلال تطبيقات Chat

interaction

enum ( Interaction )

اختيارية: مطلوبة عند فتح مربّع حوار .

الإجراءات التي يجب اتخاذها استجابةً لتفاعل مع مستخدم، مثل نقر المستخدم على زر في رسالة بطاقة.

إذا لم يكن محدّدًا، يستجيب التطبيق عن طريق تنفيذ action ، مثل فتح رابط أو تشغيل دالة، كالمعتاد.

من خلال تحديد interaction ، يمكن للتطبيق الاستجابة بطرق تفاعلية خاصة. على سبيل المثال، من خلال ضبط interaction على OPEN_DIALOG ، يمكن للتطبيق فتح مربّع حوار .

عند تحديد ذلك، لا يتم عرض مؤشر التحميل.

متاحة من خلال تطبيقات Chat، ولكنها غير متوافقة مع إضافات Google Workspace. إذا تم تحديد إضافة، يتم نزع البطاقة بالكامل ولا يتم عرض أي شيء في البرنامج.

معلَمة الإجراء

قائمة معلَمات السلسلة المطلوب تقديمها عند استدعاء طريقة الإجراء. على سبيل المثال، جرِّب ثلاثة أزرار تأجيل: تأجيل الآن، وتأجيل لمدة يوم واحد، وتأجيل الأسبوع القادم. ويمكنك استخدام طريقة الإجراء = تأجيل()، مع تمرير نوع التأجيل ووقت التأجيل في قائمة معلّمات السلسلة.

لمزيد من المعلومات، راجِع CommonEventObject .

تمثيل JSON
{
  "key": string,
  "value": string
}
الحقول
key

string

اسم المعلّمة للنص البرمجي للإجراء.

value

string

قيمة المَعلمة.

مؤشر التحميل

تحدِّد هذه العلامة مؤشر التحميل الذي يُظهِر الإجراء أثناء إجراء عبارة الحث على اتخاذ إجراء.

عمليات التعداد
SPINNER عرض مؤشر سريان يشير إلى أنه يتم تحميل المحتوى.
NONE لا يتم عرض أي شيء.

تفاعل

اختيارية: مطلوبة عند فتح مربّع حوار .

الإجراءات التي يجب اتخاذها استجابةً لتفاعل مع مستخدم، مثل نقر المستخدم على زر في رسالة بطاقة.

إذا لم يكن محدّدًا، يستجيب التطبيق عن طريق تنفيذ action ، مثل فتح رابط أو تشغيل دالة، كالمعتاد.

من خلال تحديد interaction ، يمكن للتطبيق الاستجابة بطرق تفاعلية خاصة. على سبيل المثال، من خلال ضبط interaction على OPEN_DIALOG ، يمكن للتطبيق فتح مربّع حوار .

عند تحديد ذلك، لا يتم عرض مؤشر التحميل.

متاحة من خلال تطبيقات Chat، ولكنها غير متوافقة مع إضافات Google Workspace. إذا تم تحديد إضافة، يتم نزع البطاقة بالكامل ولا يتم عرض أي شيء في البرنامج.

عمليات التعداد
INTERACTION_UNSPECIFIED القيمة التلقائية يتم تنفيذ action كالمعتاد.
OPEN_DIALOG

يؤدي هذا الإعداد إلى فتح مربّع حوار . عبارة عن واجهة مستند إلى بطاقات مستندة إلى البطاقة تستخدمها تطبيقات Chat للتفاعل مع المستخدمين.

لا تتوفّر هذه الميزة إلا في تطبيقات Chat استجابةً للنقرات على الأزرار في رسائل البطاقة.

غير متوافقة مع إضافات Google Workspace. إذا تم تحديد إضافة، يتم نزع البطاقة بالكامل ولا يتم عرض أي شيء في البرنامج.

OpenAs

عندما يفتح OnClick رابطًا، يمكن للعميل فتحه كنافذة بالحجم الكامل (إذا كان هذا هو الإطار الذي يستخدمه العميل)، أو يمكن أن يظهر على سطح الصفحة (مثل النافذة المنبثقة). يعتمد التنفيذ على إمكانات النظام الأساسي للعميل، وقد يتم تجاهل القيمة المحدّدة إذا لم يكن العميل متوافقًا. FULL_SIZE متوافق مع جميع البرامج.

متوافقة مع إضافات Google Workspace، ولكنها غير متوافقة مع تطبيقات Chat.

عمليات التعداد
FULL_SIZE يتم فتح الرابط كنافذة بالحجم الكامل (إذا كان هذا هو الإطار الذي يستخدمه العميل).
OVERLAY يفتح الرابط في شكل تراكب، مثل نافذة منبثقة.

عند الإغلاق

الإجراءات التي يتّخذها العميل عند إغلاق رابط الإجراء OnClick

يعتمد التنفيذ على إمكانات النظام الأساسي للعميل. على سبيل المثال، قد يفتح متصفّح الويب رابطًا في نافذة منبثقة من خلال معالج OnClose .

إذا تم ضبط كل من المعالجات OnOpen و OnClose ، ولم يتمكّن النظام الأساسي للعميل من دعم كلتا القيمتَين، ستُمنح OnClose الأولوية.

متوافقة مع إضافات Google Workspace، ولكنها غير متوافقة مع تطبيقات Chat.

عمليات التعداد
NOTHING القيمة التلقائية لا تتم إعادة تحميل البطاقة، ولا يحدث أي شيء.
RELOAD

لإعادة تحميل البطاقة بعد إغلاق النافذة الفرعية

إذا تم استخدامها مع OpenAs.OVERLAY ، تعمل النافذة الفرعية كمربّع حوار مشروط ويتم حظر البطاقة الرئيسية إلى أن يتم إغلاق النافذة الفرعية.

نص مزخرف

أداة تعرض نصًا مزخرفًا، مثل تصنيف أعلى النص أو أسفله، أو رمز أمام النص، أو أداة اختيار أو زر بعد النص.

تمثيل 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

مطلوبة. النص الأساسي.

إتاحة تنسيق بسيط يمكنك الاطّلاع على تنسيق النص لمعرفة تفاصيل التنسيق.

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 )

رمز يتم عرضه بعد النص.

متوافق مع الرموز العادية و الرموز المخصصة.

الرمز

رمز يظهر في أداة على بطاقة.

متوافق مع الرموز العادية و الرموز المخصصة.

تمثيل JSON
{
  "altText": string,
  "imageType": enum (ImageType),

  // Union field icons can be only one of the following:
  "knownIcon": string,
  "iconUrl": string
  // End of list of possible types for union field icons.
}
الحقول
altText

string

اختيارية: وصف للرمز المستخدم لتسهيل الاستخدام. إذا لم يتم تحديدها، يتم تقديم قيمة تلقائية. وفقًا لأفضل الممارسات، يجب إعداد وصف مفيد. على سبيل المثال، إذا كان الرمز يعرض صورة حساب المستخدم، يمكنك وصفها على أنها "صورة حساب المستخدم".

إذا كان الرمز معروضًا في Button ، تكون الأولوية للنص البديل هذا ويحل محل النص البديل للزر، لذا عليك كتابة نص بديل للزر: اضبط النص الوصفي الذي يسمح للمستخدمين بمعرفة ما يفعله الزر. على سبيل المثال، إذا فتح زر رابطًا تشعّبيًا، يمكنك كتابة: "يفتح علامة تبويب جديدة في المتصفّح وينتقل إلى مستندات مطوّري برامج Google Chat على https://developers.google.com/chat" .

imageType

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

زرّ

نص أو رمز أو زر نصي + رمز يمكن للمستخدمين النقر عليه.

لجعل الصورة زرًا قابلاً للنقر، حدِّد السمة Image (وليس ImageComponent ) واضبط الإجراء onClick .

تمثيل JSON
{
  "text": string,
  "icon": {
    object (Icon)
  },
  "color": {
    object (Color)
  },
  "onClick": {
    object (OnClick)
  },
  "disabled": boolean,
  "altText": string
}
الحقول
text

string

النص المعروض داخل الزر.

icon

object ( Icon )

صورة الرمز إذا تم ضبط كل من icon و text ، سيظهر الرمز بدلاً من النص.

وستتوفر قريبًا لكلٍّ من الرمز والنص.

color

object ( Color )

عند ضبط هذا الإعداد، يكون الزر ممتلئًا بلون خلفية خالص، ويتغير لون الخط للحفاظ على التباين مع لون الخلفية. على سبيل المثال، من المحتمل أن يؤدي ضبط خلفية زرقاء إلى استخدام نص أبيض.

في حال ترك السياسة بدون ضبط، تكون خلفية الصورة باللون الأبيض ولون الخط أزرق.

بالنسبة إلى الأحمر والأخضر والأزرق، تكون قيمة كل حقل رقمًا في float يمكن التعبير عنه بأي من الطريقتين: رقم يتراوح بين 0 و255 مقسومًا على 255 (153/255) أو كقيمة بين 0 و1 (0.6). ويمثل 0 عدم وجود لون ويشير 1 أو 255/255 إلى وجود هذا اللون بشكل كامل على مقياس RGB.

يمكنك ضبط ألفا بشكل اختياري، الذي يضبط مستوى من الشفافية باستخدام المعادلة التالية:

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

بالنسبة إلى ألفا، تتطابق القيمة 1 مع لون خالص، وتتطابق القيمة 0 مع لون شفاف بالكامل.

على سبيل المثال، يمثّل اللون التالي نصف أحمر شفاف:

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

object ( OnClick )

الإجراء الذي سيتم تنفيذه عند النقر على الزر، مثل فتح رابط تشعّبي أو تشغيل دالة مخصّصة.

disabled

boolean

إذا true ، يتم عرض الزر في حالة غير نشطة ولا يستجيب لإجراءات المستخدمين.

altText

string

النص البديل المُستخدَم لتسهيل الاستخدام.

يمكنك ضبط نص وصفي يسمح للمستخدمين بمعرفة ما يفعله الزر. على سبيل المثال، إذا فتح زر رابطًا تشعّبيًا، يمكنك كتابة: "يفتح علامة تبويب جديدة في المتصفّح وينتقل إلى مستندات مطوّري برامج Google Chat على https://developers.google.com/chat" .

ليس له أي تأثير عند ضبط رمز، لذا استخدِم icon.alt_text بدلاً من ذلك.

اللون

ويمثل لونًا في مساحة لون RGBA. تم تصميم هذا التمثيل البصري ببساطة لتبسيط الإحالة الناجحة من/إلى تمثيلات اللغات بلغات مختلفة على الحجم الصغير. على سبيل المثال، يمكن تقديم حقول هذا التمثيل بشكل مبسّط إلى منشئ java.awt.Color في Java، ويمكن أيضًا توفيره بشكل بسيط لأسلوب واجهة المستخدم في Usercolor في iOS

لا تتضمّن هذه الصفحة المرجعية معلومات عن مساحة اللون المطلقة التي يجب استخدامها لتفسير قيمة RGB (مثل sRGB وAdobe RGB وDCI-P3 وBT.2020 وما إلى ذلك). بشكل تلقائي، من المفترض أن تفترض التطبيقات مساحة لون sRGB.

عند تحديد المساواة في اللون، يجب التعامل مع عمليات التنفيذ بلونَين متساويَين إذا كانت كل قيمهما باللون الأحمر والأخضر والأزرق والألفي مختلفة، ما لم يتم توثيق ذلك خلاف ذلك.

مثال (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 مع لون شفاف بالكامل. يستخدم هذا رسالة برنامج تضمين بدلاً من حجم رقمي عائم بسيط بحيث يمكن التمييز بين القيمة التلقائية والقيمة بدون ضبط. وفي حال الإسقاط، يتم عرض كائن اللون هذا باعتباره لونًا خالصًا (كما لو تم منح قيمة ألفا بشكل صريح قيمة 1.0).

عنصر تحكم التبديل

إما مفتاح تبديل على شكل مفتاح تحكّم أو مربّع اختيار داخل أداة decoratedText .

هذه الأداة متاحة فقط على أداة 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 )

كيفية ظهور مفتاح التبديل في واجهة المستخدم

نوع التحكم

كيفية ظهور مفتاح التبديل في واجهة المستخدم

عمليات التعداد
SWITCH مفتاح تبديل بأسلوب التبديل
CHECKBOX تم إيقاف العمل به لصالح CHECK_BOX .
CHECK_BOX مربّع اختيار.

قائمة الأزرار

تم عرض قائمة بالأزرار أفقيًا.

تمثيل JSON
{
  "buttons": [
    {
      object (Button)
    }
  ]
}
الحقول
buttons[]

object ( Button )

مجموعة من الأزرار.

إدخال النص

حقل يمكن للمستخدمين إدخال نص فيه. إتاحة الاقتراحات والإجراءات عند التغيير

تتلقّى تطبيقات Chat قيمة النص الذي تم إدخاله أثناء أحداث إدخال النموذج وتعالجها. للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

عندما تحتاج إلى جمع بيانات نظرية من المستخدمين، استخدِم إدخالاً نصيًا. ولجمع بيانات محددة من المستخدمين، استخدم أداة إدخال الاختيار بدلاً من ذلك.

لا يمكن استخدام هذه السمة إلا في مربّعات الحوار . سيتم توفير الرسائل الخاصة بالبطاقة قريبًا.

تمثيل JSON
{
  "name": string,
  "label": string,
  "hintText": string,
  "value": string,
  "type": enum (Type),
  "onChangeAction": {
    object (Action)
  },
  "initialSuggestions": {
    object (Suggestions)
  },
  "autoCompleteAction": {
    object (Action)
  }
}
الحقول
name

string

الاسم الذي يتم من خلاله تحديد إدخال النص في حدث إدخال النموذج.

للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

label

string

النص الذي يظهر أعلى حقل إدخال النص في واجهة المستخدم.

حدِّد النص الذي يساعد المستخدم في إدخال المعلومات التي يحتاج إليها تطبيقك. على سبيل المثال، إذا كنت تطلب اسم أحد الأشخاص، ولكنك تحتاج إلى اسم العائلة على وجه التحديد، اكتب "اسم العائلة" بدلاً من "الاسم".

مطلوبة إذا لم يتم تحديد 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" والبعض الآخر على "نص JavaScript". يمكن أن يؤدي اقتراح "JavaScript" إلى توحيد طريقة تفاعل المستخدمين مع تطبيقك.

وعندما يتم تحديدها، تكون قيمة TextInput.type دائمًا SINGLE_LINE ، حتى في حال ضبطها على MULTIPLE_LINE .

autoCompleteAction

object ( Action )

اختيارية: حدد الإجراء الذي يجب اتخاذه عندما يقدم حقل إدخال النص اقتراحات للمستخدمين الذين يتفاعلون معه.

إذا لم يتم تحديد هذه القيمة، يتم ضبط الاقتراحات من قِبل initialSuggestions ويعالجها العميل.

وفي حال تحديد ذلك، يتخذ التطبيق الإجراء المحدّد هنا، مثل تشغيل دالة مخصّصة.

متوافقة مع إضافات Google Workspace، ولكنها غير متوافقة مع تطبيقات Chat. وستتوفّر الدعم قريبًا من خلال تطبيقات Chat.

النوع

طريقة ظهور حقل إدخال النص في واجهة المستخدم. على سبيل المثال، يمكنك إدخال سطر واحد أو إدخال متعدد الأسطر.

إذا تم تحديد initialSuggestions ، ستكون قيمة type دائمًا SINGLE_LINE ، حتى إذا تم ضبطها على MULTIPLE_LINE .

عمليات التعداد
SINGLE_LINE ارتفاع حقل واحد لإدخال حقل النص الثابت.
MULTIPLE_LINE يحتوي حقل إدخال النص على ارتفاع ثابت لعدة أسطر.

الاقتراحات

القيم المقترَحة التي يمكن للمستخدمين إدخالها تظهر هذه القيم عندما ينقر المستخدمون داخل حقل إدخال النص. أثناء كتابة المستخدمين، تتم فلترة القيم المقترَحة ديناميكيًا لمطابقة ما كتبه المستخدمون.

على سبيل المثال، قد يقترح حقل إدخال نص للغة البرمجة Java وJavaScript وPython وC++. وعند بدء المستخدمين في كتابة "Jav"، تظهر قائمة باقتراحات الاقتراحات لعرض Java وJavaScript فقط.

تساعد القيم المقترحة على توجيه المستخدمين إلى إدخال قيم يمكن لتطبيقك الاستفادة منها. عند الإشارة إلى JavaScript، قد يُدخِل بعض المستخدمين "JavaScript" والبعض الآخر على "نص JavaScript". يمكن أن يؤدي اقتراح "JavaScript" إلى توحيد طريقة تفاعل المستخدمين مع تطبيقك.

وعندما يتم تحديدها، تكون قيمة TextInput.type دائمًا SINGLE_LINE ، حتى في حال ضبطها على MULTIPLE_LINE .

تمثيل JSON
{
  "items": [
    {
      object (SuggestionItem)
    }
  ]
}
الحقول
items[]

object ( SuggestionItem )

قائمة اقتراحات مستخدَمة في اقتراحات الإكمال التلقائي في حقول إدخال النص

عنصر الاقتراح

قيمة واحدة مقترحة يمكن للمستخدمين إدخالها في حقل إدخال النص.

تمثيل JSON
{
  "text": string
}
الحقول
text

string

قيمة الإدخال المُقترَح في حقل إدخال النص. وهذا يعادل ما قد يُدخله المستخدمون بأنفسهم.

الإدخال المحدد

أداة تنشئ عنصر واجهة مستخدم بخيارات ليختارها المستخدمون. على سبيل المثال، قائمة منسدلة أو قائمة التحقق.

تتلقّى تطبيقات Chat قيمة النص الذي تم إدخاله أثناء أحداث إدخال النموذج وتعالجها. للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

عندما تحتاج إلى جمع بيانات من المستخدمين الذين يتطابقون مع الخيارات التي تحدّدها، استخدم إدخال اختيار. لجمع بيانات تجريدية من المستخدمين، يمكنك استخدام أداة إدخال النص بدلاً من ذلك.

لا يمكن استخدام هذه السمة إلا في مربّعات الحوار . سيتم توفير الرسائل الخاصة بالبطاقة قريبًا.

تمثيل JSON
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  }
}
الحقول
name

string

الاسم الذي يتم من خلاله تحديد إدخال الإدخال في حدث إدخال النموذج.

للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

label

string

النص الذي يظهر أعلى حقل إدخال التحديد في واجهة المستخدم.

حدِّد النص الذي يساعد المستخدم في إدخال المعلومات التي يحتاج إليها تطبيقك. على سبيل المثال، إذا كان المستخدمون يحدّدون بشكل عاجل تذكرة عمل من القائمة المنسدلة، قد يكون التصنيف "عاجلة" أو "اختيار عاجلة".

type

enum ( SelectionType )

طريقة ظهور الخيار للمستخدمين. تسمح الخيارات المختلفة بأنواع مختلفة من التفاعلات. على سبيل المثال، يمكن للمستخدمين تفعيل مربعات اختيار متعددة، ولكن يمكنهم اختيار قيمة واحدة فقط من القائمة المنسدلة.

يدعم كل إدخال اختيار نوعًا واحدًا من الاختيارات. على سبيل المثال، لا يمكن مزج مربعات الاختيار ومفاتيح التحكّم.

items[]

object ( SelectionItem )

مصفوفة من العناصر المحددة. على سبيل المثال، جميع مربّعات الاختيار التي تم اختيارها.

onChangeAction

object ( Action )

وإذا تم تحديد النموذج، يتم إرساله عند تغيير الاختيار. وإذا لم يتم تحديدها، عليك تحديد زر منفصل لإرسال النموذج.

للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

نوع التحديد

طريقة ظهور الخيار للمستخدمين. تسمح الخيارات المختلفة بأنواع مختلفة من التفاعلات. على سبيل المثال، يمكن للمستخدمين تفعيل مربعات اختيار متعددة، ولكن يمكنهم اختيار قيمة واحدة فقط من القائمة المنسدلة.

يدعم كل إدخال اختيار نوعًا واحدًا من الاختيارات. على سبيل المثال، لا يمكن مزج مربعات الاختيار ومفاتيح التحكّم.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

عمليات التعداد
CHECK_BOX

مجموعة من مربعات الاختيار. يمكن للمستخدمين اختيار مربّعات اختيار متعددة لكل إدخال تم اختياره.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

RADIO_BUTTON

مجموعة من أزرار الاختيار. يمكن للمستخدمين اختيار زر اختيار واحد لكل إدخال يتم اختياره.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

SWITCH

مجموعة من مفاتيح التحكّم يمكن للمستخدمين تفعيل عدة مفاتيح تحكّم في آنٍ واحد لكل إدخال اختيار.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

DROPDOWN

قائمة منسدلة. يمكن للمستخدمين اختيار عنصر قائمة منسدلة واحد لكل إدخال اختيار.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

عنصر التحديد

تمثّل هذه السمة عنصرًا قابلاً للاختيار في إدخال اختيار، مثل مربّع اختيار أو مفتاح تحكّم.

تمثيل JSON
{
  "text": string,
  "value": string,
  "selected": boolean
}
الحقول
text

string

النص المعروض للمستخدمين.

value

string

القيمة المرتبطة بهذا العنصر. يجب أن يستخدم العميل هذه القيمة كقيمة إدخال النموذج.

للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

selected

boolean

عند true ، يتم اختيار أكثر من عنصر واحد. في حال اختيار أكثر من عنصر واحد لأزرار الاختيار والقوائم المنسدلة، سيتم تلقّي أول عنصر محدَّد وتجاهل العناصر التالية.

منتقي الوقت

يتيح للمستخدمين تحديد تاريخ أو وقت أو كليهما تاريخ ووقت.

يقبل الإدخال النصي من المستخدمين، ولكنه يحتوي على أداة اختيار التاريخ والوقت التفاعلية التي تساعد المستخدمين على إدخال التواريخ والأوقات بالتنسيق الصحيح. وإذا أدخل المستخدمون تاريخًا أو وقتًا غير صحيح، ستعرض الأداة خطأ يطلب من المستخدمين إدخال التنسيق الصحيح.

غير متاحة من خلال تطبيقات Chat وستتوفّر الدعم قريبًا من خلال تطبيقات Chat.

تمثيل JSON
{
  "name": string,
  "label": string,
  "type": enum (DateTimePickerType),
  "valueMsEpoch": string,
  "timezoneOffsetDate": integer,
  "onChangeAction": {
    object (Action)
  }
}
الحقول
name

string

الاسم الذي يتم من خلاله تحديد منتقي التاريخ والوقت في حدث إدخال النموذج.

للحصول على تفاصيل عن التعامل مع إدخالات النموذج، راجِع تلقّي بيانات النموذج. .

label

string

النص الذي يطلب من المستخدمين إدخال تاريخ أو وقت أو تاريخ.

حدِّد النص الذي يساعد المستخدم في إدخال المعلومات التي يحتاج إليها تطبيقك. على سبيل المثال، إذا كان المستخدمون يحدّدون موعدًا، قد يعمل تصنيف مثل "تاريخ الموعد" أو "تاريخ الموعد ووقته".

type

enum ( DateTimePickerType )

نوع التاريخ والوقت الذي يدعمه منتقي التاريخ والوقت.

valueMsEpoch

string ( int64 format)

القيمة المعروضة على أنها القيمة التلقائية قبل إدخال المستخدم أو الإدخال السابق للمستخدم، ويتم تمثيلها بالملي ثانية ( وقت الحقبة ).

بالنسبة إلى النوع DATE_AND_TIME ، يتم استخدام قيمة الحقبة الكاملة.

بالنسبة إلى النوع DATE_ONLY ، يتم استخدام تاريخ وقت الحقبة فقط.

بالنسبة إلى النوع TIME_ONLY ، يتم استخدام وقت الوقت فقط. على سبيل المثال، لتمثيل الساعة 3:00 صباحًا، اضبط وقت الحقبة على 3 * 60 * 60 * 1000 .

timezoneOffsetDate

integer

الرقم الذي يشير إلى معادلة المنطقة الزمنية من UTC. في حال ضبط هذه السياسة، يتم عرض valueMsEpoch حسب المنطقة الزمنية المحدّدة. وفي حال ترك هذه السياسة بدون ضبط، يتم استخدام إعداد المنطقة الزمنية للمستخدم من جهة العميل.

onChangeAction

object ( Action )

يتم تشغيله عندما ينقر المستخدم على حفظ أو محو من واجهة أداة اختيار التاريخ.

نوع أداة اختيار التاريخ

نوع التاريخ والوقت الذي يدعمه منتقي التاريخ والوقت.

عمليات التعداد
DATE_AND_TIME ويمكن للمستخدم اختيار تاريخ ووقت.
DATE_ONLY ويمكن للمستخدم اختيار تاريخ فقط.
TIME_ONLY ويمكن للمستخدم اختيار وقت واحد فقط.

أداة تقسيم الشاشة

يعرض هذا الإعداد تقسيمًا بين الأدوات، وهو خط أفقي.

على سبيل المثال، ينشئ JSON التالي أداة تقسيم:

"divider": {
}

معرّف الإصدار العالمي (GRid)

يتم عرض شبكة تضم مجموعة من العناصر.

تدعم الشبكة أي عدد من الأعمدة والعناصر. ويتم تحديد عدد الصفوف حسب العناصر مقسومة على الأعمدة. شبكة تحتوي على 10 عناصر وعمودين بها 5 صفوف. تحتوي الشبكة التي تتضمّن 11 عنصرًا وعمودين على 6 صفوف.

متاح حاليًا في مربّعات الحوار . وستتوفّر قريبًا إمكانية استلام رسائل البطاقة.

على سبيل المثال، ينشئ JSON التالي شبكة من عمودين مع عنصر واحد:

"grid": {
  "title": "A fine collection of items",
  "numColumns": 2,
  "borderStyle": {
    "type": "STROKE",
    "cornerRadius": 4.0
  },
  "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 )

يُعيد كل من عناصر الشبكة الفردية استخدام معاودة الاتصال هذه، ولكن مع معرّف السلعة وفهرسها في قائمة العناصر المضافة إلى معلمات معاودة الاتصال.

عنصر في الشبكة

تمثّل هذه السمة عنصرًا واحدًا في تنسيق الشبكة.

تمثيل JSON
{
  "id": string,
  "image": {
    object (ImageComponent)
  },
  "title": string,
  "subtitle": string,
  "layout": enum (GridItemLayout)
}
الحقول
id

string

معرّف يحدّده المستخدم لعنصر الشبكة هذا. ويتم عرض هذا المعرّف في معلّمات استدعاء onClick الرئيسية في الشبكة.

image

object ( ImageComponent )

الصورة التي يتم عرضها في عنصر الشبكة.

title

string

عنوان العنصر على الشبكة.

subtitle

string

العنوان الفرعي لعنصر الشبكة.

layout

enum ( GridItemLayout )

التنسيق المطلوب استخدامه للعنصر في الشبكة.

مكوّن الصورة

ويمثل صورة.

تمثيل JSON
{
  "imageUri": string,
  "altText": string,
  "cropStyle": {
    object (ImageCropStyle)
  },
  "borderStyle": {
    object (BorderStyle)
  }
}
الحقول
imageUri

string

عنوان URL للصورة.

altText

string

تصنيف تسهيل الاستخدام للصورة.

cropStyle

object ( ImageCropStyle )

نمط الاقتصاص المراد تطبيقه على الصورة.

borderStyle

object ( BorderStyle )

نمط الحد المراد تطبيقه على الصورة.

نمط الصورة

ويمثل نمط الاقتصاص الذي تم تطبيقه على الصورة.

على سبيل المثال، في ما يلي كيفية تطبيق نسبة عرض إلى ارتفاع تبلغ 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
}

نوع CCropType

ويمثل نمط الاقتصاص الذي تم تطبيقه على الصورة.

عمليات التعداد
IMAGE_CROP_TYPE_UNSPECIFIED لم يتم تحديد أي قيمة. لا يُستخدم.
SQUARE القيمة التلقائية ينطبق اقتصاص مربّع.
CIRCLE يتم تطبيق الاقتصاص الدائري.
RECTANGLE_CUSTOM طبِّق اقتصاصًا مستطيلًا بنسبة عرض إلى ارتفاع مخصّصة. اضبط نسبة العرض إلى الارتفاع المخصّصة باستخدام aspectRatio .
RECTANGLE_4_3 يتم تطبيق اقتصاص مستطيل بنسبة عرض إلى ارتفاع 4:3.

نمط الحد

ويمثل نمط الحد الكامل المطبّق على العناصر في الأداة.

تمثيل JSON
{
  "type": enum (BorderType),
  "strokeColor": {
    object (Color)
  },
  "cornerRadius": integer
}
الحقول
type

enum ( BorderType )

نوع الحد.

strokeColor

object ( Color )

الألوان التي يمكن استخدامها عندما يكون النوع BORDER_TYPE_STROKE

cornerRadius

integer

نطاق الزاوية للحدود.

نوع الحد

ويمثل أنواع الحدود المطبَّقة على الأدوات.

عمليات التعداد
BORDER_TYPE_UNSPECIFIED لم يتم تحديد أي قيمة.
NO_BORDER القيمة التلقائية بلا حدود.
STROKE مخطط.

تخطيط الشبكة

تمثّل هذه السمة خيارات التنسيق المختلفة المتاحة لعنصر شبكة.

عمليات التعداد
GRID_ITEM_LAYOUT_UNSPECIFIED لم يتم تحديد أي تخطيط.
TEXT_BELOW يظهر العنوان والترجمة أسفل صورة العنصر على شكل شبكة.
TEXT_ABOVE يظهر العنوان والترجمة فوق صورة الشبكة.

إجراء بشأن البطاقة

إجراء البطاقة هو الإجراء المرتبط بالبطاقة. على سبيل المثال، قد تتضمّن بطاقة الفاتورة إجراءات مثل حذف الفاتورة أو فاتورة منها أو فتح الفاتورة في متصفّح.

غير متاحة من خلال تطبيقات Chat

تمثيل JSON
{
  "actionLabel": string,
  "onClick": {
    object (OnClick)
  }
}
الحقول
actionLabel

string

التصنيف الذي يتم عرضه كعنصر في قائمة الإجراءات.

onClick

object ( OnClick )

الإجراء onClick لبند العمل هذا.

إصلاح البطاقة

تذييل ثابت (ثابت) يظهر في أسفل البطاقة.

يؤدي ضبط السمة fixedFooter بدون تحديد primaryButton أو secondaryButton إلى حدوث خطأ.

تتيح تطبيقات Chat fixedFooter في مربعات الحوار ، ولكن ليس في رسائل البطاقات .

تمثيل JSON
{
  "primaryButton": {
    object (Button)
  },
  "secondaryButton": {
    object (Button)
  }
}
الحقول
primaryButton

object ( Button )

الزر الأساسي في التذييل الثابت. ويجب أن يكون الزر زر نص فيه نص ومجموعة ألوان.

secondaryButton

object ( Button )

الزر الثانوي للتذييل الثابت. ويجب أن يكون الزر زر نص فيه نص ومجموعة ألوان. ويجب ضبط primaryButton في حال ضبط السياسة secondaryButton .

نمط العرض

تحدد إضافات Google Workspace كيفية عرض البطاقة.

غير متاحة من خلال تطبيقات Chat

عمليات التعداد
DISPLAY_STYLE_UNSPECIFIED لا يُستخدم.
PEEK يظهر عنوان البطاقة في أسفل الشريط الجانبي، لتغطية جزء من البطاقة الحالية الحالية للحزمة. يؤدي النقر على العنوان إلى إخراج البطاقة في حزمة البطاقة. وإذا لم يكن للبطاقة عنوان، يتم استخدام عنوان تم إنشاؤه بدلاً من ذلك.
REPLACE القيمة التلقائية يتم عرض البطاقة عن طريق استبدال طريقة عرض البطاقة العلوية في حزمة البطاقة.