简介

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	—	''
showSearch	是否显示搜索框（下拉模式）	Boolean	—	false

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），横向排列（row）
• 颜色、尺寸、间距等细节与 fxui 设计规范保持一致
• 支持单个选项禁用和整体禁用
• 自动同步选中状态，确保 UI 与数据一致
• value 为数组类型，支持多选

下拉模式（dropdown）

• 样式参考 fs-form-date，显示选中选项的名称，多个选项以逗号分隔
• 基于 fs-radio-picker-m 实现弹窗多选
• 支持搜索、全选、不同 radio 类型等高级功能
• 适合选项较多或需要节省页面空间的场景
• 下拉模式需要在页面引入 dialog-center 组件

---

打开预览