React Router 声明式模式 URL 值完全指南路由参数、URL Search Params 与 Location 对象【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router本文基于react-router仓库中的 docs/start/declarative/url-values.md 展开。React Router 把 URL 中携带的信息归纳为三种“URL 值”——路径中的动态段route params、?之后的查询参数search params以及承载整条 URL 细节的 location 对象。掌握它们你就掌握了声明式路由下URL 即状态的读写基础既能从地址栏读出当前页面上下文也能在组件里自由拼装下一次导航的目标。读完本文你将能够熟练使用useParams、useSearchParams与useLocation三个 Hook并结合源码理解它们的取值与联动机制。适用范围本文面向Declarative声明式模式即通过BrowserRouter/Routes/Route组合而非数据路由data routers的方式来组织路由。若使用 Framework 或 Data 模式URL 值的读取方式基本相同但数据加载会改由loader/action承担参见 docs/start/index.md 中三种模式的划分与 docs/start/declarative/index.md。一、URL 值的三种形态总览一个典型的 URLhttps://example.com/concerts/shanghai?sortdate#top中React Router 关注的三个部分分别是URL 形态示例读取 Hook返回类型动态段参数route params/concerts/shanghai中的shanghaiuseParams()ReadonlyParams对象查询参数search paramssortdateuseSearchParams()[URLSearchParams, SetURLSearchParams]元组location 对象整个 pathname / search / hash / key / stateuseLocation()Location对象三者背后都指向同一个事实路由在内部维护一条当前 location这些 Hook 只是以不同视角对外暴露它。下面逐一深入。二、Route Params读取动态段解析值2.1 动态段与解析值Route params 是从 URL 的**动态段dynamic segment**中解析出来的值。在声明式路由中先通过Route的path声明动态段Route path/concerts/:city element{City /} /此时:city就是一个动态段。当 URL 为/concerts/shanghai时该段位对应的解析值shanghai会出现在useParams的返回值里import { useParams } from react-router; function City() { let { city } useParams(); let data useFakeDataLibrary(/api/v2/cities/${city}); // ... }这正是原文档的经典示例。注意city是字符串即便动态段里是数字如/users/42解析出的42仍是字符串需要自行转换。2.2 多参数与通配参数catchall动态段可以在一条路径中多处出现所有解析值会共同放进同一个 params 对象。以useParams的类型文档packages/react-router/lib/hooks.tsx中的例子为证// 路由声明 // /posts/:postId/comments/:commentId import { useParams } from react-router; export default function Post() { let params useParams(); return ( h1 Post: {params.postId}, Comment: {params.commentId} /h1 ); }此外路径段还支持以*结尾的通配段catchall / splat例如/files/*。它会匹配剩余的任意多层路径并在 params 中以*为键存放因此既可以下标访问也可以解构export default function File() { let params useParams(); let catchall params[*]; // 或使用解构别名 // let { *: catchall } useParams(); // console.log(catchall); }更完整的路径语法可选段、无路径路由、通配匹配规则可参考 docs/start/declarative/routing.md。2.3 源码视角params 从哪来useParams的实现packages/react-router/lib/hooks.tsx非常短但信息量很大export function useParams ParamsOrKey extends string | Recordstring, string | undefined string, (): Readonly [ParamsOrKey] extends [string] ? ParamsParamsOrKey : PartialParamsOrKey { let { matches } React.useContext(RouteContext); let routeMatch matches[matches.length - 1]; return (routeMatch?.params ?? {}) as any; }从中可以提炼出三个关键点取值来自 RouteContext当前激活的路由匹配结果matches被放进 React ContextuseParams直接读取最深一层匹配matches[matches.length - 1]的params。未命中返回空对象若不存在匹配routeMatch为空返回{}不会抛错。类型由路径静态推导泛型约束使得当路由由字面量路径模式驱动时TypeScript 能推导出形如{ city?: string }的准确类型配合useParams的类型参数可获得更强的类型安全参考 docs/start/declarative/route-object.md 与 docs/start/data/route-object.md 中的类型推导讨论。实际动态段的解析与 URL 解码发生在路由匹配阶段matchRoutes等模块因此 params 中的值已经是解码后的、可直接使用的字符串。useParams属于路由上下文敏感 Hook若在Router/Routes之外调用相关的useInRouterContext保护packages/react-router/lib/hooks.tsx会通过 invariant 抛错。三、URL Search Params读写?查询字符串3.1 读取查询参数Search params 是 URL 中?之后的一串keyvaluekey2value2键值对。useSearchParams返回的查询参数是一个Web 平台内置的URLSearchParams实例因此可以直接调用其全部标准方法get/getAll/has/entries等无需学习额外 APIimport { useSearchParams } from react-router; function SearchResults() { let [searchParams] useSearchParams(); return ( div p You searched for i{searchParams.get(q)}/i /p FakeSearchResults / /div ); }例如访问/search?qreactsortstarssearchParams.get(q)返回reactsearchParams.get(sort)返回stars。多个相同键的值可用getAll获取如?tagatagb。与动态段同理URL 中的百分号编码也会由URLSearchParams自动完成解码。3.2 更新查询参数setSearchParams元组的第二个元素是setSearchParams函数调用它会触发一次导航从而把新参数写进地址栏。可传入的形态包括查询字符串、键值对象、元组数组或现成的URLSearchParams实例let [searchParams, setSearchParams] useSearchParams(); // 追加单个参数跳转后 URL 包含 ?tab1 setSearchParams({ tab: 1 }); // 覆盖整个查询字符串 setSearchParams(?qreactpage2); // 支持函数式更新基于当前参数 setSearchParams((prev) { prev.set(tab, 2); return prev; });setSearchParams也接收第二个navigateOptions参数如{ replace: true }、{ preventScrollReset: true }语义与useNavigate的选项一致可参考 docs/start/declarative/navigating.md 与 docs/api/hooks/useNavigate.md。3.3 源码视角searchParams 的合并与稳定性useSearchParams的实现位于 packages/react-router/lib/dom/lib.tsx其核心行为可从源码归纳默认值合并可通过useSearchParams(defaultInit)提供默认参数支持字符串、对象、数组、URLSearchParams等URLSearchParamsInit形态。默认值只在首次渲染时兜底并不会真正修改 URL而且一旦调用过setSearchParams后续渲染就不再并入默认值——否则你就永远无法通过setSearchParams({})把某个默认参数删掉了。相关逻辑见getSearchParamsForLocationpackages/react-router/lib/dom/dom.ts。写入即导航setSearchParams内部本质是navigate(? newSearchParams, navigateOptions)也就是把序列化后的查询串拼到当前路径后面发起一次标准导航。引用稳定性searchParams是通过useMemo按location.search缓存出来的稳定引用适合放进useEffect的依赖数组但注意返回的对象是可变的如果直接修改它却不调用setSearchParamsURL 不会变化而对象内容却可能因其它渲染而漂移——这正是源码注释中特别提示的陷阱packages/react-router/lib/dom/lib.tsx。// searchParams 引用稳定可安全作为 effect 依赖 useEffect(() { console.log(searchParams.get(tab)); }, [searchParams]);另外仓库在浏览器不支持URLSearchParams的场景下如老 IE会打印一段 polyfill 建议packages/react-router/lib/dom/lib.tsx现代浏览器环境下无需任何额外处理。四、Location Object整条 URL 的上下文4.1 认识 location 对象React Router 内部维护了一个自定义的location对象它是对当前 URL 的结构化描述。从类型定义packages/react-router/lib/router/history.ts可以看到它的完整形态export interface LocationState any extends Path { state: State; // 与该 location 绑定的任意历史状态 key: string; // 唯一 key初始 location 恒为 default mask?: Path; // 地址栏显示但并非路由实际操作的 URL框架内部使用 }由于它继承了Path同时具备pathname、search、hash三个属性。可通过useLocation()在任意组件中读取import { useLocation } from react-router; function useAnalytics() { let location useLocation(); useEffect(() { sendFakeAnalytics(location.pathname); }, [location]); } function useScrollRestoration() { let location useLocation(); useEffect(() { fakeRestoreScroll(location.key); }, [location]); }这是原文档的完整示例。它展示了两类典型的 location 消费方式按 pathname 上报每次路由切换location变化时上报当前页面路径天然适配埋点/分析需求按 key 做副作用去重location.key在每个新 location 上都是唯一字符串可用作滚动位置恢复、缓存键或localStorage存储的关联标识。4.2 location 各字段的含义字段含义典型用途pathname路径部分如/concerts/shanghai判断当前路由、上报埋点search查询字符串含?如?sortdate配合createSearchParams解析出结构化的参数hash锚点部分含#如#top处理页内定位state导航时携带的任意数据跨页传递非 URL 敏感信息keylocation 唯一标识首个 location 恒为default滚动恢复、状态存储的关联键mask地址栏掩码后的展示 URL区别于路由实际操作的 URL框架级内部能力4.3 源码视角location 是单一数据源useLocation的实现packages/react-router/lib/hooks.tsx只是从LocationContext取出当前location并做一次上下文存在性检查export function useLocation(): Location { invariant( useInRouterContext(), useLocation() may be used only in the context of a Router component., ); return React.useContext(LocationContext).location; }也就是说React Router 的所有导航能力Link、useNavigate、useSearchParams、useParams、NavLink的激活态判断等最终都以同一个 location 为数据源。正因为如此我们还可以读取到导航的类型——useNavigationType()返回当前 location 是通过POP、PUSH还是REPLACE到达的packages/react-router/lib/hooks.tsx这同样是基于LocationContext中记录的navigationType。想进一步按路径模式匹配当前 location例如计算激活路由可结合useMatch或useLocation与matchPath声明式模式下还可用useRoutes根据 location 动态渲染。这些 Hook 的完整 API 见 docs/api/hooks/useParams.md、docs/api/hooks/useSearchParams.md 与 docs/api/hooks/useLocation.md。五、综合实战把三种 URL 值串起来真实业务里三者经常协同出现。例如一个带城市过滤、关键词与排序的可分享搜索页import { useParams, useSearchParams } from react-router; // 假设路由/concerts/:city 下渲染本组件URL 形如 // /concerts/shanghai?genrerocksortdate function ConcertList() { let { city } useParams(); // shanghai let [searchParams, setSearchParams] useSearchParams(); let genre searchParams.get(genre); // rock let sort searchParams.get(sort); // date function toggleGenre(value: string) { // 函数式更新可安全基于最新值叠加 setSearchParams((prev) { if (prev.get(genre) value) { prev.delete(genre); // 再次点击则移除过滤 } else { prev.set(genre, value); } return prev; }, { replace: true }); } // fetch(/api/concerts/${city}?genre${genre}sort${sort}) return ( button onClick{() toggleGenre(rock)} 切换流派{genre ?? 全部} /button ); }这段代码把三类 URL 值各自用到了正确的位置路径参数承载所在实体/页面的身份城市搜索参数承载页面上可调整的视图状态过滤与排序而需要观察整条 URL 变化时如滚动恢复、埋点再使用useLocation。如何取舍三者内容标识与深链接语义应放进路径参数如/concerts/:city可分享、可回退、无需改动路由层级的临时状态应放进搜索参数如排序、分页、筛选天然支持前进后退与刷新保留与具体渲染、历史栈关联的副作用逻辑应观察location 对象或其key、pathname。六、小结与延伸阅读本文以 docs/start/declarative/url-values.md 为主干围绕声明式模式下的三种 URL 值展开Route Params——由:param动态段解析而来经useParams读取支持多参数与*通配段深层实现从RouteContext的matches末项取参packages/react-router/lib/hooks.tsx。URL Search Params——?后的键值对经useSearchParams以原生URLSearchParams形式暴露setSearchParams本质是一次携带新查询串的导航并支持默认值、函数式更新与导航选项packages/react-router/lib/dom/lib.tsx。Location Object——由useLocation读取的完整 location含pathname/search/hash/state/key/mask是路由匹配、导航与副作用观察的公共数据源packages/react-router/lib/router/history.ts。想继续深入建议按以下顺序阅读仓库文档声明式模式路由与导航基础docs/start/declarative/routing.md、docs/start/declarative/navigating.md、docs/start/declarative/url-values.md三种模式的差异与选择docs/start/modes.md、docs/start/index.md各 Hook 的完整类型签名与示例docs/api/hooks/index.md类型安全的参数推导实践docs/start/data/route-object.md。【免费下载链接】react-routerDeclarative routing for React项目地址: https://gitcode.com/GitHub_Trending/re/react-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考