@tmagic/form 1.8.0-manmanyu.8 → 1.8.0

package/src/utils/formStateProxy.ts

@@ -0,0 +1,149 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { type Ref, unref } from 'vue';
+
+import type { FormContext, FormState } from '../schema';
+
+/** 无上下文时共用的空对象，避免每次读取都分配新对象 */
+const EMPTY_CONTEXT: FormContext = Object.freeze({});
+
+/**
+ * 按优先级分层合并上下文，**靠后的层优先**。
+ *
+ * 用读穿 Proxy 而非 `{ ...a, ...b }`：展开会立即执行 accessor，
+ * 而宿主允许用 `{ get stage() { ... } }` 这类读时求值的描述符。
+ */
+export const mergeFormContexts = (...layers: (FormContext | undefined | null)[]): FormContext => {
+  const stack = layers.filter((layer): layer is FormContext => Boolean(layer));
+
+  if (stack.length === 0) return EMPTY_CONTEXT;
+  if (stack.length === 1) return stack[0];
+
+  // 反转成「高优先级在前」，查找时取第一个命中的层
+  const ordered = stack.slice().reverse() as Record<string | symbol, any>[];
+  const owner = (k: string | symbol) => ordered.find((layer) => Reflect.has(layer, k));
+
+  const target: Record<string | symbol, any> = {};
+
+  return new Proxy(target, {
+    get: (_t, k) => owner(k)?.[k],
+    has: (_t, k) => Boolean(owner(k)),
+    ownKeys: () => [...new Set(ordered.flatMap((layer) => Reflect.ownKeys(layer)))],
+    getOwnPropertyDescriptor: (_t, k) => {
+      for (const layer of ordered) {
+        const descriptor = Object.getOwnPropertyDescriptor(layer, k);
+        // 目标是空对象，必须报告为 configurable，否则违反 Proxy 不变式
+        if (descriptor) return { ...descriptor, configurable: true };
+      }
+      return undefined;
+    },
+  }) as FormContext;
+};
+
+/**
+ * 存量下发配置沿用 Vue2 时代的写法，把回调第一个参数当组件实例用，靠 `vm.mForm.xxx`
+ * 取表单状态。这类配置除了读，还会往上面挂方法做跨字段通信，例如：
+ *
+ * ```js
+ * vm.mForm.checkPropertyLimit = async (...) => { ... }   // 一个字段的 validator 里挂
+ * await vm.mForm.checkPropertyLimit(...)                 // 另一处再取出来调用
+ * ```
+ *
+ * 所以 `mForm` 必须能指回某个 formState：读能落到 core / context，写能经 `set` trap
+ * 落到 coreState 并持久化。
+ *
+ * 优先级是 core > context > 合成自引用，三者都是刻意的：
+ *
+ * - **core**：`formState.mForm = formState` 这类直写（如 FormPreview 用自建 services 时）
+ *   必须最优先。
+ * - **context**：唯一的生产者是把父 formState 整体当 context 传下来的嵌套表单
+ *   （ComponentForm）。此时 `mForm` 命中 context 指向**父表单**，与 `extendState` 时代
+ *   把父 formState 并入子状态的结果一致，跨字段通信仍落在同一份对象上。父 formState
+ *   本身也是 Proxy，写入照样持久化，所以这里让 context 赢是对的，别「修正」成指向子表单。
+ * - **合成自引用**：前两者都没有时才兜底，让 `vm.mForm.xxx = fn` 落到自己的 coreState。
+ *
+ * 由此推出一条约束：**不要往 context 里塞普通对象充当 `mForm`**。context 通常是 computed
+ * 产物，依赖一变就重建，挂上去的方法会静默丢失。要么直写 core，要么什么都不放交给兜底。
+ *
+ * 枚举语义上合成的自引用表现得像原型链上的属性：`'mForm' in state` 为真，但不出现在
+ * `Object.keys(state)` 里，`getOwnPropertyDescriptor` 也返回 undefined。这是故意的——
+ * 按扩展字段打包 formState 的调用方（如发给 AI 的逻辑）会因循环引用炸掉。
+ */
+const SELF_REF_KEY = 'mForm';
+
+/**
+ * 将 coreState 与宿主业务上下文关联：读取时优先 core，miss 再读穿到 context。
+ *
+ * - `get` 用属性访问而非 `Reflect.get(t, k, receiver)`，避免破坏 Vue reactive 的 `__v_raw`；
+ * - symbol 键一律只走 core，四个 trap 保持一致。context 是业务数据袋，不承载 symbol 键，
+ *   把 Vue / 工具链的内部 symbol 隔离在 core 上才能让 `toRaw` / `isReactive` 判定正确；
+ * - `ownKeys` + `getOwnPropertyDescriptor` 保证 `Object.entries(formState)` 能枚举到扩展字段
+ *   （admin-web-next 的 `pickPanelFormStateExtendFields` 依赖此语义）；
+ * - `set` 写入 coreState，第三方 `formState.xxx = v` 仍生效且优先于 context。
+ *
+ * 独立成文件，避免与 `form.ts` ↔ `typeMatch.ts` 形成循环依赖。
+ */
+export const createFormStateProxy = (
+  coreState: FormState,
+  getContext: (() => FormContext) | Ref<FormContext>,
+): FormState => {
+  const resolve = (): Record<string | symbol, any> => {
+    const ctx = (typeof getContext === 'function' ? getContext() : unref(getContext)) || EMPTY_CONTEXT;
+    // 把 formState 自己当 context 传回来（`:context="formState"`）会让 get / has 无限递归，
+    // 直接爆栈。这种自引用本就提供不了任何额外字段，断掉即可。
+    return ctx === proxy ? EMPTY_CONTEXT : ctx;
+  };
+
+  const proxy = new Proxy(coreState as object, {
+    get(t, k) {
+      if (typeof k === 'symbol') return Reflect.get(t, k);
+      const v = (t as any)[k];
+      if (v !== undefined || Reflect.has(t, k)) return v;
+
+      const ctx = resolve();
+      if (k in ctx) return ctx[k];
+      // 自引用不进 ownKeys：枚举 formState 的调用方（如按扩展字段打包发给 AI 的逻辑）
+      // 会因为循环引用炸掉，这里只在显式读取时才合成
+      return k === SELF_REF_KEY ? proxy : undefined;
+    },
+    set(t, k, value) {
+      (t as any)[k] = value;
+      return true;
+    },
+    // `mForm` 在这里为真，但不进 ownKeys、getOwnPropertyDescriptor 也返回 undefined
+    // （见 SELF_REF_KEY 注释）。因此展开 / Object.entries 不会循环引用，
+    // 但对 proxy 直接做递归遍历（`for...in`、深拷贝、直接 JSON.stringify(formState)）仍会。
+    has: (t, k) => Reflect.has(t, k) || (typeof k !== 'symbol' && (k in resolve() || k === SELF_REF_KEY)),
+    ownKeys: (t) => [
+      ...new Set([...Reflect.ownKeys(t), ...Reflect.ownKeys(resolve()).filter((k) => typeof k !== 'symbol')]),
+    ],
+    getOwnPropertyDescriptor: (t, k) => {
+      const own = Reflect.getOwnPropertyDescriptor(t, k);
+      if (own) return own;
+      if (typeof k === 'symbol') return undefined;
+
+      const ctx = resolve();
+      if (!(k in ctx)) return undefined;
+      // core 上不存在该键，必须报告为 configurable，否则违反 Proxy 不变式
+      return { configurable: true, enumerable: true, writable: true, value: ctx[k] };
+    },
+  }) as FormState;
+
+  return proxy;
+};

package/src/utils/registerField.ts

@@ -0,0 +1,308 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { App, Component } from 'vue';
+
+import { toLine } from '@tmagic/utils';
+
+import {
+  clearContainerWalkers,
+  type ContainerWalker,
+  deleteContainerWalker,
+  registerContainerWalker,
+} from './collectFields';
+import {
+  clearFieldInnerConfigs,
+  deleteFieldInnerConfig,
+  type FieldInnerConfig,
+  registerFieldInnerConfig,
+} from './fieldInnerConfig';
+import {
+  clearLeafFieldTypes,
+  deleteLeafFieldType,
+  type FieldMountValueEffect,
+  registerLeafFieldType,
+} from './fieldValueEffects';
+import { clearTypeMatchRules, deleteTypeMatchRule, registerTypeMatchRule, type TypeMatchValidator } from './typeMatch';
+
+// #region FieldOptions
+/**
+ * 自定义字段 type 的登记项。
+ *
+ * 不传或只传空对象：当作叶子，不再下钻 `items`。
+ */
+export interface FieldOptions {
+  /**
+   * 渲染用的 Vue 组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-fields-*')`。
+   */
+  component?: Component;
+  /**
+   * 容器组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-form-*')`。
+   */
+  container?: Component;
+  /** 字段挂载时改写 model 的副作用。可与 `innerConfig` 同时登记。 */
+  effect?: FieldMountValueEffect;
+  /**
+   * 按容器模板遍历（tab / table 等）。
+   * 与 `innerConfig` / `effect` 同时传入时 `walk` 优先。
+   */
+  walk?: ContainerWalker;
+  /**
+   * 把内部会挂到父表单的配置交出来。
+   * 可与 `effect` 同时传入：`effect` 负责本字段的值初始化，`innerConfig` 只做配置派生。
+   */
+  innerConfig?: FieldInnerConfig;
+  /** 该 type 的 typeMatch 校验；可与叶子、walk 或 innerConfig 同时登记。 */
+  typeMatch?: TypeMatchValidator;
+}
+
+/**
+ * 无渲染校验用的登记项，不含 Vue 组件。
+ *
+ * 给 Node / `validateForm` / `submitForm` 用。
+ */
+export type HeadlessFieldOptions = Omit<FieldOptions, 'component' | 'container'>;
+// #endregion FieldOptions
+
+const extraComponents = new Map<string, Component>();
+const builtInComponents = new Map<string, Component>();
+
+const applyVueComponent = (
+  type: string,
+  component: Component,
+  app: App | undefined,
+  builtIn: boolean,
+  kind: 'fields' | 'form',
+): void => {
+  const key = toLine(type);
+  if (builtIn) {
+    builtInComponents.set(key, component);
+  } else {
+    extraComponents.set(key, component);
+  }
+  app?.component(`m-${kind}-${key}`, component);
+};
+
+/**
+ * 把已登记字段的 Vue 组件写入注册表；传入 `app` 时同时挂 `m-fields-*` / `m-form-*`。
+ *
+ * @param fields - 字段登记表
+ * @param [app] - Vue 应用；省略则只写入注册表
+ * @param [builtIn=false] - 是否写入内置表（`clearFields` 不会清掉）
+ */
+export const bindFieldApp = (fields: Record<string, FieldOptions>, app?: App, builtIn = false): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    if (options?.component) {
+      applyVueComponent(type, options.component, app, builtIn, 'fields');
+    }
+    if (options?.container) {
+      applyVueComponent(type, options.container, app, builtIn, 'form');
+    }
+  }
+};
+
+/**
+ * 把多份字段登记表按 type 浅合并。后一份只覆盖自己带了的 key，未出现的 key 保留前一份。
+ *
+ * 安装插件时用：Node 侧只登记 `headless`，浏览器再补 `component` / `container`。
+ *
+ * @param tables - 待合并的登记表，`undefined` 会被跳过
+ * @returns 合并后的登记表
+ */
+export const mergeFieldOptions = (
+  ...tables: Array<Record<string, HeadlessFieldOptions | FieldOptions> | undefined>
+): Record<string, FieldOptions> => {
+  const result: Record<string, FieldOptions> = {};
+  for (const table of tables) {
+    if (!table) continue;
+    for (const [type, options] of Object.entries(table)) {
+      result[type] = { ...result[type], ...pickDefinedFieldOptions(options) };
+    }
+  }
+  return result;
+};
+
+const FIELD_OPTION_KEYS = ['component', 'container', 'effect', 'walk', 'innerConfig', 'typeMatch'] as const;
+
+const pickDefinedFieldOptions = (options?: FieldOptions): FieldOptions => {
+  if (!options) return {};
+  const next: FieldOptions = {};
+  for (const key of FIELD_OPTION_KEYS) {
+    if (options[key] !== undefined) {
+      (next as any)[key] = options[key];
+    }
+  }
+  return next;
+};
+
+const extraFieldOptions = new Map<string, FieldOptions>();
+const builtInFieldOptions = new Map<string, FieldOptions>();
+
+const removeFormComponent = (type: string): void => {
+  extraComponents.delete(toLine(type));
+};
+
+const clearFormComponents = (): void => {
+  extraComponents.clear();
+};
+
+/**
+ * 按字段 type 取已登记的渲染组件（`codeSelect` 与 `code-select` 等价）。
+ *
+ * @param type - 字段 type
+ * @returns 已登记的 Vue 组件；未登记则为 `undefined`
+ */
+export const getField = (type: string): Component | undefined => {
+  const key = toLine(type);
+  return extraComponents.get(key) ?? builtInComponents.get(key);
+};
+
+const registerFieldImpl = (type: string, options: FieldOptions | undefined, app: App | undefined, builtIn: boolean) => {
+  if (typeof type !== 'string' || !type) return;
+
+  const key = toLine(type);
+  const store = builtIn ? builtInFieldOptions : extraFieldOptions;
+  const incoming = pickDefinedFieldOptions(options);
+  const merged: FieldOptions = { ...store.get(key), ...incoming };
+  store.set(key, merged);
+
+  if (incoming.walk && (incoming.innerConfig || typeof incoming.effect === 'function')) {
+    console.warn(
+      `[MForm] registerField("${key}"): walk is set together with innerConfig/effect; ` +
+        'headless validation will use walk and innerConfig/effect will be ignored.',
+    );
+  }
+
+  if (incoming.component && incoming.container) {
+    console.warn(
+      `[MForm] registerField("${key}"): component and container are both set; ` +
+        'getField will use container, and both m-fields-* / m-form-* will be registered.',
+    );
+  }
+
+  if (merged.component) {
+    applyVueComponent(type, merged.component, app, builtIn, 'fields');
+  }
+
+  if (merged.container) {
+    applyVueComponent(type, merged.container, app, builtIn, 'form');
+  }
+
+  if (merged.typeMatch) {
+    registerTypeMatchRule(type, merged.typeMatch, builtIn);
+  }
+
+  if (merged.walk) {
+    registerContainerWalker(type, merged.walk, builtIn);
+    if (!builtIn) {
+      deleteLeafFieldType(type);
+      deleteFieldInnerConfig(type);
+    }
+    return;
+  }
+
+  if (!builtIn) {
+    deleteContainerWalker(type);
+  }
+
+  if (merged.innerConfig) {
+    registerFieldInnerConfig(type, merged.innerConfig, builtIn);
+    if (typeof merged.effect === 'function') {
+      registerLeafFieldType(type, merged.effect, builtIn);
+    } else if (!builtIn) {
+      deleteLeafFieldType(type);
+    }
+    return;
+  }
+
+  // 只登记了容器组件：不当叶子，dispatch 会按 items 下钻
+  if (merged.container && !merged.component && typeof merged.effect !== 'function') {
+    if (!builtIn) deleteLeafFieldType(type);
+    return;
+  }
+
+  if (!builtIn) {
+    deleteFieldInnerConfig(type);
+  }
+  registerLeafFieldType(type, merged.effect, builtIn);
+};
+
+/**
+ * 登记一个字段 type 在无渲染校验里的行为，以及可选的渲染组件。
+ *
+ * `type` 会按 Container 的规则归一化为中划线形式（`codeSelect` 与 `code-select` 等价）。
+ * 对同一 type 重复登记按字段浅合并：后一次只覆盖自己传入的 key，未传入的 key 保留。
+ * 传入 `app` 且带了 `component` / `container` 时，会同步 `app.component('m-fields-*'` / `'m-form-*')`。
+ *
+ * @param type - 字段 type
+ * @param [options] - 登记项；省略或空对象视为叶子
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerField = (type: string, options?: FieldOptions, app?: App): void => {
+  registerFieldImpl(type, options, app, false);
+};
+
+/**
+ * 批量登记字段。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerFields = (fields: Record<string, FieldOptions>, app?: App): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    registerFieldImpl(type, options, app, false);
+  }
+};
+
+/**
+ * 登记内置字段（`clearFields` / `unregisterField` 不会清掉）。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerBuiltInFields = (fields: Record<string, FieldOptions>, app?: App): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    registerFieldImpl(type, options, app, true);
+  }
+};
+
+/**
+ * 删除业务侧对指定 type 的登记（不影响内置；主要用于单测）。
+ *
+ * @param type - 字段 type
+ */
+export const unregisterField = (type: string): void => {
+  extraFieldOptions.delete(toLine(type));
+  deleteLeafFieldType(type);
+  deleteFieldInnerConfig(type);
+  deleteTypeMatchRule(type);
+  deleteContainerWalker(type);
+  removeFormComponent(type);
+};
+
+/** 清空业务侧登记（不影响内置；主要用于单测）。 */
+export const clearFields = (): void => {
+  extraFieldOptions.clear();
+  clearLeafFieldTypes();
+  clearFieldInnerConfigs();
+  clearTypeMatchRules();
+  clearContainerWalkers();
+  clearFormComponents();
+};

package/src/utils/submitHeadless.ts

@@ -0,0 +1,206 @@
+/*
+ * Tencent is pleased to support the open source community by making TMagicEditor available.
+ *
+ * Copyright (C) 2025 Tencent.  All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { AppContext } from 'vue';
+import { cloneDeep } from 'lodash-es';
+
+import type { ChangeRecord, FormConfig, FormContext } from '../schema';
+
+import { validateValues, type ValidateValuesResult } from './validateValues';
+
+// #region SubmitFormOptions
+/**
+ * submitForm 函数参数（与 Form.vue 组件 props 对齐）
+ */
+export interface SubmitFormOptions {
+  /** 表单配置 */
+  config: FormConfig;
+  /** 表单初始值 */
+  initValues?: Record<string, any>;
+  /** 需对比的值（开启对比模式时传入） */
+  lastValues?: Record<string, any>;
+  /** 是否开启对比模式 */
+  isCompare?: boolean;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  disabled?: boolean;
+  height?: string;
+  stepActive?: string | number;
+  size?: 'small' | 'default' | 'large';
+  inline?: boolean;
+  labelPosition?: 'top' | 'left' | 'right';
+  keyProp?: string;
+  popperClass?: string;
+  preventSubmitDefault?: boolean;
+  /**
+   * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: FormContext;
+  /** 透传给 Form.submitForm 的参数：是否直接返回原始响应式 values */
+  native?: boolean;
+  /**
+   * 是否在 resolve 结果中携带 changeRecords（变更记录）。
+   * 开启后 resolve 的结果为 `{ values, changeRecords }`，否则仅 resolve values。
+   */
+  returnChangeRecords?: boolean;
+  /**
+   * 父级应用上下文，用于继承全局组件、指令、provide 等。
+   * 仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+// #endregion SubmitFormOptions
+
+// #region SubmitFormResult
+/**
+ * 开启 `returnChangeRecords` 时 submitForm 的返回结果
+ */
+export interface SubmitFormResult {
+  /** 校验通过后的表单值 */
+  values: any;
+  /** 表单变更记录 */
+  changeRecords: ChangeRecord[];
+}
+// #endregion SubmitFormResult
+
+// #region ValidateFormOptions
+/**
+ * validateForm 函数参数（与 Form.vue 组件 props 对齐，取校验所需子集）
+ */
+export interface ValidateFormOptions {
+  /** 表单配置 */
+  config: FormConfig;
+  /** 待校验的表单值 */
+  initValues?: Record<string, any>;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  keyProp?: string;
+  /**
+   * 校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: FormContext;
+  /**
+   * 父级应用上下文。仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+// #endregion ValidateFormOptions
+
+const throwIfAborted = (signal: AbortSignal | undefined, fnName: string) => {
+  if (signal?.aborted) {
+    throw signal.reason ?? new Error(`${fnName} aborted`);
+  }
+};
+
+const throwIfDialog = (dialog: boolean | undefined, fnName: string) => {
+  if (dialog) {
+    throw new Error(
+      `[MForm] ${fnName}({ dialog: true }) is not available from @tmagic/form/headless. Import from @tmagic/form instead.`,
+    );
+  }
+};
+
+/**
+ * `submitForm` 与 `validateForm` 共用的无渲染校验流程：中断检查 → `validateValues`。
+ */
+export const validateWithoutRender = async (
+  fnName: 'submitForm' | 'validateForm',
+  options: SubmitFormOptions | ValidateFormOptions,
+): Promise<ValidateValuesResult> => {
+  const { signal, config, initValues, parentValues, keyProp, typeMatchValid, useFieldTextInError, context } = options;
+
+  throwIfAborted(signal, fnName);
+
+  const result = await validateValues({
+    config,
+    initValues,
+    parentValues,
+    keyProp,
+    popperClass: (options as SubmitFormOptions).popperClass,
+    typeMatchValid,
+    useFieldTextInError,
+    context,
+  });
+
+  throwIfAborted(signal, fnName);
+
+  return result;
+};
+
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次校验并取回表单值（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export const submitForm = async (options: SubmitFormOptions): Promise<any> => {
+  throwIfDialog(options.dialog, 'submitForm');
+
+  const validated = await validateWithoutRender('submitForm', options);
+
+  if (validated.error) throw new Error(validated.error);
+
+  const values = options.native ? validated.values : cloneDeep(validated.values);
+  return options.returnChangeRecords ? { values, changeRecords: [] as ChangeRecord[] } : values;
+};
+
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次静默校验（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export const validateForm = async (options: ValidateFormOptions): Promise<string> => {
+  throwIfDialog(options.dialog, 'validateForm');
+
+  return (await validateWithoutRender('validateForm', options)).error;
+};