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

package/src/utils/registerField.ts

@@ -0,0 +1,308 @@
+/*
+ * 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 { App, Component } from 'vue';
+
+import { toLine } from '@tmagic/utils';
+
+import {
+  clearContainerWalkers,
+  type ContainerWalker,
+  deleteContainerWalker,
+  registerContainerWalker,
+} from './collectFields';
+import {
+  clearFieldInnerConfigs,
+  deleteFieldInnerConfig,
+  type FieldInnerConfig,
+  registerFieldInnerConfig,
+} from './fieldInnerConfig';
+import {
+  clearLeafFieldTypes,
+  deleteLeafFieldType,
+  type FieldMountValueEffect,
+  registerLeafFieldType,
+} from './fieldValueEffects';
+import { clearTypeMatchRules, deleteTypeMatchRule, registerTypeMatchRule, type TypeMatchValidator } from './typeMatch';
+
+// #region FieldOptions
+/**
+ * 自定义字段 type 的登记项。
+ *
+ * 不传或只传空对象：当作叶子，不再下钻 `items`。
+ */
+export interface FieldOptions {
+  /**
+   * 渲染用的 Vue 组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-fields-*')`。
+   */
+  component?: Component;
+  /**
+   * 容器组件，写入字段注册表。
+   * 传入 `app` 时同时 `app.component('m-form-*')`。
+   */
+  container?: Component;
+  /** 字段挂载时改写 model 的副作用。可与 `innerConfig` 同时登记。 */
+  effect?: FieldMountValueEffect;
+  /**
+   * 按容器模板遍历（tab / table 等）。
+   * 与 `innerConfig` / `effect` 同时传入时 `walk` 优先。
+   */
+  walk?: ContainerWalker;
+  /**
+   * 把内部会挂到父表单的配置交出来。
+   * 可与 `effect` 同时传入：`effect` 负责本字段的值初始化，`innerConfig` 只做配置派生。
+   */
+  innerConfig?: FieldInnerConfig;
+  /** 该 type 的 typeMatch 校验；可与叶子、walk 或 innerConfig 同时登记。 */
+  typeMatch?: TypeMatchValidator;
+}
+
+/**
+ * 无渲染校验用的登记项，不含 Vue 组件。
+ *
+ * 给 Node / `validateForm` / `submitForm` 用。
+ */
+export type HeadlessFieldOptions = Omit<FieldOptions, 'component' | 'container'>;
+// #endregion FieldOptions
+
+const extraComponents = new Map<string, Component>();
+const builtInComponents = new Map<string, Component>();
+
+const applyVueComponent = (
+  type: string,
+  component: Component,
+  app: App | undefined,
+  builtIn: boolean,
+  kind: 'fields' | 'form',
+): void => {
+  const key = toLine(type);
+  if (builtIn) {
+    builtInComponents.set(key, component);
+  } else {
+    extraComponents.set(key, component);
+  }
+  app?.component(`m-${kind}-${key}`, component);
+};
+
+/**
+ * 把已登记字段的 Vue 组件写入注册表；传入 `app` 时同时挂 `m-fields-*` / `m-form-*`。
+ *
+ * @param fields - 字段登记表
+ * @param [app] - Vue 应用；省略则只写入注册表
+ * @param [builtIn=false] - 是否写入内置表（`clearFields` 不会清掉）
+ */
+export const bindFieldApp = (fields: Record<string, FieldOptions>, app?: App, builtIn = false): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    if (options?.component) {
+      applyVueComponent(type, options.component, app, builtIn, 'fields');
+    }
+    if (options?.container) {
+      applyVueComponent(type, options.container, app, builtIn, 'form');
+    }
+  }
+};
+
+/**
+ * 把多份字段登记表按 type 浅合并。后一份只覆盖自己带了的 key，未出现的 key 保留前一份。
+ *
+ * 安装插件时用：Node 侧只登记 `headless`，浏览器再补 `component` / `container`。
+ *
+ * @param tables - 待合并的登记表，`undefined` 会被跳过
+ * @returns 合并后的登记表
+ */
+export const mergeFieldOptions = (
+  ...tables: Array<Record<string, HeadlessFieldOptions | FieldOptions> | undefined>
+): Record<string, FieldOptions> => {
+  const result: Record<string, FieldOptions> = {};
+  for (const table of tables) {
+    if (!table) continue;
+    for (const [type, options] of Object.entries(table)) {
+      result[type] = { ...result[type], ...pickDefinedFieldOptions(options) };
+    }
+  }
+  return result;
+};
+
+const FIELD_OPTION_KEYS = ['component', 'container', 'effect', 'walk', 'innerConfig', 'typeMatch'] as const;
+
+const pickDefinedFieldOptions = (options?: FieldOptions): FieldOptions => {
+  if (!options) return {};
+  const next: FieldOptions = {};
+  for (const key of FIELD_OPTION_KEYS) {
+    if (options[key] !== undefined) {
+      (next as any)[key] = options[key];
+    }
+  }
+  return next;
+};
+
+const extraFieldOptions = new Map<string, FieldOptions>();
+const builtInFieldOptions = new Map<string, FieldOptions>();
+
+const removeFormComponent = (type: string): void => {
+  extraComponents.delete(toLine(type));
+};
+
+const clearFormComponents = (): void => {
+  extraComponents.clear();
+};
+
+/**
+ * 按字段 type 取已登记的渲染组件（`codeSelect` 与 `code-select` 等价）。
+ *
+ * @param type - 字段 type
+ * @returns 已登记的 Vue 组件；未登记则为 `undefined`
+ */
+export const getField = (type: string): Component | undefined => {
+  const key = toLine(type);
+  return extraComponents.get(key) ?? builtInComponents.get(key);
+};
+
+const registerFieldImpl = (type: string, options: FieldOptions | undefined, app: App | undefined, builtIn: boolean) => {
+  if (typeof type !== 'string' || !type) return;
+
+  const key = toLine(type);
+  const store = builtIn ? builtInFieldOptions : extraFieldOptions;
+  const incoming = pickDefinedFieldOptions(options);
+  const merged: FieldOptions = { ...store.get(key), ...incoming };
+  store.set(key, merged);
+
+  if (incoming.walk && (incoming.innerConfig || typeof incoming.effect === 'function')) {
+    console.warn(
+      `[MForm] registerField("${key}"): walk is set together with innerConfig/effect; ` +
+        'headless validation will use walk and innerConfig/effect will be ignored.',
+    );
+  }
+
+  if (incoming.component && incoming.container) {
+    console.warn(
+      `[MForm] registerField("${key}"): component and container are both set; ` +
+        'getField will use container, and both m-fields-* / m-form-* will be registered.',
+    );
+  }
+
+  if (merged.component) {
+    applyVueComponent(type, merged.component, app, builtIn, 'fields');
+  }
+
+  if (merged.container) {
+    applyVueComponent(type, merged.container, app, builtIn, 'form');
+  }
+
+  if (merged.typeMatch) {
+    registerTypeMatchRule(type, merged.typeMatch, builtIn);
+  }
+
+  if (merged.walk) {
+    registerContainerWalker(type, merged.walk, builtIn);
+    if (!builtIn) {
+      deleteLeafFieldType(type);
+      deleteFieldInnerConfig(type);
+    }
+    return;
+  }
+
+  if (!builtIn) {
+    deleteContainerWalker(type);
+  }
+
+  if (merged.innerConfig) {
+    registerFieldInnerConfig(type, merged.innerConfig, builtIn);
+    if (typeof merged.effect === 'function') {
+      registerLeafFieldType(type, merged.effect, builtIn);
+    } else if (!builtIn) {
+      deleteLeafFieldType(type);
+    }
+    return;
+  }
+
+  // 只登记了容器组件：不当叶子，dispatch 会按 items 下钻
+  if (merged.container && !merged.component && typeof merged.effect !== 'function') {
+    if (!builtIn) deleteLeafFieldType(type);
+    return;
+  }
+
+  if (!builtIn) {
+    deleteFieldInnerConfig(type);
+  }
+  registerLeafFieldType(type, merged.effect, builtIn);
+};
+
+/**
+ * 登记一个字段 type 在无渲染校验里的行为，以及可选的渲染组件。
+ *
+ * `type` 会按 Container 的规则归一化为中划线形式（`codeSelect` 与 `code-select` 等价）。
+ * 对同一 type 重复登记按字段浅合并：后一次只覆盖自己传入的 key，未传入的 key 保留。
+ * 传入 `app` 且带了 `component` / `container` 时，会同步 `app.component('m-fields-*'` / `'m-form-*')`。
+ *
+ * @param type - 字段 type
+ * @param [options] - 登记项；省略或空对象视为叶子
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerField = (type: string, options?: FieldOptions, app?: App): void => {
+  registerFieldImpl(type, options, app, false);
+};
+
+/**
+ * 批量登记字段。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerFields = (fields: Record<string, FieldOptions>, app?: App): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    registerFieldImpl(type, options, app, false);
+  }
+};
+
+/**
+ * 登记内置字段（`clearFields` / `unregisterField` 不会清掉）。
+ *
+ * @param fields - type 到登记项的映射
+ * @param [app] - Vue 应用；省略则不调用 `app.component`
+ */
+export const registerBuiltInFields = (fields: Record<string, FieldOptions>, app?: App): void => {
+  for (const [type, options] of Object.entries(fields)) {
+    registerFieldImpl(type, options, app, true);
+  }
+};
+
+/**
+ * 删除业务侧对指定 type 的登记（不影响内置；主要用于单测）。
+ *
+ * @param type - 字段 type
+ */
+export const unregisterField = (type: string): void => {
+  extraFieldOptions.delete(toLine(type));
+  deleteLeafFieldType(type);
+  deleteFieldInnerConfig(type);
+  deleteTypeMatchRule(type);
+  deleteContainerWalker(type);
+  removeFormComponent(type);
+};
+
+/** 清空业务侧登记（不影响内置；主要用于单测）。 */
+export const clearFields = (): void => {
+  extraFieldOptions.clear();
+  clearLeafFieldTypes();
+  clearFieldInnerConfigs();
+  clearTypeMatchRules();
+  clearContainerWalkers();
+  clearFormComponents();
+};

package/src/utils/submitHeadless.ts

@@ -0,0 +1,206 @@
+/*
+ * 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 { AppContext } from 'vue';
+import { cloneDeep } from 'lodash-es';
+
+import type { ChangeRecord, FormConfig, FormContext } from '../schema';
+
+import { validateValues, type ValidateValuesResult } from './validateValues';
+
+// #region SubmitFormOptions
+/**
+ * submitForm 函数参数（与 Form.vue 组件 props 对齐）
+ */
+export interface SubmitFormOptions {
+  /** 表单配置 */
+  config: FormConfig;
+  /** 表单初始值 */
+  initValues?: Record<string, any>;
+  /** 需对比的值（开启对比模式时传入） */
+  lastValues?: Record<string, any>;
+  /** 是否开启对比模式 */
+  isCompare?: boolean;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  disabled?: boolean;
+  height?: string;
+  stepActive?: string | number;
+  size?: 'small' | 'default' | 'large';
+  inline?: boolean;
+  labelPosition?: 'top' | 'left' | 'right';
+  keyProp?: string;
+  popperClass?: string;
+  preventSubmitDefault?: boolean;
+  /**
+   * 表单校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: FormContext;
+  /** 透传给 Form.submitForm 的参数：是否直接返回原始响应式 values */
+  native?: boolean;
+  /**
+   * 是否在 resolve 结果中携带 changeRecords（变更记录）。
+   * 开启后 resolve 的结果为 `{ values, changeRecords }`，否则仅 resolve values。
+   */
+  returnChangeRecords?: boolean;
+  /**
+   * 父级应用上下文，用于继承全局组件、指令、provide 等。
+   * 仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+// #endregion SubmitFormOptions
+
+// #region SubmitFormResult
+/**
+ * 开启 `returnChangeRecords` 时 submitForm 的返回结果
+ */
+export interface SubmitFormResult {
+  /** 校验通过后的表单值 */
+  values: any;
+  /** 表单变更记录 */
+  changeRecords: ChangeRecord[];
+}
+// #endregion SubmitFormResult
+
+// #region ValidateFormOptions
+/**
+ * validateForm 函数参数（与 Form.vue 组件 props 对齐，取校验所需子集）
+ */
+export interface ValidateFormOptions {
+  /** 表单配置 */
+  config: FormConfig;
+  /** 待校验的表单值 */
+  initValues?: Record<string, any>;
+  parentValues?: Record<string, any>;
+  labelWidth?: string;
+  keyProp?: string;
+  /**
+   * 校验失败时，错误提示前缀是否使用字段的 text 文案（通过 `getTextByName` 从 config 中查找）。
+   * 默认 `true`，置为 `false` 时直接使用字段 name。
+   */
+  useFieldTextInError?: boolean;
+  /** 宿主业务上下文，与 MForm 的同名 prop 语义一致 */
+  context?: FormContext;
+  /**
+   * 父级应用上下文。仅 `dialog: true` 时生效。`@tmagic/form/headless` 不支持弹层。
+   */
+  appContext?: AppContext | null;
+  /**
+   * 是否以弹层展示表单。默认 `false`。
+   *
+   * `@tmagic/form/headless` 不支持 `dialog: true`，请从 `@tmagic/form` 引入。
+   */
+  dialog?: boolean;
+  /**
+   * 弹层标题，仅 `dialog: true` 时生效。
+   */
+  title?: string;
+  typeMatchValid?: boolean;
+  /**
+   * 外部中断信号。abort 时会立即以 `signal.reason` reject。
+   */
+  signal?: AbortSignal;
+}
+// #endregion ValidateFormOptions
+
+const throwIfAborted = (signal: AbortSignal | undefined, fnName: string) => {
+  if (signal?.aborted) {
+    throw signal.reason ?? new Error(`${fnName} aborted`);
+  }
+};
+
+const throwIfDialog = (dialog: boolean | undefined, fnName: string) => {
+  if (dialog) {
+    throw new Error(
+      `[MForm] ${fnName}({ dialog: true }) is not available from @tmagic/form/headless. Import from @tmagic/form instead.`,
+    );
+  }
+};
+
+/**
+ * `submitForm` 与 `validateForm` 共用的无渲染校验流程：中断检查 → `validateValues`。
+ */
+export const validateWithoutRender = async (
+  fnName: 'submitForm' | 'validateForm',
+  options: SubmitFormOptions | ValidateFormOptions,
+): Promise<ValidateValuesResult> => {
+  const { signal, config, initValues, parentValues, keyProp, typeMatchValid, useFieldTextInError, context } = options;
+
+  throwIfAborted(signal, fnName);
+
+  const result = await validateValues({
+    config,
+    initValues,
+    parentValues,
+    keyProp,
+    popperClass: (options as SubmitFormOptions).popperClass,
+    typeMatchValid,
+    useFieldTextInError,
+    context,
+  });
+
+  throwIfAborted(signal, fnName);
+
+  return result;
+};
+
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次校验并取回表单值（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export const submitForm = async (options: SubmitFormOptions): Promise<any> => {
+  throwIfDialog(options.dialog, 'submitForm');
+
+  const validated = await validateWithoutRender('submitForm', options);
+
+  if (validated.error) throw new Error(validated.error);
+
+  const values = options.native ? validated.values : cloneDeep(validated.values);
+  return options.returnChangeRecords ? { values, changeRecords: [] as ChangeRecord[] } : values;
+};
+
+/**
+ * 以命令式方式对一份「表单配置 + 值」做一次静默校验（无渲染）。
+ *
+ * `@tmagic/form/headless` 不支持 `dialog: true`。
+ */
+export const validateForm = async (options: ValidateFormOptions): Promise<string> => {
+  throwIfDialog(options.dialog, 'validateForm');
+
+  return (await validateWithoutRender('validateForm', options)).error;
+};

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 循环依赖 */