TanStack Router RouteMask 类型详解:声明式路由掩码(Location Masking)的原理与实战

原创2026-09-13 12:31:161,603 阅读
文章标签:前端路由Web框架SSRUI组件

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 提供两种使用方式:

  1. 内联 mask 选项:在 Link 组件或 useNavigate 的 to 选项中直接传 mask: { to, params, ... },属于单次导航级别的临时掩码;
  2. 路由级 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,
    })
  }
}

可以归纳出三条规则:

  1. 无匹配则无掩码: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" 两个用例验证了这一点;
  2. maskedLocation 是第二个完整 location:测试 "should find and apply mask when pathname matches" 展示了结果形态——location.pathname 为 /photos/123/modal,location.maskedLocation.pathname 为 /photos/123,history 中提交的是掩码 URL,而路由匹配仍走真实路径;
  3. 显式 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。
登录后查看全文
router