简介

fs-form-checkbox 是表单项多选控件，用于在一组选项中进行多项选择。基于 ava-ui/fxui/fs-checkbox-group 和 ava-ui/fxui/fs-checkbox 封装，使用胶囊样式（capsule），横向排列。可独立使用或配合 fs-form 使用。

使用方法

局部引入时，在页面的 index.json 中配置：

"usingComponents": {
  "fs-form-checkbox": "/avaui-sub/fs-form/fs-form-checkbox/index"
}

配合 fs-form 使用时：

"usingComponents": {
  "fs-form": "/avaui-sub/fs-form/index",
  "fs-form-item": "/avaui-sub/fs-form/fs-form-item/index",
  "fs-form-checkbox": "/avaui-sub/fs-form/fs-form-checkbox/index"
}

PWC（自定义组件/插件）使用：仅 usingComponents 注册方式使用 avaComponent:// 协议，其他用法一致。

单独使用时：

"usingComponents": {
  "fs-form-checkbox": "avaComponent://avaui-sub/fs-form/fs-form-checkbox/index"
}

代码演示

1. 基础用法

通过 value 绑定当前选中值数组，通过 options 配置选项列表。

2. 禁用状态

通过 disabled 属性禁用整个多选组，或在 options 中单独禁用某个选项。

3. 下拉选择模式

通过 mode="dropdown" 启用下拉选择模式，组件将显示为类似 fs-form-date 的样式，点击后弹出多选选择器。选中的选项名称以逗号分隔显示。

4. 配合 fs-form 使用

fs-form-checkbox 可以作为 fs-form-item 的内容控件，支持表单校验和数据收集。

---

API

fs-form-checkbox 属性

参数	说明	类型	可选值	默认值
value	当前选中的值数组	Array	—	[]
options	选项列表	Array	—	[]
disabled	是否禁用	Boolean	—	false
mode	显示模式	String	inline/dropdown	inline
placeholder	下拉模式的占位提示文字	String	—	''
pickerTitle	下拉选择器标题	String	—	''
bordered	是否显示边框，仅下拉模式生效	Boolean	—	false
showSearch	是否显示搜索框（下拉模式）	Boolean	—	false
checkboxType	选项样式类型，下拉模式仅 card 生效	String	capsule/card	capsule
direction	内联模式选项排列方向	String	row/column	row

options 数组项

字段	说明	类型
label	选项显示文本	String
value	选项值	any
disabled	是否禁用该选项	Boolean

fs-form-checkbox 事件

事件名	说明	回调参数
change	选中值变更时

注意： change 事件开启了 bubbles: true 和 composed: true，可被 fs-form-item 捕获用于表单校验。

---

校验规则

多选框的校验需要指定 type: 'array'，可以配合 min / max 限制选择数量：

{
  hobbies: [
    { 
      required: true, 
      message: '请至少选择一项',
      type: 'array',
      min: 1
    },
    {
      message: '最多选择3项',
      type: 'array',
      max: 3
    }
  ]
}

---

设计说明

内联模式（inline）

• 使用胶囊样式（capsule）横向排列，可通过 checkboxType="card" 切换为卡片样式
• 通过 direction 属性控制排列方向：row（横向）/ column（纵向）
• 支持单个选项禁用和整体禁用
• 自动同步选中状态，确保 UI 与数据一致

下拉模式（dropdown）

• 样式参考 fs-form-date，显示选中选项的名称，多个选项以逗号分隔
• 基于 fs-radio-picker-m 实现弹窗多选
• 支持 bordered 边框样式，适用于需要 32px 高度输入框视觉的场景
• 支持搜索、全选、checkboxType="card" 卡片样式等
• 适合选项较多或需要节省页面空间的场景

---

打开预览