FaForm 表单
在 ElForm 上增加响应式 Grid、详情模式、团队标签格式和滚动校验方法。
validate()(不传回调)与 validateScrollToField() 校验成功时 Promise 以 true 完成;从 2.0.16 起,校验失败时以 Element Plus 的 invalidFields 详情拒绝,需通过 catch 处理,并非返回一个成功完成的 false。实例尚未挂载时仍以 Error 拒绝。validate(callback) 保持 Element Plus 原生回调行为。
响应式表单布局与字段提示
可操作示例查看代码
<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
可操作示例查看代码
<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>详情表单模式
可操作示例查看代码
<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 完整 API
Props 属性
EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
labelWidth | Fast 全局增强 | 表单标签宽度。 | String / Number | FastautoEL"" |
labelSuffix | Fast 全局增强 | 表单标签统一后缀。 | String | Fast:EL"" |
scrollToError | Fast 全局增强 | 校验失败时是否滚动到首个错误字段。 | Boolean | FasttrueELfalse |
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 原生 | 标签对齐位置。设为 left 或 right 时需要指定标签宽度。 | String | right |
requireAsteriskPosition | EL 原生 | 必填星号的位置。 | String | left |
inline | EL 原生 | 是否在同一行排列表单项。 | Boolean | false |
inlineMessage | EL 原生 | 是否在表单项内联显示校验提示。 | Boolean | false |
statusIcon | EL 原生 | 是否显示校验结果图标。 | Boolean | false |
showMessage | EL 原生 | 是否显示校验错误提示。 | Boolean | true |
validateOnRuleChange | EL 原生 | 校验规则变化后是否重新校验。 | Boolean | true |
hideRequiredAsterisk | EL 原生 | 是否隐藏必填项标签旁的星号。 | Boolean | false |
scrollIntoViewOptions | EL 原生 | 滚动到首个校验失败项时传入 scrollIntoView 的选项。 | Object / Boolean | true |
Events 事件
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
validate | EL 原生 | 表单项校验后触发。 | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default | EL 原生 | 组件默认内容插槽。 | — |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
validate | EL 原生 | 校验整个表单。 | — |
validateField | EL 原生 | 校验一个或多个指定字段。 | — |
resetFields | EL 原生 | 将整个表单或指定字段重置为初始值并清除校验。 | — |
clearValidate | EL 原生 | 清除一个或多个表单字段的校验状态。 | — |
scrollToField | EL 原生 | 滚动到指定表单字段。 | — |
fields | EL 原生 | 当前注册到表单中的字段上下文集合。 | — |
getField | EL 原生 | 按 prop 获取指定表单字段上下文。 | — |
setInitialValues | EL 原生 | 批量更新表单字段的初始值。 | — |
validateScrollToField | Fast 新增 | 校验表单并滚动到首个错误字段。 | — |
关联组件:FaFormItem
支持普通布局或 Grid 布局,提供 span、offset、row、标签提示和原生校验插槽。
从 2.0.28 起,可以通过 value 直接展示字符串或数字。0 和空字符串按传入值展示,null 和 undefined 回退到默认插槽。自定义 #label 时仍可使用 tips。详情模式加高了标签和内容行,标签按基线对齐,长内容可以换行。
FaFormItem 完整 API
Props 属性
EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
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 原生 | 此表单项的标签对齐位置。未指定时继承表单配置。 | String | "" |
prop | EL 原生 | 表单模型中的字段路径,支持 a.b.0 或路径数组。调用校验或重置方法时需提供。 | String / Array | — |
required | EL 原生 | 是否必填。省略时由校验规则决定。 | Boolean | false |
rules | EL 原生 | 此字段使用的校验规则。 | Object / Array | — |
error | EL 原生 | 指定后立即将该字段标为校验失败,并显示此提示。 | String | — |
validateStatus | EL 原生 | 此表单项的校验状态。 | String | — |
for | EL 原生 | 与原生 label 的 for 属性相同,用于关联输入控件。 | String | — |
inlineMessage | EL 原生 | 是否在当前表单项内联显示校验提示。 | Boolean | false |
showMessage | EL 原生 | 是否显示此字段的校验提示。 | Boolean | true |
size | EL 原生 | 组件尺寸。 | String | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
default | EL 原生 | 组件默认内容插槽。 | — |
label({ label }) | EL 原生 | 自定义表单标签、树节点标签或选择项标签。 | ({ label }) |
error({ error }) | EL 原生 | 表单校验错误或图片加载失败时的自定义内容。 | ({ error }) |
实例成员
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
size | EL 原生 | 按钮解析后的实际尺寸。 | — |
validateMessage | EL 原生 | 表单项当前校验提示文本。 | — |
validateState | EL 原生 | 表单项当前校验状态。 | — |
validate | EL 原生 | 校验整个表单。 | — |
clearValidate | EL 原生 | 清除一个或多个表单字段的校验状态。 | — |
resetField | EL 原生 | 将表单字段重置为初始值并清除校验。 | — |
setInitialValue | EL 原生 | 更新单个表单字段的初始值。 | — |
关联组件:FaFormItemTip
用于在表单标签旁展示统一的问号提示,tips 支持 HTML 内容,label 可由属性或插槽提供。
FaFormItemTip 完整 API
Props 属性
| 属性 | 来源 | 说明 | 类型 | 默认值 |
|---|---|---|---|---|
tips | Fast 新增 | 标签提示内容。 | String | — |
label | Fast 新增 | 显示文本或同步标签值。 | String | — |
Slots 插槽
| 名称 | 来源 | 说明 | 参数 / 类型 |
|---|---|---|---|
label | Fast 新增 | 自定义表单标签、树节点标签或选择项标签。 | — |
FaForm 实例方法
以下代码为调用片段。行、选项和字段应对应实际数据。
validate 校验
对整个表单的内容进行验证。 接收一个回调函数,或返回 Promise。
签名
validate(callback?: FormValidateCallback): import("element-plus").FormValidationResult;示例
<template>
<FaForm ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
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" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
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" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
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" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
props | Arrayable<FormItemProp> | undefined | 否 | 需要重置或清除校验的表单字段路径。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
scrollToField 滚动
滚动到指定的字段
签名
scrollToField(prop: import("element-plus").FormItemProp): void;示例
<template>
<FaForm ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
prop | FormItemProp | 是 | 表单字段路径或表格排序字段名。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
getField 字段
获取指定字段的 context。
签名
getField(prop: import("element-plus").FormItemProp): import("element-plus").FormItemContext | undefined;示例
<template>
<FaForm ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
prop | FormItemProp | 是 | 表单字段路径或表格排序字段名。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FormItemContext | undefined | 方法调用结果,具体数据与当前组件状态一致。 |
setInitialValues 初值
设置表单字段的初始值。
签名
setInitialValues(initModel: Record<string, any>): void;示例
<template>
<FaForm ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
initModel | Record<string, any> | 是 | 作为后续 reset 基准的表单初始数据。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
validateScrollToField 校验
对整个表单的内容进行验证,带滚动。 接收一个回调函数,或返回 Promise。
签名
validateScrollToField(): import("element-plus").FormValidationResult;示例
<template>
<FaForm ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FormValidationResult | 方法调用结果,具体数据与当前组件状态一致。 |
FaFormItem 实例方法
以下代码为调用片段。行、选项和字段应对应实际数据。
validate 校验
验证表单项
签名
validate(trigger: string, callback?: import("element-plus").FormValidateCallback): import("element-plus").FormValidationResult;示例
<template>
<FaFormItem ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
trigger | string | 是 | 触发表单项校验的场景名称,例如 blur。 |
callback | FormValidateCallback | undefined | 否 | 校验完成后的回调函数。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FormValidationResult | 方法调用结果,具体数据与当前组件状态一致。 |
clearValidate 校验
移除该表单项的校验结果
签名
clearValidate(): void;示例
<template>
<FaFormItem ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入: 无参数。
返回: void。
resetField 重置
对该表单项进行重置,将其值重置为初始值并移除校验结果
签名
resetField(): void;示例
<template>
<FaFormItem ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入: 无参数。
返回: void。
setInitialValue 初值
设置该表单项的初始值。
签名
setInitialValue(value: any): void;示例
<template>
<FaFormItem ref="componentRef" />
<button type="button" @click="handleExample">调用方法</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>输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
value | any | 是 | 要设置的表单值、选择值或过滤关键字。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | void | 没有返回值。 |
