API 概览

FormCreate 提供了丰富的 API 接口，允许开发者在表单的各个阶段进行全面控制，包括表单的生成、动态更新、验证和数据处理等功能。这些 API 可以帮助您轻松实现各种复杂的表单需求。

获取API

FormCreate 提供了多种方式获取 api 对象，以便开发者可以在不同的场景中操作和管理表单。

全局方法

通过 create 方法可以直接生成表单并获取 api 对象。这种方法适用于在非组件的场景中使用，如在单独的脚本文件中生成表单。

const api = formCreate.create(rules)

组件模式

在 Vue 组件中，通过 v-model:api 绑定 api 对象，以便在组件内部操作表单。

<form-create name="form" :rule="rules" v-model:api="api"></form-create>

示例： 在 Vue 组件中使用 api 进行表单的动态操作：

<template>
  <form-create name="form" :rule="rules" v-model:api="api"></form-create>
</template>


<script setup>
const rules = ref([
  { type: 'input', field: 'username', title: '用户名', props: { placeholder: '请输入用户名' } },
  { type: 'input', field: 'email', title: '邮箱', props: { placeholder: '请输入邮箱' } },
  { type: 'input', field: 'password', title: '密码', props: { type: 'password', placeholder: '请输入密码' } },
]);
const api = ref(null);
onMounted(() => {
  // 使用 api 进行操作
  api.value.setValue('username', 'example_user');
});
</script>

此外，您还可以使用 getApi 方法在任何位置获取 api 对象，例如在其他组件中：

const api = formCreate.getApi('form')

事件注入

在表单事件的处理函数中，api 对象可以通过事件参数自动注入。这种方式特别适用于处理与表单交互相关的事件。

type InjectArg = {
    api: API,// 表单 API 对象
    rule: Rule[],// 表单生成规则
    self: Rule,// 当前组件生成规则
    option: Object,// 表单全局配置
    inject: Any,// 自定义注入的参数
    args: any[],// 原始回调参数
}

示例： 在表单组件的 blur 事件中获取 api 对象并进行操作：

const rule = {
  type: 'input',
  field: 'inputField',
  title: '输入框',
  inject: true,
  on: {
    blur(inject) {
      console.log(inject.api);  // 获取 API 对象
      inject.api.setValue('inputField', 'blurred');
    }
  }
}

自定义组件注入

FormCreate 在生成自定义组件时，会自动向组件注入一些有用的参数。通过 props.formCreateInject 可以获取。

• formCreateInject 对象包含以下属性：
  • formCreateInject.api 表单 API 对象，用于操作表单。
  • formCreateInject.options 表单组件的全局配置。
  • formCreateInject.rule 生成规则对象，定义了组件的所有配置。
  • formCreateInject.field 字段名称，与表单数据绑定。

示例： 在自定义组件中使用 formCreateInject 对象进行操作：

const customComponent = defineComponent({
  name: 'custom-component',
  props: {
    formCreateInject: Object, // 自动注入的表单参数
  },
  mounted() {
    console.log(this.formCreateInject.api);  // 在组件内部访问 API
  }
});

注意

父表单与子表单、子表单之间相互独立，操作时需要调用各自表单对应的 API。通过 getSubForm 方法可获取指定子表单的操作接口。

API 功能说明

Api 属性

属性名	类型	说明
config	Options	表单的全局配置对象
index	number｜undefined	当前表单在子表单中的索引
siblings	Api[]｜undefined	同级表单的API数组
rule	Rule[]	当前表单的生成规则列表
form	Object	当前表单的数据对象
parent	Api｜undefined	父级表单的Api对象
top	Api｜undefined	最顶层表单的Api对象
children	Api[]	子表单的Api对象数组

Api 方法

按钮控制方法

方法名	参数	返回值	说明
btn.loading	loading: boolean	void	设置提交按钮加载状态
btn.disabled	disabled: boolean	void	设置提交按钮禁用状态
btn.show	show: boolean	void	设置提交按钮显示状态
resetBtn.loading	loading: boolean	void	设置重置按钮加载状态
resetBtn.disabled	disabled: boolean	void	设置重置按钮禁用状态
resetBtn.show	show: boolean	void	设置重置按钮显示状态
submitBtnProps	props: ButtonProps	void	更新提交按钮配置
resetBtnProps	props: ButtonProps	void	更新重置按钮配置

元素操作方法

方法名	参数	返回值	说明
el	id: string	any	获取指定组件的DOM元素或Vue实例
formEl	-	ComponentInternalInstance｜undefined	获取整个表单的Vue组件实例
wrapEl	id: string	ComponentInternalInstance｜undefined	获取指定表单项的Vue组件实例

数据操作方法

方法名	参数	返回值	说明
formData	-	Object	获取当前表单数据对象
formData	field: string[]	Object	获取特定字段的数据
getValue	field: string	any	获取指定字段的值
coverValue	formData: Object	void	用新数据覆盖表单当前值
setValue	formData: Object	void	设置整个表单的值
setValue	field: string, value: any	void	设置特定字段的值

表单结构操作方法

方法名	参数	返回值	说明
removeField	field: string	Rule	根据字段名删除组件
removeRule	rule: Rule	Rule	根据规则删除组件
fields	-	string[]	获取所有字段名称
append	rule: Rule	void	追加新组件
append	rule: Rule, field: string	void	在指定字段后追加组件
append	rule: Rule, field: string, child: boolean	void	在指定字段后追加子组件
prepend	rule: Rule	void	在开头插入新组件
prepend	rule: Rule, field: string	void	在指定字段前插入组件
prepend	rule: Rule, field: string, child: boolean	void	在指定字段前插入子组件

显示控制方法

方法名	参数	返回值	说明
hidden	hidden: Boolean	void	隐藏/显示表单组件(无DOM)
hidden	hidden: Boolean, field: string｜Array<string>	void	隐藏/显示指定组件
display	hidden: Boolean	void	控制组件显示与否(有DOM)
display	hidden: Boolean, field: string｜Array<string>	void	控制指定组件显示
hiddenStatus	field: String	Boolean	获取组件隐藏状态
displayStatus	field: String	Boolean	获取组件显示状态
disabled	disabled: Boolean	void	禁用/启用表单组件
disabled	disabled: Boolean, field: string｜Array<string>	void	禁用/启用指定组件

规则操作方法

方法名	参数	返回值	说明
model	-	{ [field: string]: Rule }	获取表单组件生成规则
component	-	{ [name: string]: Rule }	获取所有定义name属性的组件规则
reload	rules: Rule[]	void	重新加载表单规则
updateOptions	options: Options	void	更新表单全局配置
updateRule	field: string, rule: Rule	void	更新指定字段规则
updateRule	rules: { [field: string]: Rule }	void	批量更新字段规则
mergeRule	field: string, rule: Rule	void	合并指定字段规则
mergeRules	rules: { [field: string]: Rule }	void	批量合并字段规则
getRule	id: string	Rule	获取指定字段规则
getRule	id: string, origin: true	Rule	获取原始规则
getRule	id: string, origin: false	Rule	获取处理后的规则
findType	type: string	Rule	通过组件类型获取规则
findTypes	type: string	Rule[]	通过组件类型获取多个规则
getCurrentFormRule	-	Rule	获取当前子表单规则
getRenderRule	id: string	Rule	获取组件最终渲染规则
getRefRule	id: string	Rule｜Rule[]	通过name属性获取规则
getParentRule	id: string｜Rule	Rule｜undefined	获取父级规则

验证相关方法

方法名	参数	返回值	说明
updateValidate	id: string, validate: Object[], merge?: Boolean	Promise<any>	更新组件验证规则
updateValidates	validates: { [id: string]: Object[] }, merge?: Boolean	Promise<any>	批量更新验证规则
refreshValidate	-	void	刷新表单验证状态
clearValidateState	fields?: string｜string[], clearSub?: Boolean	void	清理验证状态
clearSubValidateState	fields?: string｜string[]	void	清理子表单验证状态
validate	callback?: (state: any) => void	Promise<any>	验证整个表单
validateField	field: string, callback?: (state: any) => void	Promise<any>	验证指定字段

组件操作方法

方法名	参数	返回值	说明
method	id: string, name: string	(...args: any[]) => any	获取组件方法
exec	id: string, name: string, ...args: any[]	any	执行组件方法
trigger	id: string, event: string, ...args: any[]	void	触发组件事件

表单操作方法

方法名	参数	返回值	说明
onSubmit	fn: (formData: Object, api: Api) => void	void	监听表单提交事件
submit	success?: (formData: Object, api: Api) => void, fail?: (api: Api) => void	Promise<any>	手动提交表单
sync	field: string｜string[]	void	同步指定字段
sync	rule: Rule｜Rule[]	void	同步指定规则
refresh	-	void	重新渲染整个表单
refreshOptions	-	void	刷新表单选项
hideForm	hide?: Boolean	void	隐藏整个表单
changeStatus	-	Boolean	获取表单修改状态
clearChangeStatus	-	void	重置表单修改状态
toJson	space?: string｜number	string	获取表单JSON规则
closeModal	id: string	void	关闭frame组件弹出框
resetFields	-	void	重置整个表单
resetFields	field: string｜string[]	void	重置指定字段
getSubForm	field: string	Api｜Api[]	获取子表单Api对象

异步操作方法

方法名	参数	返回值	说明
nextTick	fn: (api: Api) => void	void	表单渲染后执行回调
nextRefresh	fn: Function	void	回调后重新渲染表单
deferSyncValue	fn: Function, autoSync?: boolean	void	回调后同步表单数据

数据管理方法

方法名	参数	返回值	说明
fetch	opt: FetchOption	Promise<any>	发送远程请求
setData	id: string, value?: any	void	设置外部数据
getData	id: string, defaultValue?: any	any	获取外部数据
watchData	fn: (get: (id: string, defaultValue?: any) => any, change: boolean) => void	() => Function	监听数据变化
refreshData	id: string	void	刷新外部数据相关组件

事件管理方法

方法名	参数	返回值	说明
bus.$emit	event: string, ...args: any[]	void	手动触发事件
bus.$on	event: string｜string[], callback: Function	void	监听事件
bus.$once	event: string｜string[], callback: Function	void	监听一次性事件
bus.$off	event: string｜string[], callback: Function	void	取消事件监听
emit	event: string, ...args: any[]	void	触发表单自定义事件
on	event: string｜string[], callback: Function	this	监听表单自定义事件
once	event: string｜string[], callback: Function	this	监听一次性表单事件
off	event?: string｜string[], callback?: Function	this	取消表单事件监听

自定义属性方法

方法名	参数	返回值	说明
setEffect	id: string, attr: string, value: any	void	设置自定义属性
clearEffectData	id: string, attr?: string	void	清理自定义属性数据

数据结构

以下是 Api 的完整数据结构及其可用方法的简明解释：

interface Api {
  // 表单的全局配置对象，包含了所有表单的配置信息
  readonly config: Options;
  readonly options: Options;
  // 获取当前表单在子表单(group)中的索引（如果表单是嵌套的子表单）
  readonly index: number|undefined;
  // 获取当前表单所在的子表单(group)中所有表单的API（如果表单是嵌套的子表单）
  readonly siblings: Api[]|undefined;
  // 当前表单的生成规则列表，定义了表单的结构和组件
  readonly rule: Rule[];
  // 当前表单的数据对象，其中包含了所有字段的值
  readonly form: Object;
  // 父级表单的 Api 对象（如果表单是嵌套的子表单）
  readonly parent: Api | undefined;
  // 最顶层表单的 Api 对象（适用于嵌套表单的场景）
  readonly top: Api | undefined;
  // 子表单的 Api 对象数组，允许对嵌套的子表单进行操作
  readonly children: Api[];
  // 提交按钮的控制接口，允许动态设置提交按钮的状态
  btn: {
    // 设置提交按钮的加载状态，如加载中状态
    loading(loading: boolean): void;
    // 设置提交按钮的禁用状态
    disabled(disabled: boolean): void;
    // 设置提交按钮的显示状态，控制按钮是否可见
    show(show: boolean): void;
  }
  // 重置按钮的控制接口，允许动态设置重置按钮的状态
  resetBtn: {
    // 设置重置按钮的加载状态
    loading(loading: boolean): void;
    // 设置重置按钮的禁用状态
    disabled(disabled: boolean): void;
    // 设置重置按钮的显示状态
    show(show: boolean): void;
  }
  // 获取指定组件的 DOM 元素或 Vue 实例
  el(id: string): any;
  // 获取整个表单的 Vue 组件实例，便于直接操作组件的内部方法或属性
  formEl(): undefined | ComponentInternalInstance;
  // 获取指定表单项的 Vue 组件实例，用于对具体表单项的操作
  wrapEl(id: string): undefined | ComponentInternalInstance;
  // 更新表单提交按钮的配置，如文本、样式等
  submitBtnProps(props: ButtonProps): void;
  // 更新表单重置按钮的配置
  resetBtnProps(props: ButtonProps): void;
  // 获取当前表单的数据对象，返回所有字段的值
  formData(): Object;
  // 获取特定字段的数据，返回指定字段的值
  formData(field: string[]): Object;
  // 获取指定字段的值
  getValue(field: string): any;
  // 用新的数据覆盖表单的当前值
  coverValue(formData: Object): void;
  // 设置表单的值，可以为整个表单设置，也可以为特定字段设置
  setValue(formData: Object): void;
  setValue(field: string, value: any): void;
  // 根据字段名删除对应的组件
  removeField(field: string): Rule;
  // 根据组件生成规则删除对应的组件
  removeRule(rule: Rule): Rule;
  // 获取表单中所有字段的名称
  fields(): string[];
  // 在指定字段后追加新的组件
  append(rule: Rule): void;
  append(rule: Rule, field: string): void;
  append(rule: Rule, field: string, child: boolean): void;
  // 在指定字段前插入新的组件
  prepend(rule: Rule): void;
  prepend(rule: Rule, field: string): void;
  prepend(rule: Rule, field: string, child: boolean): void;
  // 隐藏或显示表单的指定组件(无 DOM 节点)
  hidden(hidden: Boolean): void;
  hidden(hidden: Boolean, field: string | Array<string>): void;
  // 控制表单组件的显示与否(有 DOM 节点)
  display(hidden: Boolean): void;
  display(hidden: Boolean, field: string | Array<string>): void;
  // 获取组件的隐藏状态，返回布尔值
  hiddenStatus(field: String): Boolean;
  // 获取组件的显示状态，返回布尔值
  displayStatus(field: String): Boolean;
  // 禁用或启用表单的指定组件
  disabled(disabled: Boolean): void;
  disabled(disabled: Boolean, field: string | Array<string>): void;
  // 获取所有表单组件的生成规则，返回一个对象，键为字段名，值为规则对象
  model(): { [field: string]: Rule };
  // 获取所有定义了 `name` 属性的组件规则，返回一个对象，键为组件名，值为规则对象
  component(): { [name: string]: Rule };
  // 重新加载表单，使用新的规则列表替换当前表单的规则
  reload(rules: Rule[]): void;
  // 更新表单的全局配置
  updateOptions(options: Options): void;
  // 监听表单提交事件，当表单被提交时执行回调
  onSubmit(fn: (formData: Object, api: Api) => void): void;
  // 手动提交表单，触发提交流程并执行成功或失败的回调
  submit(success?: (formData: Object, api: Api) => void, fail?: (api: Api) => void): Promise<any>;
  // 同步指定字段或规则，确保表单的状态与最新数据同步
  sync(field: string | string[]): void;
  sync(rule: Rule | Rule[]): void;
  // 重新渲染整个表单，适用于更新表单布局或内容
  refresh(): void;
  refreshOptions(): void;
  // 隐藏整个表单，通常用于表单不需要展示的场景
  hideForm(hide?: Boolean): void;
  // 获取表单的修改状态，返回布尔值
  changeStatus(): Boolean;
  // 重置表单的修改状态
  clearChangeStatus(): void;
  // 设置自定义属性，用于扩展表单功能
  setEffect(id: string, attr: string, value: any): void;
  // 清理自定义属性的数据
  clearEffectData(id: string, attr?: string): void;
  // 更新指定字段的表单生成规则
  updateRule(field: string, rule: Rule): void;
  updateRule(rules: { [field: string]: Rule }): void;
  // 合并指定字段的表单生成规则
  mergeRule(field: string, rule: Rule): void;
  mergeRules(rules: { [field: string]: Rule }): void;
  // 获取指定字段的生成规则
  getRule(id: string): Rule;
  getRule(id: string, origin: true): Rule;
  getRule(id: string, origin: false): Rule;
  //通过组件类型获取生成规则
  findType(type: string): Rule;
  findTypes(type: string): Array<Rule>;
  //如果当前表单是子表单, 可以通过这个方法获取子表单组件的规则
  getCurrentFormRule(): Rule;
  // 获取组件最终渲染的规则，包含动态变化后的内容
  getRenderRule(id: string): Rule;
  // 通过 `name` 属性获取组件规则，支持单个或多个组件
  getRefRule(id: string): Rule | Rule[];
  // 通过 `name`,`field`或者规则获取父级规则
  getParentRule(id: string | Rule): undefined | Rule;
  // 更新组件的验证规则，支持合并或替换
  updateValidate(id: string, validate: Object[], merge?: Boolean): Promise<any>;
  updateValidates(validates: { [id: string]: Object[] }, merge?: Boolean): Promise<any>;
  // 刷新表单的验证状态，重新触发验证逻辑
  refreshValidate(): void;
  // 清理指定字段或整个表单的验证状态
  clearValidateState(fields?: string | string[], clearSub?: Boolean): void;
  // 清理指定字段子表单的表单的验证状态
  clearSubValidateState(fields?: string | string[]): void;
  // 验证表单，返回验证结果的 Promise
  validate(callback?: (state: any) => void): Promise<any>;
  // 验证指定字段，返回验证结果的 Promise
  validateField(field: string, callback?: (state: any) => void): Promise<any>;
  // 获取指定组件的方法，用于调用组件的自定义方法
  method(id: string, name: string): (...args: any[]) => any;
  // 手动执行指定组件的方法
  exec(id: string, name: string, ...args: any[]): any;
  // 手动触发组件的事件，适用于模拟用户操作或触发自定义逻辑
  trigger(id: string, event: string, ...args: any[]): void;
  // 获取表单的 JSON 生成规则，用于导出或保存表单结构
  toJson(space?: string | number): string;
  // 关闭指定 frame 组件的弹出框
  closeModal(id: string): void;
  // 重置表单，将所有字段的值重置为初始状态
  resetFields(): void;
  resetFields(field: string | string[]): void;
  // 获取指定字段的子表单 Api 对象，支持嵌套表单的操作
  getSubForm(field: string): Api | Api[];
  // 在表单渲染后执行回调，确保所有组件都已加载完毕
  nextTick(fn: (api: Api) => void): void;
  // 在执行回调后重新渲染表单，适用于动态更新后的表单刷新
  nextRefresh(fn: Function): void;
  // 在执行回调后同步表单数据，确保数据与 UI 同步
  deferSyncValue(fn: Function, autoSync?: boolean): void;
  // 发送远程请求，支持自定义的请求逻辑和处理方式
  fetch(opt: FetchOption): Promise<any>;
  // 设置外部数据，支持在表单中使用外部数据源
  setData(id: string, value?: any): void;
  // 获取外部数据，返回之前设置的数据对象
  getData(id: string, defaultValue?: any): any;
  // 在回调中通过get方法读取外部数据,获取对数据的变化监听,当数据变化后重新触发回调.返回解除监听函数
  watchData(fn: (get: (id: string, defaultValue?: any) => any, change: boolean) => void): () => Function;
  // 刷新与外部数据相关的组件，确保数据变更后 UI 同步更新
  refreshData(id: string): void;
  // 内置事件管理系统，支持手动触发和监听自定义事件
  bus: {
    $emit(event: string, ...args: any[]): void;  // 手动触发事件
    $on(event: string | string[], callback: Function): void;  // 监听事件
    $once(event: string | string[], callback: Function): void;  // 监听一次性事件
    $off(event: string | string[], callback: Function): void;  // 取消事件监听
  };
  // 手动触发表单的自定义事件
  emit(event: string, ...args: any[]): void;
  // 监听表单自定义事件
  on(event: string | string[], callback: Function): this;
  // 监听一次性表单自定义事件
  once(event: string | string[], callback: Function): this;
  // 取消表单自定义事件的监听
  off(event?: string | string[], callback?: Function): this;
}

API 的扩展

FormCreate 的 API 具有高度的扩展性，允许开发者创建自定义的操作和功能，以满足复杂的业务需求。

示例： 扩展 API 实现自定义操作

import formCreate from '@form-create/element-ui';


formCreate.extendApi((api) => {
  api.customMethod = function() {
    // 执行自定义操作
    console.log('这是一个自定义 API 方法');
  }
})

通过extendApi方法，可以添加新的方法或属性，使 api 更加适应特定的业务需求。这种方式非常适合在大型项目中进行 API 的个性化定制。

示例

禁用表单

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">禁用表单</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        api.value.disabled(true);
    }
</script>

修改组件值

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">禁用表单</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        api.value.setValue({
            field: 'value'
        });
    }
</script>

获取组件规则

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">获取规则</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        const rule = api.value.getRule('field');
        api.value.getRule('name'); //通过 name 获取规则
    }
</script>

修改组件规则

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">修改规则</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        api.value.getRule('field').prpos.disabled = true;
    }
</script>

表单验证

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">验证</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        api.value.validate().then(()=>{
            //todo 验证通过
        });
    }
</script>

提交表单

<template>
    <div>
        <form-create :v-model:api="api"/>
        <el-button @click="handle">提交</el-button>
    </div>
</template>
<script setup>
    import {ref} from 'vue';
    const api = ref(null);
    function handle() {
        api.value.submit();
    }
</script>