用途:介绍 TanStack Router 的数据加载机制,用于在路由层声明式获取数据并在组件中消费。
主要能力:loader 返回数据,在组件中通过 Route.useLoaderData 读取;代码分割组件用 getRouteApi 获取。loaderDeps 声明哪些 search params 影响缓存键,deps 变化时无视 staleTime 重新加载。内置 Stale-While-Revalidate 缓存,默认 staleTime 为 0、preloadStaleTime 为 30 秒、gcTime 为 30 分钟,可全局或按路由配置。pendingMs 默认 1000、pendingMinMs 默认 500,可自定义 pendingComponent。支持从 loader 返回未 await 的 Promise 做延迟加载,用 Await 渲染。变更后用 router.invalidate({ sync: true }) 强制重跑 loader 并标记缓存过期。createRootRouteWithContext 以工厂模式注入 context,供 loader/beforeLoad 使用。
使用方式:在 createFileRoute 中声明 loader、loaderDeps、staleTime、gcTime、pendingComponent、errorComponent 等选项;loader 接收 params、deps、context、abortController、cause、preload、location 等参数。
限制与注意:loader 默认在客户端运行,不可直接使用 fs、数据库等仅服务端代码;SSR 下需用 server function,避免相对 fetch。不能在 loader/beforeLoad 中调用 React hooks,需经 router context 注入。错误组件重试应使用 router.invalidate() 而非 reset()。createRootRouteWithContext 需双重调用。属性顺序影响类型推断。loaderDeps 不应返回整个 search 对象。SSR 与外部缓存协调等细节暂未提供。