表单与容器集成

本页整合业务仓库旧表单用法；完整契约见 ProForm、ProFormItem 及对应容器 API。不要复制旧手写参数表。

模型、布局和选项

传入 columns 与 v-model 构建表单，列 prop 支持对象路径。rowProps、全局 colProps 与列级 colProps 控制布局，列级配置覆盖全局；showLabel 也有整体与单列控制。表单 width 默认为 100%。

options 支持数组、响应式值及异步提供者；通过 optionField 映射非标准 label/value。选项解析和缓存由组件管理，但不意味着任意网络请求都永久缓存；响应式源变化、请求失效和组件销毁应遵循当前实现。应用不要再维护第二份派生 options。

输入组件的 .trim、.number、.lazy 通过对应 elProps.modelModifiers 配置。内置组件映射见 ProFormItem 类型；树形表单支持 keys/nodes 返回模式、展开已选父级及工具栏开关，具体属性见生成类型表。编辑器、图标选择器使用项目映射名称，不凭 Element Plus 标签名推断。

自定义内容与标签

表单项 render 支持 VNode；不支持 v-model 的自定义组件需调用提供的更新回调。TSX 示例使用 <script setup lang="tsx">。内容插槽取列 prop，标签插槽取 ${prop}-label。标签自定义按 renderLabel、renderLabelHTML、插槽路径选择；旧文档中混用 header/label 或 HTML 大小写的写法不再沿用。

HTML 回调仅接收可信内容；尤其表单标签路径直接渲染 HTML，不可注入外部未净化字符串。需要安全富文本展示时使用 SafeHtml。

footerAlign 控制按钮位置。footer 替换底部，footer-before / footer-after 添加按钮，可利用提交、重置回调和当前 model。Tooltip 图标可通过对应插槽定制。

容器选择

容器	适用方式与注意事项
ProFormGroup	按组组织 columns，支持 hidden、header、组 prop 和 form-main 插槽
ProFormTabs	标签形式的分组；按类型声明配置标题、name、图标、隐藏及禁用，监听切换，子项组件参数使用 elProps
ProFormSteps	步骤模型初始为 1，步骤内容插槽从 step-1 开始；不要将 ElSteps 的内部零基索引当作公开模型默认值
ProFormDialog	表单与弹框组合；可分别配置 dialog/form 的底部，避免同时出现两组提交按钮
ProFormDrawer	表单与抽屉组合；沿用模型与验证事件，并处理关闭时的局部状态

弹框默认展示弹框底部、隐藏内部表单底部；需要表单底部时显式设置 dialog.showFooter: false、form.showFooter: true。相关插槽分别带 dialog-、form- 前缀；不要把两层 footer 参数混用。

命令式使用

需要函数式创建时使用各模块实际导出的 useProForm、createFormComponent、createForm 等入口；挂载容器及返回实例归调用方管理，关闭/卸载时释放。事件注册复用同一函数引用，不依赖全局 DOM 查询取得内部实例。普通页面优先声明式组件和模板 ref。

ProDialog / ProDrawer 负责可见性、头部、确认取消及全屏等 UI。确认事件不代表接口保存成功，调用方需在真实保存成功后关闭，并保留失败反馈。