表单 API

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

注意

更多详细使用方法请参考Api文档

获取API

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

在事件中获取

const api = $inject.api;

在自定义验证函数中获取

const api = this.api;

在钩子事件中获取

const api = data.api;

自定义组件注入

如果您使用自定义组件，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 提供了一系列丰富的方法，允许开发者在表单的各个阶段动态控制和操作表单。

方法名称	类型	说明
print Pro版	(config: Object)=>void	打印当前表单，查看详细文档。
exportPdf Pro版	(config: Object)=>void	导出当前表单为 PDF，查看详细文档。
message Pro版	(config: {message:string})=>void	弹出框提示消息
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	取消事件监听

示例

发送请求

在事件中可以通过 fetch 方法手动发送远程请求

api.fetch({
    action: '/api/getdata',
    query: {
        name: api.getValue('name')
    }
}).then(res=>{
    //todo
});

禁用组件

通过 disabled 方法禁用指定组件

//通过组件的 field 禁用组件
api.disabled(true, ['field1', 'field2', 'field3']);
//通过组件的 name 禁用组件
api.disabled(true, ['name1', 'name2', 'name3']);

隐藏组件

通过 hidden 方法隐藏指定组件

//通过组件的 field 隐藏组件
api.hidden(true, ['field1', 'field2', 'field3']);
//通过组件的 name 隐藏组件
api.hidden(true, ['name1', 'name2', 'name3']);

调用组件方法

通过 el 方法调用组件实例方法

//获取 elTable 组件选中的行
api.el('elTable').getSelectionRows();

修改表单值

通过 setValue 方法修改表单值

api.setValue({
    field1: 'value1',
    field2: 'value2',
    field3: 'value3',
});

修改组件的属性

通过 getRule 方法获取组件规则并修改, 可以通过设计器右侧的 JSON 面板查看组件的对应配置的层级和配置名

//通过组件的 field 获取组件规则
const rule1 = api.getRule('field');
//通过组件的 name 获取组件规则
const rule2 = api.getRule('name');


axios.get('/api/getForm').then(data => {
    //修改组件配置项中的 data 数据
    rule1.props.data = data;
})
//修改组件是否必填
rule2.$required = true;
//修改组件的文字
rule2.children[0] = '新文字';

手动验证指定字段

通过 api.validateField 方法手动触发对指定字段的表单验证

api.validateField('field').then(() => {
    // 验证通过
});

手动触发表单验证

通过 api.validate 方法手动触发表单的整体验证

api.validate().then(() => {
    // 验证通过
});

手动触发表单提交

通过调用 api.submit() 方法，无需用户点击提交按钮即可手动触发表单的提交操作

api.submit();

设置/获取外部数据

api.setData('Token', 'xxx');
const token = api.getData('Token');