Skip to content

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

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

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

Interactive example
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">
import { version } from "fast-element-plus";

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

FaForm Complete API

Props

EL defaults refer to Element Plus before Fast is imported. 2.14.7

PropertySourceDescriptionTypeDefault
labelWidthFast global enhancementForm-label width.String / NumberFastautoEL""
labelSuffixFast global enhancementShared form-label suffix.StringFast:EL""
scrollToErrorFast global enhancementScroll to the first invalid field.BooleanFasttrueELfalse
detailFormFast additionEnable detail-form styling.Booleanfalse
gridFast additionUse the Fast responsive grid.Booleantrue
colsFast additionColumn counts at responsive breakpoints.String / Number / Object{"xs":1,"sm":2,"md":3,"lg":4,"xl":5}
sizeEL nativeComponent size.String—
disabledEL nativeDisable the component or current option.Booleanfalse
modelEL nativeForm model object.Object—
rulesEL nativeForm validation rules.Object—
labelPositionEL nativePosition of label. If set to 'left' or 'right', label-width prop is also required.Stringright
requireAsteriskPositionEL nativePosition of asterisk.Stringleft
inlineEL nativeWhether the form is inline.Booleanfalse
inlineMessageEL nativeWhether to display the error message inline with the form item.Booleanfalse
statusIconEL nativeWhether to display an icon indicating the validation result.Booleanfalse
showMessageEL nativeWhether to show the error message.Booleantrue
validateOnRuleChangeEL nativeWhether to trigger validation when the rules prop is changed.Booleantrue
hideRequiredAsteriskEL nativeWhether to hide required fields should have a red asterisk (star) beside their labels.Booleanfalse
scrollIntoViewOptionsEL nativeWhen validation fails, it scrolls to the first error item based on the scrollIntoView option. scrollIntoView.Object / Booleantrue

Events

NameSourceDescriptionParameters / type
validateEL nativeForm item validation completes.—

Slots

NameSourceDescriptionParameters / type
defaultEL nativeDefault component content.—

Exposes

NameSourceDescriptionParameters / type
validateEL nativeValidates the entire form.—
validateFieldEL nativeValidates one or more fields.—
resetFieldsEL nativeResets all or selected form fields and clears validation.—
clearValidateEL nativeClears validation for one or more form fields.—
scrollToFieldEL nativeScrolls to a form field.—
fieldsEL nativeField contexts currently registered with the form.—
getFieldEL nativeGets a form field context by prop.—
setInitialValuesEL nativeUpdates initial values for multiple fields.—
validateScrollToFieldFast additionValidates and scrolls to the first invalid field.—

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

Since 2.0.28, value displays a string or number directly. Both 0 and an empty string are valid display values. null and undefined fall back to the default slot. tips also works with a custom #label. Detail mode uses taller lines and baseline alignment, and long content can wrap.

FaFormItem Complete API

Props

EL defaults refer to Element Plus before Fast is imported. 2.14.7

PropertySourceDescriptionTypeDefault
tipsFast additionTag tooltip content.String—
gridFast additionUse the Fast responsive grid.Booleantrue
offsetFast additionOffset or overlay offset.String / Number0
spanFast additionGrid columns occupied.String / Number—
rowFast additionOccupy a full row.Booleanfalse
labelEL nativeDisplay text or synchronized label.String—
labelWidthEL nativeForm-label width.String / Number—
labelPositionEL nativePosition of item label. If set to 'left' or 'right', label-width prop is also required. Default extend label-position of form.String""
propEL nativeA 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—
requiredEL nativeWhether the field is required or not, will be determined by validation rules if omitted.Booleanfalse
rulesEL nativeValidation rules of form, see the following table, more advanced usage at async-validator.Object / Array—
errorEL nativeField error message, set its value and the field will validate error and show this message immediately.String—
validateStatusEL nativeValidation state of formItem.String—
forEL nativeSame as for in native label.String—
inlineMessageEL nativeInline style validate message.Booleanfalse
showMessageEL nativeWhether to show the error message.Booleantrue
sizeEL nativeComponent size.String—

Slots

NameSourceDescriptionParameters / type
defaultEL nativeDefault component content.—
label({ label })EL nativeCustom form, tree-node, or option label.({ label })
error({ error })EL nativeCustom validation-error or image-load-error content.({ error })

Exposes

NameSourceDescriptionParameters / type
sizeEL nativeResolved button size.—
validateMessageEL nativeCurrent form-item validation message.—
validateStateEL nativeCurrent form-item validation state.—
validateEL nativeValidates the entire form.—
clearValidateEL nativeClears validation for one or more form fields.—
resetFieldEL nativeResets a form field and clears validation.—
setInitialValueEL nativeUpdates one form field's initial value.—

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

PropertySourceDescriptionTypeDefault
tipsFast additionTag tooltip content.String—
labelFast additionDisplay text or synchronized label.String—

Slots

NameSourceDescriptionParameters / type
labelFast additionCustom form, tree-node, or option label.—

FaForm instance methods ​

These are call snippets. Use rows, options and fields from your actual data.

validate Validate ​

Validates the entire form through a callback or returned Promise.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
callbackFormValidateCallback | undefinedOptionalCallback after validation.

Returns ​

ValueTypeDescription
resultFormValidationResultMethod result consistent with the current component state.

validateField Validate ​

Validates a specific field.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
propsArrayable<FormItemProp> | undefinedOptionalForm field paths to reset or clear.
callbackFormValidateCallback | undefinedOptionalCallback after validation.

Returns ​

ValueTypeDescription
resultFormValidationResultMethod result consistent with the current component state.

resetFields Reset ​

Resets form fields to initial values and removes validation results.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
propsArrayable<FormItemProp> | undefinedOptionalForm field paths to reset or clear.

Returns ​

ValueTypeDescription
resultvoidNo return value.

clearValidate Validate ​

Clears a field's validation state.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
propsArrayable<FormItemProp> | undefinedOptionalForm field paths to reset or clear.

Returns ​

ValueTypeDescription
resultvoidNo return value.

scrollToField Scroll ​

Scrolls to the specified field.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
propFormItemPropRequiredForm field path or table sort property.

Returns ​

ValueTypeDescription
resultvoidNo return value.

getField Field ​

Gets the context for a field.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaForm>>();
function handleExample() {
	const result = componentRef.value?.getField("name");
	console.log(result);
}
</script>

Input ​

InputTypeRequired / defaultDescription
propFormItemPropRequiredForm field path or table sort property.

Returns ​

ValueTypeDescription
resultFormItemContext | undefinedMethod result consistent with the current component state.

setInitialValues Initial ​

Sets initial form values.

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
initModelRecord<string, any>RequiredInitial form data used by subsequent resets.

Returns ​

ValueTypeDescription
resultvoidNo return value.

validateScrollToField Validate ​

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

Signature ​

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

Example ​

vue
<template>
	<FaForm ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

const componentRef = ref<InstanceType<typeof FaForm>>();
function handleExample() {
	const result = componentRef.value?.validateScrollToField();
	console.log(result);
}
</script>

Input ​

This method has no input parameters.

Returns ​

ValueTypeDescription
resultFormValidationResultMethod result consistent with the current component state.

FaFormItem instance methods ​

These are call snippets. Use rows, options and fields from your actual data.

validate Validate ​

Validates the form item.

Signature ​

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

Example ​

vue
<template>
	<FaFormItem ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
triggerstringRequiredValidation trigger name, such as blur.
callbackFormValidateCallback | undefinedOptionalCallback after validation.

Returns ​

ValueTypeDescription
resultFormValidationResultMethod result consistent with the current component state.

clearValidate Validate ​

Clears this form item's validation result.

Signature ​

ts
clearValidate(): void;

Example ​

vue
<template>
	<FaFormItem ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

resetField Reset ​

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

Signature ​

ts
resetField(): void;

Example ​

vue
<template>
	<FaFormItem ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input: No parameters.

Returns: void.

setInitialValue Initial ​

Sets this form item's initial value.

Signature ​

ts
setInitialValue(value: any): void;

Example ​

vue
<template>
	<FaFormItem ref="componentRef" />
	<button type="button" @click="handleExample">Call method</button>
</template>

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

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

Input ​

InputTypeRequired / defaultDescription
valueanyRequiredForm value, selected value, or filter keyword to set.

Returns ​

ValueTypeDescription
resultvoidNo return value.