@tmagic/form 1.8.0-manmanyu.8 → 1.8.0

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 }),
+  };
+};