API 属性

API 提供了一些关键属性，帮助开发者控制和操作表单。这些属性为您提供了对表单的全面控制，允许您根据不同的业务场景灵活操作和配置表单。

数据结构

以下是 Api 属性部分的数据结构及简明解释：

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

表单生成规则

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

type rule = Rule[]

• 示例：

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

表单全局配置

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

type config = Object

• 示例：

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

表单数据

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

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

• 示例：

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

该属性是双向绑定的

表单索引

index 属性用于获取当前表单在子表单（group）中的索引。它适用于表单嵌套的场景，用于确定当前表单在同级子表单中的位置。

type index = number | undefined;

• 示例：

// 获取当前表单在子表单中的索引
const formIndex = fApi.index;
// 使用索引进行操作
console.log('当前表单在子表单中的索引:', formIndex);

兄弟表单 API

siblings 属性用于获取当前表单所在的子表单（group）中所有表单的 API 对象。它适用于表单嵌套的场景，用于获取同级表单的 API，便于批量操作或协调操作。

type siblings = Api[] | undefined;

• 示例：

// 获取当前表单所在的子表单中所有表单的API对象
const siblingApis = fApi.siblings;
// 遍历所有兄弟表单并进行操作
if (siblingApis) {
    siblingApis.forEach(siblingApi => {
        // 例如，验证所有兄弟表单
        siblingApi.validate();
    });
}

顶级表单 API

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

type top = Api | undefined;

• 示例：

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

子表单 API

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

type children = Api[];

• 示例：

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

示例

级联操作父子表单

在一个多级嵌套的表单中，某些操作需要影响父级表单的状态。例如，当子表单中的字段验证通过时，需要自动提交父级表单。

const subFormApi = fApi.children[0]; // 获取第一个子表单 API
subFormApi.onSubmit((formData) => {
    if (subFormApi.validate()) {
        const parentApi = fApi.parent;
        if (parentApi) {
            parentApi.submit(); // 验证通过后提交父表单
        }
    }
});

动态更新表单配置

在一个多角色的管理系统中，不同的用户角色需要不同的表单布局和配置。例如，管理员有权限查看和编辑所有字段，而普通用户只能查看部分字段。

const userRole = fApi.getData('userRole', 'user'); // 从外部数据中获取当前用户角色
if (userRole === 'admin') {
    fApi.updateOptions({ form: { inline: false } }); // 管理员有更宽松的表单布局
} else {
    fApi.updateOptions({ form: { inline: true } }); // 普通用户使用紧凑的表单布局
}
fApi.refresh(); // 确保配置立即生效

批量操作子表单

在一个复杂的表单中，可能嵌套了多个子表单，每个子表单都有独立的验证逻辑。在提交主表单之前，需要确保所有子表单都已经验证通过。

const subFormApis = fApi.children; // 获取所有子表单的 API
let allValid = true;
subFormApis.forEach(subApi => {
    if (!subApi.validate()) {
        allValid = false;
    }
});
if (allValid) {
    fApi.submit(); // 所有子表单验证通过后，提交主表单
} else {
    console.log('有子表单验证未通过');
}

实时更新和处理表单数据

在一个订单结算系统中，用户输入订单金额后，需要实时计算并显示税额和总金额。通过 form 属性，可以实时更新和同步表单中的相关字段数据。

fApi.on('change', (field, value) => {
    if(field === 'amount' || field === 'tax') {
        const taxRate = 0.1;
        fApi.form.tax = fApi.form.amount * taxRate;
        fApi.form.total = fApi.form.amount + fApi.form.tax;
        fApi.refresh(); // 刷新表单显示税额和总金额
    }
});

嵌套表单数据同步和操作

在一个复杂的嵌套表单系统中，子表单的某些数据需要实时同步到父级表单。通过 parent 属性，可以实现子表单数据变化时，自动更新父级表单的数据。

fApi.on('change', (field, value) => {
    if(field === 'child') {
        const parentFormApi = fApi.parent;
        if (parentFormApi) {
            parentFormApi.setValue('childData', value); // 将子表单的数据传递给父表单
            parentFormApi.refresh(); // 刷新父表单以应用新数据
        } 
    }
});

批量操作子表单的验证和提交

在一个需要多个子表单独立验证的场景中，可以利用 children 属性批量操作所有子表单，确保每个子表单都通过验证后再统一提交。

const subFormApis = fApi.children; // 获取所有子表单的 API 对象
Promise.all(subFormApis.map(subApi => subApi.validate())).then(() => {
    fApi.submit(); // 所有子表单验证通过后提交主表单
}).catch(() => {
    console.error('某个子表单验证未通过');
});

根据权限动态生成或调整表单字段

在一个权限控制的系统中，不同用户可能具有不同的操作权限。例如，某些用户只能查看表单数据，而不能进行编辑操作。在生成表单时，可以根据用户的权限动态调整字段的可编辑状态。

const userPermissions = fApi.getData('userPermissions', {}); // 获取用户权限数据
fApi.rule.forEach(rule => {
    if (!userPermissions.editableFields.includes(rule.field)) {
        rule.props.disabled = true; // 如果字段不可编辑，则禁用它
    }
});
fApi.refresh(); // 应用修改后的规则