Checkbox 复选框
xy-checkbox、xy-checkbox-group 和 xy-checkbox-button 用于多选状态录入。它适合权限勾选、能力开关集合、批量过滤条件和列表配置选择这类场景。
基础用法
单个 xy-checkbox 适合布尔或枚举值切换，支持 true-value / false-value。
基础用法双向绑定
支持布尔值和枚举值的双向绑定，可通过 border 属性添加边框样式。
CheckboxGroup 与 options
多选数组优先使用 xy-checkbox-group，当选项来自配置或接口时可直接传 options。
当前选中：api
中间态与全选
indeterminate 常用于“部分选中”的汇总状态，它只负责视觉呈现，具体逻辑由业务层控制。
当前选择：上海
最少/最多限制
min / max 适合权限范围、能力包和筛选维度这类需要约束选择数量的场景。
至少保留 1 项，最多选择 2 项。当前：read
CheckboxButton 按钮化多选
xy-checkbox-button 更适合维度筛选、标签式多选和更紧凑的筛选区。
禁用与边框样式
disabled 和 border 更适合设置面板、强调型选项和不可编辑回显场景。
无文案与可访问性
当复选框没有可见文字时，建议补 aria-label；如果它和一个受控区域有关联，也可以加上 aria-controls。
无可见文案时，建议补 `aria-label`；如果组件会影响某个区域，也可以补 `aria-controls`。 当前状态：星标 关闭，归档 开启
表单场景
放在 xy-form-item 内部时，xy-checkbox-group 会在值变化后参与 change 校验。
行为约定
- 单个
xy-checkbox默认走布尔值切换，也可以通过true-value / false-value映射到后端枚举值。 - 在 group 场景里，组件会自动基于
modelValue数组增删当前值。 min / max只在 group 场景中生效，用于限制最少/最多可选项数。
API
Checkbox Attributes
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
model-value | 当前值 | CheckboxValue | undefined |
value | 当前项值 | CheckboxValue | undefined |
label | 展示文案 | string | number | boolean | undefined |
indeterminate | 是否为中间态，仅控制样式 | boolean | false |
disabled | 是否禁用 | boolean | false |
checked | 非受控场景下是否默认选中 | boolean | false |
name | 原生 name | string | undefined |
true-value | 选中时的值 | string | number | true |
false-value | 未选中时的值 | string | number | false |
id | 原生 id | string | undefined |
border | 是否显示边框样式 | boolean | false |
size | 组件尺寸 | ComponentSize | 跟随全局配置 |
tabindex | 原生 tabindex | string | number | undefined |
validate-event | 是否触发表单校验 | boolean | true |
aria-label | 原生 aria-label | string | undefined |
aria-controls | 原生 aria-controls | string | undefined |
Checkbox Events
| 事件 | 说明 | 参数 |
|---|---|---|
update:model-value | 选中值变化时触发 | CheckboxValueChangeHandler |
change | 用户切换时触发 | CheckboxValueChangeHandler |
Checkbox Slots
| 插槽 | 说明 |
|---|---|
default | 自定义标签内容 |
CheckboxGroup Attributes
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
model-value | 当前选中值数组 | CheckboxGroupValue | [] |
options | 选项数组 | CheckboxOption[] | [] |
type | 组内渲染类型 | CheckboxGroupProps["type"] | 'checkbox' |
disabled | 是否整体禁用 | boolean | false |
size | 组内尺寸 | ComponentSize | 跟随全局配置 |
name | 原生 name | string | 自动生成 |
direction | 排列方向 | CheckboxGroupDirection | 'horizontal' |
validate-event | 是否触发表单校验 | boolean | true |
aria-label | group 的辅助标签 | string | 'checkbox-group' |
fill | 按钮化激活态背景色 | string | undefined |
text-color | 按钮化激活态文字色 | string | undefined |
min | 最少可选项数 | number | undefined |
max | 最多可选项数 | number | undefined |
CheckboxGroup Events
| 事件 | 说明 | 参数 |
|---|---|---|
update:model-value | 选中值数组变化时触发 | CheckboxGroupValueChangeHandler |
change | 用户切换时触发 | CheckboxGroupValueChangeHandler |
CheckboxGroup Slots
| 插槽 | 说明 |
|---|---|
default | 自定义渲染整组 xy-checkbox / xy-checkbox-button；存在时会覆盖 options 的默认渲染 |
CheckboxOption
| 字段 | 说明 | 类型 | 默认值 |
|---|---|---|---|
label | 展示文案 | string | — |
value | 选项值 | string | number | boolean | — |
disabled | 是否禁用 | boolean | false |
description | 选项副文案 | string | undefined |