TanStack Router 的 ToMaskOptions 类型路由掩码配置的类型定义与三层 unmaskOnReload 机制【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router本文围绕 TanStack Router 的ToMaskOptions类型展开它是路由掩码Route Masking场景下描述掩码后 URL的完整类型契约相当于ToOptions去掉mask字段后额外叠加掩码专用选项的产物。读完后你将理解该类型每一组字段的含义与类型约束、unmaskOnReload在掩码级 / 导航级 / 路由器级三层配置中的优先级规则以及它在 link.ts 与 router.ts 中的实际落地位置。ToMaskOptions 的定位ToOptions 的无 mask 子集官方文档对 ToMaskOptions 的定义是它包含与 ToOptions 相同的目的地字段排除mask并添加路由掩码专用的选项。其类型签名为type ToMaskOptions { from?: ValidRoutePath | string to?: ValidRoutePath | string hash?: true | string | ((prev?: string) string) state?: true | HistoryState | ((prev: HistoryState) HistoryState) } SearchParamOptions PathParamOptions { unmaskOnReload?: boolean }在源码 packages/router-core/src/link.ts 中它的真实实现是export type ToMaskOptions TRouter extends AnyRouter RegisteredRouter, TMaskFrom extends string string, TMaskTo extends string ., ToSubOptionsTRouter, TMaskFrom, TMaskTo { unmaskOnReload?: boolean }两个细节值得注意文档签名里的from、to、hash、state四个字段并非手工罗列而是由ToSubOptions统一提供的——它由ToSubOptionsProps、SearchParamOptions、PathParamOptions三块交叉构成见 link.ts。这与ToOptions ToSubOptions MaskOptions的结构见 link.ts完全一致区别仅在于ToMaskOptions不带MaskOptions从而天然规避了掩码里再套掩码的递归问题。类型参数TMaskFrom/TMaskTo的默认值分别是string与.即掩码目的地默认按相对当前路径解析与主导航的默认行为保持一致。也就是说ToMaskOptions与ToOptions共享同一套目的地解析能力路径、search、params、hash、state 的类型安全推导只是砍掉了mask字段、新增了unmaskOnReload。各字段详解路径字段from/toto掩码后的目标路径支持绝对路径/public/path或相对路径./x、../y。其可选性由MakeToRequired根据TRouter、TFrom、TTo推导当TTo是具体字面量且不是通配路径时to会被强制为必填见 link.ts保证掩码目标必须指向一个可解析的位置。from指定相对路径的解析基准。不传时以当前路由路径为基准传入一个已注册路径后to会基于该路径解析。这与 ToOptions 中的语义一致。hash 与 statehash支持true保留当前 hash、字符串字面量或(prev?: string) string更新函数三种形式true | Updaterstring见 link.ts。statehistory state 的配置支持true保留当前值、HistoryState字面量或(prev) HistoryState更新函数。注意其更新函数签名是NonNullableUpdater即回调必须返回非空 state。SearchParamOptions 与 PathParamOptions与 ToOptions 相同这两组选项让掩码 URL 也具备完整的类型安全参数能力type SearchParamOptions { search?: true | TToSearch | ((prev: TFromSearch) TToSearch) } type PathParamOptions { params?: | true | Recordstring, TPathParam | ((prev: TFromParams) TToParams) }search: true表示沿用当前 URL 的查询参数也可传入具体对象或基于前值的更新函数目标 search 的字段集合由路由树推导多传/漏传字段都会触发类型错误。params: true表示沿用当前路径参数掩码路径本身含路径参数时如掩码到/public/post/:postId这里必须提供或沿用对应参数。unmaskOnReload掩码专用选项unmaskOnReload?: boolean是ToMaskOptions相对ToOptions唯一新增的字段用于声明页面刷新后是否移除该掩码、暴露真实 URL。它的完整语义链如下导航级在mask配置中直接设置例如navigate({ to: /protected/data, // 真实路由 mask: { to: /public-view, unmaskOnReload: true }, })掩码级在路由树中声明routeMasks时每个 mask 也可携带unmaskOnReloadRouteMask类型见 route.ts由 createRouteMaskFunction 创建的路由掩码会走这条链路。路由器级RouterOptions.unmaskOnReload提供全局默认值注释明确说明可被单个 mask 的unmaskOnReload或单次导航的unmaskOnReload覆盖见 router.ts。三者的优先级在buildLocation中有明确的短路顺序见 router.tsif ( nextHistory.unmaskOnReload ?? // 导航/掩码级设置 this.options.unmaskOnReload ?? // 路由器级设置 false // 均未设置时保持掩码 ) { nextHistory.state.__tempKey this.tempLocationKey }即单次导航的 mask 配置优先于路由器全局配置两者都缺省时保持掩码。命中时会在 history state 上写入__tempKey临时位置键刷新后路由器据此识别这是一次待解除掩码的临时位置从而导航回真实路由——完整流程在 route-masking 指南 的 Unmasking on page reload 一节有描述。掩码结果如何落到位置对象上router.buildLocation处理带掩码的导航时见 router.tsconst next build(opts) if (opts.mask) { next.maskedLocation build({ from: opts.from, // 以 mask 的 ToMaskOptions 再构建一次位置 ... }) }它先用主选项构建真实位置next再把opts.mask作为ToMaskOptions二次调用同一个build生成next.maskedLocation。这个结构最终体现在ParsedLocation上maskedLocation?: ParsedLocation与unmaskOnReload?: boolean两个字段并存见 location.ts前者保存掩码后展示给地址栏的位置后者把生效的解除掩码策略随位置一起传递。与 ToOptions 的关系小结类型组成用途ToOptionsToSubOptions MaskOptions常规导航/链接的全部目的地选项含maskMaskOptions{ mask?: ToMaskOptions, _fromLocation?: ParsedLocation }mask字段本身所在的接口ToMaskOptionsToSubOptions { unmaskOnReload? }掩码目的地选项无mask多unmaskOnReload从源码结构看ToMaskOptions被MaskOptions.mask字段引用并随ToOptions一起从 router-core 入口 导出供react-router、solid-router、vue-router各框架适配层在类型层面复用同一套掩码契约。验证与延伸掩码位置在 history state 提交时的行为由 masked-location-state-commit.test.ts 覆盖unmaskOnReload在位置构建中的透传可在 build-location.test.ts 中检索到相关断言。完整的掩码用法含routeMasks声明、createRouteMask函数、刷新解除掩码建议结合 route-masking 指南、RouteMask 类型文档 与 RouterOptions 文档 一起阅读。【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考