API 概览

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

获取API

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

全局方法

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

const fApi = formCreate.create(rules)

组件模式

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

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

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

<template>
  <form-create name="form" :rule="rules" v-model:api="fApi"></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 fApi = ref(null);
onMounted(() => {
  // 使用 fApi 进行操作
  fApi.value.setValue('username', 'example_user');
});
</script>

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

const fApi = formCreate.getApi('form')

事件注入

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

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

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

{
  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 的完整数据结构及其可用方法的简明解释：

interface Api {
  // 表单的全局配置对象，包含了所有表单的配置信息
  readonly config: Options;
  readonly options: Options;
  // 获取当前表单在子表单(group)中的索引（如果表单是嵌套的子表单）
  readonly index: number|undefined;
  // 获取当前表单所在的子表单(group)中所有表单的API（如果表单是嵌套的子表单）
  readonly siblings: Api[]|undefined;
  // 当前表单的生成规则列表，定义了表单的结构和组件
  readonly rule: Rule[];
  readonly options: Options;
  // 当前表单的数据对象，其中包含了所有字段的值
  readonly form: Object;
  // 当前表单的生成规则列表，定义了表单的结构和组件
  readonly rule: Rule[];
  // 父级表单的 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;
  // 获取组件最终渲染的规则，包含动态变化后的内容
  getRenderRule(id: string): Rule;
  // 通过 `name` 属性获取组件规则，支持单个或多个组件
  getRefRule(id: string): Rule | 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;
  // 刷新与外部数据相关的组件，确保数据变更后 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 方法');
  }
  return api;
})

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