@aspire-ui/element-component-pro 1.0.26 → 1.0.27

package/docs/ProForm.md

@@ -0,0 +1,879 @@
+# ProForm 表单组件
+
+基于 Element UI Form 的二次封装，参考 [Vben Admin Form](https://doc.vvbin.cn/components/form.html)，支持 Schema 驱动、useForm、render/slot、动态显示等能力。
+
+## 组件构成
+
+- **ProForm** - 主表单组件
+- **ProFormItem** - 表单项（按 schema 自动渲染）
+- **FormActions** - 提交/重置/展开按钮组（可单独使用）
+
+## 基础用法
+
+通过 `schemas` 配置表单项，支持 `input`、`select`、`api-select`、`tree-select`、`date-picker`、`switch` 等组件类型。
+
+```vue
+<template>
+  <ProForm
+    :schemas="schemas"
+    :initial-values="{ name: '' }"
+    :base-col-props="{ span: 8 }"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+import { ProForm } from 'element-component-pro'
+import type { ProFormSchema } from 'element-component-pro'
+
+const schemas: ProFormSchema[] = [
+  { field: 'name', label: '姓名', component: 'input', required: true, colProps: { span: 8 } },
+  {
+    field: 'status',
+    label: '状态',
+    component: 'select',
+    componentProps: {
+      options: [
+        { label: '启用', value: 1 },
+        { label: '禁用', value: 0 },
+      ],
+    },
+    colProps: { span: 8 },
+  },
+]
+
+const handleSubmit = (values: Record<string, unknown>) => {
+  console.log(values)
+}
+</script>
+```
+
+## useForm 方式
+
+通过 `useForm` 传入 formProps，支持编程式调用表单方法。**参数 props 内的值可以是 computed 或 ref 类型**。
+
+```vue
+<template>
+  <ProForm @register="register" @submit="handleSubmit" />
+</template>
+
+<script setup lang="ts">
+import { ProForm, useForm } from 'element-component-pro'
+
+const [register, formActions] = useForm({
+  schemas: [...],
+  labelWidth: '120px',
+  actionColOptions: { span: 24 },
+})
+
+// 响应式 props
+const formProps = ref({ schemas: [...], disabled: false })
+const [register2] = useForm(formProps)
+
+const handleSubmit = (values: Record<string, unknown>) => {
+  console.log(values)
+}
+</script>
+```
+
+## 自定义 component
+
+`schema.component` 除内置类型外，支持**自定义组件**，有两种用法：
+
+### 1. 组件名 + components 映射
+
+在 ProForm 上传入 `components`，schema 中 `component` 填组件名字符串，会从 `components` 中解析；若未找到则当作全局注册的组件名。
+
+```vue
+<template>
+  <ProForm :schemas="schemas" :components="customComponents" @submit="handleSubmit" />
+</template>
+
+<script setup lang="ts">
+import { ProForm } from 'element-component-pro'
+import type { ProFormSchema } from 'element-component-pro'
+import MyRate from './MyRate.vue'
+
+const customComponents = { MyRate }
+
+const schemas: ProFormSchema[] = [
+  { field: 'name', label: '姓名', component: 'input' },
+  { field: 'score', label: '评分', component: 'MyRate', componentProps: { max: 5 } },
+]
+
+const handleSubmit = (values: Record<string, unknown>) => {
+  console.log(values)
+}
+</script>
+```
+
+### 2. 内联组件（直接传组件定义）
+
+`schema.component` 可直接传入 Vue 组件选项对象或构造函数，无需事先注册到 `components`。
+
+```ts
+import Rate from './Rate.vue'
+
+const schemas: ProFormSchema[] = [
+  { field: 'score', label: '评分', component: Rate, componentProps: { max: 5 } },
+]
+```
+
+**约定**：自定义组件需支持 `value`（或 `modelValue`）prop 与 `input` 事件，以与表单双向绑定；也可通过 `componentProps` 覆盖 `value` / `@input`。
+
+## Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| schemas | `ProFormSchema[]` | - | 表单项配置 |
+| modelValue | `Record<string, unknown>` | - | 受控表单值，支持 `v-model` 双向绑定 |
+| initialValues | `Record<string, unknown>` | - | 初始值 |
+| labelWidth | `string` | `'120px'` | 标签宽度 |
+| labelPosition | `'left' \| 'right' \| 'top'` | `'right'` | 标签位置 |
+| colon | `boolean` | `true` | 是否在 label 后显示冒号 |
+| gutter | `number` | `24` | 栅格间距 |
+| size | `'medium' \| 'small' \| 'large'` | `'medium'` | 尺寸 |
+| disabled | `boolean` | `false` | 是否禁用 |
+| baseColProps | `ColEx` | - | 全局栅格配置 |
+| baseRowStyle | `Record<string, string \| number>` | - | 栅格行样式 |
+| autoSetPlaceholder | `boolean` | `true` | 是否自动设置 placeholder |
+| showSubmitButton | `boolean` | `true` | 是否显示提交按钮 |
+| showResetButton | `boolean` | `true` | 是否显示重置按钮 |
+| submitButtonText | `string` | `'提交'` | 提交按钮文字 |
+| resetButtonText | `string` | `'重置'` | 重置按钮文字 |
+| submitButtonIcon | `string` | `'el-icon-search'` | 提交按钮图标 |
+| resetButtonIcon | `string` | `'el-icon-refresh-left'` | 重置按钮图标 |
+| showActionButtonGroup | `boolean` | `true` | 是否显示操作按钮组 |
+| actionColOptions | `ColEx` | 响应式配置 | 操作按钮区域栅格，支持 xs/sm/md/lg/xl |
+| showAdvancedButton | `boolean` | `false` | 是否显示展开/收起按钮 |
+| autoAdvancedLine | `number` | `3` | 超过指定行数默认折叠 |
+| alwaysShowLines | `number` | `1` | 折叠时显示的行数 |
+| submitFunc | `() => Promise<void>` | - | 自定义提交逻辑 |
+| resetFunc | `() => Promise<void>` | - | 自定义重置逻辑 |
+| submitOnReset | `boolean` | `false` | 重置时是否提交 |
+| fieldMapToTime | `FieldMapToTime[]` | - | 时间范围字段映射 |
+| formListeners | `FormListeners` | - | 透传给 el-form 的事件监听器 |
+| components | `Record<string, unknown>` | - | 自定义组件映射（组件名 -> 组件），供 schema.component 使用 |
+
+## ProFormSchema
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| field | `string` | 字段名 |
+| label | `string` | 标签 |
+| labelWidth | `string` | 当前表单项标签宽度，配置后可覆盖 ProForm 的 `labelWidth` |
+| colon | `boolean` | 当前表单项是否显示 label 冒号，优先级高于 ProForm 的 `colon` |
+| component | `string \| object \| Function` | 组件类型：input、select、**api-select**、**tree-select**、date-picker、date-range、input-number、**formatted-number**、switch、cascader、checkbox、radio；或自定义组件名（ProForm components/全局注册）；或内联组件（Vue 组件选项/构造函数） |
+| componentProps | `object \| function` | 组件属性，支持对象或函数，详见 [componentProps 详解](#componentprops-详解) |
+| placeholder | `string` | 占位符 |
+| defaultValue | `unknown` | 默认值 |
+| required | `boolean` | 是否必填 |
+| rules | `Array` | 校验规则 |
+| colProps | `ColEx` | 栅格配置，支持 span、xs、sm、md、lg、xl 等响应式断点 |
+| hidden | `boolean` | 是否隐藏 |
+| render | `(params) => VNode \| string` | 自定义渲染 |
+| slot | `string` | 具名插槽名称 |
+| show | `boolean \| (params) => boolean` | 动态显示（CSS 控制） |
+| ifShow | `boolean \| (params) => boolean` | 动态显示（不渲染 DOM） |
+| dynamicDisabled | `boolean \| (params) => boolean` | 动态禁用 |
+| dynamicRules | `Array \| (params) => Array` | 动态校验规则 |
+| helpMessage | `string \| string[]` | 标签右侧温馨提示 |
+| helpComponentProps | `object` | 温馨提示组件 props |
+| tooltip | `boolean \| string \| object \| (params) => boolean \| string \| object` | 表单项 value tooltip，`true` 时默认展示当前值 |
+
+### ColEx 栅格配置
+
+`colProps`、`baseColProps`、`actionColOptions` 均支持响应式断点，与 Element UI 一致：
+
+| 断点 | 视口宽度 |
+|------|----------|
+| xs | <768px |
+| sm | ≥768px |
+| md | ≥992px |
+| lg | ≥1200px |
+| xl | ≥1920px |
+
+```ts
+// 响应式栅格示例
+baseColProps: { xs: 24, sm: 12, md: 8, lg: 6 }
+```
+
+## useForm 方法
+
+| 方法 | 类型 | 说明 |
+|------|------|------|
+| getFieldsValue | `() => Record<string, unknown>` | 获取表单值 |
+| setFieldsValue | `(values) => Promise<void>` | 设置表单字段值 |
+| resetFields | `() => Promise<void>` | 重置表单 |
+| validate | `(nameList?) => Promise<unknown>` | 校验整个表单 |
+| validateFields | `(nameList?) => Promise<unknown>` | 校验指定表单项 |
+| submit | `() => Promise<void>` | 提交表单 |
+| scrollToField | `(name, options?) => Promise<void>` | 滚动到对应字段 |
+| clearValidate | `(name?) => void` | 清空校验 |
+| updateSchema | `(data) => Promise<void>` | 更新 schema |
+| appendSchemaByField | `(schema, prefixField?, first?) => Promise<void>` | 插入 schema |
+| removeSchemaByField | `(field) => Promise<void>` | 删除 schema |
+| setProps | `(props) => Promise<void>` | 设置表单 Props |
+| getComponentInstance | `(field) => ComponentPublicInstance \| null` | 获取指定字段的组件实例 |
+| getFieldOptions | `(field, raw?) => Array<{ label: string; value: unknown }> \| unknown[]` | 获取 `api-select` 字段的 options；`raw = true` 时返回接口原始列表数据 |
+| isFieldLoading | `(field) => boolean` | 获取 `api-select` 字段的加载状态 |
+
+## Slots
+
+| 名称 | 说明 |
+|------|------|
+| formHeader | 表单顶部区域 |
+| formFooter | 表单底部区域 |
+| submitBefore | 提交按钮前 |
+| resetBefore | 重置按钮前 |
+| advanceBefore | 展开/收起按钮前 |
+| advanceAfter | 展开/收起按钮后 |
+| actions | 操作按钮区域（在展开/收起按钮后） |
+| [schema.field] / [schema.slot] | 自定义表单项内容 |
+
+操作按钮顺序：**提交 → 重置 → 展开/收起 → 自定义操作**。表单项与操作按钮在同一行，操作按钮右对齐。
+
+**展开/收起**：当 `showAdvancedButton` 且字段数超过 `alwaysShowLines` 行可容纳数量时显示。`hasMoreFields` 会根据当前视口宽度和 `colProps` 的响应式断点（xs/sm/md/lg/xl）动态计算。
+
+## 示例
+
+### v-model / modelValue
+
+`ProForm` 支持通过 `v-model` 进行受控绑定。传入 `modelValue` 后，表单项变更、`setFieldsValue()`、`resetFields()` 都会触发 `update:modelValue`。
+
+`initialValues` 只用于补齐缺失字段，不会覆盖 `modelValue` 中已经存在的值。
+
+```vue
+<template>
+  <ProForm
+    v-model="formData"
+    :schemas="schemas"
+    :initial-values="{ status: 0, remark: '默认备注' }"
+    @submit="handleSubmit"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { ProFormSchema } from 'element-component-pro'
+
+const formData = ref({
+  name: '张三',
+})
+
+const schemas: ProFormSchema[] = [
+  { field: 'name', label: '姓名', component: 'input' },
+  { field: 'status', label: '状态', component: 'select', defaultValue: 1, componentProps: {
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  } },
+  { field: 'remark', label: '备注', component: 'input' },
+]
+
+const handleSubmit = (values: Record<string, unknown>) => {
+  console.log(values)
+}
+</script>
+```
+
+上例初始化后的值为：`name` 使用 `modelValue` 中的 `'张三'`，`status` 补 `defaultValue: 1`，`remark` 补 `initialValues.remark`。
+
+调用 `resetFields()` 或点击重置按钮时，也会按同样规则重建值：优先保留当前外部显式传入的字段，其余字段按 `defaultValue`、`initialValues` 补齐，并触发 `update:modelValue`。
+
+### useForm + v-model
+
+`useForm` 可以和 `v-model` 一起使用。此时 `setFieldsValue()`、`resetFields()` 等编程式方法同样会触发 `update:modelValue`，父组件拿到的仍然是统一的受控数据源。
+
+```vue
+<template>
+  <ProForm v-model="formData" @register="register" />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useForm } from 'element-component-pro'
+
+const formData = ref({ name: '张三' })
+
+const [register, formActions] = useForm({
+  schemas,
+  modelValue: formData,
+  initialValues: { remark: '默认备注' },
+})
+
+const fillValues = () => {
+  formActions.setFieldsValue({ name: '李四' })
+}
+
+const resetValues = () => {
+  formActions.resetFields()
+}
+</script>
+```
+
+### labelWidth
+
+表单级 `labelWidth` 用于统一控制标签宽度；当某个字段需要更宽或更窄的标签区域时，可在该项 schema 上单独配置 `labelWidth`，其优先级高于 `ProForm` 的 `labelWidth`。
+
+```vue
+<template>
+  <ProForm :schemas="schemas" label-width="120px" />
+</template>
+
+<script setup lang="ts">
+import type { ProFormSchema } from 'element-component-pro'
+
+const schemas: ProFormSchema[] = [
+  {
+    field: 'name',
+    label: '姓名',
+    component: 'input',
+  },
+  {
+    field: 'identityCard',
+    label: '身份证号码',
+    component: 'input',
+    labelWidth: '160px',
+  },
+]
+</script>
+```
+
+### colon
+
+`ProForm` 默认会在 label 后显示冒号，可通过表单级 `colon` 统一关闭，也可以在单个 schema 上单独覆盖。
+
+```vue
+<template>
+  <ProForm :schemas="schemas" :colon="false" />
+</template>
+
+<script setup lang="ts">
+const schemas = [
+  {
+    field: 'name',
+    label: '姓名',
+    component: 'input',
+  },
+  {
+    field: 'status',
+    label: '状态',
+    component: 'select',
+    colon: true,
+  },
+]
+</script>
+```
+
+规则如下：
+
+- `ProForm` 默认 `colon: true`
+- `schema.colon` 优先级高于 `ProForm.colon`
+- 关闭后只影响 label 文案展示，不影响校验、helpMessage 和 tooltip
+
+### helpMessage
+
+```ts
+{
+  field: 'name',
+  label: '姓名',
+  helpMessage: '请输入真实姓名',
+  // 或
+  helpMessage: ['提示1', '提示2'],
+}
+```
+
+### tooltip
+
+`tooltip` 用于给表单项 value 增加悬浮提示，适合输入内容较长、需要补充说明或希望直接回显当前值的场景。
+
+支持以下几种写法：
+
+| 写法 | 说明 |
+|------|------|
+| `true` | 启用 tooltip，并默认使用当前字段值作为内容 |
+| `string` | 使用固定文案作为 tooltip 内容 |
+| `object` | 透传给 `el-tooltip` 的 props；未传 `content` 时默认使用当前字段值 |
+| `(params) => ...` | 动态返回上面任一类型，适合根据其他字段联动 |
+
+`params` 与 `render`、`show` 等回调保持一致，包含以下字段：
+
+- `schema`：当前字段 schema
+- `field`：当前字段名
+- `model` / `values`：当前表单值
+
+默认行为：
+
+- 默认 `placement` 为 `top`
+- 默认 `effect` 为 `dark`
+- 当 tooltip 内容为空字符串、`null`、`undefined` 或空数组时，会自动禁用 tooltip
+- 当传入数组值（如多选、级联）且未显式指定 `content` 时，会自动用逗号拼接后展示
+
+```ts
+{
+  field: 'name',
+  label: '姓名',
+  component: 'input',
+  tooltip: true, // 默认展示当前字段值
+}
+
+{
+  field: 'status',
+  label: '状态',
+  component: 'select',
+  tooltip: '请选择账号状态',
+}
+
+{
+  field: 'remark',
+  label: '备注',
+  component: 'input',
+  tooltip: ({ values }) => values.status === 0 ? '禁用状态下仅支持查看' : false,
+}
+
+{
+  field: 'address',
+  label: '地址',
+  component: 'input',
+  tooltip: {
+    placement: 'top-start',
+    effect: 'dark',
+    content: '请填写详细地址',
+  },
+}
+```
+
+当传入对象且未显式指定 `content` 时，会默认使用当前字段值作为 tooltip 内容。
+
+建议：
+
+- 输入框、文本域、级联、多选这类“内容可能被遮挡或较长”的字段优先使用 `tooltip: true`
+- 下拉、开关等语义明确的控件，更适合使用固定文案或函数式 tooltip 做补充说明
+- 如果需要完全自定义展示内容，优先使用对象写法并显式传入 `content`
+
+### tooltip 常见问题
+
+#### 1. `tooltip: true` 显示的是什么？
+
+默认显示当前字段的实际值：
+
+- 普通输入值会转成字符串展示
+- 多选、级联这类数组值会按逗号拼接展示
+- 空值、`null`、`undefined`、空数组时不会显示 tooltip
+
+#### 2. 对 `select` / `radio` / `checkbox` 会显示 label 还是 value？
+
+当前默认显示的是字段真实值，而不是选项的 `label`。
+
+如果你希望展示更友好的文案，建议使用函数或对象形式自行指定 `content`：
+
+```ts
+{
+  field: 'status',
+  label: '状态',
+  component: 'select',
+  componentProps: {
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+  },
+  tooltip: ({ values }) => values.status === 1 ? '当前为启用状态' : '当前为禁用状态',
+}
+```
+
+#### 3. 我想自定义 tooltip 的位置、主题、延迟怎么办？
+
+直接使用对象形式，透传 `el-tooltip` 的 props：
+
+```ts
+{
+  field: 'remark',
+  label: '备注',
+  component: 'input',
+  tooltip: {
+    placement: 'top-start',
+    effect: 'light',
+    openDelay: 300,
+    content: '请填写详细说明',
+  },
+}
+```
+
+#### 4. 哪些场景更推荐开启 tooltip？
+
+推荐优先用于以下字段：
+
+- 长文本输入
+- 多选结果较多
+- 级联选择层级较深
+- 需要补充业务解释的控件
+
+如果字段本身语义很直观、值也很短，可以不必开启，避免交互噪音。
+
+#### 5. tooltip 能不能根据其他字段动态变化？
+
+可以，直接使用函数形式即可。该函数会拿到当前表单值，适合做联动说明：
+
+```ts
+{
+  field: 'email',
+  label: '邮箱',
+  component: 'input',
+  tooltip: ({ values }) => values.status === 0 ? '禁用状态下邮箱仅做展示' : false,
+}
+```
+
+### slot 自定义
+
+```vue
+<ProForm :schemas="schemas" @submit="handleSubmit">
+  <template #customField="{ model, field }">
+    <el-input v-model="model[field]" />
+  </template>
+</ProForm>
+
+// schemas
+{ field: 'customField', label: '自定义', slot: 'customField' }
+```
+
+### ifShow / dynamicDisabled
+
+```ts
+{
+  field: 'remark',
+  label: '备注',
+  ifShow: ({ values }) => !!values.status,  // 仅当 status 有值时显示
+},
+{
+  field: 'email',
+  label: '邮箱',
+  dynamicDisabled: ({ values }) => values.status === 0,  // status 为 0 时禁用
+}
+```
+
+**注意**：当 `ifShow` 为 `false` 时，该字段不会出现在提交数据和 `getFieldsValue()` 的返回值中。
+
+## componentProps 详解
+
+`componentProps` 用于配置底层 Element UI 组件的属性，支持**对象**和**函数**两种形式，会透传给 `el-input`、`el-select`、`el-date-picker` 等组件。
+
+### 对象形式
+
+直接传入对象，适用于静态配置：
+
+```ts
+{
+  field: 'status',
+  label: '状态',
+  component: 'select',
+  componentProps: {
+    options: [
+      { label: '启用', value: 1 },
+      { label: '禁用', value: 0 },
+    ],
+    clearable: true,
+    filterable: true,
+  },
+}
+```
+
+### api-select（接口下拉）
+
+选项由接口动态拉取，适合字典、远程数据。在 schema 中设置 `component: 'api-select'`，并在 `componentProps` 中传入 `api`（及可选的 `labelField`、`valueField`）：
+
+```ts
+{
+  field: 'status',
+  label: '状态',
+  component: 'api-select',
+  componentProps: {
+    api: () => api.getStatusList(),  // 返回 Promise<{ label, value }[]> 或 Promise<{ list: [] }>
+    labelField: 'label',             // 可选，默认 'label'
+    valueField: 'value',             // 可选，默认 'value'
+    clearable: true,
+    filterable: true,
+  },
+}
+```
+
+`api` 可声明为 `(params?: Record<string, unknown>) => Promise<...>`，会收到当前 `params`；传入 **params** 后，当 `params` 变化时会自动重新拉取 options（适合依赖其他表单项的联动下拉）。**lazy: true** 时改为懒加载：仅在展开下拉时请求，不在挂载时请求。**filterable: true** 时开启下拉内关键字搜索（在已加载的选项中做前端过滤，与 el-select 一致）。
+
+`api` 返回值约定：直接为 `Array<{ label, value }>`，或为 `{ list: [] }` / `{ data: [] }`，列表项可为任意结构，通过 `labelField` / `valueField` 指定字段名。
+
+### api-select 动态获取 Options
+
+`api-select` 组件支持通过 `formActionType` 动态获取内部加载的 options 和 loading 状态，便于实现联动逻辑或展示辅助信息。
+
+新增的 `FormActionType` 方法：
+
+| 方法 | 说明 | 返回值 |
+|------|------|--------|
+| `getFieldOptions(field, raw?)` | 获取指定 `api-select` 字段的 options；`raw = true` 时返回接口原始列表数据 | `Array<{ label: string; value: unknown }> \| unknown[]` |
+| `isFieldLoading(field)` | 获取指定字段的加载状态 | `boolean` |
+| `getComponentInstance(field)` | 获取组件实例（含 `options`、`loading`、`fetchOptions`） | `ComponentPublicInstance \| null` |
+
+**示例：联动下拉**
+
+```vue
+<template>
+  <ProForm ref="formRef" :schemas="schemas" @submit="handleSubmit" />
+  <el-button @click="getCityLabel">获取选中城市的名称</el-button>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { ProFormSchema } from 'element-component-pro'
+
+const formRef = ref()
+
+const fetchProvinces = () => Promise.resolve([
+  { label: '广东', value: 'gd' },
+  { label: '浙江', value: 'zj' },
+])
+
+const fetchCities = (params) => Promise.resolve([
+  { label: '广州', value: 'gz' },
+  { label: '深圳', value: 'sz' },
+])
+
+const schemas: ProFormSchema[] = [
+  {
+    field: 'province',
+    label: '省份',
+    component: 'api-select',
+    componentProps: {
+      api: fetchProvinces,
+      onChange: () => {
+        // 省份变化时，清空城市并触发重新加载
+        formRef.value.setFieldsValue({ city: null })
+        formRef.value.updateSchema([{
+          field: 'city',
+          componentProps: { params: { provinceId: formRef.value.getFieldsValue().province } }
+        }])
+      }
+    }
+  },
+  {
+    field: 'city',
+    label: '城市',
+    component: 'api-select',
+    componentProps: {
+      api: fetchCities,
+      params: { provinceId: '' }
+    }
+  }
+]
+
+const getCityLabel = () => {
+  const options = formRef.value.getFieldOptions('city')
+  const rawOptions = formRef.value.getFieldOptions('city', true)
+  const currentValue = formRef.value.getFieldsValue().city
+  const label = options.find(o => o.value === currentValue)?.label
+  console.log('当前选中城市:', label)
+  console.log('城市原始数据:', rawOptions)
+}
+</script>
+```
+
+**示例：在 componentProps 回调中获取 Options**
+
+```ts
+{
+  field: 'category',
+  label: '子类目',
+  component: 'api-select',
+  componentProps: ({ formActionType }) => ({
+    api: fetchCategoryList,
+    params: { type: formActionType.getFieldsValue().type },
+    onChange: (value) => {
+      // 在回调中也能获取到当前 options 和原始数据
+      const options = formActionType.getFieldOptions('category')
+      const rawOptions = formActionType.getFieldOptions('category', true)
+      console.log('子类目 Options:', options)
+      console.log('子类目原始数据:', rawOptions)
+    }
+  }),
+}
+```
+
+### tree-select（树选择）
+
+树形数据选择，支持 **直接传入 treeData** 或 **api + params** 远程拉取；**treeData 优先**，仅当未传 treeData（或为空数组）时才请求 api。
+
+- **treeData**：树形数组，直接传入时使用本地数据，不请求 api；可与 `labelField` / `valueField` / `childrenField` 配合使用。
+- **api**：`(params?) => Promise<树数据>`，在未提供 treeData 时拉取树数据；返回值为树形数组，每项含 `label`、`value`、`children`（字段名可通过 `labelField` / `valueField` / `childrenField` 配置）。
+- **params**：请求参数，变化时重新拉取（仅在使用 api 时生效）。
+- **filterable**：为 true 时下拉内显示搜索框，按关键字过滤树节点（前端过滤）。
+- **lazy**：为 true 时在展开下拉时再请求数据（仅在使用 api 时生效）。
+
+仅用 treeData 示例：
+
+```ts
+{
+  field: 'deptId',
+  label: '部门',
+  component: 'tree-select',
+  componentProps: {
+    treeData: [
+      { label: '总部', value: 'hq', children: [
+        { label: '技术部', value: 'hq-tech' },
+        { label: '产品部', value: 'hq-product' },
+      ]},
+      { label: '华东区', value: 'east', children: [
+        { label: '上海分公司', value: 'east-sh' },
+      ]},
+    ],
+    labelField: 'label',
+    valueField: 'value',
+    childrenField: 'children',
+    filterable: true,
+    placeholder: '请选择部门',
+    clearable: true,
+  },
+}
+```
+
+使用 api 示例：
+
+```ts
+{
+  field: 'deptId',
+  label: '部门',
+  component: 'tree-select',
+  componentProps: {
+    api: () => api.getDeptTree(),
+    params: { type: 1 },
+    labelField: 'name',
+    valueField: 'id',
+    childrenField: 'children',
+    filterable: true,
+    placeholder: '请选择部门',
+    clearable: true,
+  },
+}
+```
+
+### 函数形式
+
+传入函数可获取表单上下文，适用于动态配置或联动逻辑。参数类型：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| schema | `ProFormSchema` | 当前表单项的 schema |
+| values | `Record<string, unknown>` | 表单数据（与 model 相同引用） |
+| model | `Record<string, unknown>` | 表单数据，可直接修改实现联动 |
+| field | `string` | 当前字段名 |
+| formActionType | `FormActionType` | 表单操作 API |
+
+```ts
+{
+  field: 'name',
+  component: 'input',
+  componentProps: ({ values, model, formActionType }) => ({
+    // 根据其他字段动态配置
+    disabled: values.status === 0,
+    // 或使用 formActionType 编程式操作
+    onChange: (val: string) => {
+      formActionType.setFieldsValue({ otherField: val + '_suffix' })
+    },
+  }),
+}
+```
+
+### 事件监听
+
+以 `on` 开头的属性会被识别为事件监听器，通过 `v-on` 绑定到组件。支持 `onChange`、`onInput`、`onBlur` 等，**不区分大小写**（`onchange` 与 `onChange` 均可）。
+
+```ts
+{
+  field: 'remark',
+  component: 'input',
+  componentProps: ({ formActionType }) => ({
+    onChange: (value: string) => {
+      formActionType.setFieldsValue({ phone: value })
+    },
+    onInput: (value: string) => {
+      console.log('输入中', value)
+    },
+  }),
+}
+```
+
+### 各组件常用 props
+
+| 组件 | 常用 props | 说明 |
+|------|------------|------|
+| input | `maxlength`, `clearable`, `showPassword`, `prefixIcon`, `suffixIcon` | 参考 [el-input](https://element.eleme.cn/#/zh-CN/component/input) |
+| select | `options` | `{ label, value }[]`，必填 |
+| api-select | `api`, `params`, `lazy`, `labelField`, `valueField`, `filterable` | `api` 可接收 `params`；`params` 变化时重新拉取；`lazy: true` 为懒加载；`filterable: true` 开启下拉内关键字搜索（前端过滤已加载选项），见上文 |
+| tree-select | `treeData`, `api`, `params`, `lazy`, `labelField`, `valueField`, `childrenField`, `filterable` | 树选择；**treeData 优先**，未传时用 api/params 拉取；filterable 搜索树节点，见上文 |
+| input-number | `min`, `max`, `step`, `precision`, `controls` | 参考 [el-input-number](https://element.eleme.cn/#/zh-CN/component/input-number) |
+| formatted-number | 在 **`componentProps`** 中传入：`integerDigits`、`decimalPlaces`、`rounding`、`inputLimit`，以及 `clearable`、`placeholder` 等同 el-input | 仅数字输入；失焦时按整数位数上限与小数位舍入后格式化为千分位；`integerDigits` 默认 6，`decimalPlaces` 默认 6，`rounding` 为 `floor` \| `ceil` \| `round`（默认 `round`）；`inputLimit` 默认 `true`，为 `true` 时输入过程中限制整数位不超过 `integerDigits`、小数位不超过 `decimalPlaces`；表单值为**固定小数位的字符串**（如 `12.340000`，以保留配置的小数位；`number` 无法保留尾随 0），清空为 `undefined` |
+| date-picker | `value-format`, `type`, `format` | 参考 [el-date-picker](https://element.eleme.cn/#/zh-CN/component/date-picker) |
+| switch | `activeText`, `inactiveText`, `activeValue`, `inactiveValue` | 参考 [el-switch](https://element.eleme.cn/#/zh-CN/component/switch) |
+| cascader | `options`, `props` | 参考 [el-cascader](https://element.eleme.cn/#/zh-CN/component/cascader) |
+| checkbox / radio | `options` | `{ label, value }[]`，必填 |
+
+### fieldMapToTime
+
+将日期范围映射为两个字段：
+
+```ts
+useForm({
+  schemas: [
+    { field: 'dateRange', component: 'date-range', label: '日期范围' },
+  ],
+  fieldMapToTime: [
+    ['dateRange', ['startTime', 'endTime']],
+  ],
+})
+// getFieldsValue() => { startTime, endTime }
+```
+
+### formListeners
+
+透传事件监听器到 el-form：
+
+```vue
+<ProForm
+  :schemas="schemas"
+  :form-listeners="{
+    validate: (valid) => console.log('validate', valid),
+    'validate-field': (prop, valid, msg) => {},
+  }"
+  @submit="handleSubmit"
+/>
+```
+
+## FormActions 组件
+
+提交/重置/展开按钮组已抽离为独立组件，可单独使用。提交、重置按钮默认带图标。
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| submitButtonText | `string` | `'提交'` | 提交按钮文字 |
+| resetButtonText | `string` | `'重置'` | 重置按钮文字 |
+| submitButtonIcon | `string` | `'el-icon-search'` | 提交按钮图标 |
+| resetButtonIcon | `string` | `'el-icon-refresh-left'` | 重置按钮图标 |
+| submitLoading | `boolean` | `false` | 提交中 loading 状态 |
+
+```vue
+<template>
+  <FormActions
+    :submit-loading="loading"
+    submit-button-text="查询"
+    reset-button-text="重置"
+    submit-button-icon="el-icon-search"
+    reset-button-icon="el-icon-refresh-left"
+    @submit="handleSubmit"
+    @reset="handleReset"
+  />
+</template>
+
+<script setup lang="ts">
+import { FormActions } from 'element-component-pro'
+</script>
+```