AtForm 复杂用法

夏源庆

最后更新于 2026-10-30 11:40:07

本文依据当前组件源码，示例是脱离业务项目后的可运行场景。完整表单见 弹窗表单。类型定义使用 MCP get_type 查询 AtFormItemConfig、ListenerOptions、OnChangeOptions 和 FieldPropMap，不要把配置字段当作 AtForm 实例方法。

依赖与远程选项

deps 中的字符串读取当前层 model 的直接键，不是点路径解析器。需要监听嵌套值时传入 computed/ref。数组对象行的字符串依赖只针对本行；跨行选择排除可以把所有行已选值汇总为 computed，再将它放入 deps。

listener 默认挂载时执行，后续依赖变化再执行；noCallListenerOnMounted 只跳过首次调用。deep 控制依赖的深度监听。可以修改回调里的 config，也可以返回状态对象；静态 config 上已明确设置的 hide/props 可能优先于返回状态，避免为同一字段设置两套来源。

apiFn 必须返回选项数组。挂载时 hide 为 true 会跳过初始化请求。依赖变化需要刷新选项时调用回调里的 refreshApi；不要假设改变 model 会自动刷新接口。refreshApiWhenShow 在字段显示时重新请求，适用于 select、treeSelect、cascader，不应推广到所有字段。

编辑回填和用户修改依赖是两种场景：回填时不要清掉已保存的下游值；用户切换上游时应清空失效下游值。样板用 initializing 区分这两个阶段。需要保序的远程选项由业务请求层提供取消/序号控制，组件本身没有“最后一次请求必然胜出”的保证。

隐藏、自定义字段与嵌套数据

隐藏使用 hide；隐藏不会自动删除 model 中的旧值，提交时按接口约定决定是否排除。自定义字段使用 type: 'custom' 和 component，组件接收 value / update:value 双向绑定，以及 config、model、parentModel、index 等上下文；render 不是这里的配置 API。可用 markRaw 保存自定义 Vue 组件。

• objBlock 对应对象，children 描述内部字段。
• objArrayBlock 对应对象数组，明确提供 multipleConfig.defaultItem。
• objArrayTable 对应可编辑表格，children 描述列字段，tableProps 是表格配置。
• basicArray 对应基础值数组，使用 basicArray 配置内部控件。

数组字段内的 model 是当前行，parentModel 是外层模型。需要外层模型变化触发行内 listener 时，同时设置 deps（可为空数组）和 observeParentModel: true；实现只在存在 deps 时建立监听。外部 Ref 依赖与数组行 model 不要混淆。

初始化、回填、重置与提交

选择类字段需要使用底层组件支持的受控空值。NSelect 的空选为 null；从已选值设回 undefined 会回退到内部状态，可能仍显示旧选项。样板的 ownerId 因此使用 number | null，提交真实接口前再按接口约定转换。

AtForm 在 mounted 时记录初始快照，此时容器子字段已补全结构。setValue 合并新数据，数组会调整到新数组长度；它不是“彻底清空旧表单”。resetValue 使用 initValue 或初始快照，替换嵌套对象/数组、移除多余顶层键，并清除校验提示。

弹窗保留内容时，每次打开显式重置，再回填详情。需要 reset 回到当前记录时绑定明确的 initValue；不要依赖首次挂载快照自动更新。setValue、resetValue 均返回 Promise，应在依赖其完成的流程中 await。

提交顺序是 await form.validate() → 开启提交 loading → 调用接口 → 检查 err 和返回结果 → 成功后通知父级与关闭 → finally 清理 loading。校验失败会拒绝 Promise，不能继续请求或伪报保存成功。

场景来源与核验

• dt-lion-platform-pc/src/views/ScriptConfig/components/FieldMappingModal/FieldMappingModal.vue:48：objArrayTable；76 行起通过 Ref deps 处理跨行选项。
• dt-lion-center-pc/src/views/CollectionStandardManagement/TimeFormModal.vue:70：table_ids 联动远程选项；89 行 refreshApi。
• dt-gov-manage-pc/src/views/Governance/TextExtractionStandards/components/use-form-config.tsx:37：对象数组和自定义字段；79 行行内依赖显隐。
• dt-gov-develop-pc/src/views/GeneralData/Production/components/OrchestrationFromModal.vue:107：数组行中依赖控制 disabled。
• 当前实现：components/src/form/src/AtForm.vue、types.ts、utils.ts、fields/custom.vue 及 select/tree-select/cascader 字段。业务项目只用于发现场景，历史写法不作为 API 规范。