# 下拉选择-多选组件 下拉选择-多选组件支持自定义多选菜单的选项文本、图标等，是一种交互组件，需嵌入在表单容器中使用。 **注意事项**：本文档介绍下拉选择-多选组件的 JSON 2.0 结构，要查看历史 JSON 1.0 结构，参考[下拉选择-多选](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/interactive-components/multi-select-dropdown-menu)。 ![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/4be44d6bee1193690adb76ddbf6271ee_41d9tuYXZd.gif?height=208&lazyload=true&maxWidth=400&width=780) ## 嵌套规则 下拉选择-多选组件仅支持内嵌在表单容器中使用，通过表单容器的“提交”按钮提交选择的内容。了解表单容器及其交互配置，参考[表单容器](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-components/containers/form-container)。 ## 组件属性 ### JSON 结构 下拉选择-多选组件的完整 JSON 2.0 结构如下所示： ```json { "schema": "2.0", "body": { "elements": [ { "tag": "form", // 表单容器的标签。下拉选择-多选组件必须放置在表单容器中使用。 "elements": [ { "tag": "multi_select_static", // 下拉选择-多选组件的标签。 "element_id": "custom_id", // 操作组件的唯一标识。用于在调用组件相关接口中指定组件。需开发者自定义。 "margin": "0px 0px 0px 0px", // 组件的外边距，默认值 "0"，支持范围 [-99,99]px。 "type": "default", // 组件边框样式。默认值 default。 "name": "multi_select_departments", // 表单容器中下拉选择-多选组件的自定义唯一标识，用于识别用户提交的是哪个组件的数据。 "required": true, // 选项是否必填。当多选组件内嵌在表单容器时，该属性可用。其它情况将报错或不生效。 "disabled": false, // 选项是否禁用。 "placeholder": { // 下拉选择组件内的占位文本。 "tag": "plain_text", "content": "默认提示文本" }, "width": "default", // 下拉选择组件的宽度。 "behaviors": [ { // 为下拉选择组件配置回传交互。 "type": "callback", "value": { // 回传交互数据。支持 object 数据类型。开放平台 SDK 仅支持 object 类型的回传交互数据。 "key_1": "value_1" } } ], "selected_values": [], // 选项初始值。数组项的值需要和 options.value 对应。 "options": [ // 选项配置 { "text": { // 选项名称 "tag": "plain_text", "content": "我是交互组件" }, "icon": { // 添加图标作为选项前缀图标。支持自定义或使用图标库中的图标。 "tag": "standard_icon", // 图标类型。 "token": "chat-forbidden_outlined", // 图标的 token。仅在 tag 为 standard_icon 时生效。 "color": "orange", // 图标颜色。仅在 tag 为 standard_icon 时生效。 "img_key": "img_v2_38811724" // 图片的 key。仅在 tag 为 custom_icon 时生效。 }, "value": "selectDemo1" // 选项回调值，支持 string 类型数据。 } ], "confirm": { // 二次确认弹窗配置 "title": { "tag": "plain_text", "content": "弹窗标题" }, "text": { "tag": "plain_text", "content": "弹窗正文文案" } } }, { // 以下为表单容器中内嵌的分栏、按钮等组件属性，详情参考表单容器文档。 "tag": "column_set", "columns": [ { "tag": "column", "width": "auto", "elements": [ { "tag": "button", "text": { "tag": "plain_text", "content": "提交" }, "type": "primary", "width": "default", "form_action_type": "submit", "name": "Button_m8gyoz81" } ], "vertical_align": "top" }, { "tag": "column", "width": "auto", "elements": [ { "tag": "button", "text": { "tag": "plain_text", "content": "取消" }, "type": "default", "width": "default", "form_action_type": "reset", "name": "Button_m8gyoz82" } ], "vertical_align": "top" } ] } ], "padding": "4px 0px 4px 0px", "margin": "0px 0px 0px 0px", "name": "Form_m8gyoz80" } ] } } ``` ### 字段说明 下拉选择-多选组件的字段说明如下表。 字段 | 是否必填 | 类型 | 默认值 | 说明 ---|---|---|---|--- tag | 是 | String | / | 组件的标签。下拉选择-多选组件取固定值 `multi_select_static`。 element_id | 否 | String | 空 | 操作组件的唯一标识。JSON 2.0 新增属性。用于在调用[组件相关接口](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/cardkit-v1/card-element/create)中指定组件。在同一张卡片内，该字段的值全局唯一。仅允许使用字母、数字和下划线，必须以字母开头，不得超过 20 字符。 margin | 否 | String | 0 | 组件的外边距。JSON 2.0 新增属性。值的取值范围为 [-99,99]px。可选值：
- 单值，如 "10px"，表示组件的四个外边距都为 10 px。
- 双值，如 "4px 0"，表示组件的上下外边距为 4 px，左右外边距为 0 px。使用空格间隔（边距为 0 时可不加单位）。
- 多值，如 "4px 0 4px 0"，表示组件的上、右、下、左的外边距分别为 4px，12px，4px，12px。使用空格间隔。 type | 否 | String | default | 组件边框样式。可选值：
- default：带边框样式
- text：不带边框的纯文本样式 name | 是 | string | 空 | 表单容器中组件的唯一标识。当多选组件内嵌在表单容器时，该属性生效，用于识别用户提交的数据属于哪个组件。
**注意**：当多选组件嵌套在表单容器中时，该字段必填且需在卡片全局内唯一。 placeholder | 否 | Object | 空 | 用户未选择选项时，下拉选择组件内的占位文本。 └ tag | 是 | String | plain_text | 占位提示的标签。固定值为 `plain_text`。 └ content | 否 | String | 请选择 | 占位文本的内容，最多支持 100 个字符。 width | 否 | String | default | 下拉选择组件的宽度。支持以下枚举值：
- default：默认宽度：
- 当组件带边框时（即 `"type":"default"`），默认宽度值固定为 282 px
- 当组件不带边框时（即 `"type":"text"`），组件宽度自适应选择器的内容宽度
- fill：组件宽度将撑满父容器宽度
- [100,∞)px：自定义固定数值宽度，如 200px。最小值为 100px。超出父容器宽度时，按撑满父容器宽度展示 behaviors | 是 | Struct | / | 配置交互类型和具体交互行为。详情参考[配置卡片交互](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions)中 behaviors 的字段说明。 required | 否 | Bool | true | 多选组件的选项是否必选。当组件内嵌在表单容器中时，该属性可用。其它情况将报错或不生效。可取值：
- true：多选组件必选。当用户点击表单容器的“提交”时，未选择多选选项，则前端提示“有必填项未填写”，不会向开发者的服务端发起回传请求。
- false：多选组件可选。当用户点击表单容器的“提交”时，未选择多选选项，仍提交表单容器中的数据。 disabled | 否 | Bool | false | 是否禁用该多选组件。可选值：
- true：禁用该多选组件，组件展示自定义的占位文本或选项初始值，且终端用户不可修改交互
- false：多选组件保持可用状态 selected_values | 否 | Array of string | 空 | 多选组件默认选中的选项。数组项的值需要和 `options.value` 对应。 options | 否 | Array of objects | / | 选项值配置。按选项数组的顺序展示选项内容。 └ text | 是 | Object | 空 | 选项名称。为空时展示空白选项。JSON 结构如下所示，使用 plain text 对象描述：
```json
"text": {
// 选项名称标签。固定值为 plain_text。
"tag": "plain_text",
// 选项名称文本。
"content": "我是一个选项"
}
``` └ icon | 否 | Object | / | 添加图标作为选项前缀图标。支持自定义或使用图标库中的图标。 └ └ tag | 否 | String | / | 图标类型的标签。可取值：
- `standard_icon`：使用图标库中的图标。
- `custom_icon`：使用自定义图片作为图标。 └ └ token | 否 | String | / | 图标库中图标的 token。当 `tag` 为 `standard_icon` 时生效。枚举值参见[图标库](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-icons)。 └ └ color | 否 | String | / | 图标的颜色。支持设置线性和面性图标（即 token 末尾为 `outlined` 或 `filled` 的图标）的颜色。当 `tag` 为 `standard_icon` 时生效。枚举值参见[颜色枚举值](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/enumerations-for-fields-related-to-color)。 └ └ img_key | 否 | String | / | 自定义前缀图标的图片 key。当 `tag` 为 `custom_icon` 时生效。
图标 key 的获取方式：调用[上传图片](https://open.larksuite.com/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/image/create)接口，上传用于发送消息的图片，并在返回值中获取图片的 image_key。 └ value | 是 | String | / | 自定义选项回调值。当用户点击交互组件的选项后，会将 value 的值返回给接收回调数据的服务器。后续你可以通过服务器接收的 value 值进行业务处理。
**注意**：同一个选择组件内，各选项的 value 值不可重复，否则将无法识别用户点击的是哪个选项。 confirm | 否 | Struct | 默认不生效此属性。 | 二次确认弹窗配置。指在用户提交时弹出二次确认弹窗提示；只有用户点击确认后，才提交输入的内容。该字段默认提供了确认和取消按钮，你只需要配置弹窗的标题与内容即可。
**注意**：confirm 字段仅在用户点击包含提交属性的按钮时才会触发二次确认弹窗。 └ title | 是 | Struct | / | 二次确认弹窗标题。 └ └ tag | 是 | String | plain_text | 二次确认弹窗标题文本的标签。固定取值为 `plain_text`。 └ └ content | 是 | String | / | 二次确认弹窗标题的内容。 └ text | 是 | Struct | / | 二次确认弹窗的文本内容。 └ └ tag | 是 | String | plain_text | 二次确认弹窗文本的标签。固定取值为 `plain_text`。 └ └ content | 是 | String | / | 二次确认弹窗文本的具体内容。 ## 回调示例 下拉选择-多选组件默认拥有交互能力。当用户点击表单容器的提交按钮时，你在开发者后台配置的请求地址将会收到回调数据。 **注意事项**：下拉选择-多选组件包含多个选项，因此你需配置自定义回传参数，以区分用户提交的是哪个选项。详情参考[配置卡片交互](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/configuring-card-interactions)。 - 如果你添加的是新版卡片回传交互回调(`card.action.trigger`)，卡片将默认将回传如下所示的交互事件。详情参考[卡片回传交互回调](https://open.larksuite.com/document/uAjLw4CM/ukzMukzMukzM/feishu-cards/card-callback-communication)。 - 如果你添加的是旧版卡片回传交互回调(`card.action.trigger_v1`)，可参考[消息卡片回传交互（旧）](https://open.larksuite.com/document/ukTMukTMukTM/uYzM3QjL2MzN04iNzcDN/configuring-card-callbacks/card-callback-structure)了解回调结构。 新版卡片回传交互(`card.action.trigger`)下拉选择-多选组件回调示例： ```json { "schema": "2.0", // 回调的版本 "header": { // 回调基本信息 "event_id": "f7984f25108f8137722bb63c*****", // 回调的唯一标识 "token": "066zT6pS4QCbgj5Do145GfDbbag*****", // 应用的 Verification Token "create_time": "1603977298000000", // 回调发送的时间，接近回调发生的时间 "event_type": "card.action.trigger", // 回调类型卡片交互场景中，固定为 "card.action.trigger" "tenant_key": "2df73991750*****", // 应用归属的 tenant key，即租户唯一标识 "app_id": "cli_a5fb0ae6a4******" // 应用的 App ID }, "event": { // 回调的详细信息 "operator": { // 回调触发者信息 "tenant_key": "2df73991750*****", // 回调触发者的 tenant key，即租户唯一标识 "user_id": "867*****", // 回调触发者的 user ID。当应用开启“获取用户 user ID”权限后，该参数返回 "open_id": "ou_3c14f3a59eaf2825dbe25359f15*****", // 回调触发者的 Open ID "union_id": "on_cad4860e7af114fb4ff6c5d496d*****" // 回调触发者的 Union ID }, "token": "c-295ee57216a5dc9de90fefd0aadb4b1d7d******", // 更新卡片用的凭证，有效期为 30 分钟，最多可更新 2 次 "action": { // 用户点击表单容器中的提交按钮后回传的数据 "tag": "button", // 按钮组件标签 "timezone": "Asia/Shanghai", // 用户当前所在地区的时区 "form_value": { // 表单容器内用户提交的数据 "multi_select_departments": [ // 多选组件内用户提交的选项的回传数据。需开发者通过 options.value 自定义该值 "selectDemo1", "selectDemo2" ] }, "name": "Button_lrztw8x3" // 如果按钮内嵌在表单容器中，将返回该值。表示按钮组件的表单项标识，开发者可自定义 } }, "host": "im_message", // 卡片展示场景 "context": { // 卡片展示场景相关信息 "open_message_id": "om_574d639e4a44e4dd646eaf628e2*****", // 卡片所在的消息 ID "open_chat_id": "oc_e4d2605ca917e695f54f11aaf56*****" // 卡片所在的会话 ID } } ``` ## 示例代码 以下 JSON 2.0 结构的示例代码可实现如下图所示的卡片效果。 ![](//sf16-sg.larksuitecdn.com/obj/open-platform-opendoc-sg/4be44d6bee1193690adb76ddbf6271ee_af1qOua3DK.gif?height=208&lazyload=true&maxWidth=400&width=780) ```json { "schema": "2.0", "body": { "elements": [ { "tag": "form", "elements": [ { "tag": "column_set", "flex_mode": "none", "horizontal_spacing": "default", "background_style": "default", "columns": [ { "tag": "column", "elements": [ { "tag": "multi_select_static", "type": "default", "name": "multi_select_departments", "placeholder": { "tag": "plain_text", "content": "默认提示文本" }, "width": "fill", "required": true, "disabled": false, "selected_values": [], "behaviors": [ { "type": "callback", "value": { "select_static": "click" } } ], "options": [ { "text": { "tag": "plain_text", "content": "选项1" }, "icon": { "tag": "standard_icon", "token": "chat-forbidden_outlined", "color": "orange" }, "value": "selectDemo1" }, { "text": { "tag": "plain_text", "content": "选项2" }, "icon": { "tag": "standard_icon", "token": "chat-forbidden_outlined", "color": "orange" }, "value": "selectDemo2" } ] } ], "width": "weighted", "weight": 1 } ] }, { "tag": "column_set", "flex_mode": "none", "background_style": "default", "horizontal_spacing": "default", "columns": [ { "tag": "column", "width": "auto", "vertical_align": "top", "elements": [ { "tag": "button", "text": { "tag": "plain_text", "content": "提交" }, "type": "primary", "action_type": "form_submit", "name": "Button_lrztw8x3" } ] }, { "tag": "column", "width": "auto", "vertical_align": "top", "elements": [ { "tag": "button", "text": { "tag": "plain_text", "content": "取消" }, "type": "default", "action_type": "form_reset", "name": "Button_lrztw8x4" } ] } ] } ], "name": "Form_lrztw8x2" } ] } } ```