API

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

获取API

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

全局方法

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

const fApi = formCreate.create(rules)

组件模式

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

vue

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

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

vue

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


<script>
export default {
  data() {
    return {
      rules: [
        { type: 'input', field: 'username', title: '用户名', props: { placeholder: '请输入用户名' } },
        { type: 'input', field: 'email', title: '邮箱', props: { placeholder: '请输入邮箱' } },
        { type: 'input', field: 'password', title: '密码', props: { type: 'password', placeholder: '请输入密码' } },
      ],
      fApi: null,
    };
  },
  mounted() {
    // 使用 fApi 进行操作
    this.fApi.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 字段名称，与表单数据绑定。

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;
  // 当前表单的数据对象，其中包含了所有字段的值
  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;
}

属性

表单生成规则

rule 属性表示当前表单的生成规则列表，定义了表单中所有组件的结构和配置。通过操作 rule 可以动态调整表单的布局和内容。

typescript

type rule = Rule[]

用法：

// 获取当前表单的生成规则
const rules = fApi.rule;
// 修改某个组件的标题
rules[0].title = '新的标题';

表单全局配置

config 是当前表单的全局配置对象，包含了所有表单的基本设置，例如按钮配置、布局选项等。fApi.options 是 config 的别名。

typescript

type config = Object

用法：

// 获取当前表单的全局配置
const options = fApi.config;
// 更新表单配置
fApi.updateOptions({ submitBtn: false });

表单数据

form 属性是当前表单的数据对象，包含了表单中所有字段的值。该属性是双向绑定的，即通过操作 form 对象可以直接更新表单的数据，表单中的数据变化也会同步反映在 form 对象上。

typescript

type form = { [field:string]:any }

用法：

// 获取表单数据
const formData = fApi.form;
// 修改表单某个字段的值
formData.goods_name = 'huawei';
// 提交表单时获取表单数据
fApi.onSubmit((formData) => {
  console.log('提交的表单数据:', formData);
});

该属性是双向绑定的

父级表单 API

parent 属性用于获取当前表单的父级表单 API 对象，适用于嵌套表单的场景。当表单嵌套在其他表单中时，可以通过 parent 属性访问父表单的 API。

typescript

type parent = Api | undefined;

用法：

// 获取父级表单的API对象
const parentFormApi = fApi.parent;
// 使用父级表单的API操作父表单
if (parentFormApi) {
  parentFormApi.submit(); // 提交父表单
}

顶级表单 API

top 属性用于获取当前表单的顶级表单 API 对象。在嵌套表单的结构中，top 始终指向最外层的表单 API。

typescript

type top = Api | undefined;

用法：

// 获取顶级表单的API对象
const topFormApi = fApi.top;
// 重新加载顶级表单的规则
if (topFormApi) {
  topFormApi.submit(); // 提交父表单
}

子表单 API

children 属性用于获取当前表单下所有子表单的 API 对象列表。这对于操作嵌套在当前表单中的多个子表单非常有用。

typescript

type children = Api[];

用法：

// 获取所有子表单的API对象
const subFormApis = fApi.children;
// 遍历所有子表单并验证它们
subFormApis.forEach(subApi => {
  subApi.validate();
});

字段操作

获取表单字段

fields 方法返回表单中所有字段的名称列表。该方法非常适合在需要遍历表单字段或动态操作多个字段时使用。

typescript

type fields = ()=>string[]

用法：

const fields = fApi.fields();
console.log(fields); // 输出表单中所有字段的名称数组

获取指定字段值

getValue 方法根据字段名获取对应字段的当前值。

typescript

type getValue = (field:string) => any

用法：

const value = fApi.getValue('goods_name');
console.log(value); // 输出指定字段的当前值

设置表单值

coverValue 方法会覆盖未定义的字段，设置为 undefined。

typescript

type coverValue = (formData:{[field:string]:any}) => void

用法：

fApi.coverValue({ goods_name: 'HuaWei', price: 1000 });
// 覆盖所有字段，未定义的字段会被设置为 undefined

setValue 方法会合并传入的字段值，formData 中未定义的字段不做修改。

typescript

interface setValue {
    (formData:{[field:string]:any}): void
    (field:string, value:any): void
}

用法：

fApi.setValue({ goods_name: 'HuaWei', price: 1000 });
// 或者单独设置某个字段的值
fApi.setValue('goods_name', 'HuaWei');

别名方法changeValue, changeField

重置表单值

resetFields 方法用于重置表单的所有字段值，或重置指定字段的值。

typescript

interface resetFields {
    ():void
    (field:string[]):void
}

用法：

fApi.resetFields(); // 重置所有字段的值
fApi.resetFields(['goods_name', 'price']); // 仅重置指定字段的值

隐藏字段 (不渲染)

隐藏字段的组件不会渲染，DOM 节点不生成，因此表单验证不会生效。

typescript

interface hidden {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}

用法：

fApi.hidden(true); // 隐藏所有组件
fApi.hidden(true, 'goods_name'); // 隐藏指定组件
fApi.hidden(true, ['goods_name', 'price']); // 隐藏多个组件

获取组件隐藏状态

hiddenStatus 方法用于获取指定字段是否处于隐藏状态。

typescript

type hiddenStatus = (field:string)=>Boolean

用法：

const status = fApi.hiddenStatus('goods_name');
console.log(status); // 输出 true 或 false

隐藏组件 (渲染)

通过 display: none 隐藏组件，组件仍然渲染但不显示。

typescript

interface display {
    //隐藏全部组件
    (status:Boolean):void
    //隐藏指定组件
    (status:Boolean, field:string):void 
    //隐藏部分组件
    (status:Boolean, field:string[]):void 
}

用法：

fApi.display(false); // 显示所有组件
fApi.display(false, 'goods_name'); // 显示指定组件
fApi.display(false, ['goods_name', 'price']); // 显示多个组件

获取组件隐藏状态

displayStatus 方法用于获取指定字段是否处于显示状态。

typescript

type displayStatus = (field:string)=>Boolean

用法：

const status = fApi.displayStatus('goods_name');
console.log(status); // 输出 true 或 false

禁用组件

disabled 方法用于禁用表单中的所有组件、指定组件或部分组件。

typescript

interface disabled {
    //禁用全部组件
    (status:Boolean):void 
    //禁用指定组件
    (status:Boolean, field:string):void 
    //禁用部分组件
    (status:Boolean, field:string[]):void 
}

用法：

fApi.disabled(true); // 禁用所有组件
fApi.disabled(true, 'goods_name'); // 禁用指定组件
fApi.disabled(true, ['goods_name', 'price']); // 禁用多个组件

删除字段

removeField 方法用于从表单中删除指定组件。

typescript

type removeField = (field:string) => Rule

用法：

const rule = fApi.removeField('goods_name');
console.log(rule); // 返回被删除的字段生成规则

刷新组件渲染

sync 方法用于手动刷新指定字段的组件渲染。

typescript

interface sync{
    //通过 field 更新指定组件
    (field:string):void
    //通过生成规则更新指定组件
    (rule:Rule):void
}

用法：

fApi.sync('goods_name'); // 刷新指定字段的组件
fApi.sync(rule); // 通过生成规则刷新组件

组件方法

exec 方法用于手动执行指定字段组件的某个方法。

typescript

type exec = (field:string, method:string, ...args:any[]) => any

用法：

fApi.exec('goods_name', 'focus'); // 让指定字段的组件获得焦点

method 方法用于获取指定字段组件的某个方法，以便后续手动调用。

typescript

type method = (field:string, method:string) => Function

用法：

const focusMethod = fApi.method('goods_name', 'focus');
focusMethod(); // 手动调用组件的 focus 方法

手动触发组件事件

trigger 方法用于手动触发指定字段组件的事件。

typescript

type trigger = (field:string, event:string, ...args:any[]) => void

用法：

fApi.trigger('goods_name', 'change', 'new value'); // 手动触发 change 事件

获取组件的`vm/dom`元素

el 方法用于获取指定字段组件的 Vue 实例或 DOM 元素。

typescript

type el = (field:string) => Vue|Document|undefined

用法：

const vm = fApi.el('goods_name');
console.log(vm); // 输出组件的 Vue 实例或 DOM 元素

关闭frame组件的弹出框

closeModal 方法用于关闭指定 frame 组件的弹出框。

typescript

type closeModal = (field:string) => void

用法：

fApi.closeModal('frame'); // 关闭指定 frame 组件的弹出框

规则操作

获取组件规则

获取指定字段的规则

getRule 方法用于获取指定字段的规则。可以选择获取原始规则或当前的规则状态。

typescript

interface getRule {
    (field:string):Rule
    (field:string, origin: true): Rule
}

用法：

const rule = fApi.getRule('goods_name');
console.log(rule); // 获取当前字段的生成规则

通过 name 获取组件的规则

getRefRule 方法通过 name 获取组件的生成规则。适用于多个组件使用相同 name 的场景。

typescript

interface getRefRule {
    (name:string):Rule | Rule[]
}

用法：

const rule = fApi.getRefRule('input');
console.log(rule); // 获取指定 name 对应的规则

获取组件最终的渲染规则getRenderRule 方法获取组件的最终渲染规则，即组件当前状态下的规则配置。

typescript

interface getRenderRule {
    (field:string):Rule
}

用法：

const rule = fApi.getRenderRule('input');
console.log(rule); // 获取最终渲染规则

插入组件

prepend 方法用于在表单规则中前置插入新规则，可以插入到第一个位置、指定字段前或作为子规则插入。

typescript

interface prepend {
    //插入到第一个
    (rule:Rule):void 
    //插入指定字段前面
    (rule:Rule, field:string):void
    //插入到指定字段 children 中
    (rule:Rule, field:string, child:true):void
}

用法：

fApi.prepend({
  type: "input",
  title: "商品简介",
  field: "goods_info",
  value: "",
  props: {
    type: "text",
    placeholder: "请输入商品简介",
  },
  validate: [
    { required: true, message: '请输入商品简介', trigger: 'blur' },
  ],
}, 'goods_name'); // 在 'goods_name' 前插入新的规则

append 方法用于在表单规则中后置追加新规则，可以插入到最后一个位置、指定字段后或作为子规则追加。

typescript

interface append {
    //插入到最后一个
    (rule:Rule):void 
    //插入指定字段后面
    (rule:Rule, field:string):void
    //插入到指定字段 children 中
    (rule:Rule, field:string, child:true):void
}

用法：

fApi.append({
  type: "input",
  title: "商品简介",
  field: "goods_info",
  value: "",
  props: {
    type: "text",
    placeholder: "请输入商品简介",
  },
  validate: [
    { required: true, message: '请输入商品简介', trigger: 'blur' },
  ],
}, 'goods_name'); // 在 'goods_name' 后插入新的规则

删除指定组件

removeRule 方法用于从表单中删除指定规则的组件，并返回被删除的规则。

typescript

type removeRule = (rule:Rule) => Rule

用法：

const rule = { type: 'input', field: 'goods_info' };
fApi.removeRule(rule);
console.log('规则已删除:', rule);

获取表单组件规则

model 方法用于获取当前表单的所有生成规则或原始规则。

typescript

interface model{                
    //获取Object规则
    ():Rule[]              
    //获取原始规则
    (origin:true):Rule[]
}

用法：

const rules = fApi.model(); // 获取当前状态的规则
console.log(rules);
const originalRules = fApi.model(true); // 获取原始规则
console.log(originalRules);

获取自定义组件规则

component 方法用于获取所有定义了 name 属性的自定义组件的规则。

typescript

interface component{                
    //获取Object规则
    ():Rule[]              
    //获取原始规则
    (origin:true):Rule[]
}

用法：

const componentRules = fApi.component(); // 获取当前状态的自定义组件规则
console.log(componentRules);

更新指定规则

mergeRule 方法用于合并更新指定字段的规则。

typescript

type mergeRule = (rule:Rule)=>void

用法：

fApi.mergeRule('goods_name', { hidden: true }); // 合并更新 'goods_name' 字段的规则

mergeRules 方法用于批量合并更新多个字段的规则。

typescript

type mergeRules = (rules:{[field:string]:Rule})=>void

用法：

fApi.mergeRules({ 'goods_name': { hidden: true }, 'price': { disabled: true } });

updateRule 方法用于覆盖更新指定字段的规则。

typescript

type updateRule = (rule:Rule)=>void

用法：

fApi.updateRule('goods_name', { props: {disabled: true} }); // 覆盖更新 'goods_name' 字段的规则

updateRules 方法用于批量覆盖更新多个字段的规则。

typescript

type updateRules = (rules:{[field:string]:Rule})=>void

用法：

fApi.updateRules({ 'goods_name': { props: {disabled: true} }, 'price': { props: {disabled: true} } });

更新自定义属性

setEffect 方法用于更新指定字段的自定义属性。

typescript

type setEffect = (id:string, attr: string, value:any)=>void

用法：

fApi.setEffect('goods_name', 'required', false); // 将 'goods_name' 字段的 'required' 属性设置为 false

验证操作

验证表单

validate 方法用于验证整个表单，并在回调中返回验证结果。该方法返回一个 Promise 对象，验证通过则 resolve，否则 reject。

typescript

type validate = (callback:(...args:any[]) => void)=> Promise

用法：

fApi.validate((valid, fail) => {
  if (valid === true) {
    console.log('表单验证通过');
  } else {
    console.log('表单验证未通过');
  }
}).then(() => {
    //推荐
  console.log('Promise resolved: 表单验证通过');
}).catch(() => {
  console.log('Promise rejected: 表单验证未通过');
});

验证指定字段

validateField 方法用于验证指定字段，并在回调中返回验证结果。该方法返回一个 Promise 对象，验证通过则 resolve，否则 reject。

typescript

type validateField = (field, callback:(...args:any[]) => void)=> Promise

用法：

fApi.validateField('goods_name', (valid, fail) => {
  if (valid === true) {
    console.log('字段验证通过');
    // todo 字段验证通过后的处理逻辑
  } else {
    console.log('字段验证未通过');
    // todo 字段验证未通过的处理逻辑
  }
}).then(() => {
    //推荐
  console.log('Promise resolved: 字段验证通过');
}).catch(() => {
  console.log('Promise rejected: 字段验证未通过');
});

更新验证规则

updateValidate 方法用于更新指定字段的验证规则。可以选择覆盖更新或合并更新。

typescript

interface updateValidate{
    //覆盖更新
    (field:string, validate:Object[]):void
    //合并更新
    (field:string, validate:Object[], merge:true):void
}

用法：

// 合并更新 goods_name 字段的验证规则
fApi.updateValidate('goods_name', [{ required: true }], true);
// 覆盖更新 goods_name 字段的验证规则
fApi.updateValidate('goods_name', [{ required: true }]);

updateValidates 方法用于批量更新多个字段的验证规则。可以选择覆盖更新或合并更新。

typescript

interface updateValidates{
    //覆盖更新
    (validates:{[field:string]: Object[]}):void
    //合并更新
    (validates:{[field:string]: Object[]}, merge:true):void
}

用法：

// 合并更新多个字段的验证规则
fApi.updateValidates({
  'goods_name': [{ required: false }],
  'price': [{ required: true, type: 'number' }]
}, true);
// 覆盖更新多个字段的验证规则
fApi.updateValidates({
  'goods_name': [{ required: true }],
  'price': [{ required: true, type: 'number' }]
});

刷新验证规则

refreshValidate 方法用于手动刷新表单的验证规则。如果修改了验证规则但未生效，可以通过调用此方法来确保规则生效。

typescript

type refreshValidate = ()=>void

用法：

fApi.refreshValidate();
console.log('验证规则已刷新');

清除表单验证状态

clearValidateState 方法用于清除表单或指定字段的验证状态。

typescript

interface clearValidateState {
    ():void
    (field:string, clearSub?:boolean):void
    (field:string[], clearSub?:boolean):void
}

用法：

// 清除整个表单的验证状态
fApi.clearValidateState();
// 清除单个字段的验证状态
fApi.clearValidateState('goods_name');
// 清除多个字段的验证状态
fApi.clearValidateState(['goods_name', 'price']);

清除子表单验证状态

clearSubValidateState 方法用于清除 group、object等子表单的验证状态。

typescript

interface clearSubValidateState {
    (field:string):void
    (field:string[]):void
}

用法：

// 清除单个子表单的验证状态
fApi.clearSubValidateState('goods_name');
// 清除多个子表单的验证状态
fApi.clearSubValidateState(['goods_name', 'price']);

表单操作

获取表单组件的`vm/dom`元素

formEl 方法用于获取整个表单组件的 Vue 实例或 DOM 元素。

typescript

type formEl = () => Vue|Document|undefined

用法：

const vm = fApi.formEl();
console.log(vm);

获取 FormItem 组件的`vm/dom`元素

wrapEl 方法用于获取指定字段的 FormItem 组件的 Vue 实例或 DOM 元素。

typescript

type wrapEl = (field:string) => Vue|Document|undefined

用法：

const vm = fApi.wrapEl('goods_name');
console.log(vm);

获取表单数据

formData 方法用于获取表单中所有字段或部分字段的数据。该方法的返回值是数据的快照，不是双向绑定。

typescript

interface formData {
    //获取全部数据
    (): {[field:string]:any }
    //获取部分字段的数据
    (field:string[]): {[field:string]:any }
}

用法：

const allData = fApi.formData();
console.log('所有表单数据:', allData);
const specificData = fApi.formData(['goods_name', 'price']);
console.log('部分表单数据:', specificData);

表单中的值是否发生变化状态

changeStatus 方法用于检查表单中的值是否发生了变化。返回的布尔值指示表单自加载以来是否被用户修改过。

typescript

type changeStatus = ()=>Boolean

用法：

const hasChanged = fApi.changeStatus();
if (hasChanged) {
  console.log('表单数据已修改');
} else {
  console.log('表单数据未修改');
}

清除变化状态

clearChangeStatus 方法用于清除表单的变化状态，这意味着在调用此方法后，changeStatus 将返回 false。

typescript

type clearChangeStatus = ()=>void

用法：

fApi.clearChangeStatus();
console.log('表单变化状态已清除');

修改提交按钮

submitBtnProps 方法用于动态修改表单提交按钮的属性，例如禁用状态、加载状态或按钮文本。

typescript

type submitBtnProps = (props:Object) => void

用法：

fApi.submitBtnProps({ disabled: true });

快捷操作:
fApi.btn.loading(true) 设置提交按钮进入loading状态
- fApi.btn.disabled(true) 设置提交按钮禁用状态
- fApi.btn.show(true) 设置提交按钮显示状态

修改重置按钮

resetBtnProps 方法用于动态修改表单重置按钮的属性，例如禁用状态、加载状态或按钮文本。

typescript

type resetBtnProps = ( props:Object) => void

用法：

fApi.resetBtnProps({ disabled: true });

快捷操作:
fApi.resetBtn.loading(true) 设置重置按钮进入loading状态
- fApi.resetBtn.disabled(true) 设置重置按钮禁用状态
- fApi.resetBtn.show(true) 设置重置按钮显示状态

更新表单配置

updateOptions 方法用于动态更新表单的全局配置选项。这些配置选项包括表单布局、按钮配置、校验规则等。

typescript

type updateOptions = (options:Object) => void

用法：

fApi.updateOptions({ form: { inline: true } });

更新表单提交事件

onSubmit 方法用于为表单设置自定义的提交事件处理函数。当用户提交表单时，会执行该回调函数，可以在回调中处理表单数据。

typescript

type onSubmit = (callback:(formData:Object,fApi:fApi)=>void) => void

用法：

fApi.onSubmit((formData, fApi) => {
  console.log('表单提交数据:', formData);
  // 自定义的提交逻辑
});

刷新表单配置

refreshOptions 方法用于手动刷新表单的配置选项，确保配置的更改立即生效。

typescript

type refreshOptions = ()=>void

用法：

fApi.refreshOptions();
console.log('表单配置已刷新');

刷新表单渲染

refresh 方法用于手动刷新表单的渲染状态。这在表单内容需要动态更新时非常有用。

typescript

type refresh = ()=>void

用法：

fApi.refresh();
console.log('表单渲染已刷新');

隐藏表单

hideForm 方法用于隐藏或显示整个表单。表单隐藏后，用户将无法看到或操作表单。

typescript

type hideForm = (hide:Boolean)=>void

用法：

fApi.hideForm(true); // 隐藏表单
fApi.hideForm(false); // 显示表单

重载表单

reload 方法用于重新加载表单，您可以选择使用现有的生成规则或传入新的生成规则来重载表单。

typescript

interface reload{
    ():void
    (rules:Rule[]):void
}

用法：

fApi.reload(); // 使用现有规则重载表单
fApi.reload(newRules); // 使用新的规则重载表单

表单渲染后回调

nextTick 方法在表单渲染完成后执行回调函数。可以用来确保 DOM 操作在渲染完成后进行。

typescript

type nextTick = (callback:Function) => void

用法：

fApi.nextTick(() => {
  console.log('表单已渲染完成');
  // 渲染完成后的操作
});

自动刷新

nextRefresh 方法执行回调函数后自动刷新表单渲染。这在回调中执行影响表单渲染的操作时特别有用。

typescript

type nextRefresh = (callback:Function) => void

用法：

fApi.nextRefresh(() => {
  console.log('表单操作已完成，正在刷新表单...');
  // 执行影响表单渲染的操作
});

提交表单

submit 方法用于手动提交表单，支持传入成功和失败的回调函数。提交表单时可以进行自定义的验证和数据处理。

typescript

type submit = (
    success?: (formData: Object, $f: Api) => void,
    fail?: ($f: Api) => void
) => Promise<any>;

用法：

fApi.submit(
        (formData, fApi) => {
          console.log('表单提交成功:', formData);
          // 提交后的逻辑处理
        },
        (fApi) => {
          console.log('表单提交失败');
          // 验证未通过的处理逻辑
        }
).then(formData => {
  // 推荐
  console.log('表单提交成功:', formData);
  // 提交后的逻辑处理
});

获取表单`json`规则

toJson 方法用于将表单规则转换为 JSON 字符串。

typescript

type toJson = () => string

用法：

const jsonString = fApi.toJson();
console.log('表单规则的 JSON 字符串:', jsonString);

数据管理

远程请求

fetch 方法用于发起远程请求，以获取外部数据或将数据发送到服务器。它与表单组件深度集成，可根据请求结果动态更新表单的选项或数据。

typescript

type fetch = (opt: FetchOption) => Promise<any>;

fApi.fetch({
    action: '/api/get-options',
    method: 'GET',
    to: 'props.options',
    onSuccess(data) {
        console.log('获取的数据:', data);
    },
    onError(error) {
        console.error('请求失败:', error);
    }
});

设置外部数据

setData 方法用于将外部数据挂载到表单中，使得这些数据可以被表单中的组件使用。这些数据可以是静态的，也可以是从外部数据源动态获取的。

typescript

type setData = (id: string, value?: any)=> void;

fApi.setData('categories', [
    { label: 'Electronics', value: 'electronics' },
    { label: 'Clothing', value: 'clothing' },
    { label: 'Home & Garden', value: 'home_garden' },
]);
console.log('外部数据已设置:', fApi.getData('categories'));

获取外部数据

getData 方法用于获取之前通过 setData 方法设置的外部数据。如果指定的数据未设置，方法将返回 defaultValue。

typescript

type getData = (id: string, defaultValue?: any) => any;

const categories = fApi.getData('categories', []);
console.log('获取的分类数据:', categories);

刷新与外部数据相关的组件渲染

refreshData 方法用于手动刷新与指定外部数据相关的组件渲染。当外部数据发生变化时，可以调用该方法以确保表单组件正确反映最新的数据状态。

typescript

type refreshData = (id: string) => void;

fApi.setData('categories', [
    { label: 'Books', value: 'books' },
    { label: 'Music', value: 'music' },
]);
fApi.refreshData('categories');
console.log('与分类数据相关的组件已刷新');

内置事件管理

触发事件

bus.$emit 方法用于手动触发指定的事件，并可以传递多个参数。这些参数会作为事件处理函数的参数进行传递。

typescript

type emit = (event:string, ...args:any[]) => void

用法：

fApi.bus.$emit('custom-event', 'param1', 'param2');

触发事件

bus.$on 方法用于监听指定的事件，当事件被触发时，会执行注册的回调函数。可以监听一个或多个事件。

typescript

type on = (event: string, callback: Function) => void

用法：

fApi.bus.$on('custom-event', (param1, param2) => {
  console.log('事件被触发:', param1, param2);
});

监听事件，只触发一次

bus.$once 方法用于监听指定的事件，但回调函数只会执行一次，执行完后会自动取消监听。

typescript

type on = (event: string, callback: Function) => void

用法：

fApi.bus.$once('init-complete', () => {
  console.log('初始化完成，事件仅触发一次');
});

取消事件监听

bus.$off 方法用于取消对指定事件的监听。

typescript

type off = (event: string, callback: Function) => void

用法：

fApi.bus.$off('custom-event', handleCustomEvent);

API ​

获取API ​

数据结构 ​

属性 ​

表单生成规则 ​

表单全局配置 ​

表单数据 ​

父级表单 API ​

顶级表单 API ​

子表单 API ​

字段操作 ​

获取表单字段 ​

获取指定字段值 ​

设置表单值 ​

重置表单值 ​

隐藏字段 (不渲染) ​

隐藏组件 (渲染) ​

禁用组件 ​

删除字段 ​

刷新组件渲染 ​

组件方法 ​

手动触发组件事件 ​

获取组件的vm/dom元素 ​

关闭frame组件的弹出框 ​

规则操作 ​

获取组件规则 ​

插入组件 ​

删除指定组件 ​

获取表单组件规则 ​

获取自定义组件规则 ​

更新指定规则 ​

更新自定义属性 ​

验证操作 ​

验证表单 ​

验证指定字段 ​

更新验证规则 ​

刷新验证规则 ​

清除表单验证状态 ​

清除子表单验证状态 ​

表单操作 ​

获取表单组件的vm/dom元素 ​

获取 FormItem 组件的vm/dom元素 ​

获取表单数据 ​

表单中的值是否发生变化状态 ​

修改提交按钮 ​

修改重置按钮 ​

更新表单配置 ​

更新表单提交事件 ​

刷新表单配置 ​

刷新表单渲染 ​

隐藏表单 ​

重载表单 ​

表单渲染后回调 ​

自动刷新 ​

提交表单 ​

获取表单json规则 ​

数据管理 ​

远程请求 ​

设置外部数据 ​

获取外部数据 ​

刷新与外部数据相关的组件渲染 ​

内置事件管理 ​

触发事件 ​

触发事件 ​

监听事件，只触发一次 ​

取消事件监听 ​

API

获取API

数据结构

属性

表单生成规则

表单全局配置

表单数据

父级表单 API

顶级表单 API

子表单 API

字段操作

获取表单字段

获取指定字段值

设置表单值

重置表单值

隐藏字段 (不渲染)

隐藏组件 (渲染)

禁用组件

删除字段

刷新组件渲染

组件方法

手动触发组件事件

获取组件的`vm/dom`元素

关闭frame组件的弹出框

规则操作

获取组件规则

插入组件

删除指定组件

获取表单组件规则

获取自定义组件规则

更新指定规则

更新自定义属性

验证操作

验证表单

验证指定字段

更新验证规则

刷新验证规则

清除表单验证状态

清除子表单验证状态

表单操作

获取表单组件的`vm/dom`元素

获取 FormItem 组件的`vm/dom`元素

获取表单数据

表单中的值是否发生变化状态

修改提交按钮

修改重置按钮

更新表单配置

更新表单提交事件

刷新表单配置

刷新表单渲染

隐藏表单

重载表单

表单渲染后回调

自动刷新

提交表单

获取表单`json`规则

数据管理

远程请求

设置外部数据

获取外部数据

刷新与外部数据相关的组件渲染

内置事件管理

触发事件

触发事件

监听事件，只触发一次

取消事件监听