TanStack Router RouteMask 类型详解:声明式路由掩码(Location Masking)的原理与实战
TanStack Router RouteMask 类型详解:声明式路由掩码(Location Masking)的原理与实战
本篇基于 RouteMask 类型文档 展开,讲解 TanStack Router 中 RouteMask 类型的完整结构、createRouteMask 辅助函数、routeMasks 路由级掩码的注册方式,以及路由器在构建 location 时如何匹配掩码并生成 maskedLocation。读完你可以掌握「URL 显示一条路径、页面渲染另一条路由」的路由掩码能力(典型场景:用模态框呈现详情而不改变地址栏),并理解其底层匹配链路与测试验证方式。
什么是路由掩码
路由掩码(route masking / location masking)的核心目标是:浏览器地址栏显示的路径(masked location)与路由器实际匹配、渲染的路由(真实 location)可以不一致。
例如一个照片详情模态框:用户点击照片列表项后,地址栏仍停留在 /photos/123(可分享、刷新可用),而页面渲染的其实是 /photos/123/modal 这条路由。这样即使刷新页面、在新标签页打开,得到的也是正常的照片详情页而不是一个"没有上下文的模态框"。
TanStack Router 提供两种使用方式:
- 内联
mask选项:在Link组件或useNavigate的to选项中直接传mask: { to, params, ... },属于单次导航级别的临时掩码; - 路由级
RouteMask:声明一组RouteMask并通过createRouter({ routeMasks })注册,由路由器在每次构建 location 时自动匹配生效,这是本篇文档的主体。
两者的关系从测试中可以确认:显式传入的 mask 选项优先于已配置的 routeMasks(见 packages/router-core/tests/mask.test.ts 中 "should prefer an explicit mask over a configured route mask" 用例)。
RouteMask 类型结构
RouteMask 文档 的定义是:RouteMask 类型扩展了 ToOptions 类型,并包含创建路由掩码所需的其余属性。
类型定义一览
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
...ToOptions |
ToOptions |
是 | 用于配置路由掩码的导航选项 |
routeTree |
TRouteTree |
是 | 该路由掩码所支持的路由树 |
unmaskOnReload |
boolean |
否 | 为 true 时,页面刷新后路由掩码会被移除 |
ToOptions 本身的定义来自 ToOptions 类型文档 与 link.ts 源码,核心字段为:
type ToOptions = {
from?: ValidRoutePath | string
to?: ValidRoutePath | string
hash?: true | string | ((prev?: string) => string)
state?: true | HistoryState | ((prev: HistoryState) => HistoryState)
} & SearchParamOptions & // search?: true | TToSearch | ((prev) => TToSearch)
PathParamOptions & // params?: true | Record<string, TPathParam> | ((prev) => TToParams)
MaskOptions // mask?: ToMaskOptions<TRouter, TMaskFrom, TMaskTo>
type ToMaskOptions = ToSubOptions & {
unmaskOnReload?: boolean // 内联 mask 场景下同样支持 unmaskOnReload
}
在源码中,RouteMask 被展开为扁平结构,定义于 route.ts:
export type RouteMask<TRouteTree extends AnyRoute> = {
routeTree: TRouteTree
from: RoutePaths<TRouteTree> // 需要被"遮盖"的真实路由路径(支持路由参数)
to?: any // 掩码显示的目标路径(类型上放宽为 any)
params?: any // true / 对象 / 函数,决定掩码 URL 中的参数
search?: any // 掩码 URL 的 search 参数
hash?: any // 掩码 URL 的 hash
state?: any // history state
unmaskOnReload?: boolean // 页面刷新时是否移除掩码
}
可以看出,文档中的 ...ToOptions 在实现层面即对应 from / to / params / search / hash / state 这组导航字段,外加 routeTree 与 unmaskOnReload 两个掩码专属字段:
from(必填语义):真实路由路径,可以包含$paramId这样的路径参数。路由器会把导航结果的路径与所有RouteMask.from做模式匹配;to:匹配命中后,掩码 URL 要显示的路径,其中$paramId会用匹配到的参数插值;params: true:把from匹配到的原始参数原样带入掩码 URL(例如/photos/123/modal匹配后显示/photos/123);params也可以是对象或函数(函数以匹配到的参数为上下文),测试中验证了params为函数时的求值行为;unmaskOnReload:为true时页面重新加载后掩码被移除,地址栏回到真实路径;对应地,buildLocation的返回值中会携带unmaskOnReload标记(见 router.ts),供提交 location 到 history 时使用。
createRouteMask 辅助函数
类型之外,各框架包提供了 createRouteMask 帮助函数来实例化掩码。以 React 为例,实现位于 route.tsx:
export function createRouteMask<
TRouteTree extends AnyRoute,
TFrom extends string,
TTo extends string,
>(
opts: {
routeTree: TRouteTree
} & ToMaskOptions<RouterCore<TRouteTree, 'never', boolean>, TFrom, TTo>,
): RouteMask<TRouteTree> {
return opts as any
}
它的职责是类型收窄:借助 ToMaskOptions 与路由树的联合,from 会被约束为该路由树中真实存在的路径(RoutePaths<TRouteTree>),而 to 也受路由树路径约束,从而在编译期拦截拼写错误的路径。返回值就是一个可直接放入 routeMasks 数组的 RouteMask。
在路由器中注册 routeMasks
RouteMask 数组通过路由器的 routeMasks 选项注册,定义在 router.ts 的 RouterOptions 中(routeMasks?: Array<RouteMask<TRouteTree>>,约 L393)。注册后,路由器在处理路由树时会调用 new-process-route-tree.ts 中的 processRouteMasks,把扁平的掩码列表构建成一棵 segment tree(masksTree) 并配套一个容量为 1000 的 SieveCache(flatCache)用于缓存匹配结果。
从源码结构看,匹配入口是 findFlatMatch(path, processedTree):先查缓存,未命中才在 masksTree 上执行 findMatch,命中后返回 { route, rawParams, branch },其中 route 即那条 RouteMask,rawParams 是 from 模式匹配到的参数原始值。
运行时匹配链路与优先级
关键逻辑位于 router.buildLocation(router.ts):
const next = build(opts)
if (opts.mask) {
// 优先级 1:显式的内联 mask 选项
next.maskedLocation = build({ from: opts.from, ...opts.mask })
} else if (this.options.routeMasks) {
// 优先级 2:注册的路由级掩码
const match = findFlatMatch<RouteMask<TRouteTree>>(
next.pathname,
this.processedTree,
)
if (match) {
const params = Object.assign(Object.create(null), match.rawParams)
const { from: _from, params: maskParams, ...maskProps } = match.route
// params 为函数时以匹配到的参数为上下文求值
const nextParams = resolveNextParams(maskParams, params)
next.maskedLocation = build({
from: opts.from,
...maskProps,
params: nextParams,
})
}
}
可以归纳出三条规则:
- 无匹配则无掩码:
buildLocation返回的location.pathname始终是真实路径;只有当路径命中某个RouteMask.from(或显式传入mask)时,才会额外生成location.maskedLocation。mask.test.ts 中 "should not create maskedLocation when no mask matches" 与 "should not create maskedLocation when routeMasks is empty" 两个用例验证了这一点; maskedLocation是第二个完整 location:测试 "should find and apply mask when pathname matches" 展示了结果形态——location.pathname为/photos/123/modal,location.maskedLocation.pathname为/photos/123,history 中提交的是掩码 URL,而路由匹配仍走真实路径;- 显式
mask选项优先级最高:当导航选项中带有mask时,注册好的routeMasks完全不会被执行(测试中让配置掩码的params抛错来确认它未被调用)。
完整实战示例:照片详情模态框
仓库中的 location-masking 示例 完整演示了这条链路。核心代码如下:
// 真实路由:照片模态框,路径 /photos/$photoId/modal
const photoModalRoute = createRoute({
getParentRoute: () => photosLayoutRoute,
path: '$photoId/modal',
loader: async ({ params: { photoId } }) => fetchPhoto(photoId),
component: PhotoModalComponent,
})
// 声明式路由掩码:模态框路径被"显示"为照片详情页
const photoModalToPhotoMask = createRouteMask({
routeTree,
from: '/photos/$photoId/modal', // 被遮盖的真实路由
to: '/photos/$photoId', // 地址栏显示的掩码路径
params: true, // 原样带入匹配到的 photoId
})
// 注册到路由器
const router = createRouter({
routeTree,
routeMasks: [photoModalToPhotoMask],
defaultPreload: 'intent',
scrollRestoration: true,
})
在这个示例中:
- 点击列表项通过
<Link to={photoModalRoute.to} params={{ photoId }}>导航到/photos/123/modal,地址栏显示/photos/123; - 由于
params: true,掩码 URL 中的photoId与真实参数保持一致,分享、刷新后直达照片详情页("de-masking"); - 关闭模态框时
navigate({ to: photosLayoutRoute.to })回到照片列表; - 示例注释中同时给出了内联写法的对比(
mask={{ to: photoRoute.to, params: { photoId: photo.id } }}),并明确指出:"it's generally safer to set up a route mask instead"——声明式RouteMask只需在路由器配置中写一次,而内联mask需要在每个Link/navigate调用点重复书写。
小结
RouteMask=ToOptions的导航字段(from/to/params/search/hash/state)+routeTree+unmaskOnReload,类型定义见 route.ts,文档入口见 RouteMask 类型;- 用
createRouteMask创建(各框架包均有同名导出),放入createRouter({ routeMasks: [...] })注册; - 运行时由
buildLocation驱动:真实 location 永远按路由树匹配,命中掩码后额外构建maskedLocation提交到地址栏;内联mask选项的优先级高于注册掩码; - 验证与回归参考 packages/router-core/tests/mask.test.ts、masked-location-state-commit.test.ts 及 examples/react/location-masking。