@tmagic/form 1.8.0-manmanyu.8 → 1.8.0

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-manmanyu.8",
+  "version": "1.8.0",
   "name": "@tmagic/form",
   "type": "module",
   "sideEffects": [
@@ -17,6 +17,11 @@
       "import": "./dist/es/index.js",
       "require": "./dist/tmagic-form.umd.cjs"
     },
+    "./headless": {
+      "types": "./types/headless.d.ts",
+      "import": "./dist/es/headless.js",
+      "require": "./dist/tmagic-form-headless.umd.cjs"
+    },
     "./dist/style.css": {
       "import": "./dist/style.css",
       "require": "./dist/style.css"
@@ -40,21 +45,22 @@
   "dependencies": {
     "@element-plus/icons-vue": "^2.3.2",
     "@popperjs/core": "^2.11.8",
-    "dayjs": "^1.11.19",
-    "lodash-es": "^4.17.21",
-    "sortablejs": "^1.15.6"
+    "async-validator": "^4.2.5",
+    "dayjs": "^1.11.23",
+    "lodash-es": "^4.18.1",
+    "sortablejs": "^1.15.7"
   },
   "devDependencies": {
-    "@types/lodash-es": "^4.17.4",
+    "@types/lodash-es": "^4.17.12",
     "@types/sortablejs": "^1.15.9",
-    "@vue/test-utils": "^2.4.6"
+    "@vue/test-utils": "^2.5.1"
   },
   "peerDependencies": {
-    "vue": "^3.5.34",
     "typescript": "^6.0.3",
-    "@tmagic/design": "1.8.0-manmanyu.8",
-    "@tmagic/utils": "1.8.0-manmanyu.8",
-    "@tmagic/form-schema": "1.8.0-manmanyu.8"
+    "vue": "^3.5.43",
+    "@tmagic/design": "1.8.0",
+    "@tmagic/form-schema": "1.8.0",
+    "@tmagic/utils": "1.8.0"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/Form.vue

@@ -23,6 +23,7 @@
         :last-values="lastValuesProcessed"
         :is-compare="isCompare"
         :label-width="item.labelWidth || labelWidth"
+        :label-position="item.labelPosition || labelPosition"
         :step-active="stepActive"
         :size="size"
         @change="changeHandler"
@@ -36,25 +37,26 @@
 </template>
 
 <script setup lang="ts">
-import { computed, inject, provide, reactive, ref, shallowRef, toRaw, useTemplateRef, watch, watchEffect } from 'vue';
-import { cloneDeep, isEqual } from 'lodash-es';
+import { computed, inject, nextTick, provide, reactive, ref, shallowRef, toRaw, useTemplateRef, watch } from 'vue';
+import { cloneDeep, isEqualWith } from 'lodash-es';
 
 import { M_THEME_KEY, TMagicForm, tMagicMessage, tMagicMessageBox } from '@tmagic/design';
 import { setValueByKeyPath } from '@tmagic/utils';
 
 import Container from './containers/Container.vue';
-import { getConfig } from './utils/config';
-import { initValue } from './utils/form';
+import { applyMountValueEffects } from './utils/collectFields';
+import { createFormStateBase, createFormStateProxy, initValue, mergeFormContexts } from './utils/form';
+import { formatValidateError as formatError, getTextByName as findTextByName } from './utils/validateError';
 import type {
   ChangeRecord,
   ContainerChangeEventData,
   FormConfig,
+  FormContext,
   FormSlots,
   FormState,
   FormValue,
-  ValidateError,
 } from './schema';
-import { FORM_DIFF_CONFIG_KEY } from './schema';
+import { FORM_CONTEXT_KEY, FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY } from './schema';
 
 defineOptions({
   name: 'MForm',
@@ -74,16 +76,37 @@ const props = withDefaults(
     isCompare?: boolean;
     parentValues?: Record<string, any>;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /**
+     * 初始化（`config` / `initValues` 就绪）后是否立即执行一次表单校验。
+     *
+     * - `false`（默认）：不自动校验，避免打开表单时就展示错误态；
+     * - `true`：初始化完成后在 `nextTick` 中调用 `validate()`。
+     */
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
     size?: 'small' | 'default' | 'large';
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     keyProp?: string;
     popperClass?: string;
     preventSubmitDefault?: boolean;
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+     *
+     * - `true`（默认）：错误提示形如 `字段文案 -> 错误信息`，找不到 text 时回退为字段 name；
+     * - `false`：跳过查找，直接使用字段 name 作为错误提示前缀（形如 `字段name -> 错误信息`）。
+     */
+    useFieldTextInError?: boolean;
+    /**
+     * 宿主业务上下文。也可由祖先 `provide(FORM_CONTEXT_KEY)` 下发，本 prop 覆盖祖先的同名字段。
+     *
+     * 配置回调通过 `mForm.xxx` 读取，由 formState 的读穿 Proxy 落到这里。
+     */
+    context?: FormContext;
     /**
      * 自定义"是否展示对比内容"的判断函数（仅在 `isCompare === true` 时生效）。
      *
@@ -134,18 +157,22 @@ const props = withDefaults(
     inline: false,
     labelPosition: 'right',
     keyProp: '__key',
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 
 const emit = defineEmits(['change', 'error', 'field-input', 'field-change', 'update:stepActive']);
 
+provide(
+  FORM_TYPE_MATCH_VALID_KEY,
+  computed(() => props.typeMatchValid),
+);
+
 const tMagicFormRef = useTemplateRef('tMagicForm');
 const initialized = ref(false);
 const values = ref<FormValue>({});
 const lastValuesProcessed = ref<FormValue>({});
-const fields = new Map<string, any>();
-
-const requestFuc = getConfig('request') as Function;
 
 /**
  * 当前表单生效的主题名称：
@@ -178,18 +205,14 @@ const themeClass = computed(() => (effectiveTheme.value ? `m-theme--${effectiveT
  * 2. `values` / `lastValuesProcessed` 是 ref，Vue 的 `reactive` 会自动解包，因此每次
  *    访问 `formState.values` / `formState.lastValuesProcessed` 也都是当前 ref 值。
  *
- * 3. `extendState` 注入的字段在下方的 `watchEffect` 中合并到 `formState`：
- *    - data 描述符（普通字段）通过 `formState[key] = value` 写入，走 reactive proxy 的
- *      set，触发依赖通知；`extendState` 同步段读到的响应式数据变化时会自动重跑，
- *      把最新值刷进 formState。
- *    - accessor 描述符（`{ get stage() { return ... } }`）按原样写入，调用方可以控制
- *      读时求值，每次读取都会重新执行 getter。
+ * 3. 宿主业务上下文不再 merge 进 coreState，而是单独放在 `contextRef` 上，由读穿
+ *    Proxy 在 miss 时落到 context。核心字段结构性优先，`mForm.xxx` 永久兼容旧读法。
  *
  * 4. `popperClass` 会自动拼接 `themeClass`：调用方传入的 `popperClass` + 当前主题
  *    修饰类（含祖先 `<MEditor>` provide 的主题）。这样所有透传到 Element Plus 弹层
  *    `popper-class` 的字段（Select / DateTime / Cascader 等）能自带主题作用域。
  */
-const formState: FormState = reactive<FormState>({
+const coreState: FormState = reactive<FormState>({
   get keyProp() {
     return props.keyProp;
   },
@@ -218,72 +241,21 @@ const formState: FormState = reactive<FormState>({
   values,
   lastValuesProcessed,
   $emit: emit as (_event: string, ..._args: any[]) => void,
-  fields,
-  setField: (prop: string, field: any) => fields.set(prop, field),
-  getField: (prop: string) => fields.get(prop),
-  deleteField: (prop: string) => fields.delete(prop),
-  $messageBox: tMagicMessageBox,
-  $message: tMagicMessage,
-  post: (options: any) => {
-    if (requestFuc) {
-      return requestFuc({
-        method: 'POST',
-        ...options,
-      });
-    }
-  },
+  ...createFormStateBase({ $message: tMagicMessage, $messageBox: tMagicMessageBox }),
 });
 
+const ancestorContext = inject(FORM_CONTEXT_KEY, undefined);
+
 /**
- * `extendState` 的同步段（直到第一个 `await` 之前）所访问的任何响应式数据，
- * 都会被 `watchEffect` 自动跟踪。这样可以兼容历史用法 ——
- *
- *   extendState: (formState) => ({
- *     username: store.username,   // 同步读 store，会被跟踪
- *     env: store.env,
- *   })
- *
- * 当 `store.username` 变化时，整个 effect 重跑，新值会被刷进 `formState`。
- *
- * prop 派生字段（initValues / config / ...）已经在上方用 getter 定义，
- * 这里不再重复同步；因此 `props.initValues` 这类高频变化也不会再触发
- * `extendState` 重跑（旧版的性能问题修复点）。
- *
- * 实现细节：
- * - data 描述符：通过 `formState[key] = value` 走 reactive proxy 的 set，
- *   触发依赖通知；与旧版「逐项赋值」语义完全等价。
- * - accessor 描述符（`{ get stage() {...} }`）按原样写入 formState，调用方
- *   可以自行控制读时求值；强制 `configurable: true` 以便下一次重跑可再 define。
+ * 宿主业务上下文：`props.context` 覆盖祖先注入的同名字段。
+ * 嵌套表单（Link / FormBox / FormDialog）通过下面的 provide 自动继承。
  */
-watchEffect(async (onCleanup) => {
-  const { extendState } = props;
-  if (typeof extendState !== 'function') return;
-
-  let stale = false;
-  onCleanup(() => {
-    stale = true;
-  });
-
-  let state: Record<string, any> = {};
-  try {
-    state = (await extendState(formState)) || {};
-  } catch (e) {
-    console.error('[MForm] extendState failed:', e);
-    return;
-  }
-  if (stale) return;
-
-  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(state))) {
-    if ('value' in descriptor) {
-      (formState as any)[key] = (state as any)[key];
-    } else {
-      descriptor.configurable = true;
-      Object.defineProperty(formState, key, descriptor);
-    }
-  }
-});
+const contextRef = computed<FormContext>(() => mergeFormContexts(ancestorContext?.value, props.context));
+
+const formState: FormState = createFormStateProxy(coreState, () => contextRef.value);
 
 provide('mForm', formState);
+provide(FORM_CONTEXT_KEY, contextRef);
 
 /**
  * 把生效主题（自身或祖先）再 provide 出去，供 form 子树内含 `Teleport` 的组件
@@ -291,7 +263,7 @@ provide('mForm', formState);
  * 详见 `@tmagic/design/theme.ts`。
  */
 provide(M_THEME_KEY, effectiveTheme);
-
+provide('formInline', props.inline);
 // 对比相关配置单独通过 provide 下发，所有层级的 Container 通过 inject 获取，无需逐层透传 prop。
 // 用 getter 对象保证读取时回到最新的 props 值，维持响应式。
 provide(FORM_DIFF_CONFIG_KEY, {
@@ -305,12 +277,23 @@ provide(FORM_DIFF_CONFIG_KEY, {
 
 const changeRecords = shallowRef<ChangeRecord[]>([]);
 
+/**
+ * 两份配置的结构是否一致；函数一律视为相等。
+ *
+ * 宿主（如编辑器属性面板）往往在每次节点更新后整份重新生成配置，其中的
+ * `display` / `options` / `onChange` 都是新闭包，深比较必然判不等。若据此把 `initialized`
+ * 置 false，整棵表单会卸载重挂，滚动位置、展开态、输入焦点全部丢失。
+ * 配置是响应式 prop，闭包换了照样生效，只有结构变化（增删字段、换组件类型）才需要重挂。
+ */
+const isSameConfigShape = (config: unknown, preConfig: unknown) =>
+  isEqualWith(config, preConfig, (a, b) => (typeof a === 'function' && typeof b === 'function' ? true : undefined));
+
 watch(
   [() => props.config, () => props.initValues],
-  ([config], [preConfig]) => {
+  async ([config], [preConfig]) => {
     changeRecords.value = [];
 
-    if (!isEqual(toRaw(config), toRaw(preConfig))) {
+    if (!isSameConfigShape(toRaw(config), toRaw(preConfig))) {
       initialized.value = false;
     }
 
@@ -319,8 +302,17 @@ watch(
       config: props.config,
     }).then((value) => {
       values.value = value;
+      // 字段的值初始化写入统一在这里执行，字段组件自身不再改写 model。
+      // 必须放在赋值之后：effect 与动态 type / display 回调读到的 formValue 才是这一轮的值。
+      applyMountValueEffects(formState, props.config, values.value);
       // 非对比模式，初始化完成
       initialized.value = !props.isCompare;
+
+      if (props.validateOnInit) {
+        nextTick(() => {
+          tMagicFormRef.value?.validate();
+        });
+      }
     });
 
     if (props.isCompare) {
@@ -330,6 +322,8 @@ watch(
         config: props.config,
       }).then((value) => {
         lastValuesProcessed.value = value;
+        // 对比模式下待对比的那份值同样要规整，否则会与当前值比出「格式差异」这种假差异
+        applyMountValueEffects(formState, props.config, lastValuesProcessed.value);
         initialized.value = true;
       });
     }
@@ -361,45 +355,17 @@ const submitHandler = (e: SubmitEvent) => {
   }
 };
 
+const getTextByName = (name: string, config: FormConfig = props.config): string | undefined =>
+  findTextByName(name, config);
+
 /**
- * 通过 name 从 config 中查找对应的 text
- * @param name - 字段名，支持点分隔的路径格式，如 'a.b.c'
- * @param config - 表单配置数组
- * @returns 找到的 text 值，如果未找到则返回 undefined
+ * 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
+ *
+ * 实现收口在 `utils/validateError`，供渲染式校验（本组件的 `submitForm` / `validate`）与
+ * 无渲染校验（`validateValues`）共用，保证两条链路产出的错误文案格式完全一致。
  */
-const getTextByName = (name: string, config: FormConfig = props.config): string | undefined => {
-  if (!name || !Array.isArray(config)) return undefined;
-
-  const nameParts = name.split('.');
-
-  const findInConfig = (configs: FormConfig, parts: string[]): string | undefined => {
-    if (parts.length === 0) return undefined;
-
-    const [currentPart, ...remainingParts] = parts;
-
-    for (const item of configs) {
-      if (item.name === currentPart) {
-        if (remainingParts.length === 0) {
-          return typeof item.text === 'string' ? item.text : undefined;
-        }
-
-        if ('items' in item && Array.isArray(item.items)) {
-          const result = findInConfig(item.items, remainingParts);
-          if (result !== undefined) return result;
-        }
-      }
-
-      if ('items' in item && Array.isArray(item.items)) {
-        const result = findInConfig(item.items, parts);
-        if (result !== undefined) return result;
-      }
-    }
-
-    return undefined;
-  };
-
-  return findInConfig(config, nameParts);
-};
+const formatValidateError = (invalidFields: Record<string, any>): string =>
+  formatError(invalidFields, { config: props.config, useFieldTextInError: props.useFieldTextInError });
 
 defineExpose({
   values,
@@ -428,18 +394,36 @@ defineExpose({
     } catch (invalidFields: any) {
       emit('error', invalidFields);
 
-      const error: string[] = [];
-
-      Object.entries(invalidFields).forEach(([prop, ValidateError]) => {
-        (ValidateError as ValidateError[]).forEach(({ field, message }) => {
-          const name = field || prop;
-          const text = getTextByName(name, props.config) || name;
-
-          error.push(`${text} -> ${message}`);
-        });
-      });
+      throw new Error(formatValidateError(invalidFields));
+    }
+  },
 
-      throw new Error(error.join('<br>'));
+  /**
+   * 校验：对表单当前值执行校验，返回汇总后的错误文案。
+   *
+   * 与 `submitForm` 的区别：
+   * - 校验失败时不抛异常、不触发 `error` 事件，而是以返回值形式给出错误文案；
+   * - 不重置 `changeRecords`，不改变提交语义，仅用于「探测」当前配置是否合法。
+   *
+   * 注意：本方法只改变「校验结果的返回方式」，并不负责「不污染页面表单状态」——
+   * 若需对一份独立的「配置 + 值」做完全不影响页面上已渲染表单的校验，请使用 `validateForm`
+   * （内部会新建一个隐藏的 MForm 实例，通过 `initValues` 传入待校验值，用完即卸载）。
+   *
+   * 典型用途：作为 `validateForm` 内部复用的校验实现；也可在已渲染的表单实例上主动调用，
+   * 根据返回的错误文案自行决定后续处理（如记录节点错误状态）。
+   *
+   * @returns 校验通过返回空字符串 `''`，否则返回以 `<br>` 拼接的错误文案。
+   */
+  validate: async (): Promise<string> => {
+    try {
+      const result = await tMagicFormRef.value?.validate();
+      // tdesign 通过返回值返回校验结果，element-plus 通过 throw error
+      if (result !== true) {
+        throw result;
+      }
+      return '';
+    } catch (invalidFields: any) {
+      return formatValidateError(invalidFields);
     }
   },
 

package/src/FormBox.vue

@@ -13,7 +13,10 @@
           :label-position="labelPosition"
           :inline="inline"
           :prevent-submit-default="preventSubmitDefault"
-          :extend-state="extendState"
+          :use-field-text-in-error="useFieldTextInError"
+          :context="context"
+          :type-match-valid="typeMatchValid"
+          :validate-on-init="validateOnInit"
           @change="changeHandler"
         ></Form>
         <slot></slot>
@@ -41,7 +44,7 @@ import { computed, ref, watchEffect } from 'vue';
 import { TMagicButton, TMagicScrollbar } from '@tmagic/design';
 
 import Form from './Form.vue';
-import type { ContainerChangeEventData, FormConfig, FormState, FormValue } from './schema';
+import type { ContainerChangeEventData, FormConfig, FormContext, FormValue } from './schema';
 
 defineOptions({
   name: 'MFormBox',
@@ -55,18 +58,27 @@ const props = withDefaults(
     width?: number;
     height?: number;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     disabled?: boolean;
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     preventSubmitDefault?: boolean;
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
+    useFieldTextInError?: boolean;
+    /** 透传给内部 `MForm` 的宿主业务上下文 */
+    context?: FormContext;
   }>(),
   {
     config: () => [],
     values: () => ({}),
     confirmText: '确定',
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/FormDialog.vue

@@ -31,7 +31,10 @@
         :label-position="labelPosition"
         :inline="inline"
         :prevent-submit-default="preventSubmitDefault"
-        :extend-state="extendState"
+        :use-field-text-in-error="useFieldTextInError"
+        :type-match-valid="typeMatchValid"
+        :validate-on-init="validateOnInit"
+        :context="context"
         :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
@@ -70,7 +73,7 @@ import { computed, inject, provide, ref } from 'vue';
 import { M_THEME_KEY, TMagicButton, TMagicCol, TMagicDialog, TMagicRow } from '@tmagic/design';
 
 import Form from './Form.vue';
-import { ContainerChangeEventData, FormConfig, FormState, FormValue, StepConfig } from './schema';
+import { ContainerChangeEventData, FormConfig, FormContext, FormValue, StepConfig } from './schema';
 
 defineOptions({
   name: 'MFormDialog',
@@ -83,11 +86,15 @@ const props = withDefaults(
     parentValues?: Object;
     width?: string | number;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     fullscreen?: boolean;
     disabled?: boolean;
     title?: string;
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     zIndex?: number;
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
@@ -97,8 +104,10 @@ const props = withDefaults(
     destroyOnClose?: boolean;
     showClose?: boolean;
     showCancel?: boolean;
-    /** 透传给内部 `MForm`，用于扩展 `formState`（如注入 `$message` / `$store` 等） */
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
+    useFieldTextInError?: boolean;
+    /** 透传给内部 `MForm` 的宿主业务上下文 */
+    context?: FormContext;
     /**
      * 主题名。优先级：传入 `theme` prop > 祖先 `provide(M_THEME_KEY)` > 空串。
      * 计算结果会再次 `provide` 出去，使得 Dialog 被 Teleport 到 body 后，内部子树
@@ -115,6 +124,8 @@ const props = withDefaults(
     destroyOnClose: false,
     showClose: true,
     showCancel: true,
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/FormDrawer.vue

@@ -2,7 +2,7 @@
   <TMagicDrawer
     :class="['m-form-drawer', effectiveTheme ? `m-theme--${effectiveTheme}` : '']"
     ref="drawer"
-    v-model="visible"
+    v-model="dialogVisible"
     :title="title"
     :close-on-press-escape="closeOnPressEscape"
     :append-to-body="true"
@@ -16,7 +16,7 @@
     @close="closeHandler"
     @closed="closedHandler"
   >
-    <div v-if="visible" ref="drawerBody" class="m-drawer-body">
+    <div v-if="dialogVisible" ref="drawerBody" class="m-drawer-body">
       <Form
         ref="form"
         :size="size"
@@ -28,7 +28,10 @@
         :label-position="labelPosition"
         :inline="inline"
         :prevent-submit-default="preventSubmitDefault"
-        :extend-state="extendState"
+        :use-field-text-in-error="useFieldTextInError"
+        :type-match-valid="typeMatchValid"
+        :validate-on-init="validateOnInit"
+        :context="context"
         :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
@@ -61,10 +64,10 @@ import { computed, inject, provide, ref, watchEffect } from 'vue';
 import { M_THEME_KEY, TMagicButton, TMagicCol, TMagicDrawer, TMagicRow } from '@tmagic/design';
 
 import Form from './Form.vue';
-import type { ContainerChangeEventData, FormConfig, FormState, FormValue } from './schema';
+import type { ContainerChangeEventData, FormConfig, FormContext, FormValue } from './schema';
 
 defineOptions({
-  name: 'MFormDialog',
+  name: 'MFormDrawer',
 });
 
 const props = withDefaults(
@@ -74,6 +77,10 @@ const props = withDefaults(
     parentValues?: Object;
     width?: string | number;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     disabled?: boolean;
     closeOnPressEscape?: boolean;
     title?: string;
@@ -81,12 +88,14 @@ const props = withDefaults(
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     preventSubmitDefault?: boolean;
+    /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
+    useFieldTextInError?: boolean;
     /** 关闭前的回调，会暂停 Drawer 的关闭; done 是个 function type 接受一个 boolean 参数, 执行 done 使用 true 参数或不提供参数将会终止关闭 */
     beforeClose?: (_done: (_cancel?: boolean) => void) => void;
-    /** 透传给内部 `MForm`，用于扩展 `formState`（如注入 `$message` / `$store` 等） */
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /** 透传给内部 `MForm` 的宿主业务上下文 */
+    context?: FormContext;
     /**
      * 主题名。优先级：传入 `theme` prop > 祖先 `provide(M_THEME_KEY)` > 空串。
      * 计算结果会再次 `provide` 出去，使得 Drawer 被 Teleport 到 body 后，内部子树
@@ -99,6 +108,8 @@ const props = withDefaults(
     config: () => [],
     values: () => ({}),
     confirmText: '确定',
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 
@@ -111,7 +122,7 @@ const emit = defineEmits(['close', 'closed', 'submit', 'error', 'change', 'open'
 const drawer = ref<InstanceType<typeof TMagicDrawer>>();
 const form = ref<InstanceType<typeof Form>>();
 const drawerBody = ref<HTMLDivElement>();
-const visible = ref(false);
+const dialogVisible = ref(false);
 const saveFetch = ref(false);
 const bodyHeight = ref(0);
 
@@ -152,25 +163,42 @@ const closedHandler = () => {
 };
 
 const show = () => {
-  visible.value = true;
+  dialogVisible.value = true;
 };
 
 const hide = () => {
-  visible.value = false;
+  dialogVisible.value = false;
+};
+const close = () => {
+  dialogVisible.value = false;
+};
+const cancel = () => {
+  hide();
 };
-
 /** 用于关闭 Drawer, 该方法会调用传入的 before-close 方法 */
 const handleClose = () => {
   drawer.value?.handleClose();
 };
 
+const save = async () => {
+  try {
+    const changeRecords = [...(form.value?.changeRecords || [])];
+    const values = await form.value?.submitForm();
+    emit('submit', values, { changeRecords });
+  } catch (e) {
+    emit('error', e);
+  }
+};
+
 defineExpose({
   form,
   saveFetch,
   bodyHeight,
-
+  close,
   show,
   hide,
+  save,
+  cancel,
   handleClose,
 });
 </script>