Class SelectionInput

选择输入

一个输入字段，允许从一组预定义选项中进行选择。

仅支持对 SelectionInputType.DROP_DOWN 和 SelectionInputType.MULTI_SELECT 菜单进行表单提交验证。当 Action.setAllWidgetsAreRequired(allWidgetsAreRequired) 设置为 true 或通过 Action.addRequiredWidget(requiredWidget) 指定此 widget 时，除非选择一个值，否则提交操作会被阻止。

适用于 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添加可在 widget 上执行的事件操作。
addItem(text, value, selected)SelectionInput添加可供选择的新项。
addMultiSelectItem(text, value, selected, startIconUri, bottomText)SelectionInput为多选菜单添加可供选择的新项。
setExternalDataSource(action)SelectionInput设置外部数据源，例如关系型数据库。
setFieldName(fieldName)SelectionInput设置在发生界面互动时生成的事件对象中用于标识相应选择输入的键。
setId(id)Widget设置用于标识要发生变异的 widget 的唯一 ID。
setMultiSelectMaxSelectedItems(maxSelectedItems)SelectionInput设置用户可选择的商品数量上限。
setMultiSelectMinQueryLength(queryLength)SelectionInput设置用户输入多少个文本字符后，应用才会查询自动补全功能并在卡片上显示建议的项目。
setOnChangeAction(action)SelectionInput设置在选择输入发生变化时执行的 Action。
setPlatformDataSource(platformDataSource)SelectionInput设置来自 Google Workspace 的数据源。
setTitle(title)SelectionInput设置要显示在输入字段前面的标题。
setType(type)SelectionInput设置相应输入的类型。
setVisibility(visibility)Widget设置 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,
                )
            )
        );

参数

名称类型说明
dataSourceConfigDataSourceConfig要应用于选择输入的相应数据源配置。

返回

SelectionInput - 此对象，用于链式调用。

addEventAction(eventAction)

添加可在 widget 上执行的事件操作。

参数

名称类型说明
eventActionEventAction要添加的 EventAction。

返回

Widget - 用于链式调用的对象。

addItem(text, value, selected)

添加可供选择的新项。

参数

名称类型说明
textObject要针对相应项显示的文本。非字符串原始实参会自动转换为字符串。
valueObject通过回调发送的表单输入值。非字符串原始实参会自动转换为字符串。
selectedBoolean相应项是否默认处于选中状态。如果选择输入仅接受一个值（例如对于单选按钮或下拉菜单），则仅为一个项设置此字段。

返回

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',
        );

参数

名称类型说明
textObject要针对相应项显示的文本。非字符串原始实参会自动转换为字符串。
valueObject通过回调发送的表单输入值。非字符串原始实参会自动转换为字符串。
selectedBoolean相应项是否默认处于选中状态。如果选择输入仅接受一个值（例如对于单选按钮或下拉菜单），则仅为一个项设置此字段。
startIconUriObject对于多选菜单，显示在商品文本字段旁边的图标的网址。支持 PNG 和 JPEG 文件。
bottomTextObject对于多选菜单，显示在商品文本字段下方的文本说明或标签。

返回

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'),
        );

参数

名称类型说明
actionAction外部数据源。

返回

SelectionInput - 此对象，用于链式调用。

setFieldName(fieldName)

设置在发生界面互动时生成的事件对象中用于标识相应选择输入的键。对用户不可见。必需，必须是唯一的。

参数

名称类型说明
fieldNameString要为此输入源分配的名称。

返回

SelectionInput - 此对象，用于链式调用。

setId(id)

设置用于标识要发生变异的 widget 的唯一 ID。只有在插件中支持 widget 突变。

参数

名称类型说明
idString微件的 ID，最多可包含 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',
        );

参数

名称类型说明
maxSelectedItemsInteger项目数量上限。

返回

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',
        );

参数

名称类型说明
queryLengthInteger文本字符数。

返回

SelectionInput - 此对象，用于链式调用。

setOnChangeAction(action)

设置在选择输入发生变化时执行的 Action。

参数

名称类型说明
actionAction要执行的操作。

返回

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 加购项。

参数

名称类型说明
platformDataSourcePlatformDataSource数据源。

返回

SelectionInput - 此对象，用于链式调用。

setTitle(title)

设置显示在输入字段前面的标题。

参数

名称类型说明
titleString输入字段标题。

返回

SelectionInput - 此对象，用于链式调用。

setType(type)

设置相应输入的类型。默认为 CHECKBOX。

参数

名称类型说明
typeSelectionInputType选择类型。

返回

SelectionInput - 此对象，用于链式调用。

setVisibility(visibility)

设置 widget 的可见性。默认值为 `VISIBLE`。

参数

名称类型说明
visibilityVisibility微件的 Visibility。

返回

Widget - 用于链式调用的对象。