@tmagic/form 1.8.0-beta.25 → 1.8.0-beta.26

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.25",
+  "version": "1.8.0-beta.26",
   "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,6 +45,7 @@
   "dependencies": {
     "@element-plus/icons-vue": "^2.3.2",
     "@popperjs/core": "^2.11.8",
+    "async-validator": "^4.2.5",
     "dayjs": "^1.11.21",
     "lodash-es": "^4.18.1",
     "sortablejs": "^1.15.7"
@@ -52,9 +58,9 @@
   "peerDependencies": {
     "typescript": "^6.0.3",
     "vue": "^3.5.41",
-    "@tmagic/form-schema": "1.8.0-beta.25",
-    "@tmagic/design": "1.8.0-beta.25",
-    "@tmagic/utils": "1.8.0-beta.25"
+    "@tmagic/design": "1.8.0-beta.26",
+    "@tmagic/utils": "1.8.0-beta.26",
+    "@tmagic/form-schema": "1.8.0-beta.26"
   },
   "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,37 +37,26 @@
 </template>
 
 <script setup lang="ts">
-import {
-  computed,
-  inject,
-  nextTick,
-  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 { applyExtendState, 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, FORM_TYPE_MATCH_VALID_KEY } from './schema';
+import { FORM_CONTEXT_KEY, FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY } from './schema';
 
 defineOptions({
   name: 'MForm',
@@ -100,7 +90,7 @@ const props = withDefaults(
     stepActive?: string | number;
     size?: 'small' | 'default' | 'large';
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     keyProp?: string;
     popperClass?: string;
     preventSubmitDefault?: boolean;
@@ -111,7 +101,12 @@ const props = withDefaults(
      * - `false`：跳过查找，直接使用字段 name 作为错误提示前缀（形如 `字段name -> 错误信息`）。
      */
     useFieldTextInError?: boolean;
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * 宿主业务上下文。也可由祖先 `provide(FORM_CONTEXT_KEY)` 下发，本 prop 覆盖祖先的同名字段。
+     *
+     * 配置回调通过 `mForm.xxx` 读取，由 formState 的读穿 Proxy 落到这里。
+     */
+    context?: FormContext;
     /**
      * 自定义"是否展示对比内容"的判断函数（仅在 `isCompare === true` 时生效）。
      *
@@ -178,9 +173,6 @@ 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;
 
 /**
  * 当前表单生效的主题名称：
@@ -213,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;
   },
@@ -253,76 +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 }),
 });
 
-/**
- * formState 的内置 key 快照（keyProp / values / $emit / fields / post 等）。
- *
- * 在 `extendState` 首次合并前捕获，`applyExtendState` 会据此禁止 `extendState`
- * 覆盖这些已有字段（只能新增字段），避免表单核心状态被外部意外改写。
- *
- * 之所以在此处（effect 之外）捕获而不是在 `applyExtendState` 内动态取：
- * `watchEffect` 会在依赖变化时重跑，若动态取，`extendState` 自己新增的字段在第二次
- * 合并时也会被当成「已有 key」而拒绝刷新；这里只锁定内置字段即可规避该问题。
- */
-const reservedStateKeys = new Set<string | symbol>(Reflect.ownKeys(formState));
+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` 重跑（旧版的性能问题修复点）。
- *
- * 实现细节：合并逻辑统一收口在 `applyExtendState`（utils/form）——
- * data 描述符走 reactive proxy 的 set 触发依赖通知（与旧版「逐项赋值」语义等价），
- * accessor 描述符按原样 defineProperty 支持读时求值；
- * props 派生的只读 getter 字段（keyProp 等）以普通字段形式返回时会被跳过并告警。
+ * 宿主业务上下文：`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;
+const contextRef = computed<FormContext>(() => mergeFormContexts(ancestorContext?.value, props.context));
 
-  applyExtendState(formState, state, reservedStateKeys);
-});
+const formState: FormState = createFormStateProxy(coreState, () => contextRef.value);
 
 provide('mForm', formState);
+provide(FORM_CONTEXT_KEY, contextRef);
 
 /**
  * 把生效主题（自身或祖先）再 provide 出去，供 form 子树内含 `Teleport` 的组件
@@ -344,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;
     }
 
@@ -358,6 +302,9 @@ watch(
       config: props.config,
     }).then((value) => {
       values.value = value;
+      // 字段的值初始化写入统一在这里执行，字段组件自身不再改写 model。
+      // 必须放在赋值之后：effect 与动态 type / display 回调读到的 formValue 才是这一轮的值。
+      applyMountValueEffects(formState, props.config, values.value);
       // 非对比模式，初始化完成
       initialized.value = !props.isCompare;
 
@@ -375,6 +322,8 @@ watch(
         config: props.config,
       }).then((value) => {
         lastValuesProcessed.value = value;
+        // 对比模式下待对比的那份值同样要规整，否则会与当前值比出「格式差异」这种假差异
+        applyMountValueEffects(formState, props.config, lastValuesProcessed.value);
         initialized.value = true;
       });
     }
@@ -406,66 +355,17 @@ const submitHandler = (e: SubmitEvent) => {
   }
 };
 
-/**
- * 通过 name 从 config 中查找对应的 text
- * @param name - 字段名，支持点分隔的路径格式，如 'a.b.c'
- * @param config - 表单配置数组
- * @returns 找到的 text 值，如果未找到则返回 undefined
- */
-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 getTextByName = (name: string, config: FormConfig = props.config): string | undefined =>
+  findTextByName(name, config);
 
 /**
  * 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
  *
- * 抽离为独立方法，供 `submitForm`（提交校验）与 `validate`（返回错误文案的校验）复用，
- * 保证两种校验入口产出的错误文案格式完全一致。
+ * 实现收口在 `utils/validateError`，供渲染式校验（本组件的 `submitForm` / `validate`）与
+ * 无渲染校验（`validateValues`）共用，保证两条链路产出的错误文案格式完全一致。
  */
-const formatValidateError = (invalidFields: Record<string, any>): string => {
-  const error: string[] = [];
-
-  Object.entries(invalidFields).forEach(([prop, validateError]) => {
-    (validateError as ValidateError[]).forEach(({ field, message }) => {
-      const name = field || prop;
-      const text = (props.useFieldTextInError ? getTextByName(name, props.config) : undefined) || name;
-
-      error.push(`${text} -> ${message}`);
-    });
-  });
-
-  return error.join('<br>');
-};
+const formatValidateError = (invalidFields: Record<string, any>): string =>
+  formatError(invalidFields, { config: props.config, useFieldTextInError: props.useFieldTextInError });
 
 defineExpose({
   values,

package/src/FormBox.vue

@@ -14,7 +14,7 @@
           :inline="inline"
           :prevent-submit-default="preventSubmitDefault"
           :use-field-text-in-error="useFieldTextInError"
-          :extend-state="extendState"
+          :context="context"
           :type-match-valid="typeMatchValid"
           :validate-on-init="validateOnInit"
           @change="changeHandler"
@@ -44,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',
@@ -66,11 +66,12 @@ const props = withDefaults(
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     preventSubmitDefault?: boolean;
     /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
     useFieldTextInError?: boolean;
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /** 透传给内部 `MForm` 的宿主业务上下文 */
+    context?: FormContext;
   }>(),
   {
     config: () => [],

package/src/FormDialog.vue

@@ -34,7 +34,7 @@
         :use-field-text-in-error="useFieldTextInError"
         :type-match-valid="typeMatchValid"
         :validate-on-init="validateOnInit"
-        :extend-state="extendState"
+        :context="context"
         :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
@@ -73,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',
@@ -94,7 +94,7 @@ const props = withDefaults(
     disabled?: boolean;
     title?: string;
     inline?: boolean;
-    labelPosition?: string;
+    labelPosition?: 'top' | 'left' | 'right';
     zIndex?: number;
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
@@ -106,8 +106,8 @@ const props = withDefaults(
     showCancel?: boolean;
     /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
     useFieldTextInError?: boolean;
-    /** 透传给内部 `MForm`，用于扩展 `formState`（如注入 `$message` / `$store` 等） */
-    extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /** 透传给内部 `MForm` 的宿主业务上下文 */
+    context?: FormContext;
     /**
      * 主题名。优先级：传入 `theme` prop > 祖先 `provide(M_THEME_KEY)` > 空串。
      * 计算结果会再次 `provide` 出去，使得 Dialog 被 Teleport 到 body 后，内部子树

package/src/FormDrawer.vue

@@ -31,7 +31,7 @@
         :use-field-text-in-error="useFieldTextInError"
         :type-match-valid="typeMatchValid"
         :validate-on-init="validateOnInit"
-        :extend-state="extendState"
+        :context="context"
         :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
@@ -64,7 +64,7 @@ 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: 'MFormDrawer',
@@ -88,14 +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 后，内部子树

package/src/containers/Col.vue

@@ -7,6 +7,7 @@
       :config="config"
       :prop="prop"
       :label-width="config.labelWidth || labelWidth"
+      :label-position="config.labelPosition || labelPosition"
       :expand-more="expandMore"
       :size="size"
       :disabled="disabled"
@@ -37,6 +38,7 @@ const props = defineProps<{
   isCompare?: boolean;
   config: FormItemConfig;
   labelWidth?: string | number;
+  labelPosition?: 'top' | 'left' | 'right';
   expandMore?: boolean;
   span?: number;
   size?: string;