Cards v2

بطاقة

واجهة بطاقة تظهر في رسالة Google Chat أو في إضافة Google Workspace

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

تصميم البطاقات ومعاينتها باستخدام "أداة إنشاء البطاقات".

فتح "أداة إنشاء البطاقات"

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

مثال: رسالة بطاقة لتطبيق Google Chat

مثال لبطاقة جهة اتصال

لإنشاء نموذج لرسالة البطاقة في Google Chat، استخدِم ملف JSON التالي: 

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
           "title": "Sasha",
           "subtitle": "Software Engineer",
           "imageUrl":
           "https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png",
           "imageType": "CIRCLE",
           "imageAltText": "Avatar for Sasha"
         },
         "sections": [
           {
             "header": "Contact Info",
             "collapsible": true,
             "uncollapsibleWidgetsCount": 1,
             "widgets": [
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "EMAIL"
                   },
                   "text": "sasha@example.com"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PERSON"
                   },
                   "text": "<font color=\"#80e27e\">Online</font>"
                 }
               },
               {
                 "decoratedText": {
                   "startIcon": {
                     "knownIcon": "PHONE"
                   },
                   "text": "+1 (555) 555-1234"
                 }
               },
               {
                 "buttonList": {
                   "buttons": [
                     {
                       "text": "Share",
                       "onClick": {
                        "openLink": {
                           "url": "https://example.com/share"
                         }
                       }
                     },
                     {
                       "text": "Edit",
                       "onClick": {
                         "action": {
                           "function": "goToView",
                           "parameters": [
                             {
                               "key": "viewType",
                               "value": "EDIT"
                             }
                           ]
                         }
                       }
                     }
                   ]
                 }
               }
             ]
           }
         ]
       }
    }
  ]
}
تمثيل JSON 
{
  "header": {
    object (CardHeader)
  },
  "sections": [
    {
      object (Section)
    }
  ],
  "sectionDividerStyle": enum (DividerStyle),
  "cardActions": [
    {
      object (CardAction)
    }
  ],
  "name": string,
  "fixedFooter": {
    object (CardFixedFooter)
  },
  "displayStyle": enum (DisplayStyle),
  "peekCardHeader": {
    object (CardHeader)
  }
}
الحقول
header

object (CardHeader)

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

sections[]

object (Section)

يحتوي على مجموعة من التطبيقات المصغّرة. يحتوي كل قسم على عنوان اختياري خاص به. يتم فصل الأقسام بصريًا بواسطة مُقسّم خطي. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة تحديد قسم في البطاقة

sectionDividerStyle

enum (DividerStyle)

نمط الفاصل بين الأقسام.

cardActions[]

object (CardAction)

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

على سبيل المثال، ينشئ JSON التالي قائمة إجراءات بطاقة تحتوي على Settings أو Send Feedback الخيارات: 

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

string

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

displayStyle

enum (DisplayStyle)

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

peekCardHeader

object (CardHeader)

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

CardHeader

عنوان بطاقة للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة أضِف عنوانًا.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

subtitle

string

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

imageType

enum (ImageType)

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

imageUrl

string

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

imageAltText

string

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

ImageType

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

القسم

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

النص الذي يظهر في أعلى القسم دعم نص بسيط بتنسيق HTML. لمزيد من المعلومات عن تنسيق النص، يمكنك الاطّلاع على تنسيق النص في تطبيقات Google Chat أو تنسيق النص في إضافات Google Workspace

widgets[]

object (Widget)

جميع التطبيقات المصغّرة في القسم يجب أن يحتوي على تطبيق مصغّر واحد على الأقل.

collapsible

boolean

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

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

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

uncollapsibleWidgetsCount

integer

عدد التطبيقات المصغّرة غير القابلة للتصغير التي تبقى مرئية حتى عند تصغير قسم.

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

collapseControl

object (CollapseControl)

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

أداة

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

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

تمثيل JSON 
{
  "horizontalAlignment": enum (HorizontalAlignment),

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

enum (HorizontalAlignment)

لتحديد ما إذا كانت الأدوات تتم محاذاة إلى اليسار أو اليمين أو منتصف العمود.

حقل الاتحاد data يمكن أن يحتوي التطبيق المصغّر على عنصر واحد فقط من العناصر التالية. يمكنك استخدام حقول متعدّدة في التطبيق المصغّر لعرض المزيد من العناصر. data واحد فقط مما يلي:
textParagraph

object (TextParagraph)

عرض فقرة نصية دعم نص بسيط بتنسيق HTML. لمزيد من المعلومات عن تنسيق النص، يمكنك الاطّلاع على تنسيق النص في تطبيقات Google Chat أو تنسيق النص في إضافات Google Workspace

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

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

object (Image)

تعرِض هذه السمة صورة.

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

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

object (DecoratedText)

تعرِض هذه السمة عنصرًا نصيًا مزخرفًا.

على سبيل المثال، ينشئ ملف JSON التالي أداة نصية مزخرفة تعرض عنوان البريد الإلكتروني: 

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

object (ButtonList)

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

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

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

object (TextInput)

تعرِض هذه السمة مربّع نص يمكن للمستخدمين الكتابة فيه.

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

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

كمثال آخر، ينشئ رمز JSON التالي إدخالاً نصيًا للغة برمجة يحتوي على اقتراحات ثابتة: 

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

object (SelectionInput)

عرض عنصر تحكّم في التحديد يتيح للمستخدمين اختيار العناصر يمكن أن تكون عناصر التحكم في التحديد مربعات اختيار أو أزرار اختيار أو مفاتيح تبديل أو قوائم منسدلة.

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

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

object (DateTimePicker)

تعرِض أداةً تتيح للمستخدمين إدخال تاريخ أو وقت أو تاريخ ووقت.

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

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

object (Divider)

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

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

"divider": {
}
grid

object (Grid)

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

تدعم الشبكة أي عدد من الأعمدة والعناصر. يتم تحديد عدد الصفوف من خلال الحدود العليا لعدد العناصر مقسومًا على عدد الأعمدة. الشبكة التي تحتوي على 10 عناصر وعمودين تحتوي على 5 صفوف. الشبكة التي تتكون من 11 عنصرًا وعمودين بها 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

object (Columns)

تعرض عمودين كحد أقصى.

لتضمين أكثر من عمودين، أو لاستخدام صفوف، استخدم Grid التطبيق المصغّر.

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

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

object (ChipList)

قائمة بالشرائح

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

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

TextParagraph

فقرة نصية تدعم التنسيق. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة أضِف فقرة من نص منسَّق. لمزيد من المعلومات عن تنسيق النص، يمكنك الاطّلاع على تنسيق النص في تطبيقات Google Chat أو تنسيق النص في إضافات Google Workspace

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

النص الذي يظهر في التطبيق المصغّر.

maxLines

integer

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

القيمة التلقائية هي 0، وفي هذه الحالة يتم عرض كل السياق. ويتم تجاهل القيم السلبية. متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

صورة

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

على سبيل المثال: 

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

object (OnClick)

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

altText

string

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

OnClick

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

تمثيل JSON 
{

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

حقل الاتحاد data

data واحد فقط مما يلي:

action

object (Action)

إذا تم تحديد قيمة، فسيتم تنفيذ إجراء من خلال هذا onClick

card

object (Card)

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

overflowMenu

object (OverflowMenu)

إذا تم تحديد قيمة السمة، سيتم onClick لفتح قائمة كاملة. متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

الإجراء

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

دالة مخصصة يتم استدعاؤها عند النقر على العنصر المتضمّن أو تنشيطه بأي شكل آخر.

على سبيل المثال، يمكنك الاطّلاع على قراءة بيانات النموذج

parameters[]

object (ActionParameter)

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

loadIndicator

enum (LoadIndicator)

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

persistValues

boolean

يشير إلى ما إذا كانت قيم النموذج تظلّ بعد الإجراء. القيمة الافتراضية هي false

في حال حذف true، تظل قيم النموذج بعد تشغيل الإجراء. للسماح للمستخدم بإجراء تغييرات أثناء معالجة الإجراء، اضبط LoadIndicator إلى NONE بالنسبة رسائل البطاقة في تطبيقات Chat، عليك أيضًا ضبط ResponseType إلى UPDATE_MESSAGE ونستخدم نفس cardId من البطاقة التي تحتوي على الإجراء.

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

interaction

enum (Interaction)

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

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

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

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

requiredWidgets[]

string

اختيارية. املأ هذه القائمة بأسماء التطبيقات المصغّرة التي يحتاجها هذا الإجراء لإرسال صالح.

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

allWidgetsAreRequired

boolean

اختيارية. إذا كان هذا صحيحًا، فستُعتبر جميع التطبيقات المصغّرة مطلوبة بموجب هذا الإجراء.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

ActionParameter

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

لمزيد من المعلومات، يُرجى مراجعة CommonEventObject

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

value

string

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

LoadIndicator

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

عمليات التعداد
SPINNER عرض مؤشر سريان العمل للإشارة إلى أنّه جارٍ تحميل المحتوى
NONE لا يتم عرض أي بيانات.

التفاعل

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

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

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

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

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

عمليات التعداد
INTERACTION_UNSPECIFIED القيمة التلقائية. تشير رسالة الأشكال البيانية action وتنفيذه كالمعتاد.
OPEN_DIALOG

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

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

OpenAs

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

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

OnClose

ما يفعله العميل عند فتح رابط بواسطة OnClick الإجراء مغلق.

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

إذا كان كلاهما OnOpen أو OnClose ولا يمكن للنظام الأساسي العميل إتاحة كلتا القيمتين، OnClose لها الأسبقية.

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

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

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

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

OverflowMenu

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

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

object (OverflowMenuItem)

يجب ملء الحقل. قائمة خيارات القائمة.

OverflowMenuItem

خيار يمكن للمستخدمين استدعاءه في قائمة كاملة.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

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

object (Icon)

الرمز المعروض أمام النص

text

string

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

onClick

object (OnClick)

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

disabled

boolean

ما إذا كان خيار القائمة معطلاً أم لا. وتكون القيمة التلقائية على "خطأ".

الرمز

رمز معروض في تطبيق مصغّر على بطاقة للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة إضافة رمز

يدعم مدمجة أو مخصّص الأيقونات.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

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

string

اختياريّ. تمثّل هذه السمة وصف الرمز المستخدَم لإمكانية الوصول. في حال عدم تحديد القيمة، يتم استخدام القيمة التلقائية Button على السطح. كأفضل ممارسة، يجب عليك إعداد وصف مفيد لما يعرضه الأيقونة، وما يفعله إن أمكن. على سبيل المثال: A user's account portrait، أو Opens a new browser tab and navigates to the Google Chat developer documentation at https://developers.google.com/workspace/chat

إذا تم تعيين الأيقونة في Button، altText يظهر كنص مساعد عندما يمرِّر المستخدم مؤشر الماوس فوق الزر. ومع ذلك، إذا ضبط الزر أيضًا text، الرمز altText تجاهله.

imageType

enum (ImageType)

نمط الاقتصاص المطبّق على الصورة في بعض الحالات، قد يؤدي تطبيق CIRCLE يؤدي الاقتصاص إلى رسم الصورة بحجم أكبر من الرمز المدمج.

حقل الاتحاد icons الرمز المعروض في التطبيق المصغّر على البطاقة icons واحد فقط مما يلي:
knownIcon

string

اعرض أحد الرموز المضمَّنة في Google Workspace.

على سبيل المثال، لعرض رمز طائرة، حدد AIRPLANE بالنسبة للحافلة، حدد BUS

للحصول على قائمة كاملة بالرموز المتوافقة، يمكنك الاطّلاع على الرموز المضمَّنة

iconUrl

string

عرض رمز مخصّص مُستضاف على عنوان URL يستخدم HTTPS

على سبيل المثال: 

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

تشمل أنواع الملفات المتاحة ما يلي: .png أو .jpg

materialIcon

object (MaterialIcon)

عرض أحد رموز المواد في Google:

على سبيل المثال، لعرض رمز مربع الاختيار، استخدم 

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

MaterialIcon

حاسمة رمز Google Material الذي يضم أكثر من 2500 خيار

على سبيل المثال، لعرض رمز مربّع الاختيار مع إمكانية تخصيص الوزن والدرجة، اكتب ما يلي: 

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{
  "name": string,
  "fill": boolean,
  "weight": integer,
  "grade": integer
}
الحقول
name

string

اسم الرمز المحدد في رمز Google Material، على سبيل المثال، check_box يتم تجاهل أي أسماء غير صالحة واستبدالها بسلسلة فارغة، ما يؤدّي إلى تعذُّر عرض الرمز.

fill

boolean

ما إذا كان سيتم عرض الرمز كممتلئ. القيمة التلقائية هي "خطأ".

لمعاينة الإعدادات المختلفة للرموز، انتقِل إلى رموز خطوط Google وضبط الإعدادات ضمن تخصيص

weight

integer

كثافة خط الرمز اختَر من بين {100, 200, 300, 400, 500, 600, 700}. في حال عدم توفّر هذه المعلومات، تكون القيمة التلقائية 400. إذا تم تحديد أي قيمة أخرى، يتم استخدام القيمة التلقائية.

لمعاينة الإعدادات المختلفة للرموز، انتقِل إلى رموز خطوط Google وضبط الإعدادات ضمن تخصيص

grade

integer

يؤثر الوزن والدرجة على سُمك الرمز. وتعد التعديلات التي يتم إجراؤها على الدرجة أكثر دقة من التعديلات على الوزن، كما أن لها تأثير بسيط في حجم الرمز. اختَر من بين {-25, 0, 200}. في حال عدم توفّر هذه المعلومات، تكون القيمة التلقائية 0. إذا تم تحديد أي قيمة أخرى، يتم استخدام القيمة التلقائية.

لمعاينة الإعدادات المختلفة للرموز، انتقِل إلى رموز خطوط Google وضبط الإعدادات ضمن تخصيص

DecoratedText

أداة تعرض نصًا مع زخارف اختيارية، مثل تصنيف أعلى النص أو أسفله، أو رمز أمام النص، أو أداة التحديد، أو زر بعد النص. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة عرض نص مع نص مزخرف:

متاحة لتطبيقات Google Chat وإضافات Google Workspace

تمثيل JSON 
{
  "icon": {
    object (Icon)
  },
  "startIcon": {
    object (Icon)
  },
  "topLabel": string,
  "text": string,
  "wrapText": boolean,
  "bottomLabel": string,
  "onClick": {
    object (OnClick)
  },

  // Union field control can be only one of the following:
  "button": {
    object (Button)
  },
  "switchControl": {
    object (SwitchControl)
  },
  "endIcon": {
    object (Icon)
  }
  // End of list of possible types for union field control.
}
الحقول
icon
(deprecated)

object (Icon)

تم إيقافها لصالح startIcon

startIcon

object (Icon)

الرمز المعروض أمام النص

topLabel

string

النص الذي يظهر أعلاه text يتم اقتطاع النص دائمًا.

text

string

يجب ملء الحقل. النص الأساسي.

إتاحة التنسيق البسيط. لمزيد من المعلومات عن تنسيق النص، يمكنك الاطّلاع على تنسيق النص في تطبيقات Google Chat أو تنسيق النص في إضافات Google Workspace

wrapText

boolean

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

ينطبق على text، ليس topLabel أو bottomLabel

bottomLabel

string

النص الذي يظهر أدناه text التفاف النص دائمًا

onClick

object (OnClick)

يتم تشغيل هذا الإجراء عندما ينقر المستخدِمون على topLabel أو bottomLabel

حقل الاتحاد control زر أو مفتاح تبديل أو مربع اختيار أو صورة تظهر في الجانب الأيمن من النص في decoratedText التطبيق المصغّر. control واحد فقط مما يلي:
button

object (Button)

زر يمكن للمستخدم النقر عليه لتشغيل إجراء.

switchControl

object (SwitchControl)

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

endIcon

object (Icon)

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

يدعم مدمجة أو مخصّص الأيقونات.

زرّ

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

لجعل صورة زرًا قابلاً للنقر، حدد Image (ليس ImageComponent) وضبط onClick اتخاذ القرار.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

icon

object (Icon)

صورة الرمز إذا كان كلاهما icon أو text البيانات، ثم يظهر الرمز قبل النص.

color

object (Color)

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

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

بالنسبة للأحمر والأخضر والأزرق، تكون قيمة كل حقل هي 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

object (OnClick)

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

disabled

boolean

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

altText

string

تمثّل هذه السمة النص البديل المستخدم في تسهيل الاستخدام.

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

type

enum (Type)

يحدد نوع الزر.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

اللون

يمثل لونًا في مساحة ألوان RGBA. تم تصميم هذا التمثيل لتبسيط عملية التحويل من وإلى تمثيلات الألوان بلغات مختلفة على مدى الاكتفاء. على سبيل المثال، يمكن تقديم حقول هذا التمثيل بشكل بسيط إلى الدالة الإنشائية java.awt.Color في Java؛ يمكن أيضًا تقديمه بشكل تافه إلى ألوان UIColor +colorWithRed:green:blue:alpha في iOS؛ ومن خلال القليل من العمل، يمكن تنسيقها بسهولة في CSS rgba() سلسلة في JavaScript.

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

عندما يلزم تحديد مساواة الألوان، فإن عمليات التنفيذ، ما لم يوثق خلاف ذلك، تعامل لونين على قدم المساواة إذا كانت جميع قيم الأحمر والأخضر والأزرق وألفا تختلف على الأكثر 1e-5

مثال (Java): 

 import com.google.type.Color;

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

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

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

مثال (iOS / Obj-C): 

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

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

مثال (JavaScript): 

// ...

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

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

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

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

// ...
تمثيل JSON 
{
  "red": number,
  "green": number,
  "blue": number,
  "alpha": number
}
الحقول
red

number

مقدار اللون الأحمر في اللون كقيمة في الفاصل [0, 1].

green

number

مقدار اللون الأخضر في اللون كقيمة في الفاصل [0, 1].

blue

number

مقدار اللون الأزرق في اللون كقيمة في الفاصل [0, 1].

alpha

number

الجزء من هذا اللون الذي يجب تطبيقه على البكسل. وهذا يعني أن لون البكسل النهائي يتم تحديده من خلال المعادلة:

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

وهذا يعني أن القيمة 1.0 تتجاوب مع لون خالص، في حين تتجاوب القيمة 0.0 مع لون شفاف تمامًا. يستخدم ذلك رسالة تضمين بدلاً من عدد قياسي عائم بسيط بحيث يمكن التمييز بين القيمة التلقائية والقيمة التي يتم إلغاء تعيينها. وعند إسقاطها، يتم عرض كائن اللون هذا كلون ثابت (كما لو تم إعطاء قيمة ألفا بوضوح قيمة 1.0).

النوع

تشير رسالة الأشكال البيانية النوع الزر.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

عمليات التعداد
TYPE_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
OUTLINED الأزرار المخططة هي أزرار متوسطة التوكيد. عادةً ما تحتوي على إجراءات مهمة، ولكنها ليست الإجراء الأساسي في تطبيق Chat أو إضافة.
FILLED يحتوي الزر المعبأ على حاوية بلون خالص. لها التأثير المرئي الأكبر، ويُنصح باستخدامها للإجراء المهم والأساسي في تطبيق Chat أو إضافة.
FILLED_TONAL زر الدرجات اللونية المملوء هو أرض متوسطة بديلة بين الأزرار المملوءة والمحددة. وهي مفيدة في السياقات التي يتطلب فيها الزر ذي الأولوية الأقل توكيدًا أكثر قليلاً مما قد يعطيه زر المخطط التفصيلي.
BORDERLESS لا يحتوي الزر على حاوية غير مرئية بحالته التلقائية. يُستخدَم عادةً لتنفيذ الإجراءات ذات الأولوية الأدنى، خاصةً عند عرض خيارات متعددة.

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

إما أن يكون مفتاح تبديل بنمط التبديل أو مربع اختيار داخل decoratedText التطبيق المصغّر.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

لا تتوفّر هذه الميزة إلا في decoratedText التطبيق المصغّر.

تمثيل JSON 
{
  "name": string,
  "value": string,
  "selected": boolean,
  "onChangeAction": {
    object (Action)
  },
  "controlType": enum (ControlType)
}
الحقول
name

string

الاسم الذي يتم من خلاله تعريف التطبيق المصغّر للتبديل في حدث إدخال النموذج.

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

value

string

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

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

selected

boolean

فعندما true، تم اختيار مفتاح التبديل.

onChangeAction

object (Action)

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

controlType

enum (ControlType)

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

ControlType

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

ButtonList

قائمة بالأزرار الموضوعة أفقيًا. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة إضافة زر

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

object (Button)

مصفوفة من الأزرار.

TextInput

حقل يمكن للمستخدمين إدخال نص فيه. دعم الاقتراحات والإجراءات عند التغيير. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة أضِف حقلاً يمكن للمستخدم إدخال نص فيه.

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

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

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

label

string

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

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

مطلوبة إذا hintText غير محدد. وبخلاف ذلك، اختياري.

hintText

string

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

مطلوبة إذا label غير محدد. وبخلاف ذلك، اختياري.

value

string

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

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

type

enum (Type)

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

onChangeAction

object (Action)

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

تشمل أمثلة الإجراءات التي يجب اتخاذها تشغيل دالة مخصصة أو فتح مربّع حوار في Google Chat

initialSuggestions

object (Suggestions)

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

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

تساعد القيم المقترَحة في توجيه المستخدمين لإدخال قيم يمكن لتطبيقك فهمها. فعند الإشارة إلى JavaScript، قد يدخل بعض المستخدمين javascript وغير ذلك java script الاقتراح JavaScript توحيد كيفية تفاعل المستخدمين مع تطبيقك.

عند تحديدها، TextInput.type دائمًا SINGLE_LINE، حتى إذا تم ضبطها على MULTIPLE_LINE

متاحة لتطبيقات Google Chat وإضافات Google Workspace

autoCompleteAction

object (Action)

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

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

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

validation

object (Validation)

حدِّد عملية التحقّق اللازمة لحقل إدخال النص هذا.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

placeholderText

string

النص الذي يظهر في حقل إدخال النص عندما يكون الحقل فارغًا استخدِم هذا النص لتوجيه المستخدمين إلى إدخال قيمة. على سبيل المثال: Enter a number from 0 to 100

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

النوع

طريقة ظهور حقل إدخال نص في واجهة المستخدم على سبيل المثال، ما إذا كان حقل إدخال سطر واحد أو إدخال متعدد الأسطر. في حال حذف initialSuggestions المحدد، type دائمًا SINGLE_LINE، حتى إذا تم ضبطها على MULTIPLE_LINE

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

RenderActions

يشير هذا المصطلح إلى مجموعة من تعليمات العرض التي تطلب من البطاقة تنفيذ إجراء. توجيه تطبيق مضيف الإضافة أو تطبيق Chat لتنفيذ إجراء خاص بالتطبيق.

متاحة لتطبيقات Google Chat وإضافات Google Workspace.

الحقول
action

Action

الإجراء

الحقول
navigations[]

Navigation

إرسال البطاقات المعروضة أو تعديلها

إضافة بطاقة جديدة إلى الحزمة (الانتقال للأمام) بالنسبة إلى تطبيقات Chat، لا يتوفّر هذا الخيار إلا في الصفحة الرئيسية للتطبيق.

متاحة لتطبيقات Google Chat وإضافات Google Workspace.

navigations: {
  pushCard: CARD
}

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace.

navigations: {
  updateCard: CARD
}

اقتراحات

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

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

تساعد القيم المقترَحة في توجيه المستخدمين لإدخال قيم يمكن لتطبيقك فهمها. فعند الإشارة إلى JavaScript، قد يدخل بعض المستخدمين javascript وغير ذلك java script الاقتراح JavaScript توحيد كيفية تفاعل المستخدمين مع تطبيقك.

عند تحديدها، TextInput.type دائمًا SINGLE_LINE، حتى إذا تم ضبطها على MULTIPLE_LINE

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

object (SuggestionItem)

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

SuggestionItem

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

تمثيل JSON 
{

  // Union field content can be only one of the following:
  "text": string
  // End of list of possible types for union field content.
}
الحقول

حقل الاتحاد content

content واحد فقط مما يلي:

text

string

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

التحقّق من الصحة

يمثل البيانات اللازمة للتحقق من التطبيق المصغّر المرفق به.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

تمثيل JSON 
{
  "characterLimit": integer,
  "inputType": enum (InputType)
}
الحقول
characterLimit

integer

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

inputType

enum (InputType)

حدد نوع أدوات الإدخال.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

InputType

نوع التطبيق المصغّر للإدخال

عمليات التعداد
INPUT_TYPE_UNSPECIFIED نوع غير محدَّد. يُرجى عدم استخدامها.
TEXT نص عادي يقبل جميع الأحرف
INTEGER قيمة عدد صحيح.
FLOAT قيمة عائمة.
EMAIL عنوان بريد إلكتروني.
EMOJI_PICKER رمز تعبيري تم اختياره من أداة اختيار الرموز التعبيرية التي يوفّرها النظام.

SelectionInput

هو تطبيق مصغّر ينشئ عنصرًا واحدًا أو أكثر في واجهة المستخدم يمكن للمستخدمين اختياره. على سبيل المثال، قائمة منسدلة أو مربعات اختيار. ويمكنك استخدام هذه الأداة لجمع البيانات التي يمكن توقُّعها أو تعدادها. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة إضافة عناصر واجهة مستخدم قابلة للاختيار:

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

لجمع بيانات غير محددة أو مجردة من المستخدمين، استخدم TextInput التطبيق المصغّر.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

تمثيل JSON 
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,
  "validation": {
    object (Validation)
  },

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
الحقول
name

string

يجب ملء الحقل. الاسم الذي يحدد الإدخال المحدد في حدث إدخال نموذج.

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

label

string

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

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

type

enum (SelectionType)

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

items[]

object (SelectionItem)

مصفوفة من العناصر القابلة للاختيار. على سبيل المثال، مصفوفة من أزرار الاختيار أو مربّعات الاختيار. يمكن إدخال ما يصل إلى 100 عنصر.

onChangeAction

object (Action)

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

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

multiSelectMaxSelectedItems

integer

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

multiSelectMinQueryLength

integer

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

وفي حال عدم تحديد ذلك، يتم ضبط الإعدادات التلقائية على 0 حرف لمصادر البيانات الثابتة و3 أحرف لمصادر البيانات الخارجية.

validation

object (Validation)

التحقق من صحة حقل إدخال التحديد هذا بالنسبة إلى القوائم المنسدلة.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

حقل الاتحاد multi_select_data_source بالنسبة إلى قائمة الاختيار المتعدد، يكون مصدر البيانات الذي يملأ عناصر الاختيار.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace. multi_select_data_source واحد فقط مما يلي:

externalDataSource

object (Action)

مصدر بيانات خارجي، مثل قاعدة بيانات ارتباطية.

platformDataSource

object (PlatformDataSource)

مصدر بيانات من Google Workspace.

SelectionType

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

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

عمليات التعداد
CHECK_BOX مجموعة من مربعات الاختيار. يمكن للمستخدمين تحديد مربّع اختيار واحد أو أكثر.
RADIO_BUTTON مجموعة من أزرار الاختيار يمكن للمستخدمين تحديد زر اختيار واحد.
SWITCH مجموعة من مفاتيح التبديل يمكن للمستخدمين تفعيل مفتاح تحكّم واحد أو أكثر.
DROPDOWN قائمة منسدلة يمكن للمستخدمين اختيار عنصر واحد من القائمة.
MULTI_SELECT

قائمة تحديد متعدد للبيانات الثابتة أو الديناميكية. من شريط القوائم، يختار المستخدمون عنصرًا واحدًا أو أكثر. يمكن للمستخدمين أيضًا إدخال قيم لتعبئة البيانات الديناميكية. على سبيل المثال، يمكن للمستخدمين بدء كتابة اسم مساحة في Google Chat، ويقترح التطبيق المصغّر المساحة تلقائيًا.

لتعبئة العناصر لقائمة اختيار متعدّد، يمكنك استخدام أحد الأنواع التالية من مصادر البيانات:

  • البيانات الثابتة: يتم تحديد العناصر كـ SelectionItem الكائنات في التطبيق المصغَّر. يمكنك الاستفادة من ما يصل إلى 100 عنصر.
  • بيانات Google Workspace: تتم تعبئة العناصر باستخدام بيانات من Google Workspace، مثل مستخدمي Google Workspace أو مساحات Google Chat.
  • البيانات الخارجية: تتم تعبئة العناصر من مصدر بيانات خارجي خارج Google Workspace.

للحصول على أمثلة حول طريقة تنفيذ قوائم تحديد متعدّدة، يُرجى الاطّلاع على: إضافة قائمة اختيار متعدّدة

متاحة لتطبيقات Google Chat وإضافات Google Workspace

SelectionItem

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

النص الذي يعرّف المستخدمين على السلعة أو يصفها

value

string

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

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

selected

boolean

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

startIconUri

string

بالنسبة إلى قوائم التحديد المتعدد، يتم استخدام عنوان URL للرمز المعروض بجوار عنوان text . يمكن استخدام الملفات بتنسيق PNG وJPEG. يجب أن تكون HTTPS عنوان URL. على سبيل المثال: https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png

bottomText

string

بالنسبة إلى قوائم التحديد المتعدد، يتم عرض وصف نصي أو تصنيف أسفل قائمة عناصر text .

PlatformDataSource

بالنسبة إلى SelectionInput تطبيق مصغّر يستخدم قائمة اختيار متعدّدة ومصدر بيانات من Google Workspace. تُستخدَم لتعبئة العناصر في قائمة اختيار متعدّد.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{

  // Union field data_source can be only one of the following:
  "commonDataSource": enum (CommonDataSource),
  "hostAppDataSource": {
    object (HostAppDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
الحقول
حقل الاتحاد data_source مصدر البيانات. data_source واحد فقط مما يلي:
commonDataSource

enum (CommonDataSource)

مصدر بيانات تشاركه جميع تطبيقات Google Workspace، مثل المستخدمين في مؤسسة Google Workspace.

hostAppDataSource

object (HostAppDataSourceMarkup)

مصدر بيانات فريد لتطبيق مضيف Google Workspace، مثل المساحات في Google Chat.

CommonDataSource

مصدر بيانات يشاركه الجميع تطبيقات Google Workspace.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

عمليات التعداد
UNKNOWN القيمة التلقائية. يُرجى عدم استخدامها.
USER مستخدمو Google Workspace يمكن للمستخدم الاطّلاع على المستخدمين واختيارهم من مؤسسة Google Workspace فقط.

HostAppDataSourceMarkup

بالنسبة إلى SelectionInput تطبيق مصغّر يستخدم قائمة اختيار متعدد ومصدر بيانات من أحد تطبيقات Google Workspace. يملأ مصدر البيانات عناصر الاختيار لقائمة التحديد المتعدد.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{

  // Union field data_source can be only one of the following:
  "chatDataSource": {
    object (ChatClientDataSourceMarkup)
  }
  // End of list of possible types for union field data_source.
}
الحقول
حقل الاتحاد data_source تطبيق Google Workspace الذي يملأ العناصر لقائمة اختيارات متعدّدة data_source واحد فقط مما يلي:
chatDataSource

object (ChatClientDataSourceMarkup)

مصدر بيانات من Google Chat

ChatClientDataSourceMarkup

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{

  // Union field source can be only one of the following:
  "spaceDataSource": {
    object (SpaceDataSource)
  }
  // End of list of possible types for union field source.
}
الحقول
حقل الاتحاد source مصدر بيانات Google Chat. source واحد فقط مما يلي:
spaceDataSource

object (SpaceDataSource)

مساحات Google Chat التي يكون المستخدم عضوًا فيها

SpaceDataSource

مصدر بيانات يملأ مساحات Google Chat كعناصر اختيار لقائمة اختيار متعدّدة لا تتم تعبئة سوى المساحات التي يكون المستخدم عضوًا فيها.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{
  "defaultToCurrentSpace": boolean
}
الحقول
defaultToCurrentSpace

boolean

في حال الضبط على true، تختار قائمة الاختيار المتعدد مساحة Google Chat الحالية كعنصر تلقائيًا.

DateTimePicker

يسمح للمستخدمين بإدخال تاريخ أو وقت أو تاريخ ووقت معًا. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة السماح للمستخدم باختيار تاريخ ووقت:

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

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

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

label

string

النص الذي يطلب من المستخدمين إدخال تاريخ أو وقت أو تاريخ ووقت. على سبيل المثال، إذا كان المستخدمون يقومون بجدولة موعد، فاستخدم تصنيفًا مثل Appointment date أو Appointment date and time

type

enum (DateTimePickerType)

ما إذا كانت الأداة تتيح إدخال التاريخ أو الوقت أو التاريخ والوقت

valueMsEpoch

string (int64 format)

القيمة التلقائية المعروضة في الأداة بالمللي ثانية منذ وقت حقبة يونكس

حدّد القيمة استنادًا إلى نوع أداة الاختيار ( DateTimePickerType):

  • DATE_AND_TIME : تاريخ ووقت تقويم حسب التوقيت العالمي المنسَّق (UTC). على سبيل المثال، لتمثيل 1 كانون الثاني (يناير) 2023 في الساعة 12:00 بعد الظهر بالتوقيت العالمي المتفق عليه، استخدِم 1672574400000
  • DATE_ONLY : تاريخ تقويم في الساعة 00:00:00 بالتوقيت العالمي المنسق (UTC). على سبيل المثال، لتمثيل 1 يناير 2023، استخدم 1672531200000
  • TIME_ONLY : وقت بالتوقيت العالمي المنسق (UTC). على سبيل المثال، لتمثيل الساعة 12:00 بعد الظهر، استخدم 43200000 (أو 12 * 60 * 60 * 1000).
timezoneOffsetDate

integer

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

onChangeAction

object (Action)

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

validation

object (Validation)

اختيارية. حدِّد عملية التحقّق المطلوبة لأداة اختيار التاريخ والوقت هذه.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

DateTimePickerType

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

عمليات التعداد
DATE_AND_TIME يُدخِل المستخدمون التاريخ والوقت.
DATE_ONLY يُدخِل المستخدمون تاريخًا.
TIME_ONLY يُدخِل المستخدمون وقتًا.

حاجز

لا يحتوي هذا النوع على أي حقول.

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

"divider": {}

شبكة

تعرض شبكة بها مجموعة من العناصر. يمكن أن تتضمن العناصر نصًا أو صورًا فقط. بالنسبة للأعمدة المتجاوبة، أو لتضمين أكثر من نص أو صور، استخدم Columns للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة عرض شبكة تتضمّن مجموعة من العناصر:

تدعم الشبكة أي عدد من الأعمدة والعناصر. يتم تحديد عدد الصفوف من خلال قسمة العناصر على الأعمدة. الشبكة التي تحتوي على 10 عناصر وعمودين تحتوي على 5 صفوف. الشبكة التي تتكون من 11 عنصرًا وعمودين بها 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"
    }
  }
}
تمثيل 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)

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

GridItem

تمثل عنصرًا في تنسيق الشبكة. يمكن أن تحتوي العناصر على نص أو صورة أو نصًا وصورة معًا.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

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

ImageComponent

يمثل هذا العنصر صورة.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

string

عنوان URL الخاص بالصورة

altText

string

تشير هذه السمة إلى تصنيف تسهيل الاستخدام الخاص بالصورة.

cropStyle

object (ImageCropStyle)

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

borderStyle

object (BorderStyle)

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

ImageCropStyle

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

على سبيل المثال، إليك كيفية تطبيق نسبة العرض إلى الارتفاع 16:9: 

cropStyle {
 "type": "RECTANGLE_CUSTOM",
 "aspectRatio": 16/9
}
تمثيل JSON 
{
  "type": enum (ImageCropType),
  "aspectRatio": number
}
الحقول
type

enum (ImageCropType)

نوع الاقتصاص

aspectRatio

number

نسبة العرض إلى الارتفاع المراد استخدامها إذا كان نوع الاقتصاص RECTANGLE_CUSTOM

على سبيل المثال، إليك كيفية تطبيق نسبة العرض إلى الارتفاع 16:9: 

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

ImageCropType

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

BorderStyle

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

enum (BorderType)

نوع الحد.

strokeColor

object (Color)

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

cornerRadius

integer

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

BorderType

تمثل هذه السمة أنواع الحدود المطبَّقة على التطبيقات المصغّرة.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

عمليات التعداد
BORDER_TYPE_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
NO_BORDER القيمة التلقائية. بلا حدود
STROKE مخطط تفصيلي.

GridItemLayout

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

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

الأعمدة

تشير رسالة الأشكال البيانية Columns يعرض التطبيق المصغّر ما يصل إلى عمودين في بطاقة أو مربع حوار. يمكنك إضافة أدوات إلى كل عمود؛ ستظهر الأدوات بالترتيب الذي تم تحديدها به. للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة عرض البطاقات ومربّعات الحوار في أعمدة:

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

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

  • على الويب، يتم التفاف العمود الثاني إذا كان عرض الشاشة أقل من أو يساوي 480 بكسل.
  • في أجهزة iOS، يتم التفاف العمود الثاني إذا كان عرض الشاشة أقل من أو يساوي 300 نقطة.
  • في أجهزة Android، يتم التفاف العمود الثاني إذا كان عرض الشاشة أقل من أو يساوي 320 وحدة بكسل مستقلة الكثافة.

لتضمين أكثر من عمودين، أو لاستخدام صفوف، استخدم Grid التطبيق المصغّر.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

object (Column)

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

العمود

عمود.

إضافات Google Workspace وتطبيقات Chat

تمثيل JSON 
{
  "horizontalSizeStyle": enum (HorizontalSizeStyle),
  "horizontalAlignment": enum (HorizontalAlignment),
  "verticalAlignment": enum (VerticalAlignment),
  "widgets": [
    {
      object (Widgets)
    }
  ]
}
الحقول
horizontalSizeStyle

enum (HorizontalSizeStyle)

تحدِّد هذه السياسة كيفية ملء العمود بعرض البطاقة.

horizontalAlignment

enum (HorizontalAlignment)

لتحديد ما إذا كانت الأدوات تتم محاذاة إلى اليسار أو اليمين أو منتصف العمود.

verticalAlignment

enum (VerticalAlignment)

لتحديد ما إذا كانت الأدوات تتم محاذاة إلى أعلى العمود أو أسفله أو وسطه.

widgets[]

object (Widgets)

مصفوفة من التطبيقات المصغّرة التي يتم تضمينها في عمود. تظهر التطبيقات المصغّرة بالترتيب الذي تم تحديدها به.

HorizontalSizeStyle

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

إضافات Google Workspace وتطبيقات Chat

عمليات التعداد
HORIZONTAL_SIZE_STYLE_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
FILL_AVAILABLE_SPACE القيمة التلقائية. يملأ العمود المساحة المتاحة، بما يصل إلى 70% من عرض البطاقة. إذا تم تعيين كلا العمودين على FILL_AVAILABLE_SPACE، يملأ كل عمود 50% من المساحة.
FILL_MINIMUM_SPACE يملأ العمود أقل مساحة ممكنة ولا تزيد عن 30% من عرض البطاقة.

HorizontalAlignment

لتحديد ما إذا كانت الأدوات تتم محاذاة إلى اليسار أو اليمين أو منتصف العمود.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

عمليات التعداد
HORIZONTAL_ALIGNMENT_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
START القيمة التلقائية. لمحاذاة الأدوات مع موضع بداية العمود. بالنسبة للتخطيطات من اليسار إلى اليمين، تتم المحاذاة إلى اليسار. بالنسبة للتخطيطات من اليمين إلى اليسار، تتم المحاذاة إلى اليمين.
CENTER لمحاذاة الأدوات في منتصف العمود.
END لمحاذاة الأدوات مع موضع نهاية العمود. بالنسبة إلى التنسيقات من اليسار إلى اليمين، تتم محاذاة الأدوات إلى اليمين. بالنسبة إلى التنسيقات من اليمين إلى اليسار، تتم محاذاة الأدوات إلى اليسار.

VerticalAlignment

لتحديد ما إذا كانت الأدوات تتم محاذاة إلى أعلى العمود أو أسفله أو وسطه.

إضافات Google Workspace وتطبيقات Chat

عمليات التعداد
VERTICAL_ALIGNMENT_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
CENTER القيمة التلقائية. لمحاذاة الأدوات في منتصف العمود.
TOP لمحاذاة الأدوات مع أعلى عمود.
BOTTOM لمحاذاة الأدوات إلى أسفل العمود.

التطبيقات المصغَّرة

التطبيقات المصغّرة المتوافقة التي يمكنك تضمينها في عمود

إضافات Google Workspace وتطبيقات Chat

تمثيل JSON 
{

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

حقل الاتحاد data

data واحد فقط مما يلي:

textParagraph

object (TextParagraph)

TextParagraph التطبيق المصغّر.

image

object (Image)

Image التطبيق المصغّر.

decoratedText

object (DecoratedText)

DecoratedText التطبيق المصغّر.

buttonList

object (ButtonList)

ButtonList التطبيق المصغّر.

textInput

object (TextInput)

TextInput التطبيق المصغّر.

selectionInput

object (SelectionInput)

SelectionInput التطبيق المصغّر.

dateTimePicker

object (DateTimePicker)

DateTimePicker التطبيق المصغّر.

chipList

object (ChipList)

ChipList التطبيق المصغّر. متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

ChipList

قائمة بالشرائح يتم وضعها أفقيًا، والتي يمكنها إما التمرير أفقيًا أو التفافها إلى السطر التالي.

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{
  "layout": enum (Layout),
  "chips": [
    {
      object (Chip)
    }
  ]
}
الحقول
layout

enum (Layout)

تنسيق قائمة الشرائح المحدّد.

chips[]

object (Chip)

مصفوفة من الشرائح.

التنسيق

تنسيق قائمة الشرائح

عمليات التعداد
LAYOUT_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
WRAPPED القيمة التلقائية. يتم التفاف قائمة الشرائح مع السطر التالي إذا لم تكن هناك مساحة أفقية كافية.
HORIZONTAL_SCROLLABLE يتم تمرير الشرائح أفقيًا في حال عدم تناسبها مع المساحة المتاحة.

شريحة

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

متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

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

object (Icon)

صورة الرمز إذا كان كلاهما icon أو text البيانات، ثم يظهر الرمز قبل النص.

label

string

النص المعروض داخل الشريحة

onClick

object (OnClick)

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

enabled
(deprecated)

boolean

ما إذا كانت الشريحة في حالة نشطة وتستجيب لإجراءات المستخدم الإعدادات التلقائية على true تمّ الإيقاف. استخدام disabled بدلاً من ذلك.

disabled

boolean

ما إذا كانت الشريحة في حالة غير نشطة وتتجاهل إجراءات المستخدم الإعدادات التلقائية على false

altText

string

تمثّل هذه السمة النص البديل المستخدم في تسهيل الاستخدام.

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

CollapseControl

مثِّل أحد عناصر التحكُّم في التوسيع والتصغير. متاحة لتطبيقات Google Chat ولا تتوفّر لإضافات Google Workspace.

تمثيل JSON 
{
  "horizontalAlignment": enum (HorizontalAlignment),
  "expandButton": {
    object (Button)
  },
  "collapseButton": {
    object (Button)
  }
}
الحقول
horizontalAlignment

enum (HorizontalAlignment)

المحاذاة الأفقية لزرَي التوسيع والتصغير

expandButton

object (Button)

اختياريّ. ويمكنك تحديد زر قابل للتخصيص لتوسيع القسم. يجب ضبط كل من حقل extendButton وzoomButton. لن يتم تطبيق سوى مجموعة حقول واحدة. وفي حال عدم ضبط هذا الحقل، يتم استخدام الزرّ التلقائي.

collapseButton

object (Button)

اختياريّ. تحديد زر قابل للتخصيص لتصغير القسم. يجب ضبط كل من حقل extendButton وzoomButton. لن يتم تطبيق سوى مجموعة حقول واحدة. وفي حال عدم ضبط هذا الحقل، يتم استخدام الزرّ التلقائي.

DividerStyle

نمط الفاصل لبطاقة. لا تُستخدَم حاليًا إلا للفواصل بين أقسام البطاقة.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

عمليات التعداد
DIVIDER_STYLE_UNSPECIFIED يُرجى عدم استخدامها. غير محدد
SOLID_DIVIDER الخيار التلقائي. اعرض مُقسّمًا ثابتًا بين الأقسام.
NO_DIVIDER في حال ضبطها، لن يتم عرض أي فاصل بين الأقسام.

CardAction

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

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

string

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

onClick

object (OnClick)

تشير رسالة الأشكال البيانية onClick الإجراء لبند العمل هذا.

CardFixedFooter

تذييل (ثابت) ثابت يظهر في الجزء السفلي من البطاقة.

الإعداد fixedFooter بدون تحديد primaryButton أو a secondaryButton إلى حدوث خطأ.

بالنسبة إلى تطبيقات Chat، يمكنك استخدام التذييلات الثابتة في مربعات الحوار، ولكن لا رسائل البطاقة للاطّلاع على مثال في تطبيقات Google Chat، يُرجى مراجعة إضافة تذييل دائم.

متاحة لتطبيقات Google Chat وإضافات Google Workspace

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

object (Button)

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

secondaryButton

object (Button)

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

DisplayStyle

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

متاحة لإضافات Google Workspace ولا تتوفّر لتطبيقات Google Chat.

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