FaForm

Adds a responsive grid, detail mode, label conventions and scroll-to-field validation to ElForm.

validate() without a callback and validateScrollToField() resolve with true on success. Since 2.0.16, invalid input rejects with Element Plus invalidFields; handle that rejection with catch rather than expecting a resolved false. An unmounted instance still rejects with Error. validate(callback) retains native Element Plus callback behavior.

Basic

View code

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>

Validation

View code

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>

Detail Form

View code

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 Complete API

Props (19)

Fast and Element Plus 2.14.6 props are merged below. Fast changes appear first; native props that are not forwarded remain visible for compatibility review.

Property	Source	Description	Type	Default
labelWidth	Fast override	Form-label width.	String / Number	FastautoELauto
labelSuffix	Fast override	Shared form-label suffix.	String	Fast：EL：
scrollToError	Fast override	Scroll to the first invalid field.	Boolean	FasttrueELtrue
detailForm	Fast addition	Enable detail-form styling.	Boolean	false
grid	Fast addition	Use the Fast responsive grid.	Boolean	true
cols	Fast addition	Column counts at responsive breakpoints.	String / Number / Object	{"xs":1,"sm":2,"md":3,"lg":4,"xl":5}
size	EL native	Component size.	String	—
disabled	EL native	Disable the component or current option.	Boolean	false
model	EL native	Form model object.	Object	—
rules	EL native	Form validation rules.	Object	—
labelPosition	EL native	Position of label. If set to 'left' or 'right', label-width prop is also required.	String	right
requireAsteriskPosition	EL native	Position of asterisk.	String	left
inline	EL native	Whether the form is inline.	Boolean	false
inlineMessage	EL native	Whether to display the error message inline with the form item.	Boolean	false
statusIcon	EL native	Whether to display an icon indicating the validation result.	Boolean	false
showMessage	EL native	Whether to show the error message.	Boolean	true
validateOnRuleChange	EL native	Whether to trigger validation when the rules prop is changed.	Boolean	true
hideRequiredAsterisk	EL native	Whether to hide required fields should have a red asterisk (star) beside their labels.	Boolean	false
scrollIntoViewOptions	EL native	When validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView.	Object / Boolean	true

Events（1）

Name	Source	Description	Parameters / type
validate	EL native	Form item validation completes.	—

Slots（1）

Name	Source	Description	Parameters / type
default	EL native	Default component content.	—

Expose（9）

Name	Source	Description	Parameters / type
validate	EL native	Validates the entire form.	—
validateField	EL native	Validates one or more fields.	—
resetFields	EL native	Resets all or selected form fields and clears validation.	—
clearValidate	EL native	Clears validation for one or more form fields.	—
scrollToField	EL native	Scrolls to a form field.	—
fields	EL native	Field contexts currently registered with the form.	—
getField	EL native	Gets a form field context by prop.	—
setInitialValues	EL native	Updates initial values for multiple fields.	—
validateScrollToField	Fast addition	Validates and scrolls to the first invalid field.	—

Related component: FaFormItem

Supports ordinary and grid layouts with span, offset, row, label tips and native validation slots.

FaFormItem Complete API

Props (17)

Fast and Element Plus 2.14.6 props are merged below. Fast changes appear first; native props that are not forwarded remain visible for compatibility review.

Property	Source	Description	Type	Default
tips	Fast addition	Tag tooltip content.	String	—
grid	Fast addition	Use the Fast responsive grid.	Boolean	true
offset	Fast addition	Offset or overlay offset.	String / Number	0
span	Fast addition	Grid columns occupied.	String / Number	—
row	Fast addition	Occupy a full row.	Boolean	false
label	EL native	Display text or synchronized label.	String	—
labelWidth	EL native	Form-label width.	String / Number	—
labelPosition	EL native	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 native	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 native	Whether the field is required or not, will be determined by validation rules if omitted.	Boolean	false
rules	EL native	Validation rules of form, see the following table, more advanced usage at async-validator.	Object / Array	—
error	EL native	Field error message, set its value and the field will validate error and show this message immediately.	String	—
validateStatus	EL native	Validation state of formItem.	String	—
for	EL native	Same as for in native label.	String	—
inlineMessage	EL native	Inline style validate message.	Boolean	false
showMessage	EL native	Whether to show the error message.	Boolean	true
size	EL native	Component size.	String	—

Events（0）

Name	Source	Description	Parameters / type
No runtime Emits declarations.

Slots（3）

Name	Source	Description	Parameters / type
default	EL native	Default component content.	—
label({ label })	EL native	Custom form, tree-node, or option label.	{ label: string }
error({ error })	EL native	Custom validation-error or image-load-error content.	{ error: string }

Expose（7）

Name	Source	Description	Parameters / type
size	EL native	Resolved button size.	—
validateMessage	EL native	Current form-item validation message.	—
validateState	EL native	Current form-item validation state.	—
validate	EL native	Validates the entire form.	—
clearValidate	EL native	Clears validation for one or more form fields.	—
resetField	EL native	Resets a form field and clears validation.	—
setInitialValue	EL native	Updates one form field's initial value.	—

Related component: FaFormItemTip

Displays a question-mark tip next to a form label. tips supports HTML; label can be provided by a prop or slot.

FaFormItemTip Complete API

Props (2)

Property	Source	Description	Type	Default
tips	Fast addition	Tag tooltip content.	String	—
label	Fast addition	Display text or synchronized label.	String	—

Events（0）

Name	Source	Description	Parameters / type
No runtime Emits declarations.

Slots（1）

Name	Source	Description	Parameters / type
label	Fast addition	Custom form, tree-node, or option label.	—

Expose（0）

Name	Source	Description	Parameters / type
None.

FaForm instance methods

validate Validate

Validates the entire form through a callback or returned Promise.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
callback	FormValidateCallback | undefined	Optional	Callback after validation.

Returns

Value	Type	Description
result	FormValidationResult	Method result consistent with the current component state.

validateField Validate

Validates a specific field.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
props	Arrayable<FormItemProp> | undefined	Optional	Form field paths to reset or clear.
callback	FormValidateCallback | undefined	Optional	Callback after validation.

Returns

Value	Type	Description
result	FormValidationResult	Method result consistent with the current component state.

resetFields Reset

Resets form fields to initial values and removes validation results.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
props	Arrayable<FormItemProp> | undefined	Optional	Form field paths to reset or clear.

Returns

Value	Type	Description
result	void	No return value.

clearValidate Validate

Clears a field's validation state.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
props	Arrayable<FormItemProp> | undefined	Optional	Form field paths to reset or clear.

Returns

Value	Type	Description
result	void	No return value.

scrollToField Scroll

Scrolls to the specified field.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
prop	FormItemProp	Required	Form field path or table sort property.

Returns

Value	Type	Description
result	void	No return value.

getField Field

Gets the context for a field.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
prop	FormItemProp	Required	Form field path or table sort property.

Returns

Value	Type	Description
result	FormItemContext | undefined	Method result consistent with the current component state.

setInitialValues Initial

Sets initial form values.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
initModel	Record<string, any>	Required	Initial form data used by subsequent resets.

Returns

Value	Type	Description
result	void	No return value.

validateScrollToField Validate

Validates the entire form with scrolling, using a callback or Promise.

Signature

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

Example

<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>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	FormValidationResult	Method result consistent with the current component state.

FaFormItem instance methods

validate Validate

Validates the form item.

Signature

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

Example

<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>

Input

Input	Type	Required / default	Description
trigger	string	Required	Validation trigger name, such as blur.
callback	FormValidateCallback | undefined	Optional	Callback after validation.

Returns

Value	Type	Description
result	FormValidationResult	Method result consistent with the current component state.

clearValidate Validate

Clears this form item's validation result.

Signature

clearValidate(): void;

Example

<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>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

resetField Reset

Resets this form item to its initial value and clears validation.

Signature

resetField(): void;

Example

<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>

Input

This method has no input parameters.

Returns

Value	Type	Description
result	void	No return value.

setInitialValue Initial

Sets this form item's initial value.

Signature

setInitialValue(value: any): void;

Example

<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>

Input

Input	Type	Required / default	Description
value	any	Required	Form value, selected value, or filter keyword to set.

Returns

Value	Type	Description
result	void	No return value.