路由掩码

路由掩码是一种掩盖路由实际 URL 的方法，该 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 是什么。一个使用此功能的示例是在 Devtools 中，我们检测路由是否被掩码，并显示实际 URL 而不是掩码后的 URL！

请记住，您无需担心任何这些。所有这些都在底层为您自动处理！

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

• 命令式地通过 mask 选项，该选项在 <Link> 和 navigate() API 上可用
• 声明式地通过 Router 的 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 之外，您还可以使用 Router 的 routeMasks 选项来声明式地掩码路由。您无需将 mask 选项传递给每个 <Link> 或 navigate() 调用，而是可以在 Router 上创建一个路由掩码，以掩码与特定模式匹配的路由。这是一个与上面相同的路由掩码示例，但使用了 routeMasks 选项

// 以下示例使用

import { createRouteMask } from '@tanstack/solid-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/solid-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 个选项，如果传递，每个选项都会覆盖前一个选项的优先级

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