mirror of
https://github.com/Tencent/tmagic-editor.git
synced 2026-09-14 16:09:08 +00:00
331 lines
21 KiB
Markdown
331 lines
21 KiB
Markdown
# submitForm 函数
|
||
|
||
以命令式方式对一份「表单配置 + 表单值」执行一次校验并取回表单值，类似 `ElMessage` 的用法。
|
||
|
||
走**无渲染**实现：不创建任何 DOM 容器、不实例化任何组件，而是直接遍历 `config` 树收集带规则的字段，交给 [`async-validator`](https://github.com/yiminghe/async-validator)（`element-plus` 内部用的也是它）执行。因此它可以在 Node / CI 等没有 DOM 的环境中使用，也省去了挂载整棵表单的开销。校验通过则 `resolve` 表单值，失败则 `reject` 错误信息。纯 Node 请从 `@tmagic/form/headless` 引入，避免加载 Vue 组件和样式。
|
||
|
||
适用于一些没有合适的容器、但又需要复用 `MForm` 校验逻辑的场景，例如：
|
||
|
||
- 通过快捷菜单/命令面板触发一次性表单
|
||
- 在脚本/服务层完成一次表单值校验后再发请求
|
||
- 把 `config` 配置当作"可执行的校验规则"使用
|
||
- 在 Node 脚本 / CI 中批量校验组件配置
|
||
|
||
## 无渲染校验与自定义字段登记
|
||
|
||
无渲染实现按 `Container.vue` 及各容器组件的模板规则遍历配置树，产出的字段 `prop` 与规则与「挂载 `MForm` 后调用 `validate()`」等价。需要 UI 时传入 `dialog: true`，会把表单以弹层渲染出来供填写/确认。
|
||
|
||
字段只要带了 `rules`（会包 FormItem），就会校验自身，不必先登记为叶子。配置里有 `items` 会下钻子项。内部再渲染 `MContainer` 的复合字段需要 `registerField(type, { innerConfig })`，把内部会挂到父表单上的配置交出来。innerConfig 回调自身抛错时，会以 `FieldInnerConfigError`（`code: 'FIELD_INNER_CONFIG'`）reject。
|
||
|
||
innerConfig 回调在校验和表单值初始化两条链路上都会被调用（后者用于走到复合字段内部、找出需要执行 `effect` 的子字段），所以它应当只做配置派生、可重复调用、不要做重活。在表单值初始化链路上，回调抛错只会记录到 console 并跳过该子树，不会让表单渲染不出来。
|
||
|
||
自定义字段的渲染组件和无渲染校验都通过 `registerField` / `registerFields` 一次登记。`component` 会写入字段注册表（`getFormField`）；传入 `app` 时同时 `app.component('m-fields-*')`。容器组件用 `container`，对应 `m-form-*`。
|
||
|
||
字段对表单值的初始化写入统一登记为 `effect`，渲染与无渲染共用同一份登记表，执行点也只有一个：表单值初始化完成后（`MForm` 内部、`validateValues`、以及 tab / table 新增行时）各执行一次 `applyMountValueEffects`，字段组件自身不要在 `setup` 里改写 `model`。因此 effect 有两个约束：一是必须幂等，同一份值可能被执行多次（如 `initValues` 变化后重新初始化）；二是不看 `display`（`display: false` 或函数返回假的字段也会被规整，避免字段由隐藏转为显示时漏掉）。`type: 'hidden'` 不同：遍历在该节点停止、不往下分派，内部字段不会执行 effect。需要按路径跨层级写值时用上下文里的 `values`（本次处理的值根对象，`prop` 即以它为根），不要用 `mForm.values`——对比模式处理的是 `lastValues` 那一份，新增行处理的则是还没挂到表单上的一行值。单个 effect 抛错只会记录到 console，不影响其余字段与表单渲染。复合字段可以同时登记 `effect` 与 `innerConfig`：前者改本字段的值，后者只派生内部配置、不要在回调里改 `model`。
|
||
|
||
| 字段形态 | 登记方式 |
|
||
| --------------------------------------------------------------------- | ------------------------------------------- |
|
||
| 自身带 `rules`，内部没有嵌套的父表单 FormItem | 无需登记，直接校验 |
|
||
| 内部只渲染叶子 UI，或把子表单渲染在独立的 `MForm` / `MFormBox` 实例里 | `registerField('my-field')`（配置里有 `items` 但不属于父表单时，避免被当下钻） |
|
||
| 同时需要渲染组件 | `registerField('my-field', { component })` |
|
||
| 容器组件（`m-form-*`） | `registerField('my-box', { container, walk })` |
|
||
| 叶子字段，但需要改写表单值（类似 `display` 的 `initValue`） | `registerField('my-field', { effect })` |
|
||
| 内部再渲染 `MContainer` / `MPanel` / `MGroupList`，向父表单注册字段 | `registerField('my-field', { innerConfig })`（需要改本字段的值时再加 `effect`） |
|
||
| 自定义 `typeMatch` 类型校验 | `registerField('my-field', { typeMatch })` |
|
||
|
||
```ts
|
||
import { registerField, registerFields } from '@tmagic/form';
|
||
import MyColorPicker from './MyColorPicker.vue';
|
||
|
||
// 叶子字段：内部没有嵌套的表单项；带 component 时即可渲染
|
||
registerFields({ 'my-color-picker': { component: MyColorPicker } });
|
||
// 需要挂到当前 app 时传入第二个参数
|
||
registerFields({ 'my-color-picker': { component: MyColorPicker } }, app);
|
||
|
||
// 叶子字段，但需要改写表单值：写成 effect，不要在组件 setup 里改 model
|
||
registerField('my-status', {
|
||
effect: ({ config, model }) => {
|
||
if ((config as any).initValue && model) {
|
||
model[(config as any).name] = (config as any).initValue;
|
||
}
|
||
},
|
||
});
|
||
|
||
// 复合字段：把组件内部渲染的 MContainer 配置交出来
|
||
registerField('my-composite', {
|
||
innerConfig: ({ config, model, prop }) => ({
|
||
// 对应组件内部 <MContainer :config="childConfig" :model="model[name]" :prop="prop">
|
||
config: childConfig,
|
||
model: model[config.name],
|
||
prop,
|
||
}),
|
||
});
|
||
|
||
// typeMatch：覆盖或扩展该 type 的类型匹配校验，可与 innerConfig / effect 同时登记
|
||
registerField('my-status', {
|
||
typeMatch: (value, { message }) => (typeof value === 'string' ? undefined : message || '应为字符串'),
|
||
});
|
||
```
|
||
|
||
返回的 `config` 的 `name` 会被追加到返回的 `prop` 上。因此当内部配置复用了字段自身的 `name`（例如内部渲染 `<MGroupList :config="{ name, items }" :model="model" :prop="prop">`）时，要返回 `parentProp` 而非 `prop`，否则 `name` 会被拼两次：
|
||
|
||
```ts
|
||
registerField('my-list', {
|
||
innerConfig: ({ config, parentProp }) => ({
|
||
config: { type: 'group-list', name: config.name, items: innerItems },
|
||
prop: parentProp,
|
||
}),
|
||
});
|
||
```
|
||
|
||
编辑器侧四个复合字段（`code-select` / `display-conds` / `event-select` / `style-setter`）的登记可参考 `packages/editor/src/fields/headless-validation.ts`：innerConfig 与组件共用同一份配置工厂（`packages/editor/src/fields/configs/`），避免两条链路各写一份而逐渐跑偏。
|
||
|
||
`type: 'component'` 会把 `config.component` 当任意 Vue 组件渲染。无渲染校验把它视为叶子，**不会**遍历内部结构。因此该组件不得再向父表单注册 FormItem；需要嵌套表单项时，应对该具体组件 `registerField(type, { innerConfig })`。
|
||
|
||
### 重复登记与撤销
|
||
|
||
同一个 type 多次登记按字段浅合并，后一次只覆盖自己传入的 key：
|
||
|
||
```ts
|
||
registerField('my-composite', { innerConfig });
|
||
registerField('my-composite', { component: MyComposite }); // innerConfig 仍在
|
||
```
|
||
|
||
登记分「内置」与「业务」两层。`app.use(MagicForm)` / `registerBuiltInFields` 写内置层，`registerField` / `registerFields` 写业务层；读取时业务层优先，`unregisterField` / `clearFields` 只清业务层，内置字段不受影响（单测里 `clearFields` 之后仍能校验 `text`、`tab` 等内置 type）。
|
||
|
||
因为是合并语义，把一个已登记 `innerConfig` 的 type 改成普通叶子，不能靠再传一次空对象，要先撤销：
|
||
|
||
```ts
|
||
registerField('my-composite', {}); // ✗ 合并后 innerConfig 还在，仍会下钻
|
||
unregisterField('my-composite'); // ✓ 先清掉业务层登记
|
||
registerField('my-composite', { component: MyComposite });
|
||
```
|
||
|
||
一次登记里同时传多个形态时的优先级：`walk` > `innerConfig` > `effect`（叶子），命中低优先级的那份会被忽略并在控制台给出告警。
|
||
|
||
## 签名
|
||
|
||
```ts
|
||
function submitForm(options: SubmitFormOptions): Promise<any>;
|
||
```
|
||
|
||
## 参数
|
||
|
||
`options` 与 `MForm` 组件的 props 基本对齐，额外提供了 `native`、`returnChangeRecords`、`dialog`、`signal` 等参数。`appContext` 仅 `dialog: true` 时生效。
|
||
|
||
| 名称 | 类型 | 默认值 | 说明 |
|
||
| ---------------------- | ------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
|
||
| `config` | `FormConfig` | — | 必填，表单配置 |
|
||
| `initValues` | `Record<string, any>` | `{}` | 表单初始值 |
|
||
| `lastValues` | `Record<string, any>` | `{}` | 需对比的值（开启对比模式时传入） |
|
||
| `isCompare` | `boolean` | `false` | 是否开启对比模式 |
|
||
| `parentValues` | `Record<string, any>` | `{}` | 父级 values，透传给字段的回调 |
|
||
| `labelWidth` | `string` | `'200px'` | label 宽度 |
|
||
| `disabled` | `boolean` | `false` | 是否禁用 |
|
||
| `height` | `string` | `'auto'` | 表单高度 |
|
||
| `stepActive` | `string \| number` | `1` | 步骤表单当前激活步骤 |
|
||
| `size` | `'small' \| 'default' \| 'large'` | — | 组件尺寸 |
|
||
| `inline` | `boolean` | `false` | 是否行内表单 |
|
||
| `labelPosition` | `string` | `'right'` | label 对齐方式 |
|
||
| `keyProp` | `string` | `'__key'` | 配置项的唯一 key |
|
||
| `popperClass` | `string` | — | 弹层 className |
|
||
| `preventSubmitDefault` | `boolean` | — | 是否阻止表单原生 submit |
|
||
| `useFieldTextInError` | `boolean` | `true` | 校验失败时错误提示前缀是否使用字段的 `text` 文案；`false` 时直接使用字段 `name` |
|
||
| `context` | `FormContext` | — | 宿主业务上下文，与 MForm 的 `context` 语义一致；配置回调通过 `mForm.xxx` 读穿取用 |
|
||
| `native` | `boolean` | `false` | 透传给 `Form.submitForm`。`true` 时返回内部响应式 `values`，否则返回 `cloneDeep(toRaw(values))` |
|
||
| `returnChangeRecords` | `boolean` | `false` | `true` 时 resolve 结果为 `{ values, changeRecords }`，携带表单变更记录；否则仅 resolve `values` |
|
||
| `appContext` | `AppContext \| null` | `null` | 父级 Vue 应用上下文。仅 `dialog: true` 时生效，用于继承全局组件、指令、provide 等，常通过 `app._context` 或 `getCurrentInstance()?.appContext` 获取 |
|
||
| `dialog` | `boolean` | `false` | `true` 时把表单以弹层形式渲染出来，点击「确定」才提交，「取消」则以 reject 中断；校验失败会保留弹层并展示错误，便于修正后重试。等待人工操作，可用 `signal` 中断 |
|
||
| `title` | `string` | `'submitForm'` / `'validateForm'` | 弹层标题，仅 `dialog: true` 时生效 |
|
||
| `signal` | `AbortSignal` | — | 外部中断信号。abort 时立即以 `signal.reason` reject，并卸载 `dialog` 模式下已挂载的临时表单实例 |
|
||
|
||
## 返回值
|
||
|
||
- `校验通过` — `Promise<any>` resolve 当前表单值（`native` 决定是否克隆）；当 `returnChangeRecords` 为 `true` 时，resolve `{ values, changeRecords }`
|
||
- `校验失败` — `Promise<any>` reject 一个 `Error`，`message` 中包含逐条字段错误信息（格式 `${text} -> ${message}`，多条用 `<br>` 分隔）
|
||
|
||
`dialog: true` 时无论成功或失败，函数都会在最后自动 `unmount` 内部 app 并移除挂载用的 DOM 容器，无需调用方手动清理。
|
||
|
||
::: tip 关于 changeRecords
|
||
`changeRecords` 记录的是表单挂载后发生的字段变更（由各字段的 `change` 事件累积而来）。无渲染校验没有用户交互，因此固定返回空数组；只有 `dialog: true` 时才可能有内容（`MForm` 内部的 `submitForm` 在校验通过后会清空变更记录，因此本函数会在调用前先做快照）。
|
||
:::
|
||
|
||
## 基础用法
|
||
|
||
```ts
|
||
import { submitForm } from '@tmagic/form';
|
||
|
||
try {
|
||
const values = await submitForm({
|
||
config: [
|
||
{
|
||
type: 'text',
|
||
name: 'username',
|
||
text: '用户名',
|
||
rules: [
|
||
{ required: true, message: '请输入用户名' },
|
||
{ typeMatch: true, message: '用户名类型不合法' },
|
||
],
|
||
},
|
||
],
|
||
initValues: { username: '' },
|
||
});
|
||
console.log('提交成功', values);
|
||
} catch (e) {
|
||
console.error('校验失败', e);
|
||
}
|
||
```
|
||
|
||
## 同时获取变更记录（changeRecords）
|
||
|
||
设置 `returnChangeRecords: true` 后，resolve 的结果会从单纯的 `values` 变为 `{ values, changeRecords }`：
|
||
|
||
```ts
|
||
import { submitForm } from '@tmagic/form';
|
||
|
||
const { values, changeRecords } = await submitForm({
|
||
config: [{ type: 'text', name: 'username', text: '用户名' }],
|
||
initValues: { username: 'foo' },
|
||
returnChangeRecords: true,
|
||
});
|
||
|
||
console.log(values); // { username: 'foo' }
|
||
console.log(changeRecords); // ChangeRecord[]
|
||
```
|
||
|
||
## 弹层模式（`dialog: true`）下继承父级应用上下文
|
||
|
||
默认路径不挂载组件，不需要 `appContext`。只有 `dialog: true` 会渲染弹层，此时 `MForm` 要用到 `@tmagic/design` 的组件（背后可能是 `element-plus` 或 `tdesign`），需要把宿主应用的上下文带过去：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { getCurrentInstance } from 'vue';
|
||
|
||
import { submitForm } from '@tmagic/form';
|
||
|
||
const { appContext } = getCurrentInstance()!;
|
||
|
||
const onClick = async () => {
|
||
const values = await submitForm({
|
||
config: [{ type: 'text', name: 'text', text: '文本' }],
|
||
initValues: { text: 'hello' },
|
||
dialog: true,
|
||
title: '编辑配置',
|
||
appContext,
|
||
});
|
||
console.log(values);
|
||
};
|
||
</script>
|
||
```
|
||
|
||
也可以在初始化 app 时把上下文缓存下来，再在任意位置复用：
|
||
|
||
```ts
|
||
import { createApp } from 'vue';
|
||
import ElementPlus from 'element-plus';
|
||
import MagicForm, { type SubmitFormOptions, submitForm as rawSubmitForm } from '@tmagic/form';
|
||
|
||
import App from './App.vue';
|
||
|
||
const app = createApp(App);
|
||
app.use(ElementPlus);
|
||
app.use(MagicForm);
|
||
app.mount('#app');
|
||
|
||
export const submitForm = (options: Omit<SubmitFormOptions, 'appContext'>) =>
|
||
rawSubmitForm({ ...options, appContext: app._context });
|
||
```
|
||
|
||
## 处理校验错误
|
||
|
||
校验失败时 reject 的 `Error.message` 已经把出错字段拼好，可以直接展示到用户：
|
||
|
||
```ts
|
||
import { tMagicMessage } from '@tmagic/design';
|
||
|
||
try {
|
||
const values = await submitForm({ config, initValues });
|
||
await save(values);
|
||
} catch (e: any) {
|
||
tMagicMessage.error({
|
||
dangerouslyUseHTMLString: true,
|
||
message: e.message,
|
||
});
|
||
}
|
||
```
|
||
|
||
## validateForm 函数
|
||
|
||
`validateForm` 与 `submitForm` 共用同一套无渲染校验实现，区别在于它是**静默**的：校验失败不抛异常、不返回表单值，而是以返回值形式给出错误文案。适合「只想探测这份配置是否合法」的场景，例如源码编辑器保存后校验、批量校验组件配置。
|
||
|
||
```ts
|
||
function validateForm(options: ValidateFormOptions): Promise<string>;
|
||
```
|
||
|
||
`options` 取 `SubmitFormOptions` 中与校验相关的子集（`config`、`initValues`、`parentValues`、`labelWidth`、`keyProp`、`useFieldTextInError`、`extendState`、`typeMatchValid`、`appContext`、`dialog`、`title`、`signal`）。
|
||
|
||
```ts
|
||
import { validateForm } from '@tmagic/form';
|
||
|
||
const error = await validateForm({
|
||
config: [{ type: 'text', name: 'username', text: '用户名', rules: [{ required: true, message: '请输入用户名' }] }],
|
||
initValues: { username: '' },
|
||
});
|
||
|
||
if (error) {
|
||
// '用户名 -> 请输入用户名'
|
||
}
|
||
```
|
||
|
||
校验通过返回空字符串 `''`，否则返回以 `<br>` 拼接的错误文案。无法完成校验时才会 reject（例如 innerConfig 回调失败抛出 `FieldInnerConfigError`）。
|
||
|
||
## 运行环境
|
||
|
||
无渲染实现不接触 `document` / `window`，因此在任何 JS 运行时中都可用：
|
||
|
||
| 环境 | 是否可用 | 说明 |
|
||
| ------------------------------------------ | -------- | ------------------------------------------------------------------------------------- |
|
||
| 浏览器 / Electron 渲染进程 / 浏览器扩展 | ✅ | 直接可用 |
|
||
| Vitest / Jest + `happy-dom` / `jsdom` | ✅ | 项目自身的单测就跑在这种环境下 |
|
||
| 纯 Node.js / Bun / Deno（无 DOM polyfill） | ✅ | 从 `@tmagic/form/headless` 引入，不要用 `@tmagic/form` 主入口 |
|
||
|
||
```ts
|
||
// scripts/check-form.ts —— 纯 Node 环境，无需任何 DOM polyfill
|
||
import { builtInFields, registerBuiltInFields, registerFields, validateForm } from '@tmagic/form/headless';
|
||
import { editorFields } from '@tmagic/editor/headless';
|
||
|
||
// `builtInFields` 只是数据；未 `app.use(MagicForm)` 时要自己登记
|
||
registerBuiltInFields(builtInFields);
|
||
registerFields(editorFields);
|
||
|
||
const error = await validateForm({
|
||
config: [{ type: 'text', name: 'username', text: '用户名', rules: [{ required: true }] }],
|
||
initValues: { username: '' },
|
||
});
|
||
|
||
if (error) {
|
||
console.error(error);
|
||
process.exit(1);
|
||
}
|
||
```
|
||
|
||
::: warning 注意
|
||
`dialog: true` 依赖 DOM 与已安装的 UI 库（`element-plus` / `tdesign`），在纯 Node 环境中不可用。
|
||
:::
|
||
|
||
::: warning ESM 与 CJS 不要混用
|
||
`@tmagic/form/headless` 的 ESM 产物与 `@tmagic/form` 共用同一批模块文件，字段注册表是同一份，两个入口可以混着 `import`。
|
||
|
||
CJS 产物是两个各自独立的 bundle，注册表不共享。所以同一进程里不要同时 `require('@tmagic/form')` 和 `require('@tmagic/form/headless')`——在一边 `registerField` 另一边读不到，校验会因为「没登记过这个 type」而静默放过。`@tmagic/editor` 与 `@tmagic/design` 的 headless 子路径同理。
|
||
:::
|
||
|
||
## 类型定义
|
||
|
||
::: details 查看 `SubmitFormOptions` 类型定义
|
||
<<< @/../packages/form/src/utils/submitHeadless.ts#SubmitFormOptions{ts}
|
||
:::
|
||
|
||
::: details 查看 `SubmitFormResult` 类型定义
|
||
<<< @/../packages/form/src/utils/submitHeadless.ts#SubmitFormResult{ts}
|
||
:::
|