跳到正文

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

属性来源说明类型默认值
labelWidthFast 全局增强表单标签宽度。String / NumberFastautoEL""
labelSuffixFast 全局增强表单标签统一后缀。StringFast:EL""
scrollToErrorFast 全局增强校验失败时是否滚动到首个错误字段。BooleanFasttrueELfalse
detailFormFast 新增是否启用详情表单样式。Booleanfalse
gridFast 新增是否使用 Fast 响应式网格。Booleantrue
colsFast 新增各响应式断点的列数。String / Number / Object{"xs":1,"sm":2,"md":3,"lg":4,"xl":5}
sizeEL 原生组件尺寸。String—
disabledEL 原生是否禁用组件或当前选项。Booleanfalse
modelEL 原生表单数据对象。Object—
rulesEL 原生表单校验规则。Object—
labelPositionEL 原生标签对齐位置。设为 left 或 right 时需要指定标签宽度。Stringright
requireAsteriskPositionEL 原生必填星号的位置。Stringleft
inlineEL 原生是否在同一行排列表单项。Booleanfalse
inlineMessageEL 原生是否在表单项内联显示校验提示。Booleanfalse
statusIconEL 原生是否显示校验结果图标。Booleanfalse
showMessageEL 原生是否显示校验错误提示。Booleantrue
validateOnRuleChangeEL 原生校验规则变化后是否重新校验。Booleantrue
hideRequiredAsteriskEL 原生是否隐藏必填项标签旁的星号。Booleanfalse
scrollIntoViewOptionsEL 原生滚动到首个校验失败项时传入 scrollIntoView 的选项。Object / Booleantrue

Events 事件

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

Slots 插槽

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

实例成员

名称来源说明参数 / 类型
validateEL 原生校验整个表单。—
validateFieldEL 原生校验一个或多个指定字段。—
resetFieldsEL 原生将整个表单或指定字段重置为初始值并清除校验。—
clearValidateEL 原生清除一个或多个表单字段的校验状态。—
scrollToFieldEL 原生滚动到指定表单字段。—
fieldsEL 原生当前注册到表单中的字段上下文集合。—
getFieldEL 原生按 prop 获取指定表单字段上下文。—
setInitialValuesEL 原生批量更新表单字段的初始值。—
validateScrollToFieldFast 新增校验表单并滚动到首个错误字段。—

关联组件:FaFormItem ​

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

从 2.0.28 起,可以通过 value 直接展示字符串或数字。0 和空字符串按传入值展示,null 和 undefined 回退到默认插槽。自定义 #label 时仍可使用 tips。详情模式加高了标签和内容行,标签按基线对齐,长内容可以换行。

FaFormItem 完整 API

Props 属性

EL 默认值取自导入 Fast 前的 Element Plus。 2.14.7

属性来源说明类型默认值
tipsFast 新增标签提示内容。String—
gridFast 新增是否使用 Fast 响应式网格。Booleantrue
offsetFast 新增偏移量或浮层偏移。String / Number0
spanFast 新增占用的网格列数。String / Number—
rowFast 新增是否独占一整行。Booleanfalse
labelEL 原生显示文本或同步标签值。String—
labelWidthEL 原生表单标签宽度。String / Number—
labelPositionEL 原生此表单项的标签对齐位置。未指定时继承表单配置。String""
propEL 原生表单模型中的字段路径,支持 a.b.0 或路径数组。调用校验或重置方法时需提供。String / Array—
requiredEL 原生是否必填。省略时由校验规则决定。Booleanfalse
rulesEL 原生此字段使用的校验规则。Object / Array—
errorEL 原生指定后立即将该字段标为校验失败,并显示此提示。String—
validateStatusEL 原生此表单项的校验状态。String—
forEL 原生与原生 label 的 for 属性相同,用于关联输入控件。String—
inlineMessageEL 原生是否在当前表单项内联显示校验提示。Booleanfalse
showMessageEL 原生是否显示此字段的校验提示。Booleantrue
sizeEL 原生组件尺寸。String—

Slots 插槽

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

实例成员

名称来源说明参数 / 类型
sizeEL 原生按钮解析后的实际尺寸。—
validateMessageEL 原生表单项当前校验提示文本。—
validateStateEL 原生表单项当前校验状态。—
validateEL 原生校验整个表单。—
clearValidateEL 原生清除一个或多个表单字段的校验状态。—
resetFieldEL 原生将表单字段重置为初始值并清除校验。—
setInitialValueEL 原生更新单个表单字段的初始值。—

关联组件:FaFormItemTip ​

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

FaFormItemTip 完整 API

Props 属性

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

Slots 插槽

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

FaForm 实例方法 ​

以下代码为调用片段。行、选项和字段应对应实际数据。

validate 校验 ​

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

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

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

validateField 校验 ​

验证具体的某个字段。

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

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

resetFields 重置 ​

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

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

clearValidate 校验 ​

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

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

scrollToField 滚动 ​

滚动到指定的字段

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

getField 字段 ​

获取指定字段的 context。

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

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

setInitialValues 初值 ​

设置表单字段的初始值。

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。

validateScrollToField 校验 ​

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

签名 ​

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

示例 ​

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

输入 ​

该方法没有输入参数。

返回 ​

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

FaFormItem 实例方法 ​

以下代码为调用片段。行、选项和字段应对应实际数据。

validate 校验 ​

验证表单项

签名 ​

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

示例 ​

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

输入 ​

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

返回 ​

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

clearValidate 校验 ​

移除该表单项的校验结果

签名 ​

ts
clearValidate(): void;

示例 ​

vue
<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 重置 ​

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

签名 ​

ts
resetField(): void;

示例 ​

vue
<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 初值 ​

设置该表单项的初始值。

签名 ​

ts
setInitialValue(value: any): void;

示例 ​

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

输入 ​

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

返回 ​

返回值返回值类型返回值说明
resultvoid没有返回值。