react-adminAuthenticated组件完全指南用声明式 JSX 保护自定义路由【免费下载链接】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-adminAuthenticated是 react-admin 提供的一个声明式身份认证组件它在挂载时调用authProvider.checkAuth()认证通过则渲染子组件失败则自动跳转到登录页。本文以 docs/Authenticated.md 为骨架结合ra-core包中的源码与测试用例深入讲解该组件的使用方式、props 语义、底层实现原理及其与useAuthenticated、useAuthState等 hook 的协作关系帮助你为自定义页面、外部路由等场景快速加上登录保护。一、组件定位何时使用Authenticated在 react-admin 应用中一旦配置了authProviderlist、edit、create、show等资源页面会自动受认证保护匿名用户会被重定向到/login。但是通过CustomRoutes添加的自定义页面默认是对匿名用户开放的参见 docs/Authentication.md#restricting-access-to-custom-pages。Authenticated组件正是用于收紧这一默认行为的。它等价于useAuthenticated()hook 的组件化封装适用场景是在无法使用 hook 的地方例如react-router的Route element属性中快速为一段 JSX 加上认证门槛import { Admin, CustomRoutes, Authenticated } from react-admin; import { Route } from react-router-dom; const App () ( Admin authProvider{authProvider} CustomRoutes Route path/foo element{AuthenticatedFoo //Authenticated} / Route path/anonymous element{Baz /} / /CustomRoutes /Admin );上例中/foo只有已登录用户才能访问而/anonymous保持公开。这一用法与 docs/Authentication.md 中“Restricting Access To Custom Pages”一节的推荐做法完全一致。二、工作原理一次checkAuth调用三种渲染状态Authenticated的核心逻辑非常简洁其完整实现位于 packages/ra-core/src/auth/Authenticated.tsxexport const Authenticated (props: AuthenticatedProps) { const { authParams, loading null, children } props; // this hook will redirect to login if the user is not authenticated const { isPending, isError } useAuthenticated({ params: authParams }); if (isPending || isError) { return loading; } return {children}/; };整个组件的生命周期可概括为三个阶段挂载检查组件挂载时内部调用useAuthenticated({ params: authParams })进而触发authProvider.checkAuth()异步方法。加载中检查尚未完成时isPending为true组件渲染loading节点默认null即渲染空内容。结果分发checkAuth成功 resolve → 渲染childrencheckAuth抛错reject→isError为true绝不渲染子组件同时内部 hook 已负责登出与重定向。需要特别指出源码中判断条件是if (isPending || isError) return loading;也就是说认证失败时子组件同样不会被渲染避免了把受保护内容短暂暴露给匿名用户的竞态问题。测试用例 packages/ra-core/src/auth/Authenticated.spec.tsx 中专门验证了这一行为当checkAuthreject 时NeverDisplayedComponent被调用次数为 0。三、Props 全解原文档给出了完整的 props 表格这里逐一展开说明Prop必填类型默认值说明children是ReactNode—认证通过后渲染的内容authParams否any{}传递给authProvider.checkAuth()的参数对象loading否ReactNodenull认证检查期间显示的加载内容3.1children受保护的渲染内容可以是一个普通元素、一个页面组件或任意 React 节点。需要明确的是只有checkAuth()成功 resolve 时才会渲染。源码的 JSDoc 示例展示了如何用它装饰自定义页面组件参见 packages/ra-core/src/auth/Authenticated.tsxconst customRoutes [ Route path/foo element{ Authenticated authParams{{ foo: bar }} Foo / /Authenticated } / ];3.2authParams把上下文信息传给认证逻辑默认值为{}。该参数会原样透传给authProvider.checkAuth()。如果你的认证策略需要区分场景——例如某些页面要求更严格的校验、某些页面只是轻量鉴权——可以通过它携带上下文Authenticated authParams{{ action: access_admin_panel }} AdminPanel / /Authenticated从源码调用链看authParams最终会进入useAuthenticated({ params: authParams })而useAuthenticated又会把它作为params转发给底层的useAuthState参见 packages/ra-core/src/auth/useAuthenticated.ts。useAuthState在 query 函数中这样调用await authProvider.checkAuth({ ...params, signal });即authParams展开后与一个signalreact-query 的请求取消信号合并作为checkAuth的唯一入参参见 packages/ra-core/src/auth/useAuthState.ts。测试 packages/ra-core/src/auth/useAuthenticated.spec.tsx 证实更新params触发重渲染后checkAuth会以{ foo: bar, signal }的形式再次被调用。3.3loading加载期 UI默认值为null渲染空白。由于checkAuth是异步调用在结果返回之前组件会保持 loading 状态。你可以传入骨架屏、Loading /或自定义提示Authenticated loading{CircularProgress /} Foo / /Authenticated测试用例 packages/ra-core/src/auth/Authenticated.spec.tsx 使用一个永不 resolve 的checkAuth验证了 loading 分支checkAuth挂起时Authenticated只渲染传入的loading节点而不渲染子组件。四、认证失败后发生了什么当checkAuth()抛错时组件本身只负责“不渲染子组件”真正的登出与重定向逻辑由底层 hook 完成。完整链路如下useAuthenticated默认logoutOnFailure: true将失败处理委托给useAuthState。useAuthState的默认onError回调packages/ra-core/src/auth/useAuthState.ts会依次调用logout({}, redirectTo)其中redirectTo优先取错误对象上的error.redirectTo否则取${basename}/login清除 storereset通过notify()弹出错误通知消息默认取自error.message否则使用ra.auth.auth_check_error英文环境下的文案是 “Please login to continue”见 packages/ra-language-english/src/index.ts若error.message false则跳过通知实现“静默登出”。测试 packages/ra-core/src/auth/Authenticated.spec.tsx 完整断言了这一失败路径checkAuthreject 后logout被调用、store 被重置、通知列表中出现ra.auth.auth_check_error且登录页能通过location.state.nextPathname得知用户原本想访问的路径/。4.1 结合checkAuth契约定制失败行为checkAuth的契约定义在 docs/AuthProviderWriting.md#checkauth 中on reject 时登出并重定向到登录页可定制。你可以通过抛出的错误对象精确控制行为const authProvider { async checkAuth() { if (!localStorage.getItem(auth)) { const error new Error(); error.redirectTo /no-access; // 自定义重定向目标覆盖默认 /login throw error; } }, // ... };还可通过error.message定制通知文案或设置为false关闭通知若checkAuth与logout都返回了重定向地址checkAuth的优先级更高详见 docs/AuthProviderWriting.md#checkauth。五、与 hook 方案如何取舍Authenticated并非唯一选择官方文档docs/useAuthenticated.md与 docs/Authentication.md 中给出了完整的决策图谱场景推荐方案无法使用 hook如Route element内Authenticated组件自定义页面组件内部且希望显示加载态useAuthenticated()hook需要根据认证状态渲染不同内容如“登录后显示 A匿名显示 B”useAuthState()hook需要手动触发一次性校验低层 APIuseCheckAuth()useAuthenticatedhook 的用法示例redirects to login if not authenticatedimport { useAuthenticated } from react-admin; const MyPage () { const { isPending } useAuthenticated(); // 未认证时自动跳转登录页 if (isPending) return divChecking auth.../div; return div.../div; };它接受一个 options 对象除params外还支持logoutOnFailure默认true设为false可禁止失败时登出其余参数会作为 react-queryuseQuery的选项透传从而支持自定义onSuccess、onError、meta、retryDelay等副作用。源码类型定义见 packages/ra-core/src/auth/useAuthenticated.ts。5.1 注意useAuthenticated默认不阻塞渲染值得留意的是useAuthenticated底层的useAuthState在默认情况下不阻止首帧渲染——测试 packages/ra-core/src/auth/useAuthenticated.spec.tsx 证明checkAuth未返回时子组件已经渲染只是logoutOnFailure为true时失败后会在下一轮被重定向走。而Authenticated组件则通过isPending || isError主动拦截了这段窗口期行为更严格。如果你希望在页面加载前就阻塞并等待认证结果可使用useAuthState参见 docs/useAuthState.md或useAuthenticated的 loading 分支自行处理。六、组合实践受保护的自定义路由综合以上内容一个完整的“受保护自定义页面”实践如下import { Admin, CustomRoutes, Authenticated } from react-admin; import { Route } from react-router-dom; import { CircularProgress } from mui/material; const RestrictedPage () ( Authenticated loading{CircularProgress /} authParams{{ page: settings }} div仅登录用户可见的设置页/div /Authenticated ); const AnonymousPage () div公开页面/div; const App () ( Admin authProvider{authProvider} CustomRoutes Route path/settings element{RestrictedPage /} / Route path/about element{AnonymousPage /} / /CustomRoutes /Admin );若你的应用完全不允许匿名访问不必逐个页面包裹Authenticated更省事的做法是在Admin上设置requireAuthprop——它会等待authProvider.checkAuth()resolve 后才渲染布局从根本上隐藏菜单等敏感信息详见 docs/Authentication.md#disabling-anonymous-access。七、延伸阅读docs/useAuthenticated.mdAuthenticated对应的 hook 版本文档docs/useAuthState.md获取认证状态、按状态渲染不同内容的 hookdocs/AuthProviderWriting.md#checkauthcheckAuth方法契约与错误定制docs/Authentication.md认证体系总览含自定义页面保护、requireAuth、匿名访问策略packages/ra-core/src/auth/Authenticated.tsx组件实现源码packages/ra-core/src/auth/useAuthenticated.tshook 实现源码packages/ra-core/src/auth/Authenticated.spec.tsx组件测试用例覆盖加载、失败、成功、登出重定向四种场景【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考