minnan-collect-web/.cursor/rules/dynamic-form.mdc

---
description: DynamicForm 动态表单定义、挂载与 dig/forms 数据工厂约定
globs: "**/*.vue"
alwaysApply: false
---

# 动态表单（DynamicForm）使用约定

本项目采用的是Vue3 web技术栈，其中主要的功能点为表单提交，因此本项目采用了动态表单库 vue-dynamic-form，
关于动态表单库的使用文档可参考https://docs.imengyu.top/vue-dynamic-form-docs/guide/about.html

基于 `DynamicForm.vue`、`DynamicForm.ts`（`IDynamicFormOptions` / `IDynamicFormItem`）及 `pages/dig/forms/data/*.ts`（如 `overview.ts`）的实际用法。

## 组件侧

- 使用 `<DynamicForm :options="..." :model="..." :name="..." :globalParams="..." />`。`model` 与表单双向绑定；`globalParams` 可在条目回调的 `formGlobalParams` 中读取。
- 通过 `ref` 拿到 `IDynamicFormRef`：`validate` / `submit`、`setValueByPath` / `getValueByPath`（路径为点分字符串或数组转点分）、`getFormRef`、`getFormItemControlRef`、`dispatchMessage` / `dispatchReload`（常量 `MESSAGE_RELOAD`）、`initDefaultValuesToModel`、`getVisibleFormNames`。
- 顶层校验：在 `options.formRules`（async-validator `Rules`）或单项 `rules`（`RuleItem[]`）。可选 `formAdditionaProps`、`disabled`、`readonly`、`suppressRootError`、`suppressEmptyError`、`nestObjectMargin`、`emptyText`。

## 选项结构 `IDynamicFormOptions`

- **必填**：`formItems: IDynamicFormItem[]`。
- 全局默认：可改 `defaultDynamicFormOptions` 或调用 `configDefaultDynamicFormOptions`（勿传入 `formItems`），与单次 `options` 合并。

## 表单项 `IDynamicFormItem`

- **必填**：`name`（字段路径名）。**常用**：`label`、`type`（内置控件类型字符串）、`additionalProps`（传给具体控件）、`formProps`（传给 `Field`）、`defaultValue`、`rules`、`children`（嵌套对象/数组项）。
- **动态字段**：`label`、`additionalProps`、部分控件字段、`show`、`disabled` 等可写成 **`IDynamicFormItemCallback<T>`**：`{ callback: (model, rawModel, parentModel, params) => T }`。关联远端字段时优先用 **`rawModel`**；列表场景用 **`parentModel`**。`params` 含 `item`、`parent`、`form`（`IDynamicFormRef`）、`formGlobalParams`、`formRules`、`isFirst` / `isLast`。
- **生命周期 / 联动**：`mounted` / `beforeUnmount` / `watch`；跨项赋值在拿到表单 ref 时用 **`form.setValueByPath('field', value)`**（参见 `overview` 中 `select-city` 的 `onSelectedTownship`）。
- **布局容器**：`flat-group` 用于横向/分组排版（可配合 `childrenColProps`、`rowProps`）；子项仍占用模型上的 `name`。嵌套对象用带 `children` 的条目（由渲染层按 `type` 区分对象/数组等）。
- **数组子项**：可选 `newChildrenObject`、`deleteChildrenCallback` 控制增删；子层可用 `childrenColProps` / `colProps` / `nestObjectMargin`。
- **默认值**：`defaultValue` 可为字面量或 **`() => value`**（惰性初始化）；`initDefaultValuesToModel` 只对仍为 `undefined`/`null` 的路径写入。
- **消息**：条目可实现 `message`，根上 `dispatchMessage` 分发；预置 `MESSAGE_RELOAD` 用于刷新类逻辑。

## 可用组件

在 \src\components\dynamicf\index.ts 中的 registerAllFormComponents 函数中有注册了本项目中可用的动态表单组件，可以在这里查阅。
register的一个参数小写名字为组件的唯一标识，在配置中使用。
本项目大部分使用 ant-design-vue 的组件，少部分组件为二次封装组件，放在项目的 \src\components\dynamicf 文件夹下。

可用组件简表：
text：单行文本框
password：密码输入框
number：数字输入框
text-area：多行文本框
switch：开关
check-box：boolean类型的勾选框
check-box-int：0，1数字类型的勾选框
rate：评星
select：静态数据下拉选择框
select-value：静态数据下拉选择框，额外参数的options可配置选项数据，格式{text: string,value: unknown}[]
select-id: 动态数据据下拉选择框，额外参数的loadData为回调：
  loadData: (searchText: string | null) => Promise<DropdownValues<T>[]>;
  DropdownValues<T> {
    label: string,
    value: number,
    raw: T;
  }
  可用来加载选项数据。
date：日期选择.
time：时间选择。
date-time：日期+时间选择
date-range：日期范围选择。
time-range：时间范围选择。
date-time-range：日期+时间范围选择。
uploader：单一图片上传。
uploader：多图上传。

formOptions 格式如下：{
  formLabelCol: { span: 6 }, //表单标签栅格宽度
  formWrapperCol: { span: 24 }, //表单容器栅格宽度
  formAdditionaProps: { //指定ant desgin form 的其他参数
    layout: 'vertical'
  },
  formItems: [//表单项目
    {
      label: '传承人姓名', //标签名称
      name: 'name', //字段名称
      type: 'text', //组件名称
      additionalProps: { //组件的额外参数
        placeholder: '请输入姓名'
      },
    },
    { 
      label: '证件照',
      name: 'idPhoto',
      type: 'uploader',
      additionalProps: {

      },
    },
    {
      label: '类型',
      name: 'type',
      type: 'select-id',//动态下拉加载
      additionalProps: {
        placeholder: '请选择类型',
        //如有动态加载数据，请为我生成类似代码
        loadData: async () =>
          (await CommonContent.getCategoryList(4)).map(p => ({
            label: p.title,
            value: p.id,
            raw: p
          }))
      } as IdAsValueDropdownProps<DataModel>,
    },
    {
      label: '性别',
      name: 'gender',
      type: 'select',
      additionalProps: {
        options: [
          { text: '男', value: '男' },
          { text: '女', value: '女' },
        ]
      },
    },
    {
      label: '生日',
      name: 'birthday',
      type: 'date',
      additionalProps: {
        placeholder: '请输入出生日期' 
      }
    },
    {
      label: '说明',
      name: 'jobTitle',
      type: 'text-area',
      additionalProps: {
        placeholder: '请输入说明' 
      }
    },
  ],
  formRules: { //表单验证项，格式与 async-validator 一致
    name: [
      { required: true, message: '请输入姓名' },
      { min: 2, max: 5, message: '长度在 2 到 5 个字符' }
    ],
    ichName: [
      { required: true, message: '请输入项目名称' }
    ],
    //....
  },
});

## 建议避免

- 勿猜测未注册的 `type`；新增类型需在动态表单渲染链路中已有对应组件映射。
- 回调里访问兄弟节点不要用错层级：`model` 是当前项值，`rawModel` 是整表根数据（跨深层字段时尤其要用根路径或 `setValueByPath`）。