Refine v5 中使用 useRadioGroup Hook 构建 Ant Design Radio 选项组完整指南【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineuseRadioGroup是refinedev/antd包提供的 Hook用于将某个资源resource中的记录映射为 Ant DesignRadio.Group的选项从而在管理后台的表单中快速渲染单选按钮组。本文基于仓库内该 Hook 的源码实现、单元测试与官方示例系统讲解其用法、全部配置项、默认行为与边界场景帮助你用最少的样板代码实现数据驱动的单选字段。快速上手三行代码接入 Radio.GroupuseRadioGroup的核心价值在于你只需把资源名交给它它就会自动通过dataProvider拉取数据并把数据转换成 Ant DesignRadio.Group可直接消费的options数组。以官方示例中从https://api.fake-rest.refine.dev/languages端点读取语言列表为例该接口返回的数据形如[ { id: 1, title: Turkish }, { id: 2, title: English }, { id: 3, title: German } ]在创建页面的表单中使用它import { useRadioGroup } from refinedev/antd; import { Form, Radio } from antd; export const PostCreate () { const { radioGroupProps } useRadioGroupILanguage({ resource: languages, }); return ( Form Form.Item labelLanguages namelanguages Radio.Group {...radioGroupProps} / /Form.Item /Form ); }; interface ILanguage { id: number; title: string; }你只需要把radioGroupProps展开到Radio.Group上即可——它已经包含正确配置的options数组默认映射为{ label: title, value: id }以及可选的defaultValue。这与仓库中官方示例 examples/field-antd-use-radio-group 的PostCreate页面写法一致该示例还同时演示了创建与编辑两种场景下的完整用法见 create.tsx 与 edit.tsx。从源码结构看useRadioGroup本质上是useSelect的轻量封装。它内部调用useSelect获取options与query再组装出radioGroupProps参见 packages/antd/src/hooks/fields/useRadioGroup/index.tsreturn { radioGroupProps: { options, defaultValue, }, query, };因此useRadioGroup的所有数据获取行为都继承自useSelect而useSelect的数据获取又依赖useList其核心实现位于 packages/core/src/hooks/useSelect/index.ts。关于useList的详细说明可参考 Refine Core 的 useList Hook 文档。Options全部配置项详解resource指定数据来源const { radioGroupProps } useRadioGroup({ resource: languages, });resource决定从dataProvider的哪个 API 端点获取记录并据此生成适合单选按钮的options值。当存在多个同名资源时可以传入identifier而不是资源的name。identifier将作为资源匹配的主键而 dataProvider 的方法仍会使用Refine/组件中定义的资源name。这一行为在useSelect中通过useResourceParams解析见 useSelect/index.ts。更多说明可参考identifier相关文档。defaultValue设置默认选中项const { radioGroupProps } useRadioGroup({ resource: languages, defaultValue: 1, });传入defaultValue是给单选字段设置默认值的最直接方式。selectedOptionsOrder控制默认选中项的位置selectedOptionsOrder决定selectedOptions由defaultValue对应记录构成的选项在最终选项列表中的排序方式取值有两种in-placeselectedOptions排在列表底部这是默认行为selected-firstselectedOptions排在列表顶部。const { radioGroupProps } useRadioGroup({ resource: languages, defaultValue: 1, selectedOptionsOrder: selected-first, // in-place | selected-first });该排序逻辑在useSelect的combinedOptions中实现——它通过uniqBy(..., value)对两类选项做去重合并顺序则取决于selectedOptionsOrder见 useSelect/index.tsuniqBy( selectedOptionsOrder in-place ? [...options, ...selectedOptions] : [...selectedOptions, ...options], value, )值得注意的边界行为当设置defaultValue时useSelect内部会额外发起一次useMany查询专门拉取默认值对应的记录以生成selectedOptions见 useSelect/index.ts。这样即使默认值对应的记录不在当前列表页中也能保证它出现在选项里。optionLabel 与 optionValue定制选项的展示与取值const { radioGroupProps } useRadioGroup({ resource: languages, optionLabel: title, optionValue: id, });optionLabel与optionValue分别决定每个选项的展示文本和提交值默认值为optionLabel title、optionValue id。这两个属性还支持使用 lodash get 的对象路径语法访问嵌套字段const { options } useRadioGroup({ resource: categories, optionLabel: nested.title, optionValue: nested.id, });同样也可以传入函数函数会收到每条记录的item参数适合做字段拼接等复杂映射const { options } useRadioGroup({ optionLabel: (item) ${item.firstName} ${item.lastName}, optionValue: (item) item.id, });在源码中字符串形式的optionLabel/optionValue通过get(item, path)解析函数形式则直接调用见 useSelect/index.ts。单元测试对这三种形态默认字段、自定义字段、函数映射都有覆盖验证例如测试中optionLabel: (item) \${item.title} - ${item.userId}会生成Necessitatibus necessitatibus id et cupiditate provident est qui amet. - 5 这样的标签见 packages/antd/src/hooks/fields/useRadioGroup/index.spec.ts。searchField指定搜索字段searchField用于指定调用onSearch时按哪个字段进行搜索const { onSearch } useRadioGroup({ searchField: name }); onSearch(John); // Searches by name field with value John.默认规则是如果optionLabel是字符串则使用optionLabel的值作为搜索字段否则回退到title字段// 当 optionLabel 为字符串时 const { onSearch } useRadioGroup({ optionLabel: name }); onSearch(John); // 按 name 字段搜索值为 John。 // 当 optionLabel 为函数时 const { onSearch } useRadioGroup({ optionLabel: (item) ${item.id} - ${item.name}, }); onSearch(John); // 按 title 字段搜索值为 John。源码中的默认值逻辑为searchField typeof optionLabel string ? optionLabel : title见 useSelect/index.ts。实际搜索时onSearch会以contains操作符构造过滤条件并经过 300ms 默认防抖后合并到列表查询中见 useSelect/index.ts。filters数据过滤filters允许在获取数据时附加过滤条件。例如只想列出title等于 German 的语言const { radioGroupProps } useRadioGroup({ resource: languages, filters: [ { field: title, operator: eq, value: German, }, ], });在useSelect中filters与搜索产生的过滤条件会被拼接后一起传给useListfilters: filters.concat(search)见 useSelect/index.ts。sorters选项排序sorters允许对选项排序。例如按title升序排列const { radioGroupProps } useRadioGroup({ resource: languages, sorters: [ { field: title, order: asc, }, ], });官方示例 create.tsx 正是用sorters对语言列表按标题升序展示的。fetchSize单次拉取数量fetchSize控制单选选项一次性拉取的记录数量const { radioGroupProps } useRadioGroup({ resource: languages, fetchSize: 20, });queryOptions透传 TanStack Query 选项queryOptions允许你设置底层 useQuery 的选项const { radioGroupProps } useRadioGroup({ resource: languages, queryOptions: { onError: () { console.log(triggers when on query return Error); }, }, });在useSelect的类型定义中queryOptions的类型为MakeOptionalUseQueryOptionsGetListResponseTQueryFnData, TError, GetListResponseTData, queryKey | queryFn即queryKey与queryFn由 Refine 内部托管其余 TanStack Query 选项均可自定义见 useSelect/index.ts。pagination分页控制pagination允许设置页码与每页条数。假设共有 1000 条记录const { radioGroupProps } useRadioGroup({ resource: categories, pagination: { currentPage: 3, pageSize: 8 }, });列表将从第 3 页开始每页显示 8 条记录。注意useSelect对pageSize有默认值 10见 useSelect/index.ts当数据量较大时建议结合fetchSize或pagination控制单次拉取规模避免一次加载过多选项。API ReferencePropertiesuseRadioGroup的完整属性定义可从refinedev/antd/useRadioGroup模块导出其类型为UseRadioGroupPropsTQueryFnData, TError, TData本质是对UseSelectProps剔除defaultValue后新增defaultValue?: BaseKey的结果见 packages/antd/src/hooks/fields/useRadioGroup/index.ts。Type Parameters属性说明类型默认值TQueryFnData查询函数返回的结果数据继承自BaseRecordBaseRecordBaseRecordTError自定义错误对象继承自HttpErrorHttpErrorHttpErrorTDataselect函数返回的结果数据继承自BaseRecord。未指定时默认使用TQueryFnDataBaseRecordTQueryFnDataReturn values属性说明类型radioGroupPropsAnt Design Radio.Group 的 propsRadio Groupquery记录查询的结果QueryObserverResult{ data: TData }来自 TanStack Query 的 useQuery返回类型在源码中的定义如下见 useRadioGroup/index.tsexport type UseRadioGroupReturnTypeTData, TOption, TError { radioGroupProps: OmitReact.ComponentPropstypeof Radio.Group, options { options: TOption[]; }; query: QueryObserverResultGetListResponseTData, TError; };可以看到radioGroupProps剔除了 Ant DesignRadio.Group原有的options属性类型改为使用 Refine 生成的TOption[]从而保证类型安全。与其他字段 Hooks 的关联useRadioGroup与useSelect、useCheckboxGroup同属 packages/antd/src/hooks/fields 目录三者共享同一套基于useSelect的数据获取与选项生成逻辑区别仅在于最终面向的 UI 组件useRadioGroup→Radio.Group单选useCheckboxGroup→Checkbox.Group多选useSelect→Select下拉选择。因此你在本文中学到的resource、filters、sorters、optionLabel/optionValue、defaultValue等配置能力可以无缝迁移到其余两个 Hook 上。运行官方示例仓库中的 examples/field-antd-use-radio-group 是完整的可运行示例演示了创建与编辑页面中语言单选组的完整用法src/pages/posts/create.tsx与src/pages/posts/edit.tsx。它基于 Vite 搭建包含App.tsx、interfaces/index.d.ts定义IPost、ILanguage类型等完整工程文件。在仓库根目录执行pnpm install后进入该示例目录运行pnpm dev即可本地启动查看效果。小结useRadioGroup将拉取资源数据 → 转换为单选选项 → 绑定到表单这一重复流程封装为一次 Hook 调用。其底层完全复用useSelect/useList的数据链路天然支持过滤、排序、分页、实时订阅live与自定义查询选项配合optionLabel/optionValue的对象路径与函数两种映射方式几乎可以覆盖任何字段结构的单选需求。在 Refine v5 中它是构建数据驱动型管理后台表单时最高效的单选字段方案。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Refine v5 中使用 useRadioGroup Hook 构建 Ant Design Radio 选项组：完整指南
Refine v5 中使用 useRadioGroup Hook 构建 Ant Design Radio 选项组完整指南【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refineuseRadioGroup是refinedev/antd包提供的 Hook用于将某个资源resource中的记录映射为 Ant DesignRadio.Group的选项从而在管理后台的表单中快速渲染单选按钮组。本文基于仓库内该 Hook 的源码实现、单元测试与官方示例系统讲解其用法、全部配置项、默认行为与边界场景帮助你用最少的样板代码实现数据驱动的单选字段。快速上手三行代码接入 Radio.GroupuseRadioGroup的核心价值在于你只需把资源名交给它它就会自动通过dataProvider拉取数据并把数据转换成 Ant DesignRadio.Group可直接消费的options数组。以官方示例中从https://api.fake-rest.refine.dev/languages端点读取语言列表为例该接口返回的数据形如[ { id: 1, title: Turkish }, { id: 2, title: English }, { id: 3, title: German } ]在创建页面的表单中使用它import { useRadioGroup } from refinedev/antd; import { Form, Radio } from antd; export const PostCreate () { const { radioGroupProps } useRadioGroupILanguage({ resource: languages, }); return ( Form Form.Item labelLanguages namelanguages Radio.Group {...radioGroupProps} / /Form.Item /Form ); }; interface ILanguage { id: number; title: string; }你只需要把radioGroupProps展开到Radio.Group上即可——它已经包含正确配置的options数组默认映射为{ label: title, value: id }以及可选的defaultValue。这与仓库中官方示例 examples/field-antd-use-radio-group 的PostCreate页面写法一致该示例还同时演示了创建与编辑两种场景下的完整用法见 create.tsx 与 edit.tsx。从源码结构看useRadioGroup本质上是useSelect的轻量封装。它内部调用useSelect获取options与query再组装出radioGroupProps参见 packages/antd/src/hooks/fields/useRadioGroup/index.tsreturn { radioGroupProps: { options, defaultValue, }, query, };因此useRadioGroup的所有数据获取行为都继承自useSelect而useSelect的数据获取又依赖useList其核心实现位于 packages/core/src/hooks/useSelect/index.ts。关于useList的详细说明可参考 Refine Core 的 useList Hook 文档。Options全部配置项详解resource指定数据来源const { radioGroupProps } useRadioGroup({ resource: languages, });resource决定从dataProvider的哪个 API 端点获取记录并据此生成适合单选按钮的options值。当存在多个同名资源时可以传入identifier而不是资源的name。identifier将作为资源匹配的主键而 dataProvider 的方法仍会使用Refine/组件中定义的资源name。这一行为在useSelect中通过useResourceParams解析见 useSelect/index.ts。更多说明可参考identifier相关文档。defaultValue设置默认选中项const { radioGroupProps } useRadioGroup({ resource: languages, defaultValue: 1, });传入defaultValue是给单选字段设置默认值的最直接方式。selectedOptionsOrder控制默认选中项的位置selectedOptionsOrder决定selectedOptions由defaultValue对应记录构成的选项在最终选项列表中的排序方式取值有两种in-placeselectedOptions排在列表底部这是默认行为selected-firstselectedOptions排在列表顶部。const { radioGroupProps } useRadioGroup({ resource: languages, defaultValue: 1, selectedOptionsOrder: selected-first, // in-place | selected-first });该排序逻辑在useSelect的combinedOptions中实现——它通过uniqBy(..., value)对两类选项做去重合并顺序则取决于selectedOptionsOrder见 useSelect/index.tsuniqBy( selectedOptionsOrder in-place ? [...options, ...selectedOptions] : [...selectedOptions, ...options], value, )值得注意的边界行为当设置defaultValue时useSelect内部会额外发起一次useMany查询专门拉取默认值对应的记录以生成selectedOptions见 useSelect/index.ts。这样即使默认值对应的记录不在当前列表页中也能保证它出现在选项里。optionLabel 与 optionValue定制选项的展示与取值const { radioGroupProps } useRadioGroup({ resource: languages, optionLabel: title, optionValue: id, });optionLabel与optionValue分别决定每个选项的展示文本和提交值默认值为optionLabel title、optionValue id。这两个属性还支持使用 lodash get 的对象路径语法访问嵌套字段const { options } useRadioGroup({ resource: categories, optionLabel: nested.title, optionValue: nested.id, });同样也可以传入函数函数会收到每条记录的item参数适合做字段拼接等复杂映射const { options } useRadioGroup({ optionLabel: (item) ${item.firstName} ${item.lastName}, optionValue: (item) item.id, });在源码中字符串形式的optionLabel/optionValue通过get(item, path)解析函数形式则直接调用见 useSelect/index.ts。单元测试对这三种形态默认字段、自定义字段、函数映射都有覆盖验证例如测试中optionLabel: (item) \${item.title} - ${item.userId}会生成Necessitatibus necessitatibus id et cupiditate provident est qui amet. - 5 这样的标签见 packages/antd/src/hooks/fields/useRadioGroup/index.spec.ts。searchField指定搜索字段searchField用于指定调用onSearch时按哪个字段进行搜索const { onSearch } useRadioGroup({ searchField: name }); onSearch(John); // Searches by name field with value John.默认规则是如果optionLabel是字符串则使用optionLabel的值作为搜索字段否则回退到title字段// 当 optionLabel 为字符串时 const { onSearch } useRadioGroup({ optionLabel: name }); onSearch(John); // 按 name 字段搜索值为 John。 // 当 optionLabel 为函数时 const { onSearch } useRadioGroup({ optionLabel: (item) ${item.id} - ${item.name}, }); onSearch(John); // 按 title 字段搜索值为 John。源码中的默认值逻辑为searchField typeof optionLabel string ? optionLabel : title见 useSelect/index.ts。实际搜索时onSearch会以contains操作符构造过滤条件并经过 300ms 默认防抖后合并到列表查询中见 useSelect/index.ts。filters数据过滤filters允许在获取数据时附加过滤条件。例如只想列出title等于 German 的语言const { radioGroupProps } useRadioGroup({ resource: languages, filters: [ { field: title, operator: eq, value: German, }, ], });在useSelect中filters与搜索产生的过滤条件会被拼接后一起传给useListfilters: filters.concat(search)见 useSelect/index.ts。sorters选项排序sorters允许对选项排序。例如按title升序排列const { radioGroupProps } useRadioGroup({ resource: languages, sorters: [ { field: title, order: asc, }, ], });官方示例 create.tsx 正是用sorters对语言列表按标题升序展示的。fetchSize单次拉取数量fetchSize控制单选选项一次性拉取的记录数量const { radioGroupProps } useRadioGroup({ resource: languages, fetchSize: 20, });queryOptions透传 TanStack Query 选项queryOptions允许你设置底层 useQuery 的选项const { radioGroupProps } useRadioGroup({ resource: languages, queryOptions: { onError: () { console.log(triggers when on query return Error); }, }, });在useSelect的类型定义中queryOptions的类型为MakeOptionalUseQueryOptionsGetListResponseTQueryFnData, TError, GetListResponseTData, queryKey | queryFn即queryKey与queryFn由 Refine 内部托管其余 TanStack Query 选项均可自定义见 useSelect/index.ts。pagination分页控制pagination允许设置页码与每页条数。假设共有 1000 条记录const { radioGroupProps } useRadioGroup({ resource: categories, pagination: { currentPage: 3, pageSize: 8 }, });列表将从第 3 页开始每页显示 8 条记录。注意useSelect对pageSize有默认值 10见 useSelect/index.ts当数据量较大时建议结合fetchSize或pagination控制单次拉取规模避免一次加载过多选项。API ReferencePropertiesuseRadioGroup的完整属性定义可从refinedev/antd/useRadioGroup模块导出其类型为UseRadioGroupPropsTQueryFnData, TError, TData本质是对UseSelectProps剔除defaultValue后新增defaultValue?: BaseKey的结果见 packages/antd/src/hooks/fields/useRadioGroup/index.ts。Type Parameters属性说明类型默认值TQueryFnData查询函数返回的结果数据继承自BaseRecordBaseRecordBaseRecordTError自定义错误对象继承自HttpErrorHttpErrorHttpErrorTDataselect函数返回的结果数据继承自BaseRecord。未指定时默认使用TQueryFnDataBaseRecordTQueryFnDataReturn values属性说明类型radioGroupPropsAnt Design Radio.Group 的 propsRadio Groupquery记录查询的结果QueryObserverResult{ data: TData }来自 TanStack Query 的 useQuery返回类型在源码中的定义如下见 useRadioGroup/index.tsexport type UseRadioGroupReturnTypeTData, TOption, TError { radioGroupProps: OmitReact.ComponentPropstypeof Radio.Group, options { options: TOption[]; }; query: QueryObserverResultGetListResponseTData, TError; };可以看到radioGroupProps剔除了 Ant DesignRadio.Group原有的options属性类型改为使用 Refine 生成的TOption[]从而保证类型安全。与其他字段 Hooks 的关联useRadioGroup与useSelect、useCheckboxGroup同属 packages/antd/src/hooks/fields 目录三者共享同一套基于useSelect的数据获取与选项生成逻辑区别仅在于最终面向的 UI 组件useRadioGroup→Radio.Group单选useCheckboxGroup→Checkbox.Group多选useSelect→Select下拉选择。因此你在本文中学到的resource、filters、sorters、optionLabel/optionValue、defaultValue等配置能力可以无缝迁移到其余两个 Hook 上。运行官方示例仓库中的 examples/field-antd-use-radio-group 是完整的可运行示例演示了创建与编辑页面中语言单选组的完整用法src/pages/posts/create.tsx与src/pages/posts/edit.tsx。它基于 Vite 搭建包含App.tsx、interfaces/index.d.ts定义IPost、ILanguage类型等完整工程文件。在仓库根目录执行pnpm install后进入该示例目录运行pnpm dev即可本地启动查看效果。小结useRadioGroup将拉取资源数据 → 转换为单选选项 → 绑定到表单这一重复流程封装为一次 Hook 调用。其底层完全复用useSelect/useList的数据链路天然支持过滤、排序、分页、实时订阅live与自定义查询选项配合optionLabel/optionValue的对象路径与函数两种映射方式几乎可以覆盖任何字段结构的单选需求。在 Refine v5 中它是构建数据驱动型管理后台表单时最高效的单选字段方案。【免费下载链接】refineA React Framework for building internal tools, admin panels, dashboards B2B apps with unmatched flexibility.项目地址: https://gitcode.com/GitHub_Trending/re/refine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考