FaForm 表单

在 ElForm 上增加响应式 Grid、详情模式、团队标签格式和滚动校验方法。

validate()（不传回调）与 validateScrollToField() 校验成功时 Promise 以 true 完成；从 2.0.16 起，校验失败时以 Element Plus 的 invalidFields 详情拒绝，需通过 catch 处理，并非返回一个成功完成的 false。实例尚未挂载时仍以 Error 拒绝。validate(callback) 保持 Element Plus 原生回调行为。

响应式表单布局与字段提示

查看代码

Vue

<template>
	<FaForm :model="form" :cols="{ xs: 1, sm: 2, md: 2, lg: 3, xl: 3 }">
		<FaFormItem label="应用名称" prop="name" tips="显示在系统标题和浏览器标签中">
			<ElInput v-model="form.name" maxlength="30" />
		</FaFormItem>
		<FaFormItem label="状态" prop="status">
			<ElSelect v-model="form.status">
				<ElOption label="启用" value="enabled" />
				<ElOption label="停用" value="disabled" />
			</ElSelect>
		</FaFormItem>
		<FaFormItem label="备注" prop="remark" row>
			<ElInput v-model="form.remark" type="textarea" :rows="3" maxlength="120" />
		</FaFormItem>
	</FaForm>
</template>

<script setup lang="ts">
import { reactive } from "vue";

const form = reactive({
	name: "Fast Admin",
	status: "enabled",
	remark: "",
});
</script>

规则校验、重置与 validateScrollToField

查看代码

Vue

<template>
	<FaForm ref="formRef" :model="form" :rules="rules" :cols="2">
		<FaFormItem label="应用名称" prop="name" tips="必填，失焦时校验">
			<ElInput v-model="form.name" placeholder="请输入应用名称" />
		</FaFormItem>
		<FaFormItem label="联系邮箱" prop="email">
			<ElInput v-model="form.email" placeholder="team@example.com" />
		</FaFormItem>
		<FaFormItem row>
			<div class="demo-row">
				<ElButton type="primary" @click="submit">提交并滚动到错误项</ElButton>
				<ElButton @click="formRef?.resetFields?.()">重置</ElButton>
			</div>
		</FaFormItem>
	</FaForm>
</template>

<script setup lang="ts">
import { reactive, useTemplateRef } from "vue";
import { ElMessage } from "element-plus";
import type { FormRules } from "element-plus";

interface FormExpose {
	resetFields?: () => void;
	validateScrollToField: () => Promise<boolean>;
}

const formRef = useTemplateRef<FormExpose>("formRef");
const form = reactive({ name: "", email: "" });
const rules: FormRules = {
	name: [{ required: true, message: "请输入应用名称", trigger: "blur" }],
	email: [
		{ required: true, message: "请输入邮箱", trigger: "blur" },
		{ type: "email", message: "邮箱格式不正确", trigger: "blur" },
	],
};

const submit = async (): Promise<void> => {
	if (await formRef.value?.validateScrollToField()) ElMessage.success("校验通过");
};
</script>

详情表单模式

查看代码

Vue

<template>
	<FaForm :model="detail" detail-form :cols="2">
		<FaFormItem label="项目名称"
			><span>{{ detail.name }}</span></FaFormItem
		>
		<FaFormItem label="当前版本"
			><ElTag>{{ detail.version }}</ElTag></FaFormItem
		>
		<FaFormItem label="开源许可"
			><span>{{ detail.license }}</span></FaFormItem
		>
		<FaFormItem label="项目说明" row
			><span>{{ detail.description }}</span></FaFormItem
		>
	</FaForm>
</template>

<script setup lang="ts">
const detail = {
	name: "Fast.Element.Plus",
	version: "2.0.3",
	license: "Apache-2.0",
	description: "Fast 系列内部业务组件库",
};
</script>

FaForm 完整 API

Props 属性 (19)

Fast 与 Element Plus 2.14.6 的属性已合并展示；Fast 修改项优先排列，未透传的原生属性保留用于兼容性核对。

属性	来源	说明	类型	默认值
labelWidth	Fast 修改	表单标签宽度。	String / Number	FastautoELauto
labelSuffix	Fast 修改	表单标签统一后缀。	String	Fast：EL：
scrollToError	Fast 修改	校验失败时是否滚动到首个错误字段。	Boolean	FasttrueELtrue
detailForm	Fast 新增	是否启用详情表单样式。	Boolean	false
grid	Fast 新增	是否使用 Fast 响应式网格。	Boolean	true
cols	Fast 新增	各响应式断点的列数。	String / Number / Object	{"xs":1,"sm":2,"md":3,"lg":4,"xl":5}
size	EL 原生	组件尺寸。	String	—
disabled	EL 原生	是否禁用组件或当前选项。	Boolean	false
model	EL 原生	表单数据对象。	Object	—
rules	EL 原生	表单校验规则。	Object	—
labelPosition	EL 原生	Position of label. If set to 'left' or 'right', label-width prop is also required.	String	right
requireAsteriskPosition	EL 原生	Position of asterisk.	String	left
inline	EL 原生	Whether the form is inline.	Boolean	false
inlineMessage	EL 原生	Whether to display the error message inline with the form item.	Boolean	false
statusIcon	EL 原生	Whether to display an icon indicating the validation result.	Boolean	false
showMessage	EL 原生	Whether to show the error message.	Boolean	true
validateOnRuleChange	EL 原生	Whether to trigger validation when the rules prop is changed.	Boolean	true
hideRequiredAsterisk	EL 原生	Whether to hide required fields should have a red asterisk (star) beside their labels.	Boolean	false
scrollIntoViewOptions	EL 原生	When validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView.	Object / Boolean	true

Events 事件（1）

名称	来源	说明	参数 / 类型
validate	EL 原生	表单项校验后触发。	—

Slots 插槽（1）

名称	来源	说明	参数 / 类型
default	EL 原生	组件默认内容插槽。	—

Expose 暴露（9）

名称	来源	说明	参数 / 类型
validate	EL 原生	校验整个表单。	—
validateField	EL 原生	校验一个或多个指定字段。	—
resetFields	EL 原生	将整个表单或指定字段重置为初始值并清除校验。	—
clearValidate	EL 原生	清除一个或多个表单字段的校验状态。	—
scrollToField	EL 原生	滚动到指定表单字段。	—
fields	EL 原生	当前注册到表单中的字段上下文集合。	—
getField	EL 原生	按 prop 获取指定表单字段上下文。	—
setInitialValues	EL 原生	批量更新表单字段的初始值。	—
validateScrollToField	Fast 新增	校验表单并滚动到首个错误字段。	—

关联组件：FaFormItem

支持普通布局或 Grid 布局，提供 span、offset、row、标签提示和原生校验插槽。

FaFormItem 完整 API

Props 属性 (17)

Fast 与 Element Plus 2.14.6 的属性已合并展示；Fast 修改项优先排列，未透传的原生属性保留用于兼容性核对。

属性	来源	说明	类型	默认值
tips	Fast 新增	标签提示内容。	String	—
grid	Fast 新增	是否使用 Fast 响应式网格。	Boolean	true
offset	Fast 新增	偏移量或浮层偏移。	String / Number	0
span	Fast 新增	占用的网格列数。	String / Number	—
row	Fast 新增	是否独占一整行。	Boolean	false
label	EL 原生	显示文本或同步标签值。	String	—
labelWidth	EL 原生	表单标签宽度。	String / Number	—
labelPosition	EL 原生	Position of item label. If set to 'left' or 'right', label-width prop is also required. Default extend label-position of form.	String	""
prop	EL 原生	A key of model. It could be a path of the property (e.g a.b.0 or ['a', 'b', '0']). In the use of validate and resetFields method, the attribute is required.	String / Array	—
required	EL 原生	Whether the field is required or not, will be determined by validation rules if omitted.	Boolean	false
rules	EL 原生	Validation rules of form, see the following table, more advanced usage at async-validator.	Object / Array	—
error	EL 原生	Field error message, set its value and the field will validate error and show this message immediately.	String	—
validateStatus	EL 原生	Validation state of formItem.	String	—
for	EL 原生	Same as for in native label.	String	—
inlineMessage	EL 原生	Inline style validate message.	Boolean	false
showMessage	EL 原生	Whether to show the error message.	Boolean	true
size	EL 原生	组件尺寸。	String	—

Events 事件（0）

名称	来源	说明	参数 / 类型
无运行时 Emits 声明。

Slots 插槽（3）

名称	来源	说明	参数 / 类型
default	EL 原生	组件默认内容插槽。	—
label({ label })	EL 原生	自定义表单标签、树节点标签或选择项标签。	{ label: string }
error({ error })	EL 原生	表单校验错误或图片加载失败时的自定义内容。	{ error: string }

Expose 暴露（7）

名称	来源	说明	参数 / 类型
size	EL 原生	按钮解析后的实际尺寸。	—
validateMessage	EL 原生	表单项当前校验提示文本。	—
validateState	EL 原生	表单项当前校验状态。	—
validate	EL 原生	校验整个表单。	—
clearValidate	EL 原生	清除一个或多个表单字段的校验状态。	—
resetField	EL 原生	将表单字段重置为初始值并清除校验。	—
setInitialValue	EL 原生	更新单个表单字段的初始值。	—

关联组件：FaFormItemTip

用于在表单标签旁展示统一的问号提示，tips 支持 HTML 内容，label 可由属性或插槽提供。

FaFormItemTip 完整 API

Props 属性 (2)

属性	来源	说明	类型	默认值
tips	Fast 新增	标签提示内容。	String	—
label	Fast 新增	显示文本或同步标签值。	String	—

Events 事件（0）

名称	来源	说明	参数 / 类型
无运行时 Emits 声明。

Slots 插槽（1）

名称	来源	说明	参数 / 类型
label	Fast 新增	自定义表单标签、树节点标签或选择项标签。	—

Expose 暴露（0）

名称	来源	说明	参数 / 类型
无。

FaForm 实例方法

validate 校验

对整个表单的内容进行验证。 接收一个回调函数，或返回 Promise。

签名

validate(callback?: FormValidateCallback): import("element-plus").FormValidationResult;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
const result = componentRef.value?.validate((valid) => console.log(valid));
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
callback	FormValidateCallback | undefined	否	校验完成后的回调函数。

返回

返回值	返回值类型	返回值说明
result	FormValidationResult	方法调用结果，具体数据与当前组件状态一致。

validateField 校验

验证具体的某个字段。

签名

validateField(props?: import("element-plus/es/utils/typescript.mjs").Arrayable<import("element-plus").FormItemProp>, callback?: FormValidateCallback): import("element-plus").FormValidationResult;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
const result = componentRef.value?.validateField("name", (valid) => console.log(valid));
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
props	Arrayable<FormItemProp> | undefined	否	需要重置或清除校验的表单字段路径。
callback	FormValidateCallback | undefined	否	校验完成后的回调函数。

返回

返回值	返回值类型	返回值说明
result	FormValidationResult	方法调用结果，具体数据与当前组件状态一致。

resetFields 重置

重置该表单项，将其值重置为初始值，并移除校验结果

签名

resetFields(props?: import("element-plus/es/utils/typescript.mjs").Arrayable<import("element-plus").FormItemProp>): void;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
componentRef.value?.resetFields("name");
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
props	Arrayable<FormItemProp> | undefined	否	需要重置或清除校验的表单字段路径。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

clearValidate 校验

清理某个字段的表单验证信息。

签名

clearValidate(props?: import("element-plus/es/utils/typescript.mjs").Arrayable<import("element-plus").FormItemProp>): void;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
componentRef.value?.clearValidate("name");
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
props	Arrayable<FormItemProp> | undefined	否	需要重置或清除校验的表单字段路径。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

scrollToField 滚动

滚动到指定的字段

签名

scrollToField(prop: import("element-plus").FormItemProp): void;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
componentRef.value?.scrollToField("name");
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
prop	FormItemProp	是	表单字段路径或表格排序字段名。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

getField 字段

获取指定字段的 context。

签名

getField(prop: import("element-plus").FormItemProp): import("element-plus").FormItemContext | undefined;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
const result = componentRef.value?.getField("name");
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
prop	FormItemProp	是	表单字段路径或表格排序字段名。

返回

返回值	返回值类型	返回值说明
result	FormItemContext | undefined	方法调用结果，具体数据与当前组件状态一致。

setInitialValues 初值

设置表单字段的初始值。

签名

setInitialValues(initModel: Record<string, any>): void;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
componentRef.value?.setInitialValues({ name: "Fast" });
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
initModel	Record<string, any>	是	作为后续 reset 基准的表单初始数据。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

validateScrollToField 校验

对整个表单的内容进行验证，带滚动。 接收一个回调函数，或返回 Promise。

签名

validateScrollToField(): import("element-plus").FormValidationResult;

示例

<template>
	<FaForm ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaForm } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaForm>>();
const result = componentRef.value?.validateScrollToField();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	FormValidationResult	方法调用结果，具体数据与当前组件状态一致。

FaFormItem 实例方法

validate 校验

验证表单项

签名

validate(trigger: string, callback?: import("element-plus").FormValidateCallback): import("element-plus").FormValidationResult;

示例

<template>
	<FaFormItem ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaFormItem } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaFormItem>>();
const result = componentRef.value?.validate("Fast", (valid) => console.log(valid));
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
trigger	string	是	触发表单项校验的场景名称，例如 blur。
callback	FormValidateCallback | undefined	否	校验完成后的回调函数。

返回

返回值	返回值类型	返回值说明
result	FormValidationResult	方法调用结果，具体数据与当前组件状态一致。

clearValidate 校验

移除该表单项的校验结果

签名

clearValidate(): void;

示例

<template>
	<FaFormItem ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaFormItem } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaFormItem>>();
componentRef.value?.clearValidate();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

resetField 重置

对该表单项进行重置，将其值重置为初始值并移除校验结果

签名

resetField(): void;

示例

<template>
	<FaFormItem ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaFormItem } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaFormItem>>();
componentRef.value?.resetField();
</script>

输入

该方法没有输入参数。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。

setInitialValue 初值

设置该表单项的初始值。

签名

setInitialValue(value: any): void;

示例

<template>
	<FaFormItem ref="componentRef" />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { FaFormItem } from "fast-element-plus";

const componentRef = ref<InstanceType<typeof FaFormItem>>();
componentRef.value?.setInitialValue(1);
</script>

输入

输入值	输入值类型	必填/默认值	输入值说明
value	any	是	要设置的表单值、选择值或过滤关键字。

返回

返回值	返回值类型	返回值说明
result	void	没有返回值。