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 exampleView code
<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 exampleView code
<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 exampleView code
<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
| Property | Source | Description | Type | Default |
|---|---|---|---|---|
labelWidth | Fast global enhancement | Form-label width. | String / Number | FastautoEL"" |
labelSuffix | Fast global enhancement | Shared form-label suffix. | String | Fast:EL"" |
scrollToError | Fast global enhancement | Scroll to the first invalid field. | Boolean | FasttrueELfalse |
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
| Name | Source | Description | Parameters / type |
|---|---|---|---|
validate | EL native | Form item validation completes. | — |
Slots
| Name | Source | Description | Parameters / type |
|---|---|---|---|
default | EL native | Default component content. | — |
Exposes
| 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.
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
| 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 | — |
Slots
| Name | Source | Description | Parameters / type |
|---|---|---|---|
default | EL native | Default component content. | — |
label({ label }) | EL native | Custom form, tree-node, or option label. | ({ label }) |
error({ error }) | EL native | Custom validation-error or image-load-error content. | ({ error }) |
Exposes
| 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
| Property | Source | Description | Type | Default |
|---|---|---|---|---|
tips | Fast addition | Tag tooltip content. | String | — |
label | Fast addition | Display text or synchronized label. | String | — |
Slots
| Name | Source | Description | Parameters / type |
|---|---|---|---|
label | Fast addition | Custom 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
validate(callback?: FormValidateCallback): import("element-plus").FormValidationResult;Example
<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
| 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" />
<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
| 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" />
<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
| 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" />
<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
| 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" />
<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
| 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" />
<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
| 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" />
<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
| 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" />
<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
| Value | Type | Description |
|---|---|---|
result | FormValidationResult | Method 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
validate(trigger: string, callback?: import("element-plus").FormValidateCallback): import("element-plus").FormValidationResult;Example
<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
| 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" />
<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
resetField(): void;Example
<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
setInitialValue(value: any): void;Example
<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
| 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. |
