FormCreate

Appearance

表单操作 ​

API 提供了一系列强大的表单操作方法，使开发者能够在不同的业务场景中灵活地控制和操作表单。这些方法涵盖了表单数据处理、DOM 操作、提交逻辑等多方面内容。

数据结构 ​

以下是 Api 表单操作相关的数据结构及简明解释：

ts
interface 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;
  }
  // 获取整个表单的 Vue 组件实例，便于直接操作组件的内部方法或属性
  formEl(): undefined | ComponentInternalInstance;
  // 获取指定表单项的 Vue 组件实例，用于对具体表单项的操作
  wrapEl(id: string): undefined | ComponentInternalInstance;
  // 更新表单提交按钮的配置，如文本、样式等
  submitBtnProps(props: ButtonProps): void;
  // 更新表单重置按钮的配置
  resetBtnProps(props: ButtonProps): 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>;
  // 隐藏整个表单，通常用于表单不需要展示的场景
  hideForm(hide?: Boolean): void;
  // 获取表单的 JSON 生成规则，用于导出或保存表单结构
  toJson(space?: string | number): string;
  // 获取指定字段的子表单 Api 对象，支持嵌套表单的操作
  getSubForm(field: string): Api | Api[];
}

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

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

typescript
type formEl = () => Vue|Document|undefined
  • 示例：
js
const vm = fApi.formEl();
console.log(vm);

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

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

typescript
type wrapEl = (field:string) => Vue|Document|undefined
  • 示例：
js
const vm = fApi.wrapEl('goods_name');
console.log(vm);

获取表单数据 ​

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

typescript
interface formData {
    //获取全部数据
    (): {[field:string]:any }
    //获取部分字段的数据
    (field:string[]): {[field:string]:any }
}
  • 示例：
js
const allData = fApi.formData();
console.log('所有表单数据:', allData);
const specificData = fApi.formData(['goods_name', 'price']);
console.log('部分表单数据:', specificData);

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

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

typescript
type changeStatus = ()=>Boolean
  • 示例：
js
const hasChanged = fApi.changeStatus();
if (hasChanged) {
  console.log('表单数据已修改');
} else {
  console.log('表单数据未修改');
}

清除变化状态

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

typescript
type clearChangeStatus = ()=>void
  • 示例：
js
fApi.clearChangeStatus();
console.log('表单变化状态已清除');

修改提交按钮 ​

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

typescript
type submitBtnProps = (props:Object) => void
  • 示例：
js
fApi.submitBtnProps({ disabled: true });

  • 快捷操作:

  • fApi.btn.loading(true) 设置提交按钮进入loading状态

    • fApi.btn.disabled(true) 设置提交按钮禁用状态
    • fApi.btn.show(true) 设置提交按钮显示状态

修改重置按钮 ​

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

typescript
type resetBtnProps = ( props:Object) => void
  • 示例：
js
fApi.resetBtnProps({ disabled: true });

  • 快捷操作:

  • fApi.resetBtn.loading(true) 设置重置按钮进入loading状态

    • fApi.resetBtn.disabled(true) 设置重置按钮禁用状态
    • fApi.resetBtn.show(true) 设置重置按钮显示状态

更新表单配置 ​

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

typescript
type updateOptions = (options:Object) => void
  • 示例：
js
fApi.updateOptions({ form: { inline: true } });

更新表单提交事件 ​

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

typescript
type onSubmit = (callback:(formData:Object,fApi:fApi)=>void) => void
  • 示例：
js
fApi.onSubmit((formData, fApi) => {
  console.log('表单提交数据:', formData);
  // 自定义的提交逻辑
});

刷新表单配置 ​

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

typescript
type refreshOptions = ()=>void
  • 示例：
js
fApi.refreshOptions();
console.log('表单配置已刷新');

刷新表单渲染 ​

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

typescript
type refresh = ()=>void
  • 示例：
js
fApi.refresh();
console.log('表单渲染已刷新');

隐藏表单 ​

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

typescript
type hideForm = (hide:Boolean)=>void
  • 示例：
js
fApi.hideForm(true); // 隐藏表单
fApi.hideForm(false); // 显示表单

重载表单 ​

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

typescript
interface reload{
    ():void
    (rules:Rule[]):void
}
  • 示例：
js
fApi.reload(); // 使用现有规则重载表单
fApi.reload(newRules); // 使用新的规则重载表单

表单渲染后回调 ​

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

typescript
type nextTick = (callback:Function) => void
  • 示例：
js
fApi.nextTick(() => {
  console.log('表单已渲染完成');
  // 渲染完成后的操作
});

自动刷新 ​

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

typescript
type nextRefresh = (callback:Function) => void
  • 示例：
js
fApi.nextRefresh(() => {
  console.log('表单操作已完成，正在刷新表单...');
  // 执行影响表单渲染的操作
});

提交表单 ​

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

typescript
type submit = (
    success?: (formData: Object, $f: Api) => void,
    fail?: ($f: Api) => void
) => Promise<any>;
  • 示例：
js
fApi.submit(
        (formData, fApi) => {
          console.log('表单提交成功:', formData);
          // 提交后的逻辑处理
        },
        (fApi) => {
          console.log('表单提交失败');
          // 验证未通过的处理逻辑
        }
).then(formData => {
  // 推荐
  console.log('表单提交成功:', formData);
  // 提交后的逻辑处理
});

获取表单json规则 ​

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

typescript
type toJson = () => string
  • 示例：
js
const jsonString = fApi.toJson();
console.log('表单规则的 JSON 字符串:', jsonString);

示例 ​

动态控制提交和重置按钮的状态 ​

在一个表单提交过程中，根据用户操作动态控制提交按钮和重置按钮的状态。例如，在提交表单时禁用按钮并显示加载状态，提交完成后恢复按钮状态。

js
fApi.onSubmit((formData) => {
    fApi.btn.loading(true); // 设置提交按钮为加载状态
    fApi.btn.disabled(true); // 禁用提交按钮
    fApi.resetBtn.disabled(true); // 禁用重置按钮
    // 模拟提交操作
    setTimeout(() => {
        fApi.btn.loading(false); // 取消加载状态
        fApi.btn.disabled(false); // 重新启用提交按钮
        fApi.resetBtn.disabled(false); // 重新启用重置按钮
        console.log('表单提交成功:', formData);
    }, 2000);
});

实时更新表单的全局配置 ​

在一个多语言支持的表单中，根据用户选择的语言动态更新表单的全局配置，如表单的布局、标签位置、验证规则等。

js
const language = fApi.getValue('language');
if (language === 'en') {
    fApi.updateOptions({ form: { labelPosition: 'top' }, validation: { message: 'Field is required' } });
} else if (language === 'zh') {
    fApi.updateOptions({ form: { labelPosition: 'left' }, validation: { message: '此字段为必填项' } });
}

导出表单的 JSON 生成规则以便保存或复用 ​

在一个表单设计器工具中，用户可以实时编辑表单结构，并导出当前表单的 JSON 规则，以便保存或在其他项目中复用。

js
const jsonRules = fApi.toJson(); // 以格式化的方式导出 JSON 规则
console.log('导出的表单规则:', jsonRules);
// 将导出的 JSON 规则保存到服务器或本地存储
saveFormConfig(jsonRules);

根据用户选择动态修改分组的字段规则 ​

在一个客户信息表单中，不同的客户类型（个人客户或企业客户）需要填写不同的信息。通过修改子表单的规则，可以动态调整表单内容以适应用户选择。

js
// 获取子表单的 API 对象
const customerInfoApi = fApi.getSubForm('customerInfo');
// 根据客户类型动态修改子表单规则
const customerType = fApi.getValue('customer_type');
if (customerType === 'individual') {
    customerInfoApi.updateRule('company_name', { hidden: true }); // 隐藏公司名称字段
    customerInfoApi.updateRule('personal_id', { hidden: false }); // 显示个人ID字段
} else if (customerType === 'business') {
    customerInfoApi.updateRule('company_name', { hidden: false }); // 显示公司名称字段
    customerInfoApi.updateRule('personal_id', { hidden: true }); // 隐藏个人ID字段
}
// 刷新子表单以应用新的规则
customerInfoApi.refresh();

批量修改子表单中的数据 ​

在一个复杂的多商品订单表单中，用户可以批量更新子订单的状态。

js
// 获取所有子订单表单的 API 对象数组
const subOrderApis = fApi.getSubForm('subOrders');
// 批量修改所有子订单的状态
subOrderApis.forEach(api => {
    api.setValue('order_status', 'shipped'); // 设置子订单状态为已发货
    api.sync('order_status'); // 同步状态到子表单的显示
});
// 刷新所有子订单表单
subOrderApis.forEach(api => {
    api.refresh();
});

批量修改子表单中组件的规则 ​

在一个订单管理系统中，每个订单可能包含多个商品。根据商品类型，需要批量修改所有子订单表单中字段的显示状态、参数和验证规则。

js
// 获取所有子订单表单的 API 对象数组
const subOrderApis = fApi.getSubForm('subOrders');
// 批量修改子订单表单中字段的参数、显示状态和验证规则
subOrderApis.forEach((api) => {
    const itemType = api.getValue('item_type'); // 获取当前子订单的商品类型
    if (itemType === 'electronic') {
        api.updateRule({
            'warranty': { hidden: false, validate: [{ required: true, message: '保修期不能为空' }] }, // 显示保修期字段并验证必填
            'discount': { props: { min: 0, max: 10 } } // 限制折扣范围为 0-10%
        });
    } else if (itemType === 'furniture') {
        api.updateRule({
            'warranty': { hidden: true, validate: [{ required: false }] }, // 隐藏保修期字段并取消验证
            'discount': { props: { min: 0, max: 20 } } // 扩大折扣范围为 0-20%
        });
    }
    // 刷新每个子订单表单以应用新的字段规则
    api.refresh();
});

FormCreate 是一个开源项目，基于 MIT 许可证发布，欢迎个人和企业用户免费使用

MIT Licensed | Copyright © 2018-present FormCreate
陕ICP备2024036423号-1