前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载本篇技术指南基于 react-admin 官方文档《Key Concepts》展开系统讲解 react-admin 赖以构建其代码库的七大核心设计决策单页应用架构、Provider 适配器、智能组件、组合式设计、Hooks 底层 API、Context 拉取模型以及内置组件可替换的开放哲学。文中所有配置示例均可直接运行并辅以本仓库源码packages/ra-core、packages/ra-ui-materialui等的实现证据帮助你从会用组件进阶到理解框架如何被设计。一、七大设计决策总览react-admin 的代码库结构由几个明确的设计决策支撑。理解这些决策就能预判某个功能应该去哪里找、某个问题应该用哪种方式解决。设计决策一句话概括核心对应物Single-Page Application浏览器只加载一次页面壳数据全部走 AJAX内部路由、Resource、CustomRoutesProviders以适配器抽象后端不假设 API 结构dataProvider、authProvider、i18nProviderSmart Components组件既渲染 UI 又管理数据与状态150 个智能组件Composition拒绝上帝组件用组合覆盖配置子组件与children插槽Hooks提供低于组件的 API 层以 Hook 暴露 Controller 逻辑ra-core中数十个以Controller结尾的 HookContext: Pull, Dont Push祖先把数据放上 Context后代用 Hook 拉取RecordContext、I18nProviderContextBatteries Included But Removable内置组件够用但任何组件都可被替换ShowBase、useShowContext等基座下文逐一深入。二、Single-Page Application单页应用与内部路由react-admin 专门为构建**单页应用SPA**而设计。在 react-admin 应用中浏览器仅在首次访问时获取渲染应用所需的 HTML、CSS 和 JavaScript此后所有数据都通过 AJAX 调用从 API 获取。这与传统 Web 应用每个界面都重新拉取一个 HTML 页面的模式形成鲜明对比。SPA 架构带来的收益非常直接应用加载一次后交互极其流畅官方文档在 Features 中将其列为exceptionally fast托管成本极低纯静态资源并且不需要专门的后端就能对接已有 API。2.1 内部路由器与可插拔的路由适配器为了实现点击链接 → 展示对应界面react-admin 在内部维护了一个路由器。默认情况下这个路由器由react-router驱动同时你也可以通过Admin的routerProvider属性切换到TanStack Router参见 TanStackRouter。这套路由器抽象层在源码中位于 packages/ra-core/src/routing/README.md其设计思路与dataProvider、authProvider完全一致——都是 Provider 模式// 默认react-router无需任何配置 Admin dataProvider{dataProvider} Resource nameposts list{PostList} / /Admin // 可选TanStack Router import { tanStackRouterProvider } from react-admin; Admin dataProvider{dataProvider} routerProvider{tanStackRouterProvider} Resource nameposts list{PostList} / /Admin抽象层定义了一个RouterProvider接口契约统一了useLocation、useNavigate、useParams、useBlocker、useMatch等 Hook以及Link、Navigate、Route、Routes、Outlet等组件。应用代码不需要感知底层用的是哪套路由库——这正是以接口而非实现编程的体现。2.2 用Resource与CustomRoutes声明路由开发者通过Resource组件声明 CRUD 路由通过CustomRoutes组件声明其他路由。例如下面的 react-admin 应用import { Admin, Resource, CustomRoutes } from react-admin; import { Route } from react-router-dom; export const App () ( Admin dataProvider{dataProvider} Resource namelabels list{LabelList} edit{LabelEdit} show{LabelShow} / Resource labelgenres list{GenreList} / Resource nameartists list{ArtistList} edit{ArtistDetail} create{ArtistCreate} Route path:id/songs element{SongList /} / Route path:id/songs/:songId element{SongDetail /} / /Resource CustomRoutes Route path/profile element{Profile /} / Route path/organization element{Organization /} / /CustomRoutes /Admin );它声明了以下路由/labelsLabelList/labels/:idLabelEdit/labels/:id/showLabelShow/genresGenreList/artistsArtistList/artists/:idArtistDetail/artists/createArtistCreate/artists/:id/songsSongList/artists/:id/songs/:songIdSongDetail/profileProfile/organizationOrganization值得注意的是Resource内部可以继续嵌套Route如上面的:id/songs并且Resource组件会自动把相关实体的 CRUD 页面互相链接起来。从源码看packages/ra-core/src/core/Resource.tsx 会读取create、edit、list、show四个 prop自动生成对应的路由// packages/ra-core/src/core/Resource.tsx节选 Routes {create Route pathcreate/* element{getElement(create)} /} {show Route path:id/show/* element{getElement(show)} /} {edit Route path:id/* element{getElement(edit)} /} {list ( Route path/* element{getElement(list)} / )} {props.children} /Routes同时Resource.registerResource()会把hasList、hasCreate、hasEdit、hasShow、recordRepresentation等元信息注册到资源定义上下文中ResourceDefinitionContext供菜单、权限等模块读取。因此Resource让你以**实体entity**的视角思考应用而不必陷入手工管理路由的泥潭。2.3 自定义页面CustomRoutes对于登录页、仪表盘、个人主页等非 CRUD 页面CustomRoutes允许你把任意react-router路由挂进应用详见 CustomRoutes。它支持三种变体noLayout不带布局、withLayout带默认布局、以及默认的authenticated需登录。三、Providers适配器模式解耦一切后端react-admin 对 API 的具体结构不做任何假设。它自定义了一套数据获取、认证、国际化与用户偏好的接口语法并通过名为provider的适配器与你的 API 对接。3.1 dataProvider数据的统一入口例如要从 API 获取记录列表可以像下面这样调用dataProvider对象dataProvider.getList(posts, { pagination: { page: 1, perPage: 5 }, sort: { field: title, order: ASC }, filter: { author_id: 12 }, }).then(response { console.log(response); }); // { // data: [ // { id: 452, title: Harry Potter Cast: Where Now?, author_id: 12 }, // { id: 384, title: Hermione: A Feminist Icon, author_id: 12 }, // { id: 496, title: Marauders Map Mysteries, author_id: 12 }, // { id: 123, title: Real-World Roots of Wizard Spells, author_id: 12 }, // { id: 189, title: Your True Hogwarts House Quiz, author_id: 12 }, // ], // total: 27 // }dataProvider.getList()的职责是把这段请求翻译成针对你 API 的 HTTP 请求。当使用 REST 系数据提供器时上面的代码会被翻译为GET http://path.to.my.api/posts?sort[title,ASC]range[0, 4]filter{author_id:12} HTTP/1.1 200 OK Content-Type: application/json Content-Range: posts 0-4/27 [ { id: 452, title: Harry Potter Cast: Where Now?, author_id: 12 }, { id: 384, title: Hermione: A Feminist Icon, author_id: 12 }, { id: 496, title: Marauders Map Mysteries, author_id: 12 }, { id: 123, title: Real-World Roots of Wizard Spells, author_id: 12 }, { id: 189, title: Your True Hogwarts House Quiz, author_id: 12 }, ]可以看到pagination被翻译为range[0, 4]查询参数sort被翻译为sort[title,ASC]filter被翻译为filter{author_id:12}而响应中的Content-Range: posts 0-4/27头则向 react-admin 报告总数total: 27。这套约定具体由ra-data-json-server参见 packages/ra-data-json-server等包实现。react-admin 提供了 超过 50 种 data provider覆盖 REST、GraphQL、Firebase、Django REST Framework、API Platform 等各类后端。如果这些 provider 都不适配你的 API你完全有能力自行开发自定义 provider。3.2 组件不直接 fetch改用数据 Hook正是这套 Provider 模式解释了为什么 react-admin 的组件从不直接调用fetch或axios——它们依赖 data provider 从 API 取数。同样官方强烈建议你的自定义组件也遵循这一模式使用 data provider hooks例如useGetListimport { useGetList } from react-admin; const MyComponent () { const { data, total, loading, error } useGetList(posts, { pagination: { page: 1, perPage: 5 }, sort: { field: title, order: ASC }, filter: { author_id: 12 }, }); if (loading) return Loading /; if (error) return Error /; return ( div h1Found {total} posts matching your query/h1 ul {data.map(record ( li key{record.id}{record.title}/li ))} /ul /div ) };提示上例是官方文档的经典写法。在当前版本中useGetList返回的加载状态字段为isPending见 packages/ra-core/src/dataProvider/useGetList.ts新代码建议按此命名使用。与裸fetch相比useGetList带来了远超数据获取本身的价值。查看 useGetList.ts 的源码实现可以发现它实际构建在tanstack/react-query之上查询缓存与请求去重以[resource, getList, { pagination, sort, filter, meta }]作为queryKey相同参数的重复请求会直接命中缓存getOne 缓存预热当结果不超过MAX_DATA_LENGTH_TO_CACHE100 条时钩子会把列表中的每条记录同步写入该资源的getOne查询缓存让用户点击进入详情页时几乎零等待凭据与 loading 状态管理统一处理用户凭据、加载指示器、错误处理AbortSignal 支持当dataProvider.supportAbortSignal true时自动透传请求中断信号支持组件卸载后取消请求。换句话说useGetList替你处理了凭据、loading 指示器、加载状态、错误、结果缓存、数据形态控制等一系列细节。每当你需要与服务器通信时都会用到这些 provider由于它们各自专注于自己的领域并与 react-admin 深度集成它们会为你节省大量时间与精力。四、Smart Components不仅仅是 UI 组件库react-admin 的出发点是避免开发者反复重写同样的代码——因为大多数 Web 应用都在使用相同的基础构件。为此它提供了一个组件库目前已有 150 多个组件。其中大部分是智能组件smart components它们不仅负责渲染 HTML还接管了数据获取、状态管理和应用内的交互。需要特别强调react-admin不是Material UI 或 Bootstrap 那样的 UI Kit。它超越表现层提供的是针对数据驱动应用量身定制的构建块。虽然它构建在 Material UI 之上但你不必熟悉 Material UI 就能高效使用 react-admin。例如要为应用创建一个自定义菜单可以直接使用Menu组件// in src/MyMenu.js import { Menu } from react-admin; import LabelIcon from mui/icons-material/Label; export const MyMenu () ( Menu Menu.DashboardItem / Menu.ResourceItem nameposts / Menu.ResourceItem namecomments / Menu.ResourceItem nameusers / Menu.Item to/custom-route primaryTextMiscellaneous leftIcon{LabelIcon /}/ /Menu );在这个例子中Menu.DashboardItem链接到/dashboard路由Menu.ResourceItem链接到Resource配置中定义的list页面Menu.Item是通用组件可链接到应用中的任意路由。Menu组件会自动响应应用路由的变化并高亮当前路由。更进一步如果你启用了基于角色的访问控制RBAC用户只会看到自己有权限访问的菜单项——智能组件已经把权限逻辑内置进去了。在动手写自定义组件之前建议先检查 react-admin 是否已提供同名的合适组件。很多时候react-admin 能为你节省数小时乃至数天的开发时间。其他常用组件还包括引导式教程、子表单、登录页、操作按钮、日历等每个组件都可以通过 props、children 和主题theme来定制以贴合应用的具体需求。五、Composition用组合对抗上帝组件react-admin 刻意避免那种接收海量 props 的上帝组件God Components。相反它鼓励组合composition组件通过接收子组件无论是 children 还是特定 props来分摊一部分逻辑。5.1 示例为Edit注入自定义操作区例如你无法直接向Edit组件传一个操作列表但可以通过传入actions组件达到同样效果import { Button } from mui/material; import { TopToolbar, ShowButton } from react-admin; export const PostEdit () ( Edit actions{PostEditActions /} ... /Edit ); const PostEditActions () ( TopToolbar ShowButton / Button colorprimary onClick{customAction}Custom Action/Button /TopToolbar );这种方式让你能够通过用另一个组件组合它来覆盖组件某一部分逻辑。5.2 组合的代价层级覆盖组合模式的代价是有时候为了开启一个特性你可能需要覆盖多个组件。例如要自定义菜单必须先创建一个以你的菜单为menuprop 的自定义布局再把该布局作为Admin的layoutprop// in src/MyLayout.js import { Layout } from react-admin; import { Menu } from ./Menu; export const MyLayout ({ children }) ( Layout menu{Menu} {children} /Layout ); // in src/App.js import { Admin } from react-admin; import { MyLayout } from ./MyLayout; const App () ( Admin layout{MyLayout} dataProvider{...} // ... /Admin );尽管存在这个缺点react-admin 团队依然接受它——因为组合让组件具有极高的可扩展性并显著提升了代码的可读性与可维护性。这条配置覆盖链Admin.layout→Layout.menu→Menu也印证了第四章所述的组合式设计哲学框架鼓励你通过组合小构件来构建大功能而不是为一个组件堆砌无穷无尽的配置项。六、Hooks低于组件的 API 与 MVC 模式当你发现无法用 props 调教某个 react-admin 组件时随时可以转向更底层的 APIhooks。事实上react-admin 的核心是一个名为ra-core的无头headless库即本仓库 packages/ra-core它主要由 hooks 构成。这些 hooks 隐藏了框架的实现细节让你专注于业务逻辑。如果默认 UI 不满足你的特定需求在自己的组件中使用 react-admin 的 hooks 是完全正常且被鼓励的做法。6.1 示例用useDeleteWithConfirmController重建删除按钮以DeleteButton为例在pessimistic悲观模式下它会在点击时渲染确认对话框然后为当前记录调用dataProvider.delete()。如果你想要同样的功能、但换成不同的 UI可以使用useDeleteWithConfirmControllerhookconst DeleteButton () { const resource useResourceContext(); const record useRecordContext(); const { open, isPending, handleDialogOpen, handleDialogClose, handleDelete, } useDeleteWithConfirmController({ redirect: list }); return ( Fragment Button onClick{handleDialogOpen} labelra.action.delete {icon} /Button Confirm isOpen{open} loading{isPending} titlera.message.delete_title contentra.message.delete_content titleTranslateOptions{{ name: resource, id: record.id, }} contentTranslateOptions{{ name: resource, id: record.id, }} onConfirm{handleDelete} onClose{handleDialogClose} / /Fragment ); };查看 useDeleteWithConfirmController.tsx 的实现可以看到它内部组合了useDeleteController、useResourceContext、useRecordContext、useNotify、useUnselect、useRedirect、useTranslate等多个 hookshandleDialogOpen/handleDialogClose负责开关确认对话框handleDelete在确认后执行删除、发送通知、取消选中并重定向到list。也就是说这个 hook 已经把删除 确认 通知 跳转的完整控制器逻辑全部封装好了你只需替换表现层。6.2 Hook 命名与 MVC 模式hook 名常以Controller结尾这是有意的设计——它反映了 react-admin 在复杂组件上使用的模型-视图-控制器MVC模式Controller 逻辑由 React hooks 承担例如useListController视图逻辑由 React 组件承担例如List模型逻辑留给开发者react-admin 只通过 Providers 定义模型必须暴露的接口。以列表页为例useListController.ts 统一负责认证检查useAuthenticated、权限检查useRequireAccess、列表参数管理useListParams支持与 URL 同步、防抖 500ms、记录选择useRecordSelection以及调用useGetList获取数据而List组件只负责把这些 controller 返回值渲染成 MUI 界面。这种控制器与视图分离的结构让你可以完全绕过默认视图自己搭建 UI。react-admin 公开了数十个 hooks 来辅助你构建自己的组件。你甚至可以完全不依赖 Material UI 组件用其他 UI 框架例如 Shadcn UI 风格的 admin 组件库构建完整的 react-admin 应用——这种灵活性允许你按自己的特定需求定制应用。七、ContextPull, Dont Push拉取而非推送在大型 React 应用中跨层级传递 props 是一件很痛苦的事。react-admin 用**拉取模型pull model**解决这一问题组件通过 context 向其后代暴露 props后代则通过自定义 hooks 消费这些 props。每当一个 react-admin 组件获取数据或定义回调时它就会创建一个 context并把数据和回调放进去。不要用依赖注入系统也不用手工逐层透传——从 context 里拉取即可。7.1 国际化I18nProviderContext与useTranslate例如Admin组件会创建一个I18nProviderContext其中暴露了translate函数。应用中所有组件都可以通过useTranslatehook 读取这个 context 来翻译标签和消息import { useTranslate } from react-admin; export const MyHelloButton ({ handleClick }) { const translate useTranslate(); return ( button onClick{handleClick}{translate(root.hello.world)}/button ); };源码层面I18nContextProvider.tsx 把i18nProvider存入 React context并监听 store 中的locale变化一旦 locale 改变就调用value.changeLocale(locale)重新加载语言包并通过更新 context 的key强制整棵子树重渲染从而保证所有translate()调用都拿到新语言。而 useTranslate.ts 则通过useI18nProvider()读取 context返回一个闭包形式的translate(key, options)函数——这就是拉取模型的标准用法。7.2 记录数据RecordContext与useRecordContext同理Show组件会获取一条记录并通过RecordContext暴露它。在Show内部你可以用useRecordContexthook 访问记录数据。例如用它在地图上展示记录的位置import { useRecordContext } from react-admin; import { MapContainer, TileLayer, Marker } from react-leaflet; const LocationField ({ source }) { const record useRecordContext(props); // use the RecordContext created by Show if (!record) return null; return ( MapContainer center{record[source]} zoom{13} scrollWheelZoom{false} TileLayer attributioncopy; a hrefhttps://www.openstreetmap.org/copyrightOpenStreetMap/a contributors urlhttps://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png / Marker position{record[source]} / /MapContainer ); }; const StoreShowPage () ( Show {/* create a RecordContext */} SimpleShowLayout TextField sourcename / LocationField sourcelocation / /SimpleShowLayout /Show )从 useRecordContext.ts 的实现看它优先读取传入的props.record允许通过 props 覆盖否则回退到读取RecordContext的当前值// packages/ra-core/src/controller/record/useRecordContext.ts节选 const context useContextRecordType | undefined(RecordContext); return (props props.record) || context;这套模式消除了对依赖注入系统的需求为从渲染树更高层访问数据和回调提供了一套优雅的解决方案。因此当你编写的组件需要访问渲染树更上层定义的数据或回调时总能找到一个 context 来获取它。Context 是 react-admin 的基础概念。如果你对 React Context 还不熟悉建议先阅读 React 官方文档中关于用 Context 深层传递数据的章节——理解 Context 会大大加深你对 react-admin 如何借此构建强大而灵活的框架的理解。八、Batteries Included But Removable内置组件可替换react-admin 允许你仅使用内置组件构建复杂的 Web 应用——前提是它的设计选择符合你的需求。但如果某个组件的能力不满足你的特定要求你完全可以自由地用自定义组件替换它。8.1 示例自定义详情页布局例如如果SimpleShowLayout不允许你像下图这样排布联系人详情你可以创建并使用自己的布局组件export const ContactShow () ( ShowBase ContactShowContent / /ShowBase ); const ContactShowContent () { const { record, isPending } useShowContextContact(); if (isPending || !record) return null; return ( Box sx{{ mt: 2, display: flex }} Box sx{{ flex: 1 }} Card CardContent Box sx{{ display: flex }} Avatar / Box sx{{ ml: 2, flex: 1 }} Typography varianth5 {record.first_name} {record.last_name} /Typography Typography variantbody2 {record.title} at{ } ReferenceField sourcecompany_id referencecompanies linkshow TextField sourcename / /ReferenceField /Typography /Box Box ReferenceField sourcecompany_id referencecompanies linkshow LogoField / /ReferenceField /Box /Box ReferenceManyField targetcontact_id referencecontactNotes sort{{ field: date, order: DESC }} NotesIterator showStatus referencecontacts / /ReferenceManyField /CardContent /Card /Box ContactAside / /Box ); };这个示例来自 Atomic CRM之一。注意它的实现手法ShowBase只提供数据获取与 contextController 层布局完全由你自己的 JSX 决定——这正是前文Hooks 与 MVC章节所讲机制的实战运用。永远不要犹豫用自己设计的组件替换 react-admin 的组件。react-admin 并不试图覆盖所有可能的用例相反它提供 hooks 来接入自定义组件。正如官方所强调的Its just React。有了这套可替换机制你永远不会被 react-admin 逼到墙角。九、Awesome Developer Experience为开发者体验设计在 react-admin 中开发者只需要组装应用组件不必操心底层细节同样的结果需要更少的代码你可以把精力集中在业务逻辑上。react-admin 团队将组件与 hooks 的 API 设计得尽可能直观并且团队每天自身就在使用 react-admin持续寻找改善开发者体验的方式。官方文档宣称提供一流的文档、演示应用与支持错误信息清晰且可操作得益于完善的 TypeScript 类型与 JSDoc在任何 IDE 中都能轻松使用API 稳定破坏性变更非常罕见可以用查询日志和表单开发者工具调试应用还能直接在浏览器中检查 react-admin 的源码。从仓库结构也能直观感受到这一点packages/ra-core中的每个 hook 都配有对应的.spec.tsx测试例如 useGetList.spec.tsx、useDeleteWithConfirmController.spec.tsx以及 Storybook 故事文件这些既是回归保障也是可运行示例级别的文档。因此react-admin 并不是 React Query、react-hook-form、react-router、Material UI 与 Emotion 的简单拼装而是一个框架——一个为加速和简化 React 单页应用开发而生的框架。十、总结一份架构心智模型回顾全文react-admin 的七大设计决策环环相扣SPA 与内部路由让你以实体为单位思考应用由Resource自动生成 CRUD 路由CustomRoutes承接自定义页面路由器本身还可插拔Providers用适配器隔离后端差异dataProvider/authProvider/i18nProvider各司其职组件只通过 hooks 与它们通信智能组件把数据获取、状态与渲染打包在一起同时保持仍是 React的可定制性组合优先拒绝了上帝组件代价是偶尔需要多级覆盖如Admin.layout→Layout.menuHooks 作为底层 API以useXxxController落实 MVC 模式让ra-core成为可脱离 UI 独立使用的无头核心Context 拉取模型让任意深度的后代组件都能拿到数据与回调无需依赖注入内置组件可替换保证框架永远不把开发者逼入死角。这套架构的关键源码入口都集中在 packages/ra-core核心逻辑与 packages/ra-ui-materialuiMUI 视图层。建议读者对照本仓库源码继续深挖阅读 Resource.tsx 理解路由生成阅读 useGetList.ts 理解缓存机制阅读 routing/README.md 理解路由器抽象。掌握了这套心智模型你就能预判 react-admin 的扩展点在哪里并在绝大多数场景下写出少而准的应用代码。赞分享前端UI组件【免费下载链接】react-adminA frontend Framework for single-page applications on top of REST/GraphQL APIs, using TypeScript, React and Material Design项目地址https://gitcode.com/gh_mirrors/re/react-admin点击查看免费下载相关推荐如何快速掌握Tangram-Android核心架构Card与Cell的设计哲学全解析如何快速掌握Tangram Android核心架构Card与Cell的设计哲学全解析 Tangram Android是一套模块化UI解决方案能够帮助开发者动移动开发前端UI组件深度解析gpt-ai-assistant架构从Context到Bot类的核心设计哲学深度解析gpt ai assistant架构从Context到Bot类的核心设计哲学 架构全景重新定义AI助手的模块化设计 你是否曾在构建AI助手时面临上下AI 应用交互助手后端PPT Master AI 生成原生 PowerPoint 完整指南PPT Master AI 生成原生 PowerPoint 完整指南 内容备好了对着空白模板却不知从何排起PPT Master 是一款开源的 AI 演示文稿AI 技能人工智能AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考