扩展业务数据

通过 config.datasets 预置业务数据树。配置后，组件「选项数据」的加载方式里会出现 业务数据。设计器里只保存所选数据的标识和附加配置，真正取数由 formCreate.setDataLoader 完成，适合把性别、部门、商品列表、图表数据等接到自己的接口或本地数据上。

数据结构

type DatasetItem = {
    // 唯一标识，加载函数按该值取数
    value: string;
    // 显示名称
    label: string;
    // 禁用后不可选择，分组节点可设为 true
    disabled?: boolean;
    // 子级节点
    children?: DatasetItem[];
    // 该项的附加配置表单，写法与组件规则相同
    // 填写结果保存在 rule.$dataset.config，全空时不写入
    rule?: Rule[] | ((designer: Object) => Rule[]);
};

type DatasetPayload = {
    key: string;
    // 返回值写入的属性路径，由组件决定，例如 options、props.data
    to?: string;
    config?: Record<string, any>;
    // 点击刷新时在 0 和 1 之间切换，用来触发重新加载
    _uni?: number;
};

预置业务数据列表

写入 config.datasets 后，加载方式中才会出现「业务数据」。未配置或为空数组时不显示该项。

<template>
    <fc-designer ref="designer" :config="config"/>
</template>
<script setup>
    const config = {
        datasets: [
            {
                value: 'flat',
                label: '选项类',
                disabled: true,
                children: [
                    { value: 'gender', label: '性别' },
                    { value: 'city', label: '城市' },
                    {
                        value: 'dept',
                        label: '部门',
                        rule() {
                            return [
                                {
                                    type: 'switch',
                                    field: 'includeDisabled',
                                    title: '包含停用部门',
                                    value: false,
                                },
                            ];
                        },
                    },
                ],
            },
            {
                value: 'tableGroup',
                label: '数据表格',
                disabled: true,
                children: [
                    { value: 'product', label: '商品列表' },
                ],
            },
        ],
    };
</script>

说明：

• value 会写入规则的 $dataset.key，并作为加载函数的查找键，建议使用稳定编码。
• disabled: true 的节点不能被选中，用来做分组标题。
• rule 可以是规则数组，也可以是函数。函数参数是设计器实例，可按当前组件决定要展示哪些配置项。用户填写的结果保存在 $dataset.config。
• 该配置只定义「可选清单」，不包含具体数据。

注册加载函数

在渲染表单之前，向 实际渲染用的 formCreate 注册加载函数。设计器预览和正式页面如果不是同一个渲染器实例，需要分别注册。

formCreate.setDataLoader((dataset, rule, api) => {
    // dataset 是 rule.$dataset 的深拷贝
    const { key, config } = dataset;

    if (key === 'gender') {
        return [
            { label: '男', value: 'male' },
            { label: '女', value: 'female' },
        ];
    }

    if (key === 'dept') {
        const list = [
            { label: '研发部', value: 'rd' },
            { label: '市场部', value: 'mkt' },
        ];
        if (config && config.includeDisabled) {
            list.push({ label: '已停用部门', value: 'disabled' });
        }
        return list;
    }

    if (key === 'city') {
        return fetch('/api/city').then(res => res.json());
    }

    return [];
});

函数签名：

参数	说明
dataset	$dataset 的深拷贝，含 key、to、config
rule	当前组件规则，手动调用且未传规则时为 null
api	表单 API

返回值可以是数据，也可以是 Promise。加载完成后，返回值会写入 dataset.to 指定的属性。

传入 null 可取消注册：

formCreate.setDataLoader(null);

也可以在表单事件里按同一份数据手动加载：

function reload($inject) {
    const rule = $inject.rule;
    $inject.api.dataLoader(rule.$dataset, rule);
}

api.dataLoader 的第一个参数也可以直接传 key 字符串，此时按选项数据加载，等价于 { key, to: 'options' }。

在组件中选择

配置好清单并注册加载函数后：

1. 选中组件，在数据加载方式中选择 业务数据
2. 从树中选择一项，例如「部门」
3. 若该项配置了 rule，下方会出现附加配置，例如「包含停用部门」
4. 需要重新取数时，点击选择框右侧的刷新按钮

选中后，规则中会保存类似结构：

{
    type: 'select',
    field: 'dept',
    title: '部门',
    $dataset: {
        key: 'dept',
        to: 'options',
        config: {
            includeDisabled: true,
        },
    },
}

$dataset 会作为名为 dataset 的 effect 参与渲染。config 为空时不会写入。

返回值写入位置

不同组件的 to 不同，加载函数要返回该属性能够使用的数据结构。to 为 options 或 props.options 时，返回值必须是数组，否则该次加载会被丢弃。

组件	to	返回值
下拉框、单选框、多选框、提及	options	{ label, value }[]
级联选择器	props.options	树形 { label, value, children }[]
树形控件、树形选择、穿梭框	props.data	选项数组或树
数据表格、Vxe 数据表格	props.data	表格数据
JSON 组件	props.rule	表单规则数组
折线图、体积图、柱状图、条形图、自定义图表	props.config	图表配置
饼图、漏斗图、雷达图、散点图	props.data	图表数据
Mermaid	props.content	图表文本

加载函数可以根据 rule.type 或 rule._fc_drag_tag 判断当前组件，对同一 key 返回不同结构。例如「商品列表」在下拉框里返回 { label, value }[]，在数据表格里返回行数据。

与远程数据、全局数据源的区别

能力	配置位置	数据来源
业务数据	config.datasets + setDataLoader	业务代码统一加载，规则里只存 key 和 config
远程数据	组件上的请求配置	每个组件单独配置接口
全局数据源	设计器内预定义	保存在表单全局配置中，组件按名称引用

不需要在设计器里暴露某一种加载方式时，用 隐藏数据加载方式 的 hiddenOptionsType: ['dataset'] 去掉「业务数据」。

注意事项

• 清单里的 value 必须和加载函数识别的 key 一致。未实现的 key 应返回空数据，避免组件保留上一次的结果。
• 加载函数抛错或 Promise 拒绝时，已写入的数据会被清空。
• 附加配置变化、以及刷新导致的 _uni 变化，都会重新调用加载函数。
• 设计器画布、预览和正式渲染要使用已注册 setDataLoader 的渲染器，否则控制台会提示未注册数据加载函数。