Checkbox 多选框
组件类型
纵向多选框
横向多选框
带全选多选框
组件状态
多选框状态
组件样式
勾选样式
勾选显示位置
非通栏多选样式
组件规格
多选框尺寸规格
Checkbox Props
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| block | Boolean | true | 是否为块级元素 | N |
| borderless | Boolean | undefined | 是否开启无边框模式 | N |
| checkAll | Boolean | false | 用于标识是否为「全选选项」。单独使用无效，需在 CheckboxGroup 中使用 | N |
| checked | Boolean | false | 是否选中。支持语法糖 v-model 或 v-model:checked | N |
| defaultChecked | Boolean | false | 是否选中。非受控属性 | N |
| content | String / Slot / Function | - | 多选框内容。TS 类型：string \| TNode。通用类型定义 | N |
| contentDisabled | Boolean | - | 是否禁用组件内容（content）触发选中 | N |
| default | String / Slot / Function | - | 多选框内容，同 label。TS 类型：string \| TNode。通用类型定义 | N |
| disabled | Boolean | undefined | 是否禁用组件。如果父组件存在 CheckboxGroup，默认值由 CheckboxGroup.disabled 控制。优先级：Checkbox.disabled > CheckboxGroup.disabled > Form.disabled | N |
| icon | String / Boolean / Array | 'circle' | 自定义选中图标和非选中图标。使用 Array 时表示：[选中态图标，非选中态图标]。使用 String 时，值为 circle 表示填充圆形图标、值为 line 表示描边型图标、值为 rectangle 表示填充矩形图标。TS 类型：'circle' \| 'line' \| 'rectangle' \| boolean \| Array<TNode \| String>。通用类型定义 | N |
| indeterminate | Boolean | false | 是否为半选 | N |
| label | String / Slot / Function | - | 主文案。TS 类型：string \| TNode。通用类型定义 | N |
| maxContentRow | Number | 5 | 内容最大行数限制 | N |
| maxLabelRow | Number | 3 | 主文案最大行数限制 | N |
| name | String | - | HTML 元素原生属性 | N |
| placement | String | left | 多选框和内容相对位置。可选项：left/right | N |
| readonly | Boolean | undefined | 只读状态 | N |
| value | String / Number / Boolean | - | 多选框的值。TS 类型：string \| number \| boolean | N |
| onChange | Function | TS 类型：(checked: boolean, context: { e: Event }) => void值变化时触发 | N |
Checkbox Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (checked: boolean, context: { e: Event }) | 值变化时触发 |
CheckboxGroup Props
| 名称 | 类型 | 默认值 | 描述 | 必传 |
|---|---|---|---|---|
| borderless | Boolean | false | 是否开启无边框模式。优先级低于 Checkbox.borderless | N |
| disabled | Boolean | undefined | 是否禁用组件。优先级：Form.disabled < CheckboxGroup.disabled < Checkbox.disabled | N |
| keys | Object | - | 用来定义 value / label / disabled 在 options 中对应的字段别名。TS 类型：KeysType。通用类型定义 | N |
| max | Number | undefined | 支持最多选中的数量 | N |
| name | String | - | 统一设置内部复选框 HTML 属性 | N |
| options | Array | - | 以配置形式设置子元素。示例1：['北京', '上海'] ，示例2: [{ label: '全选', checkAll: true }, { label: '上海', value: 'shanghai' }]。checkAll 值为 true 表示当前选项为「全选选项」。TS 类型：Array<CheckboxOption> type CheckboxOption = string \| number \| CheckboxOptionObj interface CheckboxOptionObj extends TdCheckboxProps { text?: string; }。详细类型定义 | N |
| readonly | Boolean | undefined | 只读状态 | N |
| value | Array | [] | 选中值。支持语法糖 v-model 或 v-model:value。TS 类型：T type CheckboxGroupValue = Array<string \| number \| boolean>。详细类型定义 | N |
| defaultValue | Array | [] | 选中值。非受控属性。TS 类型：T type CheckboxGroupValue = Array<string \| number \| boolean>。详细类型定义 | N |
| onChange | Function | TS 类型：(value: T, context: CheckboxGroupChangeContext) => void值变化时触发。 context.current 表示当前变化的数据项，如果是全选则为空；context.type 表示引起选中数据变化的是选中或是取消选中，context.option 表示当前变化的数据项。详细类型定义。interface CheckboxGroupChangeContext { e: Event; current: string \| number; option: CheckboxOption \| TdCheckboxProps; type: 'check' \| 'uncheck' } | N |
CheckboxGroup Events
| 名称 | 参数 | 描述 |
|---|---|---|
| change | (value: T, context: CheckboxGroupChangeContext) | 值变化时触发。context.current 表示当前变化的数据项，如果是全选则为空；context.type 表示引起选中数据变化的是选中或是取消选中，context.option 表示当前变化的数据项。详细类型定义。interface CheckboxGroupChangeContext { e: Event; current: string \| number; option: CheckboxOption \| TdCheckboxProps; type: 'check' \| 'uncheck' } |
CSS Variables
组件提供了下列 CSS 变量，可用于自定义样式。
| 名称 | 默认值 | 描述 |
|---|---|---|
| --td-checkbox-bg-color | @bg-color-container | - |
| --td-checkbox-border-color | @component-stroke | - |
| --td-checkbox-description-color | @text-color-secondary | - |
| --td-checkbox-description-disabled-color | @text-color-disabled | - |
| --td-checkbox-description-line-height | 22px | - |
| --td-checkbox-font-size | 16px | - |
| --td-checkbox-icon-checked-color | @brand-color | - |
| --td-checkbox-icon-color | var(--td-border-level-2-color, @gray-color-4) | - |
| --td-checkbox-icon-disabled-bg-color | @bg-color-component-disabled | - |
| --td-checkbox-icon-disabled-color | @brand-color-disabled | - |
| --td-checkbox-icon-size | 24px | - |
| --td-checkbox-tag-active-bg-color | @brand-color-light | - |
| --td-checkbox-tag-active-color | @brand-color | - |
| --td-checkbox-tag-bg-color | @bg-color-component | - |
| --td-checkbox-title-color | @text-color-primary | - |
| --td-checkbox-title-disabled-color | @text-color-disabled | - |
| --td-checkbox-title-line-height | 24px | - |
| --td-checkbox-vertical-padding | 16px | - |
何时使用
当用户需要从一组数据选择多个选项时使用。
组件搭配使用
多选框与索引、搜索框组合使用，便于用户从大量的选项中，快速地找到目标选项。
推荐/慎用示例
带有详情信息的选项，建议就近展开相关内容，不建议在触发一个弹窗。
在选项较多的场景下执行多选时，建议展示用户已选数量。
相似组件
| 组件名 | 何时使用 |
|---|---|
| 单选框 | 当用户需要从一组数据选择一个选项时使用。 |
