表单 API

FormCreate 提供了丰富的 API 接口，允许开发者在表单的各个阶段进行全面控制，包括表单的生成、动态更新、验证和数据处理等功能。这些 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 对象并进行操作：

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

自定义组件注入

如果您使用自定义组件，FormCreate 会自动注入一些关键参数，帮助您在组件内部操作表单。

• 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属性

API 提供了一些关键属性，帮助开发者控制和操作表单。

属性名称	类型	说明
config	Object	表单的全局配置对象，包含了所有表单的配置信息
index	number|undefined	获取当前表单在子表单(group)中的索引（如果表单是嵌套的子表单）
siblings	Api[]|undefined	获取当前表单所在的子表单(group)中所有表单的API（如果表单是嵌套的子表单）
rule	Rule[]	当前表单的生成规则列表，定义了表单的结构和组件
form	Object	当前表单的数据对象，其中包含了所有字段的值
parent	Api |undefined	父级表单的 Api 对象（如果表单是嵌套的子表单）
top	Api	最顶层表单的 Api 对象（适用于嵌套表单的场景）
children	Api[]	子表单的 Api 对象数组，允许对嵌套的子表单进行操作

API方法

API 提供了一系列丰富的方法，允许开发者在表单的各个阶段动态控制和操作表单。完整使用方法请参考Api文档

方法名称	类型	说明
formEl	()=> undefined|ComponentInternalInstance	获取整个表单的 Vue 组件实例，便于直接操作组件的内部方法或属性
wrapEl	(id: string)=> undefined|ComponentInternalInstance	获取指定表单项的 Vue 组件实例，用于对具体表单项的操作
formData	(field?: string[])=> Object	获取当前表单的数据对象，返回所有字段的值
getValue	(field: string)=> any	获取指定字段的值
coverValue	(formData: Object)=> void	用新的数据覆盖表单的当前值
setValue	(formData: Object)=> void|(field: string, value: any)=> void	设置表单的值，可以为整个表单设置，也可以为特定字段设置
fields	()=> string[]	获取表单中所有字段的名称
hidden	(hidden: Boolean, field?: string|string[])=> void	隐藏或显示表单的指定组件(无 DOM 节点)
display	(display: Boolean, field?: string|string[])=> void	控制表单组件的显示与否(有 DOM 节点)
disabled	(disabled: Boolean, field?: string|string[])=> void	禁用或启用表单的指定组件
onSubmit	(fn: (formData: Object, api: Api) => void)=> void	监听表单提交事件，当表单被提交时执行回调
updateOptions	(options: Options)=> void	更新表单的全局配置
submit	(success?: (formData: Object, api: Api) => void, fail?: (api: Api) => void)=> Promise<any>	手动提交表单，触发提交流程并执行成功或失败的回调
getRule	(id: string)=> Rule|undefined	通过name或者field获取指定字段的生成规则
getRenderRule	(id: string)=> Rule|undefined	通过name或者field获取组件最终渲染的规则，包含动态变化后的内容
validate	(callback?: (state: any) => void)=> Promise<any>	验证表单，返回验证结果的 Promise
validateField	(field: string, callback?: (state: any) => void)=> Promise<any>	验证指定字段，返回验证结果的 Promise
clearValidateState	(fields?: string|string[], clearSub?: Boolean)=> void	清理指定字段或整个表单的验证状态
resetFields	(field?: string| string[])=> void	重置表单，将所有字段的值重置为初始状态
nextTick	(fn: (api: Api) => void)=> void	在表单渲染后执行回调，确保所有组件都已加载完毕
fetch	(option: FetchOption)=> Promise<any>	发送远程请求，支持自定义的请求逻辑和处理方式
setData	(id: string, value?: any)=> void	设置外部数据，支持在表单中使用外部数据源
getData	(id: string, defaultValue?: any)=> any	获取外部数据，返回之前设置的数据对象
refreshData	(id: string)=> void	刷新与外部数据相关的组件，确保数据变更后 UI 同步更新

API.bus

API 提供了一套内置的事件管理系统，帮助开发者在表单中灵活地管理和触发自定义事件。这些事件可以用于组件之间的通信、状态管理、动态行为触发等场景。

方法名称	类型	说明
$emit	(event: string, ...args: any[])=> void	手动触发事件
$on	$on(event: string|string[], callback: Function)=> void	监听事件
$once	$once(event: string|string[], callback: Function)=> void	监听一次性事件
$off	$off(event: string|string[], callback: Function)=> void	取消事件监听