路由掩码

路由掩码是一种掩盖持久化到浏览器历史记录和 URL 栏中的路由实际 URL 的方法。这对于您想要显示与实际导航到的 URL 不同的 URL，然后在共享时（以及可选地在页面重新加载时）回退到显示的 URL 的场景很有用。以下是一些示例：

• 导航到像 /photo/5/modal 这样的模态路由，但将实际 URL 掩码为 /photos/5
• 导航到像 /post/5/comments 这样的模态路由，但将实际 URL 掩码为 /posts/5
• 导航到带有搜索参数 ?showLogin=true 的路由，但掩码 URL 使其_不_包含搜索参数
• 导航到带有搜索参数 ?modal=settings 的路由，但将 URL 掩码为 /settings

这些场景中的每一个都可以通过路由掩码实现，甚至可以扩展以支持更高级的模式，如并行路由。

路由掩码利用 location.state API 将所需的运行时位置存储在将写入 URL 的位置内。它将此运行时位置存储在 __tempLocation 状态属性下：

const location = {
  pathname: '/photos/5',
  search: '',
  hash: '',
  state: {
    key: 'wesdfs',
    __tempKey: 'sadfasd',
    __tempLocation: {
      pathname: '/photo/5/modal',
      search: '',
      hash: '',
      state: {},
    },
  },
}

const location = {
  pathname: '/photos/5',
  search: '',
  hash: '',
  state: {
    key: 'wesdfs',
    __tempKey: 'sadfasd',
    __tempLocation: {
      pathname: '/photo/5/modal',
      search: '',
      hash: '',
      state: {},
    },
  },
}

当路由器从历史记录中解析带有 location.state.__tempLocation 属性的位置时，它将使用该位置而不是从 URL 解析的位置。这允许您导航到像 /photos/5 这样的路由，并让路由器实际导航到 /photo/5/modal。当这种情况发生时，历史位置会保存回 location.maskedLocation 属性，以防我们需要知道实际 URL 是什么。使用此功能的一个例子是在开发工具中，我们检测路由是否被掩码并显示实际 URL 而不是掩码的 URL！

记住，您不需要担心任何这些。这些都在底层自动为您处理！

路由掩码是一个简单的 API，可以通过 2 种方式使用：

• 通过 <Link> 和 navigate() API 上可用的 mask 选项命令式地使用
• 通过路由器的 routeMasks 选项声明式地使用

当使用任一路由掩码 API 时，mask 选项接受与 <Link> 和 navigate() API 接受的相同导航对象。这意味着您可以使用您已经熟悉的相同 to、replace、state 和 search 选项。唯一的区别是 mask 选项将用于掩码正在导航到的路由的 URL。

🧠 mask 选项也是类型安全的！这意味着如果您使用 TypeScript，当您尝试向 mask 选项传递无效的导航对象时，您会收到类型错误。太棒了！

<Link> 和 navigate() API 都接受一个 mask 选项，可用于掩码正在导航到的路由的 URL。以下是与 <Link> 组件一起使用的示例：

<Link
  to="/photos/$photoId/modal"
  params={{ photoId: 5 }}
  mask={{
    to: '/photos/$photoId',
    params: {
      photoId: 5,
    },
  }}
>
  Open Photo
</Link>

<Link
  to="/photos/$photoId/modal"
  params={{ photoId: 5 }}
  mask={{
    to: '/photos/$photoId',
    params: {
      photoId: 5,
    },
  }}
>
  Open Photo
</Link>

以下是与 navigate() API 一起使用的示例：

const navigate = useNavigate()

function onOpenPhoto() {
  navigate({
    to: '/photos/$photoId/modal',
    params: { photoId: 5 },
    mask: {
      to: '/photos/$photoId',
      params: {
        photoId: 5,
      },
    },
  })
}

const navigate = useNavigate()

function onOpenPhoto() {
  navigate({
    to: '/photos/$photoId/modal',
    params: { photoId: 5 },
    mask: {
      to: '/photos/$photoId',
      params: {
        photoId: 5,
      },
    },
  })
}

除了命令式 API 之外，您还可以使用路由器的 routeMasks 选项来声明式地掩码路由。您可以在路由器上创建路由掩码来掩码匹配特定模式的路由，而不需要向每个 <Link> 或 navigate() 调用传递 mask 选项。以下是上面相同路由掩码的示例，但使用 routeMasks 选项：

// Use the following for the example below

import { createRouteMask } from '@tanstack/react-router'

const photoModalToPhotoMask = createRouteMask({
  routeTree,
  from: '/photos/$photoId/modal',
  to: '/photos/$photoId',
  params: (prev) => ({
    photoId: prev.photoId,
  }),
})

const router = createRouter({
  routeTree,
  routeMasks: [photoModalToPhotoMask],
})

import { createRouteMask } from '@tanstack/react-router'

const photoModalToPhotoMask = createRouteMask({
  routeTree,
  from: '/photos/$photoId/modal',
  to: '/photos/$photoId',
  params: (prev) => ({
    photoId: prev.photoId,
  }),
})

const router = createRouter({
  routeTree,
  routeMasks: [photoModalToPhotoMask],
})

创建路由掩码时，您需要传递至少包含以下内容的 1 个参数：

• routeTree - 将应用路由掩码的路由树
• from - 将应用路由掩码的路由 ID
• ...navigateOptions - <Link> 和 navigate() API 接受的标准 to、search、params、replace 等选项

🧠 createRouteMask 选项也是类型安全的！这意味着如果您使用 TypeScript，当您尝试向 routeMasks 选项传递无效的路由掩码时，您会收到类型错误。

URL 在共享时会自动取消掩码，因为一旦 URL 从浏览器本地历史堆栈中分离，URL 掩码数据就不再可用。本质上，一旦您从历史记录中复制并粘贴 URL，其掩码数据就会丢失...毕竟，这就是掩码 URL 的目的！

默认情况下，当页面在本地重新加载时，URL 不会取消掩码。掩码数据存储在历史位置的 location.state 属性中，因此只要历史位置仍在您的历史堆栈的内存中，掩码数据就会可用，URL 将继续被掩码。

如上所述，默认情况下，当页面重新加载时，URL 不会取消掩码。

如果您想在页面重新加载时在本地取消掩码 URL，您有 3 个选项，如果传递，每个选项都会按优先级覆盖前一个：

• 将路由器的默认 unmaskOnReload 选项设置为 true
• 使用 createRouteMask() 创建路由掩码时从掩码函数返回 unmaskOnReload: true 选项
• 向 <Link> 组件或 navigate() API 传递 unmaskOnReload: true 选项