前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载导读在 Formily 中下拉选择、级联、树选择等数据型组件的选项数据并不需要你在组件层手写状态管理而是统一收敛到字段模型Field的dataSource属性上。本指南以 async.zh-CN.md 为核心系统讲解异步数据源的两种核心驱动方式effects 与 reactions、内置组件对dataSource的自动消费机制以及业务自定义组件的手动映射方案读完即可在 React 与 JSON Schema 场景下落地接口返回选项、动态切换数据源的完整实践。核心模型Field 的 dataSource 属性异步数据源管理的核心载体是 Field 模型中的dataSource属性。Formily 的设计思想是把选项数据当作字段的一种响应式状态与value、loading、validating等字段状态同等对待任何来源异步请求、联动计算、外部注入只要写入dataSource消费它的组件就会自动感知并重渲染。从 Field 源码 可以看到其数据通路字段初始化时this.dataSource this.props.dataSource即支持通过x-component-props/component[1]或字段属性直接传入初始选项makeObservable中将dataSource标记为observable.ref意味着对它的整体替换会触发订阅者更新这是自动重渲染的底层原理模型上还暴露了命令式方法setDataSource(dataSource?)见 Field.ts#L385-L387可在任意生命周期内以编程方式写入数据源。dataSource的类型定义位于 core/src/types.ts其结构为对象数组且是递归自引用的天然支持树形数据export type FieldDataSource { label?: any value?: any title?: any key?: any text?: any children?: FieldDataSource [key: string]: any }[]这意味着扁平列表只需{ label, value }结构树形结构TreeSelect、Cascader通过children递归嵌套额外键如禁用状态disabled、图标等会被透传字段结构非常灵活。方式一在 effects 中修改 dataSourceeffects 是什么Formily 的 effects 是生命周期事件订阅机制通过createForm的第二个参数传入配合 onFieldEffects.ts 与 onFormEffects.ts 导出的各种事件钩子使用例如onFieldInit/onFieldMount字段初始化 / 挂载后触发onFieldValueChange字段值变化后触发onFieldReact字段反应器执行时触发onFormMount表单挂载后触发常用来做整表数据的首次拉取。典型场景 1字段挂载后拉取远程选项import { createForm, onFieldInit, onFieldValueChange } from formily/core const form createForm({ effects() { // 字段挂载后立即异步拉取该字段的选项 onFieldInit(select, async (field) { field.loading true // 进入加载态Select 组件会展示 loading 图标 const res await fetchOptions() field.dataSource res.data // 写入 dataSource组件自动重渲染 field.loading false }) // 也可以响应其他字段变化联动刷新数据源 onFieldValueChange(province, (field) { const cityField form.query(city).take() if (!cityField) return cityField.loading true fetchCities(field.value).then((res) { cityField.dataSource res.data cityField.loading false }) }) }, })典型场景 2在表单挂载时统一初始化如果多个字段共享同一份选项数据可以挂在onFormMount中统一处理import { createForm, onFormMount } from formily/core const form createForm({ effects() { onFormMount(async () { const res await fetchAllDictionaries() form.query(role).take((field) (field.dataSource res.roles)) form.query(department).take((field) (field.dataSource res.departments)) }) }, })方式二在 reactions 中修改 dataSourcereactions是字段模型上的响应式字段联动描述类型见 IFieldProps.reactions为(field: Field) void或函数数组。它与 effects 的区别在于reactions 是声明在字段自身上的跟随字段模型随 JSON Schema 一起被序列化描述更适用于 Schema 化场景如 JSON Schema 表单、设计器产物。import { createForm } from formily/core const form createForm({ fields: { province: { type: string, enum: provinceOptions, // 初始 dataSource }, city: { type: string, reactions(field) { // 当 province 变化时根据其值异步刷新 city 的数据源 const province field.query(province).get(value) if (!province) { field.dataSource [] return } field.loading true fetchCities(province).then((res) { field.dataSource res.data field.loading false }) }, }, }, })在 React 中reactions可以写在createSchemaField的组件 props 上或 JSON Schema 的x-reactions中在核心层字段初始化时会将props.reactions注册为字段的响应式依赖任何被读取的字段状态变化都会重新执行该函数对应onFieldReact生命周期。选择建议逻辑偏事件式如提交后刷新、定时轮询用effects逻辑偏声明式联动依赖其他字段值、可随 Schema 分发用reactions。两者都能修改dataSource也可以混用。内置组件的自动消费dataSource 到 props 的映射文档中强调如果字段组件内部有消费dataSource属性当dataSource变化时组件会自动重渲染。这一能力由formily/react的connectmapProps实现各内置组件的映射关系如下以 antd 包为例组件源码位置dataSource 映射到Selectpackages/antd/src/select/index.tsxoptions并同步映射loadingTreeSelectpackages/antd/src/tree-select/index.tsxtreeDataCascaderpackages/antd/src/cascader/index.tsxoptionsRadiopackages/antd/src/radio/index.tsxoptionsCheckboxpackages/antd/src/checkbox/index.tsxoptions以 Select 为例select/index.tsx 中export const Select: ReactFCSelectPropsany, any connect( AntdSelect, mapProps( { dataSource: options, loading: true, }, ... ), mapReadPretty(PreviewText.Select) )mapProps({ dataSource: options, loading: true })的含义是字段的dataSource会映射为 antd Select 的options字段的loading/validating会映射为 loading 状态并渲染旋转图标。因此只要在 effects / reactions 中写入field.dataSource与field.loadingSelect 就会自动刷新选项并展示加载动画无需任何组件层手动 setState。// 一个完整的最小示例挂载后拉取选项 const form createForm({ effects() { onFieldInit(select, (field) { field.loading true setTimeout(() { field.dataSource [ { label: 选项一, value: 1 }, { label: 选项二, value: 2 }, ] field.loading false }, 500) }) }, })业务自定义组件手动映射 dataSource如果使用业务自定义组件没有经过上述connect包装dataSource不会自动成为组件的 props必须手动映射。文档给出了两条路径路径 A使用 connect mapProps用connect包装自定义组件声明dataSource到组件 props 的映射关系import { connect, mapProps } from formily/react const MySelect connect( BaseSelect, // 你的业务组件内部读取 props.options mapProps({ dataSource: options, // 字段 dataSource - 组件 options loading: true, }) )之后在 Schema 中直接使用MySelect作为x-component即可享受与内置 Select 一致的自动数据绑定。路径 Bobserver useField 手动读取如果组件结构复杂、不适合用connect映射可以用observer包裹组件并在组件内部通过useField拿到字段模型主动读取field.dataSource并渲染import { observer, useField } from formily/react const MySelect observer(() { const field useFieldany() // 取到字段模型 return ( BaseSelect options{field.dataSource} // 手动映射 loading{field.loading} / ) })observer会让组件订阅字段模型的响应式状态当field.dataSource被替换时observable.ref变更组件自动重渲染——这与内置组件的行为完全一致只是把映射这一步从框架代劳改成了自己声明。响应式原理小结整条链路可以归纳为写入effects / reactions 中给field.dataSource赋值或调用field.setDataSource(...)通知dataSource作为observable.ref见 Field.ts#L140整体替换会触发依赖它的订阅者消费connect包装的组件通过mapProps把dataSource注入组件 propsobserver组件则通过useField直接订阅渲染组件收到新选项后自动重渲染配合field.loading展示加载状态。这套机制让异步数据源在 Formily 中不需要任何额外的状态管理库字段模型本身就是选项数据的唯一真源Single Source of Truth这也是其 JSON Schema 场景json-schema 包与 React/Vue 各渲染层packages/react、packages/vue、packages/antd、packages/next保持一致行为的基础。进阶实践建议统一字典服务将高频字典选项抽成可复用的 effects 函数或自定义 Hook在onFieldInit中按field.path匹配字典 key 拉取避免每个字段重复写请求逻辑联动清空当上游字段变化导致下游数据源失效时记得同时清空下游field.value如cityField.setValue(undefined)避免出现选项已变、旧值仍残留错误兜底异步请求失败时在 effects / reactions 的 catch 中设置field.feedback如field.setSelfErrors([数据加载失败])并关闭loading保证表单不会卡在加载态分页/搜索型下拉对于远程搜索场景可以结合onFieldValueChange或组件自身的搜索事件把关键字写入外部状态并驱动dataSource更新结构与上述示例一致。更多相关内置组件的具体行为可参考 antd 组件文档 中 Select、TreeSelect、Cascader 各章节以及核心层 Field 模型文档。赞分享前端UI组件【免费下载链接】formily Cross Device High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址https://gitcode.com/gh_mirrors/fo/formily点击查看免费下载相关推荐Formily Select 下拉框组件实战同步/异步数据源与联动场景全解formily/antdFormily Select 下拉框组件实战同步/异步数据源与联动场景全解formily/antd Formily 是一套跨端、高性能的表单解决方案支前端UI组件管理业务逻辑Formily 中 effects 与 reactions 的选型与实践指南管理业务逻辑Formily 中 effects 与 reactions 的选型与实践指南 Formily 2.x 在 docs/guide/advanced/前端UI组件formily × Element UIVue 2Select 下拉选择组件实战全指南同步/异步数据源与联动方案formily × Element UIVue 2Select 下拉选择组件实战全指南同步/异步数据源与联动方案 本指南以 formily/elemen前端UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
