表单组件

@vben/components/form 提供一组接口驱动的表单控件，全部可在 useVbenForm 的 schema 中以组件名字符串使用（组件通过 component-map.ts 自动注册），也可在模板中直接引入。

import { ApiDict, ApiSelect, FileUpload, ImageUpload } from '@vben/components/form';

在 form schema 中使用（推荐方式）：

const schema: VbenFormSchema[] = [
  {
    fieldName: 'state',
    label: '状态',
    component: 'ApiDict',            // 组件名字符串
    componentProps: {
      type: 'common.state',          // 字典类型
      renderType: 'Select',
    },
  },
];

1. ApiSelect 接口下拉框

通过 api 加载选项的下拉框，底层是 ApiComponent + antdv Select，下拉展开时才请求，自带 loading。

Prop	类型	默认值	说明
`api`	`(arg?) => Promise<any[]>`	-	选项数据接口
`params`	`Record<string, any>`	`{}`	接口参数
`valueField`	`string`	`'value'`	value 字段名
`searchKeys`	`string`	`'label'`	搜索匹配字段
`showSearch`	`boolean`	-	是否显示搜索
`allowClear`	`boolean`	`true`	可清空
`type`	`'dict'`	-	传 `'dict'` 时走字典 store，不请求 api
`disableInvalid`	`boolean`	`false`	禁用状态是否失效
`v-model:value`	`SelectValue`	-	选中值

{
  fieldName: 'orgId',
  label: '所属组织',
  component: 'ApiSelect',
  componentProps: {
    api: OrgApi.list,
    params: { state: true },
    labelField: 'name',
    valueField: 'id',
    showSearch: true,
  },
}

2. ApiTreeSelect 接口树选择

接口加载的树形下拉，底层 antdv TreeSelect。

Prop	类型	默认值	说明
`api`	`Function \| string`	-	接口函数，或直接传 URL 字符串
`requestMethod`	`string`	`'post'`	api 为 URL 时的请求方法
`params`	`object \| Function`	`{}`	参数（函数形式在请求时求值）
`resultField`	`string`	`''`	结果取值路径，支持 `a.b.c`
`labelField` / `valueField` / `childrenField`	`string`	`title` / `value` / `children`	字段映射
`immediate`	`boolean`	`true`	立即加载；`false` 时首次展开下拉才加载

通过 ref 暴露 fetch() 可手动刷新。

3. ApiDict 字典选择器（重点）

MDP 使用频率最高的表单组件：根据字典类型或枚举类型渲染选项，数据来自字典 store（全局缓存，不重复请求）。renderType 决定渲染成哪种控件。

Prop	类型	默认值	说明
`type`	`string`	必填	字典类型或枚举类型的唯一标识
`renderType`	`'Select' \| 'RadioGroup' \| 'CheckboxGroup' \| 'Switch'`	`'Select'`	渲染控件
`dataType`	`'1' \| '2' \| '3'`	-	值数据类型：1 字符串 / 2 整型 / 3 布尔
`disableInvalid`	`boolean`	`false`	字典条目被禁用后，已选中的历史值是否仍可选
`extend`	`Option`	-	扩展条目（如追加一个「全部」选项）
`extendIndex`	`number`	`0`	扩展条目插入位置
`excludes`	`string[]`	`[]`	需要排除的字典条目

// 下拉
{ component: 'ApiDict', componentProps: { type: 'common.state' } }
// 单选组
{ component: 'ApiDict', componentProps: { type: 'common.gender', renderType: 'RadioGroup' } }
// 开关（dataType 2：选中为 1，未选中为 0）
{ component: 'ApiDict', componentProps: { type: 'common.yesOrNo', renderType: 'Switch', dataType: '2' } }

4. ApiRadioGroup / ApiCheckboxGroup / ApiSwitch / ApiCascader

与 ApiSelect 同族的接口驱动控件，props 基本一致（api、params、valueField、type、disableInvalid）：

ApiRadioGroup：单选组，v-model:value；
ApiCheckboxGroup：多选组，v-model:value（数组）；
ApiSwitch：开关，v-model:checked，支持自定义选中值类型；
ApiCascader：级联选择，字段映射默认值 valueField: 'id'、labelField: 'name'、childrenField: 'children'。

一般不需要直接用这几个——通过 ApiDict 的 renderType 间接使用更常见。

5. FileUpload / ImageUpload 文件与图片上传

基于 antdv Upload 封装，对接 mdp 文件服务（上传、回显、删除、预览全流程内置）。ImageUpload 额外提供缩略图与图片预览。

Prop	类型	默认值	说明
`objectType`	`string`	必填	附件的业务对象类型（决定存储归属）
`api`	`UploadApi`	内置上传接口	自定义上传接口
`view`	`boolean`	`false`	查看模式（只读回显）
`maxCount`	`number`	`1`	最大文件数；为 1 时绑定值为 `string`，否则 `string[]`
`maxSize`	`number`	`5`	单文件最大体积（MB）
`accept`	`string`	-	接受的文件类型
`acceptFormat`	`string \| Function`	原始 accept	把 mime 类型转成用户可读的提示文案
`multiple`	`boolean`	`false`	多选
`directory`	`boolean`	`false`	上传文件夹
`enableDragUpload`	`boolean`	`false`	拖拽上传
`removeConfirm`	`boolean`	`false`	删除前确认
`removeOnError`	`boolean`	`true`	上传失败后从列表移除
`helpMessage`	`boolean`	`true`	显示「请上传不超过…」提示
`preview`	`(file) => void`	内置逻辑	自定义预览（默认图片预览、文件新窗口打开）
`customFilename` / `customThumbUrl`	`CustomGetter`	-	自定义回显文件名 / 缩略图

事件：success、remove、change、update:value、update:objectId。

objectType + objectId 绑定模式：除 v-model:value（绑定文件 ID）外，组件还支持 v-model:objectId 绑定业务对象 ID——objectId 变化时组件自动调用 findUrlByObject(objectType, objectId) 回显该业务对象下的全部附件。编辑页场景（附件挂在业务记录上而非字段上）优先用这种模式。

{
  fieldName: 'avatar',
  label: '头像',
  component: 'ImageUpload',
  componentProps: {
    objectType: 'user.avatar',
    maxCount: 1,
    maxSize: 2,
    accept: 'image/png,image/jpeg',
    acceptFormat: 'PNG 或 JPG',
  },
}

Prop	类型	默认值	说明
`value`	`string`	-	拼接后的字符串
`separator`	`string`	`,`	分隔符
`modalTitle`	`string`	-	编辑弹窗标题
`maxHeight`	`number`	-	列表区最大高度（px），超出滚动
`disabled`	`boolean`	`false`	禁用

典型场景：逗号分隔的标签、多个手机号/邮箱录入等。

表单组件

1. ApiSelect 接口下拉框

2. ApiTreeSelect 接口树选择

3. ApiDict 字典选择器（重点）

4. ApiRadioGroup / ApiCheckboxGroup / ApiSwitch / ApiCascader

5. FileUpload / ImageUpload 文件与图片上传

6. FilePartUpload 分片上传表单项

7. IconPicker 图标选择器

8. StringSplitter 字符串分割输入