Preloading | TanStack Router Solid 文档

TanStack Router 中的预加载是一种在用户实际导航到路由之前加载路由的方式。这对于用户接下来很可能访问的路由非常有用。例如，如果您有一个帖子列表，并且用户很可能单击其中一个帖子，则可以预加载帖子路由，以便在用户单击它时即可准备就绪。

支持的预加载策略

意图
- 通过“意图”进行预加载的工作原理是，通过在 <Link> 组件上使用悬停和触摸开始事件来预加载目标路由的依赖项。
- 此策略对于预加载用户接下来很可能访问的路由非常有用。
视口可见性
- 通过“视口”进行预加载的工作原理是，当 <Link> 组件在视口中时，使用 Intersection Observer API 预加载目标路由的依赖项。
- 此策略对于预加载折叠下方或屏幕外的路由非常有用。
渲染
- 通过“渲染”进行预加载的工作原理是，在 <Link> 组件在 DOM 中渲染后立即预加载目标路由的依赖项。
- 此策略对于预加载始终需要的路由非常有用。

预加载的数据在内存中保留多久？

预加载的路由匹配项会临时缓存在内存中，但有一些重要的注意事项

默认情况下，未使用的预加载数据会在 30 秒后删除。 这可以通过在您的路由器上设置 defaultPreloadMaxAge 选项来配置。
显然，当路由被加载时，其预加载版本会被提升为路由器的正常待处理匹配状态。

如果您需要更好地控制预加载、缓存和/或预加载数据的垃圾回收，则应使用外部缓存库，例如 TanStack Query。

为您的应用程序预加载路由的最简单方法是将 defaultPreload 选项设置为 intent 以用于整个路由器

tsx

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreload: 'intent',
})

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreload: 'intent',
})

这将为应用程序中所有 <Link> 组件默认启用 intent 预加载。您还可以在各个 <Link> 组件上设置 preload 属性以覆盖默认行为。

预加载延迟

默认情况下，预加载将在用户悬停或触摸 <Link> 组件 50 毫秒后开始。您可以通过在路由器上设置 defaultPreloadDelay 选项来更改此延迟

tsx

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadDelay: 100,
})

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadDelay: 100,
})

您还可以在各个 <Link> 组件上设置 preloadDelay 属性，以按链接覆盖默认行为。

内置预加载 & preloadStaleTime

如果您正在使用内置加载器，则可以通过将 routerOptions.defaultPreloadStaleTime 或 routeOptions.preloadStaleTime 设置为毫秒数来控制预加载数据被视为新鲜状态的时长，直到触发另一次预加载。默认情况下，预加载的数据被认为是 30 秒的新鲜状态。。

要更改此设置，您可以在路由器上设置 defaultPreloadStaleTime 选项

tsx

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 10_000,
})

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 10_000,
})

或者，您可以在各个路由上使用 routeOptions.preloadStaleTime 选项

tsx

// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  // Preload the route again if the preload cache is older than 10 seconds
  preloadStaleTime: 10_000,
})

// src/routes/posts.$postId.tsx
export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ params }) => fetchPost(params.postId),
  // Preload the route again if the preload cache is older than 10 seconds
  preloadStaleTime: 10_000,
})

使用外部库进行预加载

当集成像 React Query 这样的外部缓存库（它们有自己的机制来确定陈旧数据）时，您可能需要覆盖 TanStack Router 的默认预加载和 stale-while-revalidate 逻辑。这些库通常使用像 staleTime 这样的选项来控制数据的新鲜度。

要自定义 TanStack Router 中的预加载行为并充分利用外部库的缓存策略，您可以通过将 routerOptions.defaultPreloadStaleTime 或 routeOptions.preloadStaleTime 设置为 0 来绕过内置缓存。这确保了所有预加载在内部都被标记为陈旧，并且始终调用加载器，从而允许您的外部库（例如 React Query）管理数据加载和缓存。

例如

tsx

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 0,
})

import { createRouter } from '@tanstack/solid-router'

const router = createRouter({
  // ...
  defaultPreloadStaleTime: 0,
})

然后，这将允许您例如使用像 React Query 的 staleTime 这样的选项来控制预加载的新鲜度。

手动预加载

如果您需要手动预加载路由，可以使用路由器的 preloadRoute 方法。它接受标准的 TanStack NavigateOptions 对象，并返回一个在路由预加载时解析的 Promise。

tsx

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preload() {
      try {
        const matches = await router.preloadRoute({
          to: postRoute,
          params: { id: 1 },
        })
      } catch (err) {
        // Failed to preload route
      }
    }

    preload()
  }, [router])

  return <div />
}

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preload() {
      try {
        const matches = await router.preloadRoute({
          to: postRoute,
          params: { id: 1 },
        })
      } catch (err) {
        // Failed to preload route
      }
    }

    preload()
  }, [router])

  return <div />
}

如果您只需要预加载路由的 JS 代码块，可以使用路由器的 loadRouteChunk 方法。它接受一个路由对象，并返回一个在路由代码块加载时解析的 Promise。

tsx

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preloadRouteChunks() {
      try {
        const postsRoute = router.routesByPath['/posts']
        await Promise.all([
          router.loadRouteChunk(router.routesByPath['/']),
          router.loadRouteChunk(postsRoute),
          router.loadRouteChunk(postsRoute.parentRoute),
        ])
      } catch (err) {
        // Failed to preload route chunk
      }
    }

    preloadRouteChunks()
  }, [router])

  return <div />
}

function Component() {
  const router = useRouter()

  useEffect(() => {
    async function preloadRouteChunks() {
      try {
        const postsRoute = router.routesByPath['/posts']
        await Promise.all([
          router.loadRouteChunk(router.routesByPath['/']),
          router.loadRouteChunk(postsRoute),
          router.loadRouteChunk(postsRoute.parentRoute),
        ])
      } catch (err) {
        // Failed to preload route chunk
      }
    }

    preloadRouteChunks()
  }, [router])

  return <div />
}

预加载