@tmagic/form 1.8.0-manmanyu.9 → 1.8.1

package/src/utils/fieldInnerConfig.ts

@@ -0,0 +1,127 @@
+/*
+ * 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 { toLine } from '@tmagic/utils';
+
+import type { FormItemConfig, FormState, FormValue } from '../schema';
+
+// #region FieldInnerConfig
+/** innerConfig 回调的入参：字段自身的配置、所在层级的 model、完整字段路径与表单状态 */
+export interface FieldInnerConfigContext {
+  /** 字段自身的配置（已经过 filterFunction 之外的原样配置） */
+  config: FormItemConfig;
+  /** 字段所在层级的 model 切片 */
+  model: FormValue;
+  /** 字段的完整 prop 路径（含父级前缀），即字段组件拿到的 `props.prop` */
+  prop: string;
+  /** 字段所在层级的 prop 基准（父级 Container 的 `props.prop`），即 `prop` 去掉自身 name 的部分 */
+  parentProp: string;
+  /** 表单状态 */
+  mForm: FormState | undefined;
+}
+
+/** innerConfig 回调的返回值：需要继续遍历的内部配置及其 model / prop 基准 */
+export interface FieldInnerConfigResult {
+  /** 内部配置（对应字段组件内部渲染的 `MContainer` 的 `config`） */
+  config: FormItemConfig | FormItemConfig[];
+  /**
+   * 内部配置对应的 model 切片，默认沿用字段所在层级的 `model`。
+   *
+   * 例如 `code-select` 内部是 `:model="model[name]"`，就应返回 `model[config.name]`。
+   */
+  model?: FormValue;
+  /**
+   * 内部配置对应的 prop 基准，默认沿用字段自身的 `prop`。
+   *
+   * 返回的 config 的 `name` 会被追加到这个基准上。所以当内部配置复用了字段自身的 `name`
+   * （如 `display-conds` 内部的 group-list 就叫 `props.name`）时，要返回 `parentProp`，
+   * 否则 name 会被拼两次。
+   */
+  prop?: string;
+}
+
+/**
+ * 复合字段的内部配置回调。
+ *
+ * 有一类字段组件会在自身内部再渲染 `MContainer` 并传入组件内部临时算出来的 config
+ * （如编辑器的 `code-select` / `event-select` / `style-setter`），这些内部字段同样会向
+ * 父级表单注册 FormItem、参与父表单校验。无渲染校验（`validateValues`）只遍历调用方
+ * 传入的 config 树，看不到这些运行期才产生的配置，因此需要字段作者通过
+ * `registerField(type, { innerConfig })` 把内部配置交出来。
+ *
+ * 返回 `null` / `undefined` 表示该字段本次没有内部配置（例如某些分支下不渲染子表单）。
+ *
+ * 既未登记 innerConfig、也不在叶子字段表里的 type：配置里有 `items` 会下钻子项，
+ * 自身有 `rules` 会校验自身。
+ */
+export type FieldInnerConfig = (_ctx: FieldInnerConfigContext) => FieldInnerConfigResult | null | undefined | void;
+// #endregion FieldInnerConfig
+
+/** 内置内部配置（由 `registerBuiltInFields` 写入；`clearFields` 不会清掉） */
+const builtInInnerConfigs = new Map<string, FieldInnerConfig>();
+/** 业务侧登记的内部配置 */
+const extraInnerConfigs = new Map<string, FieldInnerConfig>();
+
+/**
+ * 登记复合字段的内部配置：无渲染校验遇到该 type 时，用返回值继续遍历内部字段。
+ *
+ * `type` 会按 Container 的规则归一化为中划线形式（`codeSelect` 与 `code-select` 等价）。
+ * 重复登记以最后一次为准，便于业务侧覆盖内置实现。
+ * `builtIn` 登记不受 `deleteFieldInnerConfig` / `clearFieldInnerConfigs` 影响。
+ *
+ * @param type - 字段 type
+ * @param resolve - innerConfig 回调
+ * @param [builtIn=false] - 是否写入内置表
+ */
+export const registerFieldInnerConfig = (type: string, resolve: FieldInnerConfig, builtIn = false): void => {
+  if (typeof type !== 'string' || !type || typeof resolve !== 'function') return;
+  (builtIn ? builtInInnerConfigs : extraInnerConfigs).set(toLine(type), resolve);
+};
+
+/**
+ * 获取指定 type 的 innerConfig 回调（业务侧优先于内置）。
+ *
+ * @param type - 字段 type
+ * @returns innerConfig 回调；未登记则为 `undefined`
+ */
+export const getFieldInnerConfig = (type: string): FieldInnerConfig | undefined => {
+  const key = toLine(type);
+  return extraInnerConfigs.get(key) ?? builtInInnerConfigs.get(key);
+};
+
+/**
+ * 是否已登记指定 type 的 innerConfig（内置 ∪ 已登记）。
+ *
+ * @param type - 字段 type
+ * @returns 是否已登记
+ */
+export const hasFieldInnerConfig = (type: string): boolean => {
+  const key = toLine(type);
+  return extraInnerConfigs.has(key) || builtInInnerConfigs.has(key);
+};
+
+/**
+ * 删除业务侧登记的 innerConfig（不影响内置）。
+ *
+ * @param type - 字段 type
+ * @returns 是否删除成功
+ */
+export const deleteFieldInnerConfig = (type: string): boolean => extraInnerConfigs.delete(toLine(type));
+
+/** 清空业务侧登记的 innerConfig（不影响内置；主要用于单测）。 */
+export const clearFieldInnerConfigs = (): void => extraInnerConfigs.clear();

package/src/utils/fieldValueEffects.ts

@@ -0,0 +1,140 @@
+/*
+ * 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.
+ */
+
+/**
+ * @fileoverview 叶子字段登记表：哪些 type 是叶子，以及该字段对表单值的初始化写入。
+ *
+ * 无渲染校验据此判定该 type 没有属于父表单的嵌套字段。
+ * 业务自定义字段通过 `registerField` / `registerFields` 登记。
+ * 内置叶子字段由 `MagicForm.install` 的 `registerBuiltInFields` 写入。
+ * 未登记且没有 innerConfig 的 type：有 `items` 会下钻子项，自身有 `rules` 会校验自身。
+ *
+ * 这里只是登记表。各字段的 effect 写在对应组件同目录的 `fields/<Field>/effect.ts`，
+ * 执行收口在 `collectFields` 的 `applyMountValueEffects`：渲染（`Form.vue`）
+ * 与无渲染（`validateValues`）都在表单值初始化完成后调用它一次，
+ * 字段组件自身不再在 setup 里改写 model。
+ *
+ * @module fieldValueEffects
+ */
+
+import { toLine } from '@tmagic/utils';
+
+import type { FormItemConfig, FormState, FormValue } from '../schema';
+
+// #region FieldMountValueEffect
+/** effect 的入参：字段自身的配置、所在层级的 model、完整字段路径、表单值根对象与表单状态 */
+export interface FieldMountValueEffectContext {
+  /** 字段自身的配置 */
+  config: FormItemConfig;
+  /** 字段所在层级的 model 切片 */
+  model: FormValue;
+  /** 字段的完整 prop 路径（含父级前缀），对应 Container 的 `itemProp` */
+  prop: string;
+  /**
+   * 本次处理的表单值根对象，`prop` 即以它为根。
+   *
+   * 需要按路径跨层级写值时用它，不要用 `mForm.values`：对比模式下处理的是 lastValues 那一份，
+   * tab / table 新增行处理的则是还没挂到表单上的一行值，两者都与 `mForm.values` 不是同一个对象。
+   */
+  values: FormValue;
+  /** 表单状态 */
+  mForm: FormState | undefined;
+}
+
+/**
+ * 字段对表单值的初始化写入（如 `display` 的 `initValue`、`date` 的格式归一化）。
+ *
+ * 由 `applyMountValueEffects` 在表单值初始化完成后统一执行一次，渲染与无渲染共用。
+ * 因为可能对同一份值重复执行（如 `initValues` 变化后重新初始化），实现必须幂等。
+ */
+export type FieldMountValueEffect = (_ctx: FieldMountValueEffectContext) => void;
+// #endregion FieldMountValueEffect
+
+/** 内置叶子字段（由 `MagicForm.install` 写入；clearFields 不会清掉） */
+const builtInLeafFieldTypes = new Set<string>();
+const builtInMountValueEffects = new Map<string, FieldMountValueEffect>();
+
+/** 业务侧登记的叶子字段与其挂载副作用 */
+const extraLeafFieldTypes = new Set<string>();
+const extraMountValueEffects = new Map<string, FieldMountValueEffect>();
+
+/**
+ * 登记一个叶子字段 type。由 `registerField` 调用，业务侧请走 `registerField`。
+ *
+ * 传了 `effect` 会覆盖该 type 已有的 extra effect（含覆盖内置）；不传则清掉 extra effect，
+ * 内置 effect 仍生效。
+ *
+ * @param type - 字段 type
+ * @param [effect] - 挂载时改写 model 的副作用
+ * @param [builtIn=false] - 是否写入内置表
+ */
+export const registerLeafFieldType = (type: string, effect?: FieldMountValueEffect, builtIn = false): void => {
+  if (typeof type !== 'string' || !type) return;
+
+  const key = toLine(type);
+  const types = builtIn ? builtInLeafFieldTypes : extraLeafFieldTypes;
+  const effects = builtIn ? builtInMountValueEffects : extraMountValueEffects;
+
+  types.add(key);
+
+  if (typeof effect === 'function') {
+    effects.set(key, effect);
+  } else if (!builtIn) {
+    effects.delete(key);
+  }
+};
+
+/**
+ * 是否为叶子字段 type（内置 ∪ 已登记）。
+ *
+ * @param type - 字段 type
+ * @returns 是否为叶子
+ */
+export const isLeafFieldType = (type: string): boolean => {
+  const key = toLine(type);
+  return extraLeafFieldTypes.has(key) || builtInLeafFieldTypes.has(key);
+};
+
+/**
+ * 获取指定 type 挂载时改写 model 的副作用（已登记的优先于内置）。
+ *
+ * @param type - 字段 type
+ * @returns 副作用函数；未登记则为 `undefined`
+ */
+export const getFieldMountValueEffect = (type: string): FieldMountValueEffect | undefined => {
+  const key = toLine(type);
+  return extraMountValueEffects.get(key) ?? builtInMountValueEffects.get(key);
+};
+
+/**
+ * 删除业务侧登记的叶子字段（不影响内置；主要用于单测）。
+ *
+ * @param type - 字段 type
+ * @returns 是否删除成功
+ */
+export const deleteLeafFieldType = (type: string): boolean => {
+  const key = toLine(type);
+  extraMountValueEffects.delete(key);
+  return extraLeafFieldTypes.delete(key);
+};
+
+/** 清空业务侧登记的叶子字段（不影响内置；主要用于单测）。 */
+export const clearLeafFieldTypes = (): void => {
+  extraLeafFieldTypes.clear();
+  extraMountValueEffects.clear();
+};

package/src/utils/form.ts

@@ -16,11 +16,13 @@
  * limitations under the License.
  */
 
-import { readonly } from 'vue';
+import { type MaybeRef, readonly, unref } from 'vue';
 import dayjs from 'dayjs';
-import utc from 'dayjs/plugin/utc';
+// dayjs 没有 exports 映射，原生 Node ESM 不会补扩展名，深路径必须写全 .js
+import utc from 'dayjs/plugin/utc.js';
 import { cloneDeep } from 'lodash-es';
 
+import { getDesignConfig } from '@tmagic/design/headless';
 import { getValueByKeyPath } from '@tmagic/utils';
 
 import type {
@@ -39,6 +41,64 @@ import type {
   TypeFunction,
 } from '../schema';
 
+import { getConfig } from './config';
+import { createTypeMatchValidator } from './typeMatch';
+
+export { createFormStateProxy, mergeFormContexts } from './formStateProxy';
+
+type AsyncValidatorFn = (rule: any, value: any, callback: Function, source?: any, options?: any) => any;
+
+const isTDesignAdapter = () => getDesignConfig('adapterType') === 'tdesign-vue-next';
+
+/**
+ * 将 async-validator（Element Plus）风格的 validator 适配到当前 UI 库。
+ * TDesign 调用签名为 `(val) => boolean | CustomValidateObj | Promise`，无 callback。
+ */
+export const adaptFormValidator = (validator: AsyncValidatorFn): AsyncValidatorFn => {
+  return (arg1: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any) => {
+    if (!isTDesignAdapter()) {
+      return validator(arg1, arg2, arg3, arg4, arg5);
+    }
+
+    // TDesign: validator(val)
+    const value = arg1;
+    return new Promise((resolve) => {
+      let settled = false;
+      const callback = (error?: Error | string | (Error | string)[]) => {
+        if (settled) return;
+        settled = true;
+        // async-validator 约定 callback 也可接收错误数组，TDesign 只能展示一条，取首条
+        const first = Array.isArray(error) ? error[0] : error;
+        if (first) {
+          resolve({
+            result: false,
+            message: typeof first === 'string' ? first : first.message,
+          });
+        } else {
+          resolve(true);
+        }
+      };
+
+      try {
+        // 异步 validator 会先返回 undefined，稍后再调 callback，这里不能当成 thenable 取值
+        const result = validator(undefined, value, callback);
+        if (result && typeof (result as PromiseLike<unknown>).then === 'function') {
+          Promise.resolve(result).then(
+            () => {
+              if (!settled) callback();
+            },
+            (err) => {
+              callback(err instanceof Error ? err : new Error(String(err)));
+            },
+          );
+        }
+      } catch (e) {
+        callback(e instanceof Error ? e : new Error(String(e)));
+      }
+    });
+  };
+};
+
 interface DefaultItem {
   defaultValue: any;
   type: string;
@@ -216,17 +276,106 @@ const getDefaultValue = function (
   return '';
 };
 
+/**
+ * formState 中与表单 props 无关的公共部分：字段注册表、消息组件、post 请求。
+ *
+ * 由渲染式表单（`Form.vue`）与无渲染校验（`createHeadlessFormState`）共用，
+ * 保证两者提供给字段配置（`onChange` / `validator` / 异步 options 等）的能力一致。
+ */
+const fallbackMessage = {
+  error: (msg: string) => console.error(msg),
+  success: (msg: string) => console.log(msg),
+  warning: (msg: string) => console.warn(msg),
+  info: (msg: string) => console.info(msg),
+  closeAll: () => undefined,
+};
+
+const fallbackMessageBox = {
+  alert: (msg: string) => console.log(msg),
+  confirm: (msg: string) => console.log(msg),
+  close: (msg: string) => console.log(msg),
+};
+
+export const createFormStateBase = (ui?: { $message?: any; $messageBox?: any }) => {
+  const fields = new Map<string, any>();
+  const requestFuc = getConfig('request') as Function;
+
+  return {
+    fields,
+    setField: (prop: string, field: any) => fields.set(prop, field),
+    getField: (prop: string) => fields.get(prop),
+    deleteField: (prop: string) => fields.delete(prop),
+    $messageBox: ui?.$messageBox ?? fallbackMessageBox,
+    $message: ui?.$message ?? fallbackMessage,
+    post: (options: any) => {
+      if (requestFuc) {
+        return requestFuc({
+          method: 'POST',
+          ...options,
+        });
+      }
+    },
+  };
+};
+
+/**
+ * 配置项的 `name` 是否可用于从 model 中下钻取值。
+ *
+ * 供 `Container.vue` 与无渲染校验（`collectValidatableFields`）共用，两者对「该不该下钻」
+ * 的判断必须一致。
+ */
+export const isValidName = (name: unknown): boolean => {
+  const valueType = typeof name;
+  if (valueType !== 'string' && valueType !== 'symbol' && valueType !== 'number') return false;
+  if (name === '') return false;
+  if (valueType === 'number') return (name as number) >= 0;
+  return true;
+};
+
+/**
+ * 在 `prop` 后追加一段路径。
+ *
+ * 用于容器把 `prop` 透传给子级时再拼上索引 / key（如 group-list 的行、table 的行）。
+ */
+export const appendProp = (prop: string | undefined = '', key: string | number): string =>
+  `${prop}${prop ? '.' : ''}${key}`;
+
+/**
+ * 由父级 `prop` 与配置项 `name` 拼出该配置项的完整 `prop`（即 FormItem 的 prop）。
+ *
+ * 调用方传入的 name 已按 `config.name || ''` 归一化，空 name 表示该配置项不占据值路径上的一层，
+ * 此时沿用父级 `prop`。
+ */
+export const getItemProp = (prop: string | undefined = '', name: string | number | undefined = ''): string =>
+  name === '' ? (prop ?? '') : appendProp(prop, name);
+
+/**
+ * 归一化配置项的 `type`：求值动态 type、剥离容器语义的 type、驼峰转中划线、补默认值。
+ *
+ * 供 `Container.vue` 与无渲染校验共用，保证两者分派到的 type 完全一致。
+ */
+export const resolveItemType = (mForm: FormState | undefined, config: any, props: any): string => {
+  let type = 'type' in (config || {}) ? config.type : '';
+  type = type && filterFunction<string>(mForm, type, props);
+  // form / container 都表示「仅嵌套，不渲染字段」
+  if (type === 'form' || type === 'container') return '';
+  return type?.replace(/([A-Z])/g, '-$1').toLowerCase() || (config?.items ? '' : 'text');
+};
+
 export const filterFunction = <T = any>(
   mForm: FormState | undefined,
   config: T | FilterFunction<T> | undefined,
   props: any,
 ) => {
   if (typeof config === 'function') {
+    const formValue = readonly(mForm?.values || props.model);
     return (config as FilterFunction<T>)(mForm, {
       values: readonly(mForm?.initValues || {}),
       model: readonly(props.model),
       parent: readonly(mForm?.parentValues || {}),
-      formValue: readonly(mForm?.values || props.model),
+      formValue,
+      // Select.vue / SelectOptionFunction 使用 formValues 别名
+      formValues: formValue,
       prop: props.prop,
       config: props.config,
       index: props.index,
@@ -253,39 +402,90 @@ export const display = function (mForm: FormState | undefined, config: any, prop
   return true;
 };
 
-export const getRules = function (mForm: FormState | undefined, rules: Rule[] | Rule = [], props: any) {
-  rules = cloneDeep(rules);
+const buildRules = function (
+  mForm: FormState | undefined,
+  r: Rule[] | Rule = [],
+  props: any,
+  typeMatchValid?: MaybeRef<boolean>,
+  adapt: (_validator: AsyncValidatorFn) => AsyncValidatorFn = (validator) => validator,
+) {
+  let rules = cloneDeep(r);
 
   if (typeof rules === 'object' && !Array.isArray(rules)) {
     rules = [rules];
   }
 
-  return rules.map((item) => {
-    if (typeof item.validator === 'function') {
-      const fnc = item.validator;
-
-      (item as any).validator = (rule: any, value: any, callback: Function, source: any, options: any) =>
-        fnc(
-          {
-            rule,
-            value: props.config.names ? props.model : value,
-            callback,
-            source,
-            options,
-          },
-          {
-            values: mForm?.initValues || {},
-            model: props.model,
-            parent: mForm?.parentValues || {},
-            formValue: mForm?.values || props.model,
-            prop: props.prop,
-            config: props.config,
-          },
-          mForm,
+  if (unref(typeMatchValid) && !rules.some((r) => typeof r.typeMatch !== 'undefined')) {
+    rules.push({
+      typeMatch: true,
+    });
+  }
+
+  return rules
+    .map((item) => {
+      if (item.typeMatch) {
+        (item as any).validator = adapt(createTypeMatchValidator(mForm, props, item));
+        return item;
+      }
+
+      if (typeof item.validator === 'function') {
+        const fnc = item.validator;
+
+        (item as any).validator = adapt((rule: any, value: any, callback: Function, source: any, options: any) =>
+          fnc(
+            {
+              rule,
+              value: props.config.names ? props.model : value,
+              callback,
+              source,
+              options,
+            },
+            {
+              values: mForm?.initValues || {},
+              model: props.model,
+              parent: mForm?.parentValues || {},
+              formValue: mForm?.values || props.model,
+              prop: props.prop,
+              config: props.config,
+            },
+            mForm,
+          ),
         );
-    }
-    return item;
-  });
+      }
+      return item;
+    })
+    .filter((item) => {
+      // typeMatch: false 仅用于关闭自动注入，本身没有校验能力。
+      // 若原样交给 async-validator，会因默认 type=string 误杀 number 等合法值。
+      if (item.typeMatch === false && typeof item.validator !== 'function') {
+        return false;
+      }
+      return true;
+    });
+};
+
+export const getRules = function (
+  mForm: FormState | undefined,
+  r: Rule[] | Rule = [],
+  props: any,
+  typeMatchValid?: MaybeRef<boolean>,
+) {
+  return buildRules(mForm, r, props, typeMatchValid, adaptFormValidator);
+};
+
+/**
+ * 与 `getRules` 相同，但 validator 保持 async-validator（Element Plus）原生签名，不做 UI 库适配。
+ *
+ * 供无渲染校验（`validateValues`）使用：它直接把规则交给 async-validator 执行，
+ * 不经过 TDesign 的 `validator(val)` 调用约定，因此不能套 `adaptFormValidator`。
+ */
+export const getNativeRules = function (
+  mForm: FormState | undefined,
+  r: Rule[] | Rule = [],
+  props: any,
+  typeMatchValid?: MaybeRef<boolean>,
+) {
+  return buildRules(mForm, r, props, typeMatchValid);
 };
 
 export const initValue = async (