@tmagic/form 1.8.0-beta.17 → 1.8.0-beta.19

package/dist/es/Form.vue_vue_type_script_setup_true_lang.js

@@ -21,6 +21,10 @@ var Form_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 		parentValues: { default: () => ({}) },
 		labelWidth: { default: "200px" },
 		typeMatchValid: { type: Boolean },
+		validateOnInit: {
+			type: Boolean,
+			default: false
+		},
 		disabled: {
 			type: Boolean,
 			default: false
@@ -218,7 +222,7 @@ var Form_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 			}).then((value) => {
 				values.value = value;
 				initialized.value = !props.isCompare;
-				nextTick(() => {
+				if (props.validateOnInit) nextTick(() => {
 					tMagicFormRef.value?.validate();
 				});
 			});

package/dist/es/FormBox.vue_vue_type_script_setup_true_lang.js

@@ -14,6 +14,10 @@ var FormBox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCo
 		height: {},
 		labelWidth: {},
 		typeMatchValid: { type: Boolean },
+		validateOnInit: {
+			type: Boolean,
+			default: false
+		},
 		disabled: { type: Boolean },
 		size: {},
 		confirmText: { default: "确定" },
@@ -90,6 +94,7 @@ var FormBox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCo
 					"use-field-text-in-error": __props.useFieldTextInError,
 					"extend-state": __props.extendState,
 					"type-match-valid": __props.typeMatchValid,
+					"validate-on-init": __props.validateOnInit,
 					onChange: changeHandler
 				}, null, 8, [
 					"size",
@@ -103,7 +108,8 @@ var FormBox_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCo
 					"prevent-submit-default",
 					"use-field-text-in-error",
 					"extend-state",
-					"type-match-valid"
+					"type-match-valid",
+					"validate-on-init"
 				]), renderSlot(_ctx.$slots, "default")]),
 				_: 3
 			})], 4), createElementVNode("div", {

package/dist/es/FormDialog.vue_vue_type_script_setup_true_lang.js

@@ -13,6 +13,10 @@ var FormDialog_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 		width: {},
 		labelWidth: {},
 		typeMatchValid: { type: Boolean },
+		validateOnInit: {
+			type: Boolean,
+			default: false
+		},
 		fullscreen: { type: Boolean },
 		disabled: { type: Boolean },
 		title: {},
@@ -203,6 +207,7 @@ var FormDialog_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 					"prevent-submit-default": __props.preventSubmitDefault,
 					"use-field-text-in-error": __props.useFieldTextInError,
 					"type-match-valid": __props.typeMatchValid,
+					"validate-on-init": __props.validateOnInit,
 					"extend-state": __props.extendState,
 					theme: effectiveTheme.value,
 					onChange: changeHandler
@@ -219,6 +224,7 @@ var FormDialog_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 					"prevent-submit-default",
 					"use-field-text-in-error",
 					"type-match-valid",
+					"validate-on-init",
 					"extend-state",
 					"theme"
 				]), renderSlot(_ctx.$slots, "default")], 4)) : createCommentVNode("v-if", true)]),

package/dist/es/FormDrawer.vue_vue_type_script_setup_true_lang.js

@@ -13,6 +13,10 @@ var FormDrawer_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 		width: {},
 		labelWidth: {},
 		typeMatchValid: { type: Boolean },
+		validateOnInit: {
+			type: Boolean,
+			default: false
+		},
 		disabled: { type: Boolean },
 		closeOnPressEscape: {
 			type: Boolean,
@@ -180,6 +184,7 @@ var FormDrawer_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 					"prevent-submit-default": __props.preventSubmitDefault,
 					"use-field-text-in-error": __props.useFieldTextInError,
 					"type-match-valid": __props.typeMatchValid,
+					"validate-on-init": __props.validateOnInit,
 					"extend-state": __props.extendState,
 					theme: effectiveTheme.value,
 					onChange: changeHandler
@@ -195,6 +200,7 @@ var FormDrawer_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defin
 					"prevent-submit-default",
 					"use-field-text-in-error",
 					"type-match-valid",
+					"validate-on-init",
 					"extend-state",
 					"theme"
 				]), renderSlot(_ctx.$slots, "default")], 512)) : createCommentVNode("v-if", true)]),

package/dist/es/utils/form.js

@@ -20,15 +20,16 @@ var adaptFormValidator = (validator) => {
 			const callback = (error) => {
 				if (settled) return;
 				settled = true;
-				if (error) resolve({
+				const first = Array.isArray(error) ? error[0] : error;
+				if (first) resolve({
 					result: false,
-					message: typeof error === "string" ? error : error.message
+					message: typeof first === "string" ? first : first.message
 				});
 				else resolve(true);
 			};
 			try {
 				const result = validator(void 0, value, callback);
-				if (result !== null && typeof result.then === "function") Promise.resolve(result).then(() => {
+				if (result && typeof result.then === "function") Promise.resolve(result).then(() => {
 					if (!settled) callback();
 				}, (err) => {
 					callback(err instanceof Error ? err : new Error(String(err)));

package/dist/es/utils/typeMatch.js

@@ -361,6 +361,11 @@ var validateBuiltinTypeMatch = (value, fieldType, mForm, props, message) => {
 		return;
 	}
 };
+/**
+* 校验取值与字段 type 是否匹配；通过返回 undefined，否则返回错误文案。
+*
+* 命中的自定义规则是异步校验器时返回 Promise，内置规则始终同步返回。
+*/
 var validateTypeMatch = (value, mForm, props, message) => {
 	if (isEmptyValue(value) || isEmptyArray(value)) return;
 	if (!props.config?.name) return;
@@ -376,34 +381,106 @@ var validateTypeMatch = (value, mForm, props, message) => {
 	});
 	return validateBuiltinTypeMatch(value, fieldType, mForm, props, message);
 };
+var toError = (error) => error instanceof Error ? error : /* @__PURE__ */ new Error(`${error}`);
 var createTypeMatchValidator = (mForm, props, rule) => {
 	const originalValidator = typeof rule.validator === "function" ? rule.validator : void 0;
+	/**
+	* 每次校验取一个自增序号，只有最新一轮的结论会被采用。
+	*
+	* 旧值的在途校验不能用自己的结论结算：它可能晚于新校验结束，用过期结论覆盖新结论
+	* （表单取最后结束的那次结果）；也不能在新校验开始时无条件按通过结算，否则
+	* `form.validate()` 会对一个还没校验过的值返回成功。因此所有尚未结算的调用都登记在
+	* pendingSettlers 中，等最新一轮出结论后用同一个结论一起结算。
+	*
+	* 不比较取值本身：配了 names 或取值为对象/数组时拿到的是同一个引用，就地修改后比较不出变化。
+	*/
+	let generation = 0;
+	let pendingSettlers = [];
 	return (asyncValidatorRule, value, callback, source, options) => {
 		const actualValue = props.config?.names ? props.model : value;
-		try {
-			const error = validateTypeMatch(actualValue, mForm, props, rule.message);
-			if (error) {
-				callback(new Error(error));
+		generation += 1;
+		const currentGeneration = generation;
+		/** 已有更新的一轮校验开始，本轮结论作废 */
+		const isStale = () => currentGeneration !== generation;
+		pendingSettlers.push((args) => callback(...args));
+		/**
+		* 结算本轮与被本轮取代的所有在途校验。
+		*
+		* async-validator 的 callback 不幂等：重复调用会让它的内部计数提前满足、错误信息重复；
+		* 原始 validator 写成 async 时很容易既调 callback 又返回 Promise，故所有回调都收敛到这里，
+		* 由「取出即出队」保证每个调用的 callback 只会被调用一次。
+		*/
+		const conclude = (...args) => {
+			if (isStale()) return;
+			const settlers = pendingSettlers;
+			pendingSettlers = [];
+			for (const settle of settlers) settle(args);
+		};
+		/**
+		* 执行原始 validator 并把结果统一转成 callback。
+		*
+		* async-validator 只解析同步返回给它的返回值（true / false / Error / 错误数组 / Promise，
+		* 抛错转成错误信息），异步路径已脱离它的调用栈，这些约定会失效导致校验永不结束，故复刻一份。
+		*/
+		const settleWithOriginalValidator = () => {
+			if (isStale()) return;
+			if (!originalValidator) {
+				conclude();
+				return;
+			}
+			let result;
+			try {
+				result = originalValidator({
+					rule: asyncValidatorRule,
+					value: actualValue,
+					callback: conclude,
+					source,
+					options
+				}, {
+					values: mForm?.initValues || {},
+					model: props.model,
+					parent: mForm?.parentValues || {},
+					formValue: mForm?.values || props.model,
+					prop: props.prop,
+					config: props.config
+				}, mForm);
+			} catch (err) {
+				conclude(toError(err));
 				return;
 			}
-		} catch (error) {
-			console.error(error);
+			if (isPromise(result)) result.then(() => conclude(), (err) => conclude(toError(err)));
+			else if (result === true) conclude();
+			else if (result === false) {
+				const field = asyncValidatorRule?.fullField || asyncValidatorRule?.field || props.prop;
+				conclude(new Error(rule.message || `${field} fails`));
+			} else if (result instanceof Error || Array.isArray(result)) conclude(result);
+		};
+		const skipFailedTypeMatch = (err) => {
+			console.error(err);
+			settleWithOriginalValidator();
+		};
+		let error;
+		try {
+			error = validateTypeMatch(actualValue, mForm, props, rule.message);
+		} catch (err) {
+			skipFailedTypeMatch(err);
+			return;
+		}
+		if (isPromise(error)) {
+			error.then((asyncMessage) => {
+				if (asyncMessage) {
+					conclude(new Error(asyncMessage));
+					return;
+				}
+				settleWithOriginalValidator();
+			}, skipFailedTypeMatch);
+			return;
+		}
+		if (error) {
+			conclude(new Error(error));
+			return;
 		}
-		if (originalValidator) return originalValidator({
-			rule: asyncValidatorRule,
-			value: actualValue,
-			callback,
-			source,
-			options
-		}, {
-			values: mForm?.initValues || {},
-			model: props.model,
-			parent: mForm?.parentValues || {},
-			formValue: mForm?.values || props.model,
-			prop: props.prop,
-			config: props.config
-		}, mForm);
-		callback();
+		settleWithOriginalValidator();
 	};
 };
 //#endregion

package/dist/tmagic-form.umd.cjs

@@ -3088,6 +3088,11 @@
 			return;
 		}
 	};
+	/**
+	* 校验取值与字段 type 是否匹配；通过返回 undefined，否则返回错误文案。
+	*
+	* 命中的自定义规则是异步校验器时返回 Promise，内置规则始终同步返回。
+	*/
 	var validateTypeMatch = (value, mForm, props, message) => {
 		if (isEmptyValue(value) || isEmptyArray(value)) return;
 		if (!props.config?.name) return;
@@ -3103,34 +3108,106 @@
 		});
 		return validateBuiltinTypeMatch(value, fieldType, mForm, props, message);
 	};
+	var toError = (error) => error instanceof Error ? error : /* @__PURE__ */ new Error(`${error}`);
 	var createTypeMatchValidator = (mForm, props, rule) => {
 		const originalValidator = typeof rule.validator === "function" ? rule.validator : void 0;
+		/**
+		* 每次校验取一个自增序号，只有最新一轮的结论会被采用。
+		*
+		* 旧值的在途校验不能用自己的结论结算：它可能晚于新校验结束，用过期结论覆盖新结论
+		* （表单取最后结束的那次结果）；也不能在新校验开始时无条件按通过结算，否则
+		* `form.validate()` 会对一个还没校验过的值返回成功。因此所有尚未结算的调用都登记在
+		* pendingSettlers 中，等最新一轮出结论后用同一个结论一起结算。
+		*
+		* 不比较取值本身：配了 names 或取值为对象/数组时拿到的是同一个引用，就地修改后比较不出变化。
+		*/
+		let generation = 0;
+		let pendingSettlers = [];
 		return (asyncValidatorRule, value, callback, source, options) => {
 			const actualValue = props.config?.names ? props.model : value;
-			try {
-				const error = validateTypeMatch(actualValue, mForm, props, rule.message);
-				if (error) {
-					callback(new Error(error));
+			generation += 1;
+			const currentGeneration = generation;
+			/** 已有更新的一轮校验开始，本轮结论作废 */
+			const isStale = () => currentGeneration !== generation;
+			pendingSettlers.push((args) => callback(...args));
+			/**
+			* 结算本轮与被本轮取代的所有在途校验。
+			*
+			* async-validator 的 callback 不幂等：重复调用会让它的内部计数提前满足、错误信息重复；
+			* 原始 validator 写成 async 时很容易既调 callback 又返回 Promise，故所有回调都收敛到这里，
+			* 由「取出即出队」保证每个调用的 callback 只会被调用一次。
+			*/
+			const conclude = (...args) => {
+				if (isStale()) return;
+				const settlers = pendingSettlers;
+				pendingSettlers = [];
+				for (const settle of settlers) settle(args);
+			};
+			/**
+			* 执行原始 validator 并把结果统一转成 callback。
+			*
+			* async-validator 只解析同步返回给它的返回值（true / false / Error / 错误数组 / Promise，
+			* 抛错转成错误信息），异步路径已脱离它的调用栈，这些约定会失效导致校验永不结束，故复刻一份。
+			*/
+			const settleWithOriginalValidator = () => {
+				if (isStale()) return;
+				if (!originalValidator) {
+					conclude();
 					return;
 				}
-			} catch (error) {
-				console.error(error);
+				let result;
+				try {
+					result = originalValidator({
+						rule: asyncValidatorRule,
+						value: actualValue,
+						callback: conclude,
+						source,
+						options
+					}, {
+						values: mForm?.initValues || {},
+						model: props.model,
+						parent: mForm?.parentValues || {},
+						formValue: mForm?.values || props.model,
+						prop: props.prop,
+						config: props.config
+					}, mForm);
+				} catch (err) {
+					conclude(toError(err));
+					return;
+				}
+				if (isPromise(result)) result.then(() => conclude(), (err) => conclude(toError(err)));
+				else if (result === true) conclude();
+				else if (result === false) {
+					const field = asyncValidatorRule?.fullField || asyncValidatorRule?.field || props.prop;
+					conclude(new Error(rule.message || `${field} fails`));
+				} else if (result instanceof Error || Array.isArray(result)) conclude(result);
+			};
+			const skipFailedTypeMatch = (err) => {
+				console.error(err);
+				settleWithOriginalValidator();
+			};
+			let error;
+			try {
+				error = validateTypeMatch(actualValue, mForm, props, rule.message);
+			} catch (err) {
+				skipFailedTypeMatch(err);
+				return;
 			}
-			if (originalValidator) return originalValidator({
-				rule: asyncValidatorRule,
-				value: actualValue,
-				callback,
-				source,
-				options
-			}, {
-				values: mForm?.initValues || {},
-				model: props.model,
-				parent: mForm?.parentValues || {},
-				formValue: mForm?.values || props.model,
-				prop: props.prop,
-				config: props.config
-			}, mForm);
-			callback();
+			if (isPromise(error)) {
+				error.then((asyncMessage) => {
+					if (asyncMessage) {
+						conclude(new Error(asyncMessage));
+						return;
+					}
+					settleWithOriginalValidator();
+				}, skipFailedTypeMatch);
+				return;
+			}
+			if (error) {
+				conclude(new Error(error));
+				return;
+			}
+			settleWithOriginalValidator();
 		};
 	};
 	//#endregion
@@ -3149,15 +3226,16 @@
 				const callback = (error) => {
 					if (settled) return;
 					settled = true;
-					if (error) resolve({
+					const first = Array.isArray(error) ? error[0] : error;
+					if (first) resolve({
 						result: false,
-						message: typeof error === "string" ? error : error.message
+						message: typeof first === "string" ? first : first.message
 					});
 					else resolve(true);
 				};
 				try {
 					const result = validator(void 0, value, callback);
-					if (result !== null && typeof result.then === "function") Promise.resolve(result).then(() => {
+					if (result && typeof result.then === "function") Promise.resolve(result).then(() => {
 						if (!settled) callback();
 					}, (err) => {
 						callback(err instanceof Error ? err : new Error(String(err)));
@@ -4047,6 +4125,10 @@
 			parentValues: { default: () => ({}) },
 			labelWidth: { default: "200px" },
 			typeMatchValid: { type: Boolean },
+			validateOnInit: {
+				type: Boolean,
+				default: false
+			},
 			disabled: {
 				type: Boolean,
 				default: false
@@ -4244,7 +4326,7 @@
 				}).then((value) => {
 					values.value = value;
 					initialized.value = !props.isCompare;
-					(0, vue.nextTick)(() => {
+					if (props.validateOnInit) (0, vue.nextTick)(() => {
 						tMagicFormRef.value?.validate();
 					});
 				});
@@ -4874,6 +4956,10 @@
 			width: {},
 			labelWidth: {},
 			typeMatchValid: { type: Boolean },
+			validateOnInit: {
+				type: Boolean,
+				default: false
+			},
 			fullscreen: { type: Boolean },
 			disabled: { type: Boolean },
 			title: {},
@@ -5064,6 +5150,7 @@
 						"prevent-submit-default": __props.preventSubmitDefault,
 						"use-field-text-in-error": __props.useFieldTextInError,
 						"type-match-valid": __props.typeMatchValid,
+						"validate-on-init": __props.validateOnInit,
 						"extend-state": __props.extendState,
 						theme: effectiveTheme.value,
 						onChange: changeHandler
@@ -5080,6 +5167,7 @@
 						"prevent-submit-default",
 						"use-field-text-in-error",
 						"type-match-valid",
+						"validate-on-init",
 						"extend-state",
 						"theme"
 					]), (0, vue.renderSlot)(_ctx.$slots, "default")], 4)) : (0, vue.createCommentVNode)("v-if", true)]),
@@ -5114,6 +5202,10 @@
 			width: {},
 			labelWidth: {},
 			typeMatchValid: { type: Boolean },
+			validateOnInit: {
+				type: Boolean,
+				default: false
+			},
 			disabled: { type: Boolean },
 			closeOnPressEscape: {
 				type: Boolean,
@@ -5281,6 +5373,7 @@
 						"prevent-submit-default": __props.preventSubmitDefault,
 						"use-field-text-in-error": __props.useFieldTextInError,
 						"type-match-valid": __props.typeMatchValid,
+						"validate-on-init": __props.validateOnInit,
 						"extend-state": __props.extendState,
 						theme: effectiveTheme.value,
 						onChange: changeHandler
@@ -5296,6 +5389,7 @@
 						"prevent-submit-default",
 						"use-field-text-in-error",
 						"type-match-valid",
+						"validate-on-init",
 						"extend-state",
 						"theme"
 					]), (0, vue.renderSlot)(_ctx.$slots, "default")], 512)) : (0, vue.createCommentVNode)("v-if", true)]),
@@ -5328,6 +5422,10 @@
 			height: {},
 			labelWidth: {},
 			typeMatchValid: { type: Boolean },
+			validateOnInit: {
+				type: Boolean,
+				default: false
+			},
 			disabled: { type: Boolean },
 			size: {},
 			confirmText: { default: "确定" },
@@ -5404,6 +5502,7 @@
 						"use-field-text-in-error": __props.useFieldTextInError,
 						"extend-state": __props.extendState,
 						"type-match-valid": __props.typeMatchValid,
+						"validate-on-init": __props.validateOnInit,
 						onChange: changeHandler
 					}, null, 8, [
 						"size",
@@ -5417,7 +5516,8 @@
 						"prevent-submit-default",
 						"use-field-text-in-error",
 						"extend-state",
-						"type-match-valid"
+						"type-match-valid",
+						"validate-on-init"
 					]), (0, vue.renderSlot)(_ctx.$slots, "default")]),
 					_: 3
 				})], 4), (0, vue.createElementVNode)("div", {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.8.0-beta.17",
+  "version": "1.8.0-beta.19",
   "name": "@tmagic/form",
   "type": "module",
   "sideEffects": [
@@ -52,9 +52,9 @@
   "peerDependencies": {
     "vue": "^3.5.40",
     "typescript": "^6.0.3",
-    "@tmagic/design": "1.8.0-beta.17",
-    "@tmagic/utils": "1.8.0-beta.17",
-    "@tmagic/form-schema": "1.8.0-beta.17"
+    "@tmagic/design": "1.8.0-beta.19",
+    "@tmagic/form-schema": "1.8.0-beta.19",
+    "@tmagic/utils": "1.8.0-beta.19"
   },
   "peerDependenciesMeta": {
     "typescript": {

package/src/Form.vue

@@ -88,6 +88,13 @@ const props = withDefaults(
     labelWidth?: string;
     /** 是否开启类型匹配校验 */
     typeMatchValid?: boolean;
+    /**
+     * 初始化（`config` / `initValues` 就绪）后是否立即执行一次表单校验。
+     *
+     * - `false`（默认）：不自动校验，避免打开表单时就展示错误态；
+     * - `true`：初始化完成后在 `nextTick` 中调用 `validate()`。
+     */
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -156,6 +163,7 @@ const props = withDefaults(
     labelPosition: 'right',
     keyProp: '__key',
     useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 
@@ -353,9 +361,11 @@ watch(
       // 非对比模式，初始化完成
       initialized.value = !props.isCompare;
 
-      nextTick(() => {
-        tMagicFormRef.value?.validate();
-      });
+      if (props.validateOnInit) {
+        nextTick(() => {
+          tMagicFormRef.value?.validate();
+        });
+      }
     });
 
     if (props.isCompare) {

package/src/FormBox.vue

@@ -16,6 +16,7 @@
           :use-field-text-in-error="useFieldTextInError"
           :extend-state="extendState"
           :type-match-valid="typeMatchValid"
+          :validate-on-init="validateOnInit"
           @change="changeHandler"
         ></Form>
         <slot></slot>
@@ -59,6 +60,8 @@ const props = withDefaults(
     labelWidth?: string;
     /** 是否开启类型匹配校验 */
     typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     disabled?: boolean;
     size?: 'small' | 'default' | 'large';
     confirmText?: string;
@@ -74,6 +77,7 @@ const props = withDefaults(
     values: () => ({}),
     confirmText: '确定',
     useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/FormDialog.vue

@@ -33,6 +33,7 @@
         :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"
@@ -87,6 +88,8 @@ const props = withDefaults(
     labelWidth?: string;
     /** 是否开启类型匹配校验 */
     typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     fullscreen?: boolean;
     disabled?: boolean;
     title?: string;
@@ -122,6 +125,7 @@ const props = withDefaults(
     showClose: true,
     showCancel: true,
     useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/FormDrawer.vue

@@ -30,6 +30,7 @@
         :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"
@@ -78,6 +79,8 @@ const props = withDefaults(
     labelWidth?: string;
     /** 是否开启类型匹配校验 */
     typeMatchValid?: boolean;
+    /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+    validateOnInit?: boolean;
     disabled?: boolean;
     closeOnPressEscape?: boolean;
     title?: string;
@@ -106,6 +109,7 @@ const props = withDefaults(
     values: () => ({}),
     confirmText: '确定',
     useFieldTextInError: true,
+    validateOnInit: false,
   },
 );
 

package/src/utils/form.ts

@@ -60,13 +60,15 @@ export const adaptFormValidator = (validator: AsyncValidatorFn): AsyncValidatorF
     const value = arg1;
     return new Promise((resolve) => {
       let settled = false;
-      const callback = (error?: Error | string) => {
+      const callback = (error?: Error | string | (Error | string)[]) => {
         if (settled) return;
         settled = true;
-        if (error) {
+        // async-validator 约定 callback 也可接收错误数组，TDesign 只能展示一条，取首条
+        const first = Array.isArray(error) ? error[0] : error;
+        if (first) {
           resolve({
             result: false,
-            message: typeof error === 'string' ? error : error.message,
+            message: typeof first === 'string' ? first : first.message,
           });
         } else {
           resolve(true);
@@ -74,8 +76,9 @@ export const adaptFormValidator = (validator: AsyncValidatorFn): AsyncValidatorF
       };
 
       try {
+        // 异步 validator 会先返回 undefined，稍后再调 callback，这里不能当成 thenable 取值
         const result = validator(undefined, value, callback);
-        if (result !== null && typeof (result as PromiseLike<unknown>).then === 'function') {
+        if (result && typeof (result as PromiseLike<unknown>).then === 'function') {
           Promise.resolve(result).then(
             () => {
               if (!settled) callback();

package/src/utils/typeMatch.ts

@@ -38,8 +38,15 @@ export interface TypeMatchValidateContext {
 // #endregion TypeMatchValidateContext
 
 // #region TypeMatchValidator
-/** 自定义 type 校验器：返回错误文案；通过则返回 undefined */
-export type TypeMatchValidator = (value: any, context: TypeMatchValidateContext) => string | undefined;
+/**
+ * 自定义 type 校验器：返回错误文案；通过则返回 undefined。
+ *
+ * 支持返回 Promise，用于需要异步确认取值是否合法的场景（如请求接口校验 id 是否存在）。
+ */
+export type TypeMatchValidator = (
+  value: any,
+  context: TypeMatchValidateContext,
+) => string | undefined | Promise<string | undefined>;
 // #endregion TypeMatchValidator
 
 const typeMatchRuleRegistry = new Map<string, TypeMatchValidator>();
@@ -692,12 +699,17 @@ const validateBuiltinTypeMatch = (
   return undefined;
 };
 
+/**
+ * 校验取值与字段 type 是否匹配；通过返回 undefined，否则返回错误文案。
+ *
+ * 命中的自定义规则是异步校验器时返回 Promise，内置规则始终同步返回。
+ */
 export const validateTypeMatch = (
   value: any,
   mForm: FormState | undefined,
   props: any,
   message?: string,
-): string | undefined => {
+): string | undefined | Promise<string | undefined> => {
   if (isEmptyValue(value) || isEmptyArray(value)) {
     return undefined;
   }
@@ -724,43 +736,135 @@ export const validateTypeMatch = (
   return validateBuiltinTypeMatch(value, fieldType, mForm, props, message);
 };
 
+const toError = (error: any): Error => (error instanceof Error ? error : new Error(`${error}`));
+
 export const createTypeMatchValidator = (mForm: FormState | undefined, props: any, rule: Rule) => {
   const originalValidator = typeof rule.validator === 'function' ? rule.validator : undefined;
 
+  /**
+   * 每次校验取一个自增序号，只有最新一轮的结论会被采用。
+   *
+   * 旧值的在途校验不能用自己的结论结算：它可能晚于新校验结束，用过期结论覆盖新结论
+   * （表单取最后结束的那次结果）；也不能在新校验开始时无条件按通过结算，否则
+   * `form.validate()` 会对一个还没校验过的值返回成功。因此所有尚未结算的调用都登记在
+   * pendingSettlers 中，等最新一轮出结论后用同一个结论一起结算。
+   *
+   * 不比较取值本身：配了 names 或取值为对象/数组时拿到的是同一个引用，就地修改后比较不出变化。
+   */
+  let generation = 0;
+  let pendingSettlers: ((args: any[]) => void)[] = [];
+
   return (asyncValidatorRule: any, value: any, callback: Function, source: any, options: any) => {
     const actualValue = props.config?.names ? props.model : value;
-    try {
-      const error = validateTypeMatch(actualValue, mForm, props, rule.message);
 
-      if (error) {
-        callback(new Error(error));
+    generation += 1;
+    const currentGeneration = generation;
+    /** 已有更新的一轮校验开始，本轮结论作废 */
+    const isStale = () => currentGeneration !== generation;
+
+    pendingSettlers.push((args: any[]) => callback(...args));
+
+    /**
+     * 结算本轮与被本轮取代的所有在途校验。
+     *
+     * async-validator 的 callback 不幂等：重复调用会让它的内部计数提前满足、错误信息重复；
+     * 原始 validator 写成 async 时很容易既调 callback 又返回 Promise，故所有回调都收敛到这里，
+     * 由「取出即出队」保证每个调用的 callback 只会被调用一次。
+     */
+    const conclude = (...args: any[]) => {
+      if (isStale()) {
         return;
       }
-    } catch (error) {
-      console.error(error);
-    }
-
-    if (originalValidator) {
-      return originalValidator(
-        {
-          rule: asyncValidatorRule,
-          value: actualValue,
-          callback,
-          source,
-          options,
-        },
-        {
-          values: mForm?.initValues || {},
-          model: props.model,
-          parent: mForm?.parentValues || {},
-          formValue: mForm?.values || props.model,
-          prop: props.prop,
-          config: props.config,
-        },
-        mForm,
-      );
+
+      const settlers = pendingSettlers;
+      pendingSettlers = [];
+      for (const settle of settlers) {
+        settle(args);
+      }
+    };
+
+    /**
+     * 执行原始 validator 并把结果统一转成 callback。
+     *
+     * async-validator 只解析同步返回给它的返回值（true / false / Error / 错误数组 / Promise，
+     * 抛错转成错误信息），异步路径已脱离它的调用栈，这些约定会失效导致校验永不结束，故复刻一份。
+     */
+    const settleWithOriginalValidator = () => {
+      // 本轮结论已作废，不必再跑一遍原始 validator 触发副作用
+      if (isStale()) {
+        return;
+      }
+
+      if (!originalValidator) {
+        conclude();
+        return;
+      }
+
+      let result: any;
+      try {
+        result = originalValidator(
+          { rule: asyncValidatorRule, value: actualValue, callback: conclude, source, options },
+          {
+            values: mForm?.initValues || {},
+            model: props.model,
+            parent: mForm?.parentValues || {},
+            formValue: mForm?.values || props.model,
+            prop: props.prop,
+            config: props.config,
+          },
+          mForm,
+        );
+      } catch (err) {
+        conclude(toError(err));
+        return;
+      }
+
+      if (isPromise(result)) {
+        result.then(
+          () => conclude(),
+          (err: any) => conclude(toError(err)),
+        );
+      } else if (result === true) {
+        conclude();
+      } else if (result === false) {
+        const field = asyncValidatorRule?.fullField || asyncValidatorRule?.field || props.prop;
+        conclude(new Error(rule.message || `${field} fails`));
+      } else if (result instanceof Error || Array.isArray(result)) {
+        conclude(result);
+      }
+      // 其余返回值（undefined / void）按约定由 validator 自行调用 callback
+    };
+
+    // 校验器自身失败（如接口异常）不应阻塞用户，记录后按通过处理
+    const skipFailedTypeMatch = (err: any) => {
+      console.error(err);
+      settleWithOriginalValidator();
+    };
+
+    let error: string | undefined | Promise<string | undefined>;
+    try {
+      error = validateTypeMatch(actualValue, mForm, props, rule.message);
+    } catch (err) {
+      skipFailedTypeMatch(err);
+      return;
+    }
+
+    if (isPromise(error)) {
+      error.then((asyncMessage) => {
+        if (asyncMessage) {
+          conclude(new Error(asyncMessage));
+          return;
+        }
+        settleWithOriginalValidator();
+      }, skipFailedTypeMatch);
+      return;
+    }
+
+    if (error) {
+      conclude(new Error(error));
+      return;
     }
 
-    callback();
+    settleWithOriginalValidator();
   };
 };

package/types/index.d.ts

@@ -325,6 +325,13 @@ type __VLS_Props$30 = {
   parentValues?: Record<string, any>;
   labelWidth?: string; /** 是否开启类型匹配校验 */
   typeMatchValid?: boolean;
+  /**
+   * 初始化（`config` / `initValues` 就绪）后是否立即执行一次表单校验。
+   *
+   * - `false`（默认）：不自动校验，避免打开表单时就展示错误态；
+   * - `true`：初始化完成后在 `nextTick` 中调用 `validate()`。
+   */
+  validateOnInit?: boolean;
   disabled?: boolean;
   height?: string;
   stepActive?: string | number;
@@ -435,6 +442,7 @@ declare const __VLS_base$5: import("@vue/runtime-core").DefineComponent<__VLS_Pr
   keyProp: string;
   parentValues: Record<string, any>;
   stepActive: string | number;
+  validateOnInit: boolean;
   useFieldTextInError: boolean;
 }, {}, {}, {}, string, import("@vue/runtime-core").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export$30: __VLS_WithSlots$5<typeof __VLS_base$5, __VLS_Slots$5>;
@@ -452,7 +460,8 @@ type __VLS_Props$29 = {
   parentValues?: Object;
   width?: string | number;
   labelWidth?: string; /** 是否开启类型匹配校验 */
-  typeMatchValid?: boolean;
+  typeMatchValid?: boolean; /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+  validateOnInit?: boolean;
   fullscreen?: boolean;
   disabled?: boolean;
   title?: string;
@@ -496,6 +505,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -540,6 +550,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -594,6 +605,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -628,6 +640,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -637,6 +650,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -661,7 +675,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -685,6 +699,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -729,6 +744,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -783,6 +799,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -817,6 +834,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -826,6 +844,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -850,7 +869,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -887,6 +906,7 @@ declare const __VLS_base$4: import("@vue/runtime-core").DefineComponent<__VLS_Pr
   destroyOnClose: boolean;
   showClose: boolean;
   config: schema_d_exports.FormConfig;
+  validateOnInit: boolean;
   useFieldTextInError: boolean;
   confirmText: string;
   showCancel: boolean;
@@ -906,7 +926,8 @@ type __VLS_Props$28 = {
   parentValues?: Object;
   width?: string | number;
   labelWidth?: string; /** 是否开启类型匹配校验 */
-  typeMatchValid?: boolean;
+  typeMatchValid?: boolean; /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+  validateOnInit?: boolean;
   disabled?: boolean;
   closeOnPressEscape?: boolean;
   title?: string;
@@ -946,6 +967,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -990,6 +1012,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -1044,6 +1067,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -1078,6 +1102,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -1087,6 +1112,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -1111,7 +1137,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -1135,6 +1161,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -1179,6 +1206,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -1233,6 +1261,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -1267,6 +1296,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -1276,6 +1306,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -1300,7 +1331,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -1342,6 +1373,7 @@ declare const __VLS_base$3: import("@vue/runtime-core").DefineComponent<__VLS_Pr
   values: Object;
   closeOnPressEscape: boolean;
   config: schema_d_exports.FormConfig;
+  validateOnInit: boolean;
   useFieldTextInError: boolean;
   confirmText: string;
 }, {}, {}, {}, string, import("@vue/runtime-core").ComponentProvideOptions, false, {}, any>;
@@ -1361,7 +1393,8 @@ type __VLS_Props$27 = {
   width?: number;
   height?: number;
   labelWidth?: string; /** 是否开启类型匹配校验 */
-  typeMatchValid?: boolean;
+  typeMatchValid?: boolean; /** 透传给内部 `MForm`，初始化完成后是否立即校验（默认 `false`） */
+  validateOnInit?: boolean;
   disabled?: boolean;
   size?: 'small' | 'default' | 'large';
   confirmText?: string;
@@ -1391,6 +1424,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -1435,6 +1469,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -1489,6 +1524,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -1523,6 +1559,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -1532,6 +1569,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -1556,7 +1594,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -1580,6 +1618,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       readonly parentValues?: Record<string, any> | undefined;
       readonly labelWidth?: string | undefined;
       readonly typeMatchValid?: boolean | undefined;
+      readonly validateOnInit?: boolean | undefined;
       readonly disabled?: boolean | undefined;
       readonly height?: string | undefined;
       readonly stepActive?: string | number | undefined;
@@ -1624,6 +1663,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       parentValues?: Record<string, any>;
       labelWidth?: string;
       typeMatchValid?: boolean;
+      validateOnInit?: boolean;
       disabled?: boolean;
       height?: string;
       stepActive?: string | number;
@@ -1678,6 +1718,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
       keyProp: string;
       parentValues: Record<string, any>;
       stepActive: string | number;
+      validateOnInit: boolean;
       useFieldTextInError: boolean;
     }, {}, string, {}, import("@vue/runtime-core").GlobalComponents, import("@vue/runtime-core").GlobalDirectives, string, import("@vue/runtime-core").ComponentProvideOptions> & {
       beforeCreate?: (() => void) | (() => void)[];
@@ -1712,6 +1753,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     keyProp: string;
     parentValues: Record<string, any>;
     stepActive: string | number;
+    validateOnInit: boolean;
     useFieldTextInError: boolean;
   }> & Omit<Readonly<{
     config: schema_d_exports.FormConfig;
@@ -1721,6 +1763,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     parentValues?: Record<string, any>;
     labelWidth?: string;
     typeMatchValid?: boolean;
+    validateOnInit?: boolean;
     disabled?: boolean;
     height?: string;
     stepActive?: string | number;
@@ -1745,7 +1788,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
     "onField-input"?: ((...args: any[]) => any) | undefined;
     "onField-change"?: ((...args: any[]) => any) | undefined;
     "onUpdate:stepActive"?: ((...args: any[]) => any) | undefined;
-  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "useFieldTextInError")> & {
+  }>, "values" | "changeHandler" | "validate" | "initialized" | "lastValuesProcessed" | "formState" | "changeRecords" | "resetForm" | "submitForm" | "getTextByName" | ("disabled" | "labelWidth" | "inline" | "labelPosition" | "config" | "height" | "initValues" | "lastValues" | "isCompare" | "keyProp" | "parentValues" | "stepActive" | "validateOnInit" | "useFieldTextInError")> & {
     values: schema_d_exports.FormValue;
     lastValuesProcessed: schema_d_exports.FormValue;
     formState: schema_d_exports.FormState;
@@ -1773,6 +1816,7 @@ declare const __VLS_base$2: import("@vue/runtime-core").DefineComponent<__VLS_Pr
 }>, {
   values: Object;
   config: schema_d_exports.FormConfig;
+  validateOnInit: boolean;
   useFieldTextInError: boolean;
   confirmText: string;
 }, {}, {}, {}, string, import("@vue/runtime-core").ComponentProvideOptions, false, {}, any>;
@@ -2206,8 +2250,12 @@ interface TypeMatchValidateContext {
   props: any;
   message?: string;
 }
-/** 自定义 type 校验器：返回错误文案；通过则返回 undefined */
-type TypeMatchValidator = (value: any, context: TypeMatchValidateContext) => string | undefined;
+/**
+ * 自定义 type 校验器：返回错误文案；通过则返回 undefined。
+ *
+ * 支持返回 Promise，用于需要异步确认取值是否合法的场景（如请求接口校验 id 是否存在）。
+ */
+type TypeMatchValidator = (value: any, context: TypeMatchValidateContext) => string | undefined | Promise<string | undefined>;
 /** 注册或覆盖某个字段 type 的 typeMatch 校验规则 */
 declare const registerTypeMatchRule: (type: string, validator: TypeMatchValidator) => void;
 /** 批量注册 typeMatch 校验规则 */
@@ -2218,7 +2266,12 @@ declare const getTypeMatchRule: (type: string) => TypeMatchValidator | undefined
 declare const deleteTypeMatchRule: (type: string) => boolean;
 /** 清空所有自定义 typeMatch 校验规则 */
 declare const clearTypeMatchRules: () => void;
-declare const validateTypeMatch: (value: any, mForm: schema_d_exports.FormState | undefined, props: any, message?: string) => string | undefined;
+/**
+ * 校验取值与字段 type 是否匹配；通过返回 undefined，否则返回错误文案。
+ *
+ * 命中的自定义规则是异步校验器时返回 Promise，内置规则始终同步返回。
+ */
+declare const validateTypeMatch: (value: any, mForm: schema_d_exports.FormState | undefined, props: any, message?: string) => string | undefined | Promise<string | undefined>;
 //#endregion
 //#region temp/packages/form/src/plugin.d.ts
 interface FormInstallOptions {