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

package/src/utils/tableGroupList.ts

@@ -0,0 +1,120 @@
+/*
+ * 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 { cloneDeep } from 'lodash-es';
+
+import type { GroupListConfig, TableColumnConfig, TableConfig } from '../schema';
+
+/**
+ * table / group-list 是同一份配置的两种展示形态，可以互相切换（`TableGroupList.vue`）。
+ *
+ * 本模块收口两种形态之间的配置派生，以及各形态下「子项配置怎么算出来」的规则，
+ * 供渲染（`TableGroupList.vue` / `GroupListItem.vue` / `useTableColumns.ts`）与无渲染校验
+ * （`collectValidatableFields`）共用，避免两条链路各写一份而产生偏差。
+ */
+
+/** group-list 形态的 type（兼容驼峰与中划线两种写法） */
+export const isGroupListType = (type: unknown): boolean => type === 'groupList' || type === 'group-list';
+
+/** 按 label 文案长度估算 label 宽度（中文按 20px、其他按 8px，最小 80px） */
+export const calcLabelWidth = (label: string): string => {
+  if (!label) return '0px';
+  const zhLength = label.match(/[^\x00-\xff]/g)?.length || 0;
+  const chLength = label.length - zhLength;
+  return `${Math.max(chLength * 8 + zhLength * 20, 80)}px`;
+};
+
+/** 由 group-list 形态的配置派生出 table 形态所需的配置；本身已是 table 形态则原样返回 */
+export const toTableConfig = (config: TableConfig | GroupListConfig): TableConfig => {
+  if (!isGroupListType(config.type)) return config as TableConfig;
+
+  const source = config as GroupListConfig;
+  return {
+    ...config,
+    type: 'table',
+    groupItems: source.items,
+    items:
+      source.tableItems ||
+      (source.items as any[]).map((item: any) => ({
+        ...item,
+        label: item.label || item.text,
+        text: null,
+      })),
+  } as any as TableConfig;
+};
+
+/** 由 table 形态的配置派生出 group-list 形态所需的配置；本身已是 group-list 形态则原样返回 */
+export const toGroupListConfig = (config: TableConfig | GroupListConfig): GroupListConfig => {
+  if (isGroupListType(config.type)) return config as GroupListConfig;
+
+  const source = config as TableConfig;
+  return {
+    ...config,
+    type: 'groupList',
+    tableItems: source.items,
+    items:
+      source.groupItems ||
+      (source.items as any[]).map((item: any) => {
+        const text = item.text || item.label;
+        return {
+          ...item,
+          text,
+          labelWidth: calcLabelWidth(text),
+          span: item.span || 12,
+        };
+      }),
+  } as any as GroupListConfig;
+};
+
+/**
+ * group-list 每一行渲染的 row 容器配置（`GroupListItem.vue` 渲染的 `Container` 的 config）。
+ *
+ * `keyProp` 由调用方从 `mForm.keyProp` 取，默认 `__key`。
+ */
+export const getGroupListRowConfig = (config: GroupListConfig, index: number, keyProp?: string) => {
+  const key = keyProp || '__key';
+
+  return {
+    type: 'row',
+    span: config.span || 24,
+    items: config.items,
+    labelWidth: config.labelWidth,
+    labelPosition: config.labelPosition,
+    [key]: `${(config as Record<string, any>)[key]}${String(index)}`,
+  };
+};
+
+/**
+ * 列是否会被渲染成一列（`hidden` 列不渲染，`display` 为假的列也不渲染）。
+ *
+ * `display` 的求值上下文是表格自身的 props，由调用方通过 `evalDisplay` 注入。
+ */
+export const isTableColumnRendered = (column: TableColumnConfig, evalDisplay: (_display: any) => any): boolean =>
+  column.type !== 'hidden' && Boolean(evalDisplay(column.display));
+
+/**
+ * 单元格内 `Container` 实际收到的列配置：按行求值 `itemsFunction`，并去掉已在列层面消费过的 `display`。
+ */
+export const makeTableColumnConfig = (column: TableColumnConfig, row: any): TableColumnConfig => {
+  const newConfig = cloneDeep(column);
+  if (typeof column.itemsFunction === 'function') {
+    newConfig.items = column.itemsFunction(row);
+  }
+  delete newConfig.display;
+  return newConfig;
+};

package/src/utils/typeMatch.ts

@@ -18,9 +18,10 @@
 
 import { readonly } from 'vue';
 import dayjs from 'dayjs';
-import customParseFormat from 'dayjs/plugin/customParseFormat';
+// dayjs 没有 exports 映射，原生 Node ESM 不会补扩展名，深路径必须写全 .js
+import customParseFormat from 'dayjs/plugin/customParseFormat.js';
 
-import { appendValidateSuggestion } from '@tmagic/design';
+import { appendValidateSuggestion } from '@tmagic/design/headless';
 import { getValueByKeyPath, toLine } from '@tmagic/utils';
 
 import type { CascaderOption, FormState, Rule } from '../schema';
@@ -49,33 +50,36 @@ export type TypeMatchValidator = (
 ) => string | undefined | Promise<string | undefined>;
 // #endregion TypeMatchValidator
 
-const typeMatchRuleRegistry = new Map<string, TypeMatchValidator>();
+const extraTypeMatchRules = new Map<string, TypeMatchValidator>();
+const builtInTypeMatchRules = new Map<string, TypeMatchValidator>();
 
 const isPromise = (value: any): value is Promise<unknown> =>
   typeof value === 'object' && value !== null && typeof value.then === 'function';
 
-/** 注册或覆盖某个字段 type 的 typeMatch 校验规则 */
-export const registerTypeMatchRule = (type: string, validator: TypeMatchValidator): void => {
-  typeMatchRuleRegistry.set(toLine(type), validator);
+/** 注册或覆盖某个字段 type 的 typeMatch 校验规则。`builtIn` 登记不受 `clearTypeMatchRules` / `deleteTypeMatchRule` 影响。 */
+export const registerTypeMatchRule = (type: string, validator: TypeMatchValidator, builtIn = false): void => {
+  (builtIn ? builtInTypeMatchRules : extraTypeMatchRules).set(toLine(type), validator);
 };
 
 /** 批量注册 typeMatch 校验规则 */
-export const registerTypeMatchRules = (rules: Record<string, TypeMatchValidator>): void => {
+export const registerTypeMatchRules = (rules: Record<string, TypeMatchValidator>, builtIn = false): void => {
   Object.entries(rules).forEach(([type, validator]) => {
-    registerTypeMatchRule(type, validator);
+    registerTypeMatchRule(type, validator, builtIn);
   });
 };
 
-/** 获取某个字段 type 的自定义 typeMatch 校验规则 */
-export const getTypeMatchRule = (type: string): TypeMatchValidator | undefined =>
-  typeMatchRuleRegistry.get(toLine(type));
+/** 获取某个字段 type 的 typeMatch 校验规则（业务侧优先于内置） */
+export const getTypeMatchRule = (type: string): TypeMatchValidator | undefined => {
+  const key = toLine(type);
+  return extraTypeMatchRules.get(key) ?? builtInTypeMatchRules.get(key);
+};
 
-/** 删除某个字段 type 的自定义 typeMatch 校验规则 */
-export const deleteTypeMatchRule = (type: string): boolean => typeMatchRuleRegistry.delete(toLine(type));
+/** 删除业务侧 typeMatch 校验规则（不影响内置） */
+export const deleteTypeMatchRule = (type: string): boolean => extraTypeMatchRules.delete(toLine(type));
 
-/** 清空所有自定义 typeMatch 校验规则 */
+/** 清空业务侧 typeMatch 校验规则（不影响内置） */
 export const clearTypeMatchRules = (): void => {
-  typeMatchRuleRegistry.clear();
+  extraTypeMatchRules.clear();
 };
 
 /** 本地解析配置函数，避免与 form.ts 循环依赖 */

package/src/utils/validateError.ts

@@ -0,0 +1,92 @@
+/*
+ * 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 { FormConfig, ValidateError } from '../schema';
+
+/**
+ * 通过 name 从 config 中查找对应的 text
+ *
+ * @param name - 字段名，支持点分隔的路径格式，如 'a.b.c'
+ * @param config - 表单配置数组
+ * @returns 找到的 text 值，如果未找到则返回 undefined
+ */
+export const getTextByName = (name: string, config: FormConfig = []): 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);
+};
+
+/**
+ * 将校验返回的 invalidFields 汇总为可读的错误文案（多条以 `<br>` 拼接）。
+ *
+ * `useFieldTextInError` 为 `true`（默认）时用字段的 text 文案作为错误前缀，找不到则回退为字段 name。
+ *
+ * 由渲染式校验（Form.vue 的 `submitForm` / `validate`）与无渲染校验（`validateValues`）共用，
+ * 保证两条校验链路产出的错误文案格式完全一致。
+ *
+ * @param invalidFields - async-validator 产出的字段错误表
+ * @param [options] - 文案选项
+ * @param [options.config] - 用于查找 text 的表单配置
+ * @param [options.useFieldTextInError=true] - 错误前缀是否使用字段 text
+ * @returns 拼接后的错误文案；无错误时为空串
+ */
+export const formatValidateError = (
+  invalidFields: Record<string, any>,
+  { config = [], useFieldTextInError = true }: { config?: FormConfig; useFieldTextInError?: boolean } = {},
+): string => {
+  const error: string[] = [];
+
+  Object.entries(invalidFields).forEach(([prop, validateError]) => {
+    (validateError as ValidateError[]).forEach(({ field, message }) => {
+      const name = field || prop;
+      const text = (useFieldTextInError ? getTextByName(name, config) : undefined) || name;
+
+      error.push(`${text} -> ${message}`);
+    });
+  });
+
+  return error.join('<br>');
+};

package/src/utils/validateValues.ts

@@ -0,0 +1,177 @@
+/*
+ * 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 { reactive } from 'vue';
+import Schema from 'async-validator';
+
+import type { FormConfig, FormContext, FormState, FormValue } from '../schema';
+
+import { applyMountValueEffects, type CollectedField, collectValidatableFields } from './collectFields';
+import { createFormStateBase, createFormStateProxy, initValue } from './form';
+import { formatValidateError } from './validateError';
+
+// #region HeadlessFormStateOptions
+/** 构造无渲染 formState 所需的参数（与 MForm 的同名 props 对齐） */
+export interface HeadlessFormStateOptions {
+  config: FormConfig;
+  initValues?: FormValue;
+  parentValues?: FormValue;
+  keyProp?: string;
+  popperClass?: string;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: FormContext;
+}
+// #endregion HeadlessFormStateOptions
+
+/**
+ * 构造一个不依赖组件实例的 `formState`。
+ *
+ * 字段结构与 `Form.vue` 中 provide 给子树的 `mForm` 保持一致，使配置里的
+ * `display` / `rules.validator` / `filter` 等回调拿到的上下文与渲染式校验相同。
+ *
+ * 差异：没有真实的表单实例，因此 `$emit` 为空实现、`fields` 注册表始终为空
+ * （该注册表在整个仓库中只写不读，不参与校验）。
+ */
+export const createHeadlessFormState = (options: HeadlessFormStateOptions): FormState => {
+  const context = options.context ?? {};
+  const state: FormState = {
+    keyProp: options.keyProp ?? '__key',
+    popperClass: options.popperClass ?? '',
+    config: options.config,
+    initValues: options.initValues ?? {},
+    isCompare: false,
+    lastValues: {},
+    parentValues: options.parentValues ?? {},
+    values: {},
+    lastValuesProcessed: {},
+    $emit: () => undefined,
+    ...createFormStateBase(),
+  };
+
+  return createFormStateProxy(reactive(state), () => context);
+};
+
+/**
+ * 按 prop 路径从表单值中取字段值，路径中断时返回 `undefined`。
+ *
+ * 不复用 `@tmagic/utils` 的 `getValueByKeyPath`：后者在路径中断时抛错，
+ * 而 Element Plus 的 FormItem 取值是宽松的（拿不到就是 `undefined`），此处与之对齐。
+ */
+const getFieldValue = (prop: string, values: FormValue): any => {
+  if (!prop) return undefined;
+
+  return prop.split('.').reduce<any>((acc, key) => {
+    if (acc === null || typeof acc !== 'object') return undefined;
+    return acc[key];
+  }, values);
+};
+
+/**
+ * 校验单个字段，返回 async-validator 的 `fields` 错误映射（通过则返回 `null`）。
+ *
+ * 与 Element Plus 的 FormItem 逐字段校验保持一致：
+ * 每个字段独立构造一个 `Schema({ [prop]: rules })`，以字段自身的值为 source，
+ * 并开启 `firstFields` 只取每个字段的首条错误；`trigger` 是 FormItem 用来筛选规则的
+ * 元信息，交给 async-validator 前必须剔除，否则会改变规则的匹配方式。
+ */
+const validateField = async (field: CollectedField, values: FormValue): Promise<Record<string, any> | null> => {
+  const rules = field.rules.map(({ trigger, ...rule }: any) => rule);
+  if (!rules.length) return null;
+
+  const value = getFieldValue(field.prop, values);
+
+  try {
+    await new Schema({ [field.prop]: rules } as any).validate({ [field.prop]: value }, { firstFields: true });
+    return null;
+  } catch (err: any) {
+    // async-validator reject 的形态为 { errors, fields }
+    if (err?.fields) return err.fields;
+    return { [field.prop]: [{ field: field.prop, message: err?.message ?? `${err}` }] };
+  }
+};
+
+// #region ValidateValuesOptions
+/** `validateValues` 参数 */
+export interface ValidateValuesOptions extends HeadlessFormStateOptions {
+  /** 是否开启类型匹配校验 */
+  typeMatchValid?: boolean;
+  /**
+   * 校验失败时错误提示前缀是否使用字段的 text 文案。默认 `true`。
+   */
+  useFieldTextInError?: boolean;
+}
+// #endregion ValidateValuesOptions
+
+// #region ValidateValuesResult
+/** `validateValues` 结果 */
+export interface ValidateValuesResult {
+  /** 经 `initValue` 初始化并执行字段值初始化写入后的表单值 */
+  values: FormValue;
+  /** 汇总后的错误文案（多条以 `<br>` 拼接），校验通过为空字符串 */
+  error: string;
+  /** 原始错误映射，形如 `{ [prop]: [{ field, message }] }` */
+  invalidFields: Record<string, any>;
+}
+// #endregion ValidateValuesResult
+
+/**
+ * 不挂载任何组件，纯逻辑地对「一份 config + 一份值」执行一次完整校验。
+ *
+ * 流程与渲染式校验一一对应，但不需要 DOM，也不会实例化任何字段组件：
+ *
+ * 1. 构造 headless `formState` 并挂上 `context` 读穿；
+ * 2. `initValue` 初始化表单值（默认值、嵌套结构、`onInitValue` 等）；
+ * 3. `applyMountValueEffects` 执行字段登记的值初始化写入（与渲染式共用同一份登记表）；
+ * 4. 遍历 config 树收集所有带规则的字段（等价于渲染出的 FormItem 集合）；
+ * 5. 逐字段交给 async-validator 执行，汇总错误文案。
+ *
+ * @example
+ * ```ts
+ * const { error, values } = await validateValues({
+ *   config: [...],
+ *   initValues: { name: '' },
+ *   typeMatchValid: true,
+ * });
+ * ```
+ */
+export const validateValues = async (options: ValidateValuesOptions): Promise<ValidateValuesResult> => {
+  const { config, initValues = {}, typeMatchValid, useFieldTextInError = true } = options;
+
+  const formState = createHeadlessFormState(options);
+
+  const values = await initValue(formState, { initValues, config });
+  formState.values = values;
+  // 与 Form.vue 一致：值挂到 formState 之后再执行字段的值初始化写入
+  applyMountValueEffects(formState, config, values);
+
+  const fields = collectValidatableFields(formState, config, values, Boolean(typeMatchValid));
+
+  const invalidFields: Record<string, any> = {};
+  for (const field of fields) {
+    const fieldErrors = await validateField(field, values);
+    if (fieldErrors) {
+      Object.assign(invalidFields, fieldErrors);
+    }
+  }
+
+  return {
+    values,
+    invalidFields,
+    error: formatValidateError(invalidFields, { config, useFieldTextInError }),
+  };
+};