@tmagic/form 1.8.0-beta.2 → 1.8.0-beta.21

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.2",
+  "version": "1.8.0-beta.21",
   "name": "@tmagic/form",
   "type": "module",
   "sideEffects": [
@@ -50,11 +50,11 @@
     "@vue/test-utils": "^2.4.6"
   },
   "peerDependencies": {
-    "vue": "^3.5.34",
+    "vue": "^3.5.40",
     "typescript": "^6.0.3",
-    "@tmagic/design": "1.8.0-beta.2",
-    "@tmagic/form-schema": "1.8.0-beta.2",
-    "@tmagic/utils": "1.8.0-beta.2"
+    "@tmagic/design": "1.8.0-beta.21",
+    "@tmagic/utils": "1.8.0-beta.21",
+    "@tmagic/form-schema": "1.8.0-beta.21"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/Form.vue

@@ -1,6 +1,10 @@
 <template>
   <TMagicForm
-    class="m-form"
+    :class="[
+      'm-form',
+      effectiveTheme ? `m-form--${effectiveTheme}` : '',
+      effectiveTheme ? `m-theme--${effectiveTheme}` : '',
+    ]"
     ref="tMagicForm"
     :model="values"
     :label-width="labelWidth"
@@ -32,15 +36,27 @@
 </template>
 
 <script setup lang="ts">
-import { provide, reactive, ref, shallowRef, toRaw, useTemplateRef, watch, watchEffect } from 'vue';
+import {
+  computed,
+  inject,
+  nextTick,
+  provide,
+  reactive,
+  ref,
+  shallowRef,
+  toRaw,
+  useTemplateRef,
+  watch,
+  watchEffect,
+} from 'vue';
 import { cloneDeep, isEqual } from 'lodash-es';
 
-import { TMagicForm, tMagicMessage, tMagicMessageBox } from '@tmagic/design';
+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 { applyExtendState, initValue } from './utils/form';
 import type {
   ChangeRecord,
   ContainerChangeEventData,
@@ -50,7 +66,7 @@ import type {
   FormValue,
   ValidateError,
 } from './schema';
-import { FORM_DIFF_CONFIG_KEY } from './schema';
+import { FORM_DIFF_CONFIG_KEY, FORM_TYPE_MATCH_VALID_KEY } from './schema';
 
 defineOptions({
   name: 'MForm',
@@ -70,6 +86,15 @@ 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;
@@ -79,6 +104,13 @@ const props = withDefaults(
     keyProp?: string;
     popperClass?: string;
     preventSubmitDefault?: boolean;
+    /**
+     * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+     *
+     * - `true`（默认）：错误提示形如 `字段文案 -> 错误信息`，找不到 text 时回退为字段 name；
+     * - `false`：跳过查找，直接使用字段 name 作为错误提示前缀（形如 `字段name -> 错误信息`）。
+     */
+    useFieldTextInError?: boolean;
     extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
     /**
      * 自定义"是否展示对比内容"的判断函数（仅在 `isCompare === true` 时生效）。
@@ -107,6 +139,15 @@ const props = withDefaults(
      * 通过 provide 下发，对整棵表单的所有层级 Container 生效，只需在 MForm 这一层传一次。
      */
     selfDiffFieldTypes?: string[] | ((_defaultTypes: string[]) => string[]);
+    /**
+     * 主题名称：对应 `packages/form/src/theme/themes/<theme>/index.scss` 的目录名。
+     *
+     * 设置后会在表单根元素上追加 `m-form--<theme>` 修饰类，配合按需引入
+     * `@tmagic/form/dist/themes/<theme>.css` 即可启用主题样式。
+     *
+     * 例如：`<MForm theme="magic-admin" />` + `import '@tmagic/form/dist/themes/magic-admin.css'`。
+     */
+    theme?: string;
   }>(),
   {
     config: () => [],
@@ -121,11 +162,18 @@ 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>({});
@@ -134,6 +182,27 @@ const fields = new Map<string, any>();
 
 const requestFuc = getConfig('request') as Function;
 
+/**
+ * 当前表单生效的主题名称：
+ * - 优先用本组件自己的 `props.theme`；
+ * - 没设置时回退到最近祖先 `<MEditor>` / `<MForm>` provide 的主题，便于内嵌于编辑器
+ *   时自动跟随外层主题，无需在每个 `MForm` 上重复传 `theme`。
+ *
+ * 同时把合并后的值再 provide 出去（见下方 `provide(M_THEME_KEY, ...)`），让 form 子树
+ * 里再嵌套的 portal 组件（`TMagicPopover` 等）依然能拿到非空主题。
+ */
+const ancestorTheme = inject(M_THEME_KEY, null);
+const effectiveTheme = computed(() => props.theme || ancestorTheme?.value || '');
+
+/**
+ * 拼到 `formState.popperClass` 上的主题修饰类（仅 `m-theme--<theme>`，
+ * 不带 `m-form` / `m-editor` 前缀，因为 Element Plus 弹层节点本身既不是 form 也不是 editor）。
+ *
+ * 这条类会随所有读 `mForm.popperClass` 的字段（Select / DateTime / Cascader 等）下发到
+ * Element Plus 的 `popper-class`，让 portal 节点也命中 `m-theme--<theme>` 上的 CSS 变量。
+ */
+const themeClass = computed(() => (effectiveTheme.value ? `m-theme--${effectiveTheme.value}` : ''));
+
 /**
  * formState 实现说明：
  *
@@ -150,13 +219,21 @@ const requestFuc = getConfig('request') as Function;
  *      把最新值刷进 formState。
  *    - accessor 描述符（`{ get stage() { return ... } }`）按原样写入，调用方可以控制
  *      读时求值，每次读取都会重新执行 getter。
+ *
+ * 4. `popperClass` 会自动拼接 `themeClass`：调用方传入的 `popperClass` + 当前主题
+ *    修饰类（含祖先 `<MEditor>` provide 的主题）。这样所有透传到 Element Plus 弹层
+ *    `popper-class` 的字段（Select / DateTime / Cascader 等）能自带主题作用域。
  */
 const formState: FormState = reactive<FormState>({
   get keyProp() {
     return props.keyProp;
   },
   get popperClass() {
-    return props.popperClass;
+    const userClass = props.popperClass ?? '';
+    const tc = themeClass.value;
+    if (!userClass) return tc;
+    if (!tc) return userClass;
+    return `${userClass} ${tc}`;
   },
   get config() {
     return props.config;
@@ -192,6 +269,18 @@ const formState: FormState = reactive<FormState>({
   },
 });
 
+/**
+ * formState 的内置 key 快照（keyProp / values / $emit / fields / post 等）。
+ *
+ * 在 `extendState` 首次合并前捕获，`applyExtendState` 会据此禁止 `extendState`
+ * 覆盖这些已有字段（只能新增字段），避免表单核心状态被外部意外改写。
+ *
+ * 之所以在此处（effect 之外）捕获而不是在 `applyExtendState` 内动态取：
+ * `watchEffect` 会在依赖变化时重跑，若动态取，`extendState` 自己新增的字段在第二次
+ * 合并时也会被当成「已有 key」而拒绝刷新；这里只锁定内置字段即可规避该问题。
+ */
+const reservedStateKeys = new Set<string | symbol>(Reflect.ownKeys(formState));
+
 /**
  * `extendState` 的同步段（直到第一个 `await` 之前）所访问的任何响应式数据，
  * 都会被 `watchEffect` 自动跟踪。这样可以兼容历史用法 ——
@@ -207,11 +296,10 @@ const formState: FormState = reactive<FormState>({
  * 这里不再重复同步；因此 `props.initValues` 这类高频变化也不会再触发
  * `extendState` 重跑（旧版的性能问题修复点）。
  *
- * 实现细节：
- * - data 描述符：通过 `formState[key] = value` 走 reactive proxy 的 set，
- *   触发依赖通知；与旧版「逐项赋值」语义完全等价。
- * - accessor 描述符（`{ get stage() {...} }`）按原样写入 formState，调用方
- *   可以自行控制读时求值；强制 `configurable: true` 以便下一次重跑可再 define。
+ * 实现细节：合并逻辑统一收口在 `applyExtendState`（utils/form）——
+ * data 描述符走 reactive proxy 的 set 触发依赖通知（与旧版「逐项赋值」语义等价），
+ * accessor 描述符按原样 defineProperty 支持读时求值；
+ * props 派生的只读 getter 字段（keyProp 等）以普通字段形式返回时会被跳过并告警。
  */
 watchEffect(async (onCleanup) => {
   const { extendState } = props;
@@ -231,18 +319,18 @@ watchEffect(async (onCleanup) => {
   }
   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);
-    }
-  }
+  applyExtendState(formState, state, reservedStateKeys);
 });
 
 provide('mForm', formState);
 
+/**
+ * 把生效主题（自身或祖先）再 provide 出去，供 form 子树内含 `Teleport` 的组件
+ * （如 `TMagicPopover`）在传送目标上挂 `m-theme--<theme>` 类。
+ * 详见 `@tmagic/design/theme.ts`。
+ */
+provide(M_THEME_KEY, effectiveTheme);
+provide('formInline', props.inline);
 // 对比相关配置单独通过 provide 下发，所有层级的 Container 通过 inject 获取，无需逐层透传 prop。
 // 用 getter 对象保证读取时回到最新的 props 值，维持响应式。
 provide(FORM_DIFF_CONFIG_KEY, {
@@ -272,6 +360,12 @@ watch(
       values.value = value;
       // 非对比模式，初始化完成
       initialized.value = !props.isCompare;
+
+      if (props.validateOnInit) {
+        nextTick(() => {
+          tMagicFormRef.value?.validate();
+        });
+      }
     });
 
     if (props.isCompare) {
@@ -352,6 +446,27 @@ const getTextByName = (name: string, config: FormConfig = props.config): string
   return findInConfig(config, nameParts);
 };
 
+/**
+ * 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
+ *
+ * 抽离为独立方法，供 `submitForm`（提交校验）与 `validate`（返回错误文案的校验）复用，
+ * 保证两种校验入口产出的错误文案格式完全一致。
+ */
+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>');
+};
+
 defineExpose({
   values,
   lastValuesProcessed,
@@ -379,18 +494,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"
+          :use-field-text-in-error="useFieldTextInError"
           :extend-state="extendState"
+          :type-match-valid="typeMatchValid"
+          :validate-on-init="validateOnInit"
           @change="changeHandler"
         ></Form>
         <slot></slot>
@@ -55,18 +58,26 @@ 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;
     preventSubmitDefault?: boolean;
+    /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
+    useFieldTextInError?: boolean;
     extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
   }>(),
   {
     config: () => [],
     values: () => ({}),
     confirmText: '确定',
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/FormDialog.vue

@@ -1,7 +1,7 @@
 <template>
   <TMagicDialog
     v-model="dialogVisible"
-    class="m-form-dialog"
+    :class="['m-form-dialog', effectiveTheme ? `m-theme--${effectiveTheme}` : '']"
     top="20px"
     append-to-body
     :title="title"
@@ -31,7 +31,11 @@
         :label-position="labelPosition"
         :inline="inline"
         :prevent-submit-default="preventSubmitDefault"
+        :use-field-text-in-error="useFieldTextInError"
+        :type-match-valid="typeMatchValid"
+        :validate-on-init="validateOnInit"
         :extend-state="extendState"
+        :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
       <slot></slot>
@@ -64,9 +68,9 @@
 </template>
 
 <script setup lang="ts">
-import { computed, ref } from 'vue';
+import { computed, inject, provide, ref } from 'vue';
 
-import { TMagicButton, TMagicCol, TMagicDialog, TMagicRow } from '@tmagic/design';
+import { M_THEME_KEY, TMagicButton, TMagicCol, TMagicDialog, TMagicRow } from '@tmagic/design';
 
 import Form from './Form.vue';
 import { ContainerChangeEventData, FormConfig, FormState, FormValue, StepConfig } from './schema';
@@ -82,6 +86,10 @@ const props = withDefaults(
     parentValues?: Object;
     width?: string | number;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     fullscreen?: boolean;
     disabled?: boolean;
     title?: string;
@@ -96,8 +104,16 @@ const props = withDefaults(
     destroyOnClose?: boolean;
     showClose?: boolean;
     showCancel?: boolean;
+    /** 透传给内部 `MForm`，控制表单校验失败时错误提示前缀是否使用字段的 text 文案 */
+    useFieldTextInError?: boolean;
     /** 透传给内部 `MForm`，用于扩展 `formState`（如注入 `$message` / `$store` 等） */
     extendState?: (_state: FormState) => Record<string, any> | Promise<Record<string, any>>;
+    /**
+     * 主题名。优先级：传入 `theme` prop > 祖先 `provide(M_THEME_KEY)` > 空串。
+     * 计算结果会再次 `provide` 出去，使得 Dialog 被 Teleport 到 body 后，内部子树
+     * （包括 `MForm` 以及更深的 popover / dropdown）仍能拿到主题。
+     */
+    theme?: string;
   }>(),
   {
     config: () => [],
@@ -108,9 +124,15 @@ const props = withDefaults(
     destroyOnClose: false,
     showClose: true,
     showCancel: true,
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 
+const ancestorTheme = inject(M_THEME_KEY, null);
+const effectiveTheme = computed(() => props.theme || ancestorTheme?.value || '');
+provide(M_THEME_KEY, effectiveTheme);
+
 const emit = defineEmits(['close', 'submit', 'error', 'change']);
 
 const form = ref<InstanceType<typeof Form>>();

package/src/FormDrawer.vue

@@ -1,8 +1,8 @@
 <template>
   <TMagicDrawer
-    class="m-form-drawer"
+    :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,11 @@
         :label-position="labelPosition"
         :inline="inline"
         :prevent-submit-default="preventSubmitDefault"
+        :use-field-text-in-error="useFieldTextInError"
+        :type-match-valid="typeMatchValid"
+        :validate-on-init="validateOnInit"
         :extend-state="extendState"
+        :theme="effectiveTheme"
         @change="changeHandler"
       ></Form>
       <slot></slot>
@@ -55,24 +59,28 @@
 </template>
 
 <script setup lang="ts">
-import { ref, watchEffect } from 'vue';
+import { computed, inject, provide, ref, watchEffect } from 'vue';
 
-import { TMagicButton, TMagicCol, TMagicDrawer, TMagicRow } from '@tmagic/design';
+import { M_THEME_KEY, TMagicButton, TMagicCol, TMagicDrawer, TMagicRow } from '@tmagic/design';
 
 import Form from './Form.vue';
 import type { ContainerChangeEventData, FormConfig, FormState, FormValue } from './schema';
 
 defineOptions({
-  name: 'MFormDialog',
+  name: 'MFormDrawer',
 });
 
-withDefaults(
+const props = withDefaults(
   defineProps<{
     config?: FormConfig;
     values?: Object;
     parentValues?: Object;
     width?: string | number;
     labelWidth?: string;
+    /** 是否开启类型匹配校验 */
+    typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     disabled?: boolean;
     closeOnPressEscape?: boolean;
     title?: string;
@@ -82,25 +90,39 @@ withDefaults(
     inline?: boolean;
     labelPosition?: string;
     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>>;
+    /**
+     * 主题名。优先级：传入 `theme` prop > 祖先 `provide(M_THEME_KEY)` > 空串。
+     * 计算结果会再次 `provide` 出去，使得 Drawer 被 Teleport 到 body 后，内部子树
+     * （包括 `MForm` 以及更深的 popover / dropdown）仍能拿到主题。
+     */
+    theme?: string;
   }>(),
   {
     closeOnPressEscape: true,
     config: () => [],
     values: () => ({}),
     confirmText: '确定',
+    useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 
+const ancestorTheme = inject(M_THEME_KEY, null);
+const effectiveTheme = computed(() => props.theme || ancestorTheme?.value || '');
+provide(M_THEME_KEY, effectiveTheme);
+
 const emit = defineEmits(['close', 'closed', 'submit', 'error', 'change', 'open', 'opened']);
 
 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);
 
@@ -141,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>

package/src/containers/Col.vue

@@ -12,6 +12,7 @@
       :disabled="disabled"
       @change="changeHandler"
       @add-diff-count="onAddDiffCount"
+      :is-in-row="true"
     ></Container>
   </TMagicCol>
 </template>