Class SelectionInput

SelectionInput

حقل إدخال يسمح بالاختيار من بين مجموعة من الخيارات المحدّدة مسبقًا.

تتيح التحقّق من صحة عمليات إرسال النماذج لقوائم SelectionInputType.DROP_DOWN وSelectionInputType.MULTI_SELECT فقط. عند ضبط Action.setAllWidgetsAreRequired(allWidgetsAreRequired) على true أو تحديد هذه الأداة من خلال Action.addRequiredWidget(requiredWidget)، يتم حظر إجراء الإرسال ما لم يتم تحديد قيمة.

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

const checkboxGroup =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.CHECK_BOX)
        .setTitle('A group of checkboxes. Multiple selections are allowed.')
        .setFieldName('checkbox_field')
        .addItem('checkbox one title', 'checkbox_one_value', false)
        .addItem('checkbox two title', 'checkbox_two_value', true)
        .addItem('checkbox three title', 'checkbox_three_value', true)
        .setOnChangeAction(
            CardService.newAction().setFunctionName('handleCheckboxChange'),
        );

const radioGroup =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.RADIO_BUTTON)
        .setTitle(
            'A group of radio buttons. Only a single selection is allowed.')
        .setFieldName('checkbox_field')
        .addItem('radio button one title', 'radio_one_value', true)
        .addItem('radio button two title', 'radio_two_value', false)
        .addItem('radio button three title', 'radio_three_value', false);

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('multiselect')
        .setTitle('A multi select input example.')
        .addMultiSelectItem(
            'Contact 1',
            'contact-1',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact one description',
            )
        .addMultiSelectItem(
            'Contact 2',
            'contact-2',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact two description',
            )
        .addMultiSelectItem(
            'Contact 3',
            'contact-3',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact three description',
            )
        .addMultiSelectItem(
            'Contact 4',
            'contact-4',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact four description',
            )
        .addMultiSelectItem(
            'Contact 5',
            'contact-5',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact five description',
            )
        .setMultiSelectMaxSelectedItems(3)
        .setMultiSelectMinQueryLength(1);

الطُرق

الطريقة	نوع القيمة التي تم إرجاعها	وصف قصير
addDataSourceConfig(dataSourceConfig)	SelectionInput	تضبط هذه السمة إعدادات مصدر البيانات لعنصر التحكّم في الاختيار.
addEventAction(eventAction)	Widget	تضيف هذه السمة إجراء الحدث الذي يمكن تنفيذه على التطبيق المصغّر.
addItem(text, value, selected)	SelectionInput	تضيف هذه السمة عنصرًا جديدًا يمكن اختياره.
addMultiSelectItem(text, value, selected, startIconUri, bottomText)	SelectionInput	تضيف هذه السمة عنصرًا جديدًا يمكن اختياره، وذلك للقوائم التي تتيح تحديد عناصر متعددة.
setExternalDataSource(action)	SelectionInput	تضبط هذه السمة مصدر بيانات خارجيًا، مثل قاعدة بيانات ارتباطية.
setFieldName(fieldName)	SelectionInput	تضبط هذه السمة المفتاح الذي يعرّف عنصر الإدخال المحدّد هذا في عنصر الحدث الذي يتم إنشاؤه عند حدوث تفاعل مع واجهة المستخدم.
setId(id)	Widget	يضبط هذا الإجراء المعرّف الفريد الذي تمّ تعيينه والذي يُستخدَم لتحديد الأداة التي سيتمّ تغييرها.
setMultiSelectMaxSelectedItems(maxSelectedItems)	SelectionInput	تضبط هذه السمة الحد الأقصى لعدد العناصر التي يمكن للمستخدم اختيارها.
setMultiSelectMinQueryLength(queryLength)	SelectionInput	تضبط هذه السمة عدد أحرف النص التي يدخلها المستخدم قبل أن يطلب التطبيق الإكمال التلقائي ويعرض العناصر المقترَحة على البطاقة.
setOnChangeAction(action)	SelectionInput	تضبط هذه السمة Action ليتم تنفيذها كلما تغيّر إدخال التحديد.
setPlatformDataSource(platformDataSource)	SelectionInput	تضبط هذه السمة مصدر بيانات من Google Workspace.
setTitle(title)	SelectionInput	تضبط هذه السمة العنوان الذي سيتم عرضه قبل حقل الإدخال.
setType(type)	SelectionInput	تضبط هذه السمة نوع الإدخال.
setVisibility(visibility)	Widget	تضبط هذه السمة مستوى ظهور الأداة.

مستندات تفصيلية

addDataSourceConfig(dataSourceConfig)

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

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('contacts')
        .setTitle('Selected contacts')
        .setDataSourceConfig(
            CardService.newDataSourceConfig().setPlatformDataSource(
                CardService.newPlatformDataSource().setCommonDataSource(
                    CardService.CommonDataSource.USER,
                )
            )
        );

المَعلمات

الاسم	النوع	الوصف
dataSourceConfig	DataSourceConfig	إعدادات مصدر البيانات التي سيتم تطبيقها على إدخال الاختيار.

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

addEventAction(eventAction)

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

المَعلمات

الاسم	النوع	الوصف
eventAction	EventAction	تمثّل هذه السمة EventAction المطلوب إضافتها.

الإرجاع

Widget — العنصر، للتسلسل

---

addItem(text, value, selected)

تضيف هذه السمة عنصرًا جديدًا يمكن اختياره.

المَعلمات

الاسم	النوع	الوصف
text	Object	النص الذي سيتم عرضه لهذا العنصر يتم تلقائيًا تحويل الوسيطات الأساسية غير السلسلة إلى سلاسل.
value	Object	قيمة إدخال النموذج التي يتم إرسالها من خلال وظيفة رد الاتصال. يتم تلقائيًا تحويل الوسيطات الأساسية غير السلسلة إلى سلاسل.
selected	Boolean	تُستخدَم لتحديد ما إذا كان العنصر محدَّدًا تلقائيًا. إذا كان حقل الإدخال الخاص بالاختيار يقبل قيمة واحدة فقط (مثل أزرار الاختيار أو القائمة المنسدلة)، اضبط هذا الحقل لعنصر واحد فقط.

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

addMultiSelectItem(text, value, selected, startIconUri, bottomText)

تضيف هذه السمة عنصرًا جديدًا يمكن اختياره، وذلك للقوائم التي تتيح تحديد عناصر متعددة.

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('multiselect')
        .setTitle('A multi select input example.')
        .addMultiSelectItem(
            'Contact 1',
            'contact-1',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact one description',
            )
        .addMultiSelectItem(
            'Contact 2',
            'contact-2',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact two description',
            )
        .addMultiSelectItem(
            'Contact 3',
            'contact-3',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact three description',
            )
        .addMultiSelectItem(
            'Contact 4',
            'contact-4',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact four description',
            )
        .addMultiSelectItem(
            'Contact 5',
            'contact-5',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact five description',
        );

المَعلمات

الاسم	النوع	الوصف
text	Object	النص الذي سيتم عرضه لهذا العنصر يتم تلقائيًا تحويل الوسيطات الأساسية غير السلسلة إلى سلاسل.
value	Object	قيمة إدخال النموذج التي يتم إرسالها من خلال وظيفة رد الاتصال. يتم تلقائيًا تحويل الوسيطات الأساسية غير السلسلة إلى سلاسل.
selected	Boolean	تُستخدَم لتحديد ما إذا كان العنصر محدَّدًا تلقائيًا. إذا كان حقل الإدخال الخاص بالاختيار يقبل قيمة واحدة فقط (مثل أزرار الاختيار أو القائمة المنسدلة)، اضبط هذا الحقل لعنصر واحد فقط.
startIconUri	Object	بالنسبة إلى قوائم الاختيار المتعدد، يمثّل هذا السمة عنوان URL للرمز المعروض بجانب حقل نص العنصر. يتوافق مع ملفات PNG وJPEG.
bottomText	Object	بالنسبة إلى قوائم الاختيار المتعدد، يكون الوصف أو التصنيف النصي معروضًا أسفل حقل النص الخاص بالعنصر.

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setExternalDataSource(action)

تضبط هذه السمة مصدر بيانات خارجيًا، مثل قاعدة بيانات ارتباطية.

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('contacts')
        .setTitle('Selected contacts')
        .addMultiSelectItem(
            'Contact 3',
            'contact-3',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact three description',
            )
        .setMultiSelectMaxSelectedItems(5)
        .setMultiSelectMinQueryLength(2)
        .setExternalDataSource(
            CardService.newAction().setFunctionName('getContacts'),
        );

المَعلمات

الاسم	النوع	الوصف
action	Action	مصدر البيانات الخارجية

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setFieldName(fieldName)

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

المَعلمات

الاسم	النوع	الوصف
fieldName	String	اسم مصدر الإدخال هذا

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setId(id)

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

المَعلمات

الاسم	النوع	الوصف
id	String	معرّف الأداة، ويمكن أن يتضمّن 64 حرفًا بحدّ أقصى وبالتنسيق `[a-zA-Z0-9-]+`.

الإرجاع

Widget: هذا العنصر، للتسلسل

---

setMultiSelectMaxSelectedItems(maxSelectedItems)

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

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('multiselect')
        .setTitle('A multi select input example.')
        .setMultiSelectMaxSelectedItems(3)
        .addMultiSelectItem(
            'Contact 1',
            'contact-1',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact one description',
            )
        .addMultiSelectItem(
            'Contact 2',
            'contact-2',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact two description',
            )
        .addMultiSelectItem(
            'Contact 3',
            'contact-3',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact three description',
            )
        .addMultiSelectItem(
            'Contact 4',
            'contact-4',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact four description',
            )
        .addMultiSelectItem(
            'Contact 5',
            'contact-5',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact five description',
        );

المَعلمات

الاسم	النوع	الوصف
maxSelectedItems	Integer	تمثّل هذه السمة الحد الأقصى لعدد السلع.

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setMultiSelectMinQueryLength(queryLength)

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

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('multiselect')
        .setTitle('A multi select input example.')
        .setMultiSelectMinQueryLength(1)
        .addMultiSelectItem(
            'Contact 1',
            'contact-1',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact one description',
            )
        .addMultiSelectItem(
            'Contact 2',
            'contact-2',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact two description',
            )
        .addMultiSelectItem(
            'Contact 3',
            'contact-3',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact three description',
            )
        .addMultiSelectItem(
            'Contact 4',
            'contact-4',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact four description',
            )
        .addMultiSelectItem(
            'Contact 5',
            'contact-5',
            false,
            'https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png',
            'Contact five description',
        );

المَعلمات

الاسم	النوع	الوصف
queryLength	Integer	عدد أحرف النص

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setOnChangeAction(action)

تضبط هذه السمة Action ليتم تنفيذها كلما تغيّر إدخال التحديد.

المَعلمات

الاسم	النوع	الوصف
action	Action	الإجراء المطلوب اتّخاذه

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setPlatformDataSource(platformDataSource)

تضبط هذه السمة مصدر بيانات من Google Workspace. تُستخدَم لتعبئة العناصر في قائمة اختيار متعدّد.

const multiSelect =
    CardService.newSelectionInput()
        .setType(CardService.SelectionInputType.MULTI_SELECT)
        .setFieldName('contacts')
        .setTitle('Selected contacts')
        .setPlatformDataSource(
            CardService.newPlatformDataSource().setCommonDataSource(
                CardService.CommonDataSource.USER,
                ),
        );

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

المَعلمات

الاسم	النوع	الوصف
platformDataSource	PlatformDataSource	مصدر البيانات

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setTitle(title)

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

المَعلمات

الاسم	النوع	الوصف
title	String	تمثّل هذه السمة عنوان حقل الإدخال.

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setType(type)

تضبط هذه السمة نوع الإدخال. القيمة التلقائية هي CHECKBOX.

المَعلمات

الاسم	النوع	الوصف
type	SelectionInputType	نوع التحديد

الإرجاع

SelectionInput: هذا العنصر، للتسلسل

---

setVisibility(visibility)

تضبط هذه السمة مستوى ظهور الأداة. القيمة التلقائية هي `VISIBLE`.

المَعلمات

الاسم	النوع	الوصف
visibility	Visibility	Visibility الأداة

الإرجاع

Widget — العنصر، للتسلسل