组件操作

API 提供了多种操作组件的强大方法，使得开发者能够在不同的业务场景中灵活地管理和调整表单组件的规则和行为。

数据结构

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

interface Api {
    // 获取指定字段的生成规则
    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[];
    // 根据组件生成规则删除对应的组件
    removeRule(rule: Rule): Rule;
    // 在指定字段后追加新的组件
    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;
    // 获取所有表单组件的生成规则，返回一个对象，键为字段名，值为规则对象
    model(): { [field: string]: Rule };
    // 获取所有定义了 `name` 属性的组件规则，返回一个对象，键为组件名，值为规则对象
    component(): { [name: string]: Rule };
    // 更新指定字段的表单生成规则
    updateRule(field: string, rule: Rule): void;
    updateRule(rules: { [field: string]: Rule }): void;
    // 合并指定字段的表单生成规则
    mergeRule(field: string, rule: Rule): void;
    mergeRules(rules: { [field: string]: Rule }): void;
    // 设置自定义属性，用于扩展表单功能
    setEffect(id: string, attr: string, value: any): void;
    // 清理自定义属性的数据
    clearEffectData(id: string, attr?: string): void;
}

获取组件规则

获取指定字段的规则

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

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

• 示例：

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

通过 name 获取组件的规则

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

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

• 示例：

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

获取组件最终的渲染规则

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

interface getRenderRule {
    (field:string):Rule
}

• 示例：

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

插入组件

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

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 方法用于在表单规则中后置追加新规则，可以插入到最后一个位置、指定字段后或作为子规则追加。

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 方法用于从表单中删除指定规则的组件，并返回被删除的规则。

type removeRule = (rule:Rule) => Rule

• 示例：

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

获取表单组件规则

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

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

• 示例：

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

获取自定义组件规则

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

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

• 示例：

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

更新指定规则

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

type mergeRule = (rule:Rule)=>void

• 示例：

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

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

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

• 示例：

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

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

type updateRule = (rule:Rule)=>void

• 示例：

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

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

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

• 示例：

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

更新自定义属性

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

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

• 示例：

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

示例

动态获取并更新表单字段的生成规则

在一个动态表单生成系统中，管理员可以实时查看和编辑表单字段的生成规则。

// 获取指定字段的生成规则
const rule = fApi.getRule('username');
// 修改规则
rule.title = '用户名称';

根据特定条件动态插入和移除表单组件

在一个用户填写表单时，根据他们的输入动态插入或移除相关的表单组件。例如，当用户选择“是”时，插入一个额外的说明字段，否则移除该字段。

const explanationRule = {
    type: 'textarea',
    field: 'explanation',
    title: '说明',
    props: { placeholder: '请输入说明' }
};
// 根据用户选择动态插入或移除字段
if (fApi.getValue('requires_explanation') === true) {
    fApi.append(explanationRule, 'requires_explanation');
} else {
    fApi.removeRule(explanationRule);
}

批量更新表单字段的生成规则

在一个多角色管理系统中，不同角色看到的表单字段配置不同。管理员可以批量更新表单字段的规则，以适应不同角色的需求。

const adminRules = {
    'username': { props: { disabled: false } },
    'email': { props: { disabled: false } },
    'role': { props: { disabled: false } }
};


const userRules = {
    'username': { props: { disabled: true } },
    'email': { props: { disabled: true } },
    'role': { props: { disabled: true } }
};


// 根据角色更新规则
const userRole = fApi.getData('userRole');
if (userRole === 'admin') {
    fApi.updateRules(adminRules);
} else {
    fApi.updateRules(userRules);
}

多字段规则批量合并和更新

在一个动态的表单配置场景中，多个字段需要在用户操作后，统一更新其生成规则，并进行规则的合并操作。

const batchRules = {
    'address': { props: { placeholder: '请输入新的地址' } },
    'phone': { props: { disabled: true } },
    'email': { props: { type: 'email' } }
};
// 批量合并规则
fApi.mergeRules(batchRules);
// 批量更新规则
fApi.updateRule(batchRules);