tanstack/react-start-client 客户端运行时解析StartClient、水合策略与延迟水合机制【免费下载链接】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/react-start-client是 TanStack React Start 框架的客户端运行时包承载了浏览器端的启动挂载bootstrap、服务端渲染结果的水合hydration以及按需延迟水合deferred hydration三件核心工作。它不面向最终用户直接安装而是作为tanstack/react-start的内部依赖被自动引入。阅读本文后你将理解 React Start 应用在浏览器端是如何一步步「苏醒」的掌握Hydrate组件的五种水合触发策略load / idle / visible / interaction / never的适用场景并能结合源码追踪从StartClient到RouterProvider的完整调用链。一、包的定位客户端运行时的「三层职责」从官方 READMEpackages/react-start-client/README.md可以明确两点事实该包不面向最终用户直接使用它是tanstack/react-start的依赖项TanStack React Start 是一个面向 SSR、Streaming、Server Functions、API Routes、bundling 的全栈框架其底层由 TanStack Router 驱动。从源码层面看这个包承担了 React 侧「客户端运行时」的全部薄封装核心逻辑在tanstack/start-client-core框架无关的纯客户端核心而本包负责把核心能力「翻译」成 React 组件与 Hook。三块核心职责分别是启动引导导出StartClient组件负责在浏览器端拉起路由水合流程并渲染出完整的 RouterProvider 树水合收尾导出hydrateStart函数在水合完成时通过window.$_TSR?.h()向运行时发出「水合完成」信号按需水合导出Hydrate组件及load / idle / visible / interaction / media / condition / never七种策略实现「先渲染静态 HTML再按条件补水」的渐进增强体验。包的入口 packages/react-start-client/src/index.tsx 只有两行导出恰好印证了前两块职责use client export { StartClient } from ./StartClient export { hydrateStart } from ./hydrateStart二、客户端启动StartClient 与 hydrateStart2.1 组件级入口 StartClient浏览器端应用一般从入口文件渲染StartClient开始。它的实现极短packages/react-start-client/src/StartClient.tsx但设计上有两个关键点let hydrationPromise: PromiseAnyRouter | undefined export function StartClient() { if (!hydrationPromise) { hydrationPromise hydrateStart() } return ( Await promise{hydrationPromise} children{(router) RouterProvider router{router} /} / ) }模块级缓存hydrationPromise水合过程是异步的且整个应用生命周期内只应发生一次。通过把 Promise 缓存在模块作用域即使组件在 StrictMode 或热更新下被多次渲染也只会触发一次hydrateStart()避免重复水合导致的状态错乱。AwaitRouterProvider的组合Await是 TanStack Router 提供的 Suspense 工具组件它等待水合 Promise 完成后再把已经过反序列化、拥有完整路由树的AnyRouter实例交给RouterProvider渲染。也就是说路由实例的构建水合发生在渲染之前这也保证了服务端序列化下来的路由状态、loader 数据能够无缝衔接到客户端。2.2 水合函数 hydrateStarthydrateStart是本包对tanstack/start-client-core同名函数的 React 侧包装packages/react-start-client/src/hydrateStart.tsimport { hydrateStart as coreHydrateStart } from tanstack/start-client-core/client import type { AnyRouter } from tanstack/router-core /** * React-specific wrapper for hydrateStart that signals hydration completion */ export function hydrateStart(): PromiseAnyRouter { return coreHydrateStart().finally(() window.$_TSR?.h()) }它只做了一件事调用核心的水合流程并在 Promise 无论成功还是失败地 settle 之后调用window.$_TSR?.h()通知运行时「客户端已接管」。从window.$_TSR这个全局命名空间可以看出服务端注入的序列化状态如window.__TSR__之类与客户端水合共用同一套运行时桥接协议h()即 hydration 完成信号。2.3 测试对行为的验证包的测试packages/react-start-client/src/tests/Hydrate.test.tsx从另一个侧面印证了这套机制的约定测试里renderToString与hydrateRoot配合使用并断言水合完成后 DOM 中的标记属性被移除、交互事件真正生效。也就是说服务端渲染出可交互前的内容客户端水合后补齐事件与状态这正是本包存在的意义。三、Hydrate 组件按需水合的 React 入口3.1 组件形态与类型设计Hydrate组件是本包的核心导出packages/react-start-client/src/Hydrate.tsx其类型设计非常严谨export type HydrateOptions | (HydrateCommonOptions { prefetch?: never split?: boolean }) | (HydrateCommonOptions { prefetch: HydrationPrefetchStrategy split?: true }) | (HydrateCommonOptions { prefetch: HydrationPrefetchFunction split?: boolean })其中HydrateCommonOptions包含三个通用选项选项类型说明whenHydrateWhen策略对象或返回策略对象的函数指定水合触发策略可静态传入也可用函数形式实现「服务端/客户端渲染不同的动态策略」fallbackReact.ReactNode水合尚未发生时展示的降级内容SSR 首屏 HTML 被保留时通常无需展示onHydrated() void该区块完成水合后的回调可用于打点或联动其他逻辑联合类型通过prefetch的取舍区分了三种形态完全不预取、按策略预取、自定义预取函数且split参数用于配合代码分割场景。这套类型约束让错误用法比如既传策略预取又传自定义函数在编译期就被拦截。3.2 服务端渲染与动态策略的分流Hydrate的运行时逻辑packages/react-start-client/src/Hydrate.tsx#L93-L107体现了 SSR 与客户端的不同诉求export function Hydrate(props: HydrateProps): React.JSX.Element { if (typeof props.when function) { if ( isServer ?? typeof window undefined ) { return ServerDynamicHydrate {...props} / } return props.when()._h(props) } return props.when._h(props) }策略对象形态直接调用策略对象的_h(props)方法由策略自身决定如何渲染比如visible策略的_h就是VisibleHydrate组件函数形态动态策略服务端一律走ServerDynamicHydrate——只渲染带data-ts-hydrate-id/data-ts-hydrate-whendynamic标记的占位容器并包一层 Suspense服务端不执行任何水合等待逻辑客户端才真正调用when()求值出策略。这种「服务端标记 客户端决策」的分工保证了首屏 HTML 永远即时返回。3.3 通用渲染器 GenericHydrate 与「闸门」机制除了load与never有专属渲染器其余策略统一复用GenericHydratepackages/react-start-client/src/GenericHydrate.tsx。其核心是一个**水合闸门hydration gate**模型每个Hydrate区块在渲染时都会通过getOrCreateGate(id, type)创建/获取一个Gate它内部持有一个Promise只有该 Promise resolve 后HydrationGate组件才会真正渲染 children在客户端useLayoutEffect中注册策略对应的监听器IntersectionObserver、事件监听等一旦条件满足就调用requestHydration()使闸门放行在服务端或尚未水合时shouldPreserveServerHTMLRef为真fallback 优先使用getFallbackHtml(gate.id)取回服务端渲染时的原始 HTML 原样回填避免闪烁FOUC水合成功后通过onStrategyHydrated回调移除data-ts-hydrate-when标记并执行_o?.(id)此时 DOM 上的策略标记消失表示该区块已完全客户端化。这一机制同时服务于预取prefetchprefetch可以是函数手动控制或策略对象如idle运行时通过waitForHydrationPrefetchStrategy、runHydrationStrategyCleanup等工具管理预取与监听的生命周期并用AbortController在组件卸载时中止未完成的预取。四、五种水合策略的源码级对照所有策略统一从 packages/react-start-client/src/hydration.ts 导出它们与tanstack/start-client-core的核心策略一一对应本包只负责挂接各自的 React 渲染器。以下是逐个分析。4.1 load默认的「立即水合」loadpackages/react-start-client/src/hydration/load.tsx是唯一不做任何延迟、页面加载即水合的策略export function LoadHydrate(props: HydrateProps): React.JSX.Element { return ( div React.Suspense fallback{props.fallback ?? null} HydratedBoundary onHydrated{props.onHydrated} {props.children} /HydratedBoundary /React.Suspense /div ) }它的渲染器没有任何闸门与监听器仅用React.Suspense包裹 children 以兼容其中的异步组件并在useEffect中触发onHydrated。注意loadStrategy被定义在模块级并标记/* __PURE__ */因此多次调用load()返回的是同一个单例对象有利于打包器做 tree-shaking 与去重。从源码结构看它对应shouldDeferHydration判断中的基线情况——凡是没有延迟需求的内容都应该使用load。4.2 idle浏览器空闲时水合idlepackages/react-start-client/src/hydration/idle.ts在浏览器进入空闲状态requestIdleCallback语义后再水合适用于非首屏关键、又不至于完全不水合的内容。它支持IdleHydrationOptions参数如超时时间返回类型同时满足ReactHydrationStrategyidle, true与HydrationPrefetchStrategyidle即它既能当水合触发策略也能当预取策略——例如在一个visible区块中可以把idle作为其prefetch策略实现「空闲时预取数据、可见时水合」的分层优化。4.3 visible滚动进入视口时水合visiblepackages/react-start-client/src/hydration/visible.tsx通过IntersectionObserver实现「进入视口才水合」export function visible( options?: VisibleHydrationOptions, ): ReactHydrationStrategyvisible, true HydrationPrefetchStrategyvisible { const rootMargin options?.rootMargin ?? 600px const threshold options?.threshold ?? 0 return { _s: ({ element, gate, prefetch }) { const callback prefetch || (gate as never as VisibleGate).s if (!element) { callback() return } const observer new IntersectionObserver( (entries) { if (!entries[0]!.isIntersecting) return observer.disconnect() callback() }, { rootMargin, threshold }, ) observer.observe(element) return () observer.disconnect() }, _h: VisibleHydrate, } }默认参数很有讲究rootMargin默认为600px即元素距离视口还有 600px 时就开始水合为用户滚动到目标位置预留了水合时间达到「用户看到时已经水合完成」的体验。这是长页面新闻流、商品列表等的推荐策略。其 React 渲染器VisibleHydrate维护一个自建的VisibleGatepromise resolved 标记 solve 函数在服务端直接 resolve客户端则交给_s中的 IntersectionObserver 触发。4.4 interaction首次交互时水合interactionpackages/react-start-client/src/hydration/generic.ts#L35-L42在用户发生指定交互事件时才水合适合「默认不参与交互、但一旦用户操作就必须响应」的区块export function interaction(options?: { events?: HydrationInteractionEvents }): ReactHydrationStrategyinteraction, true HydrationPrefetchStrategyinteraction { return /* __PURE__ */ withHydrationRenderer( coreInteraction(options), GenericHydrate, ) }options.events可自定义监听的事件集合如pointerenter、focusin、pointerdown、click等。测试文件 packages/react-start-client/src/tests/Hydrate.test.tsx 中专门验证了「在默认意图事件触发后仍未水合」与「点击后水合」两种行为说明默认事件集的选取经过了严格的交互语义推敲。配合GenericHydrate时注意useLayoutEffect中的逻辑interaction类型不会注册listenForDelegatedHydrationIntent事件委托监听因为其策略自身已负责监听。4.5 media / condition / never更细粒度的控制media(query)基于 CSS 媒体查询如(max-width: 640px)决定是否水合移动端与桌面端可采取不同的水合策略condition(condition)接受一个谓词函数完全由业务逻辑决定水合时机neverpackages/react-start-client/src/hydration/never.tsx永远不水合。它用一个永不 resolve 的neverPromise挂起 children客户端只保留服务端渲染的静态 HTMLshouldPreserveServerHTML为真时回填原始 HTML一旦水合完成则清空 marker 子节点element.replaceChildren()实现「纯静态、零 JS 交互」的区块。适合广告位、纯展示卡片等无需交互的内容。从类型签名也能看出能力差异media、interaction、idle、visible、load都是TCanPrefetch extends true可预取而condition与never是false不可预取。五、水合策略的选型建议综合上述源码行为可以给出一张务实的选型表策略触发时机推荐场景load立即页面加载后尽快首屏关键内容、导航栏、全局状态相关 UIidle浏览器空闲后首屏以下、折叠区之外的次要内容visible距视口 600px 内可配置长列表、无限滚动、图片画廊等滚动可见内容interaction用户首次交互事件可配置弹窗、抽屉、表单等「用到才水合」的交互组件mediaCSS 媒体查询命中按设备类型/窗口尺寸差异化水合condition业务谓词为真登录态、A/B 实验等动态决策never永不纯静态展示、SEO 优先的营销区块一个典型的分层组合是整页用visibleprefetch: idle即空闲时后台预取数据、进入视口前 600px 开始水合最大化首屏性能的同时保证交互无感知延迟。六、与框架其他部分的协作关系tanstack/react-start-client不是孤立的它的依赖packages/react-start-client/package.json显示其直接依赖tanstack/react-router、tanstack/router-core与tanstack/start-client-corepeer 依赖为react 18 || 19与react-dom 18 || 19。这意味着React 侧的薄封装所有跨框架复用的水合核心逻辑闸门、预取、委托监听都在start-client-core中Solid Start 的客户端运行时packages/solid-start-client走的是同一条核心链路只是渲染器不同路由树的一等公民StartClient产出的AnyRouter直接来自tanstack/router-core水合后的路由实例与 SSR 阶段构建的实例共享同一套类型系统保证端到端类型安全构建与发布质量包通过publint --strict与attw --ignore-rules no-resolution校验 ESM 产物与类型声明见 package.json 的test:build脚本并针对 TypeScript 5.6 ~ 7.0 多版本做类型测试确保类型声明在广泛的 TS 版本下可用。七、小结tanstack/react-start-client用不到十个源文件完成了 React Start 在浏览器端最关键的三件事以StartClienthydrateStart拉起路由水合以Hydrate组件提供声明式的水合边界以七种策略实现从「立即水合」到「永不水合」的完整光谱。理解它就理解了 React Start 应用「服务端出 HTML、客户端按需苏醒」的运行时全貌需要继续深入时可以从 packages/react-start-client/src/hydration/ 下的各策略实现一路追到tanstack/start-client-core的闸门与预取运行时那里是整个延迟水合体系的引擎所在。【免费下载链接】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），仅供参考
@tanstack/react-start-client 客户端运行时解析：StartClient、水合策略与延迟水合机制
tanstack/react-start-client 客户端运行时解析StartClient、水合策略与延迟水合机制【免费下载链接】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/react-start-client是 TanStack React Start 框架的客户端运行时包承载了浏览器端的启动挂载bootstrap、服务端渲染结果的水合hydration以及按需延迟水合deferred hydration三件核心工作。它不面向最终用户直接安装而是作为tanstack/react-start的内部依赖被自动引入。阅读本文后你将理解 React Start 应用在浏览器端是如何一步步「苏醒」的掌握Hydrate组件的五种水合触发策略load / idle / visible / interaction / never的适用场景并能结合源码追踪从StartClient到RouterProvider的完整调用链。一、包的定位客户端运行时的「三层职责」从官方 READMEpackages/react-start-client/README.md可以明确两点事实该包不面向最终用户直接使用它是tanstack/react-start的依赖项TanStack React Start 是一个面向 SSR、Streaming、Server Functions、API Routes、bundling 的全栈框架其底层由 TanStack Router 驱动。从源码层面看这个包承担了 React 侧「客户端运行时」的全部薄封装核心逻辑在tanstack/start-client-core框架无关的纯客户端核心而本包负责把核心能力「翻译」成 React 组件与 Hook。三块核心职责分别是启动引导导出StartClient组件负责在浏览器端拉起路由水合流程并渲染出完整的 RouterProvider 树水合收尾导出hydrateStart函数在水合完成时通过window.$_TSR?.h()向运行时发出「水合完成」信号按需水合导出Hydrate组件及load / idle / visible / interaction / media / condition / never七种策略实现「先渲染静态 HTML再按条件补水」的渐进增强体验。包的入口 packages/react-start-client/src/index.tsx 只有两行导出恰好印证了前两块职责use client export { StartClient } from ./StartClient export { hydrateStart } from ./hydrateStart二、客户端启动StartClient 与 hydrateStart2.1 组件级入口 StartClient浏览器端应用一般从入口文件渲染StartClient开始。它的实现极短packages/react-start-client/src/StartClient.tsx但设计上有两个关键点let hydrationPromise: PromiseAnyRouter | undefined export function StartClient() { if (!hydrationPromise) { hydrationPromise hydrateStart() } return ( Await promise{hydrationPromise} children{(router) RouterProvider router{router} /} / ) }模块级缓存hydrationPromise水合过程是异步的且整个应用生命周期内只应发生一次。通过把 Promise 缓存在模块作用域即使组件在 StrictMode 或热更新下被多次渲染也只会触发一次hydrateStart()避免重复水合导致的状态错乱。AwaitRouterProvider的组合Await是 TanStack Router 提供的 Suspense 工具组件它等待水合 Promise 完成后再把已经过反序列化、拥有完整路由树的AnyRouter实例交给RouterProvider渲染。也就是说路由实例的构建水合发生在渲染之前这也保证了服务端序列化下来的路由状态、loader 数据能够无缝衔接到客户端。2.2 水合函数 hydrateStarthydrateStart是本包对tanstack/start-client-core同名函数的 React 侧包装packages/react-start-client/src/hydrateStart.tsimport { hydrateStart as coreHydrateStart } from tanstack/start-client-core/client import type { AnyRouter } from tanstack/router-core /** * React-specific wrapper for hydrateStart that signals hydration completion */ export function hydrateStart(): PromiseAnyRouter { return coreHydrateStart().finally(() window.$_TSR?.h()) }它只做了一件事调用核心的水合流程并在 Promise 无论成功还是失败地 settle 之后调用window.$_TSR?.h()通知运行时「客户端已接管」。从window.$_TSR这个全局命名空间可以看出服务端注入的序列化状态如window.__TSR__之类与客户端水合共用同一套运行时桥接协议h()即 hydration 完成信号。2.3 测试对行为的验证包的测试packages/react-start-client/src/tests/Hydrate.test.tsx从另一个侧面印证了这套机制的约定测试里renderToString与hydrateRoot配合使用并断言水合完成后 DOM 中的标记属性被移除、交互事件真正生效。也就是说服务端渲染出可交互前的内容客户端水合后补齐事件与状态这正是本包存在的意义。三、Hydrate 组件按需水合的 React 入口3.1 组件形态与类型设计Hydrate组件是本包的核心导出packages/react-start-client/src/Hydrate.tsx其类型设计非常严谨export type HydrateOptions | (HydrateCommonOptions { prefetch?: never split?: boolean }) | (HydrateCommonOptions { prefetch: HydrationPrefetchStrategy split?: true }) | (HydrateCommonOptions { prefetch: HydrationPrefetchFunction split?: boolean })其中HydrateCommonOptions包含三个通用选项选项类型说明whenHydrateWhen策略对象或返回策略对象的函数指定水合触发策略可静态传入也可用函数形式实现「服务端/客户端渲染不同的动态策略」fallbackReact.ReactNode水合尚未发生时展示的降级内容SSR 首屏 HTML 被保留时通常无需展示onHydrated() void该区块完成水合后的回调可用于打点或联动其他逻辑联合类型通过prefetch的取舍区分了三种形态完全不预取、按策略预取、自定义预取函数且split参数用于配合代码分割场景。这套类型约束让错误用法比如既传策略预取又传自定义函数在编译期就被拦截。3.2 服务端渲染与动态策略的分流Hydrate的运行时逻辑packages/react-start-client/src/Hydrate.tsx#L93-L107体现了 SSR 与客户端的不同诉求export function Hydrate(props: HydrateProps): React.JSX.Element { if (typeof props.when function) { if ( isServer ?? typeof window undefined ) { return ServerDynamicHydrate {...props} / } return props.when()._h(props) } return props.when._h(props) }策略对象形态直接调用策略对象的_h(props)方法由策略自身决定如何渲染比如visible策略的_h就是VisibleHydrate组件函数形态动态策略服务端一律走ServerDynamicHydrate——只渲染带data-ts-hydrate-id/data-ts-hydrate-whendynamic标记的占位容器并包一层 Suspense服务端不执行任何水合等待逻辑客户端才真正调用when()求值出策略。这种「服务端标记 客户端决策」的分工保证了首屏 HTML 永远即时返回。3.3 通用渲染器 GenericHydrate 与「闸门」机制除了load与never有专属渲染器其余策略统一复用GenericHydratepackages/react-start-client/src/GenericHydrate.tsx。其核心是一个**水合闸门hydration gate**模型每个Hydrate区块在渲染时都会通过getOrCreateGate(id, type)创建/获取一个Gate它内部持有一个Promise只有该 Promise resolve 后HydrationGate组件才会真正渲染 children在客户端useLayoutEffect中注册策略对应的监听器IntersectionObserver、事件监听等一旦条件满足就调用requestHydration()使闸门放行在服务端或尚未水合时shouldPreserveServerHTMLRef为真fallback 优先使用getFallbackHtml(gate.id)取回服务端渲染时的原始 HTML 原样回填避免闪烁FOUC水合成功后通过onStrategyHydrated回调移除data-ts-hydrate-when标记并执行_o?.(id)此时 DOM 上的策略标记消失表示该区块已完全客户端化。这一机制同时服务于预取prefetchprefetch可以是函数手动控制或策略对象如idle运行时通过waitForHydrationPrefetchStrategy、runHydrationStrategyCleanup等工具管理预取与监听的生命周期并用AbortController在组件卸载时中止未完成的预取。四、五种水合策略的源码级对照所有策略统一从 packages/react-start-client/src/hydration.ts 导出它们与tanstack/start-client-core的核心策略一一对应本包只负责挂接各自的 React 渲染器。以下是逐个分析。4.1 load默认的「立即水合」loadpackages/react-start-client/src/hydration/load.tsx是唯一不做任何延迟、页面加载即水合的策略export function LoadHydrate(props: HydrateProps): React.JSX.Element { return ( div React.Suspense fallback{props.fallback ?? null} HydratedBoundary onHydrated{props.onHydrated} {props.children} /HydratedBoundary /React.Suspense /div ) }它的渲染器没有任何闸门与监听器仅用React.Suspense包裹 children 以兼容其中的异步组件并在useEffect中触发onHydrated。注意loadStrategy被定义在模块级并标记/* __PURE__ */因此多次调用load()返回的是同一个单例对象有利于打包器做 tree-shaking 与去重。从源码结构看它对应shouldDeferHydration判断中的基线情况——凡是没有延迟需求的内容都应该使用load。4.2 idle浏览器空闲时水合idlepackages/react-start-client/src/hydration/idle.ts在浏览器进入空闲状态requestIdleCallback语义后再水合适用于非首屏关键、又不至于完全不水合的内容。它支持IdleHydrationOptions参数如超时时间返回类型同时满足ReactHydrationStrategyidle, true与HydrationPrefetchStrategyidle即它既能当水合触发策略也能当预取策略——例如在一个visible区块中可以把idle作为其prefetch策略实现「空闲时预取数据、可见时水合」的分层优化。4.3 visible滚动进入视口时水合visiblepackages/react-start-client/src/hydration/visible.tsx通过IntersectionObserver实现「进入视口才水合」export function visible( options?: VisibleHydrationOptions, ): ReactHydrationStrategyvisible, true HydrationPrefetchStrategyvisible { const rootMargin options?.rootMargin ?? 600px const threshold options?.threshold ?? 0 return { _s: ({ element, gate, prefetch }) { const callback prefetch || (gate as never as VisibleGate).s if (!element) { callback() return } const observer new IntersectionObserver( (entries) { if (!entries[0]!.isIntersecting) return observer.disconnect() callback() }, { rootMargin, threshold }, ) observer.observe(element) return () observer.disconnect() }, _h: VisibleHydrate, } }默认参数很有讲究rootMargin默认为600px即元素距离视口还有 600px 时就开始水合为用户滚动到目标位置预留了水合时间达到「用户看到时已经水合完成」的体验。这是长页面新闻流、商品列表等的推荐策略。其 React 渲染器VisibleHydrate维护一个自建的VisibleGatepromise resolved 标记 solve 函数在服务端直接 resolve客户端则交给_s中的 IntersectionObserver 触发。4.4 interaction首次交互时水合interactionpackages/react-start-client/src/hydration/generic.ts#L35-L42在用户发生指定交互事件时才水合适合「默认不参与交互、但一旦用户操作就必须响应」的区块export function interaction(options?: { events?: HydrationInteractionEvents }): ReactHydrationStrategyinteraction, true HydrationPrefetchStrategyinteraction { return /* __PURE__ */ withHydrationRenderer( coreInteraction(options), GenericHydrate, ) }options.events可自定义监听的事件集合如pointerenter、focusin、pointerdown、click等。测试文件 packages/react-start-client/src/tests/Hydrate.test.tsx 中专门验证了「在默认意图事件触发后仍未水合」与「点击后水合」两种行为说明默认事件集的选取经过了严格的交互语义推敲。配合GenericHydrate时注意useLayoutEffect中的逻辑interaction类型不会注册listenForDelegatedHydrationIntent事件委托监听因为其策略自身已负责监听。4.5 media / condition / never更细粒度的控制media(query)基于 CSS 媒体查询如(max-width: 640px)决定是否水合移动端与桌面端可采取不同的水合策略condition(condition)接受一个谓词函数完全由业务逻辑决定水合时机neverpackages/react-start-client/src/hydration/never.tsx永远不水合。它用一个永不 resolve 的neverPromise挂起 children客户端只保留服务端渲染的静态 HTMLshouldPreserveServerHTML为真时回填原始 HTML一旦水合完成则清空 marker 子节点element.replaceChildren()实现「纯静态、零 JS 交互」的区块。适合广告位、纯展示卡片等无需交互的内容。从类型签名也能看出能力差异media、interaction、idle、visible、load都是TCanPrefetch extends true可预取而condition与never是false不可预取。五、水合策略的选型建议综合上述源码行为可以给出一张务实的选型表策略触发时机推荐场景load立即页面加载后尽快首屏关键内容、导航栏、全局状态相关 UIidle浏览器空闲后首屏以下、折叠区之外的次要内容visible距视口 600px 内可配置长列表、无限滚动、图片画廊等滚动可见内容interaction用户首次交互事件可配置弹窗、抽屉、表单等「用到才水合」的交互组件mediaCSS 媒体查询命中按设备类型/窗口尺寸差异化水合condition业务谓词为真登录态、A/B 实验等动态决策never永不纯静态展示、SEO 优先的营销区块一个典型的分层组合是整页用visibleprefetch: idle即空闲时后台预取数据、进入视口前 600px 开始水合最大化首屏性能的同时保证交互无感知延迟。六、与框架其他部分的协作关系tanstack/react-start-client不是孤立的它的依赖packages/react-start-client/package.json显示其直接依赖tanstack/react-router、tanstack/router-core与tanstack/start-client-corepeer 依赖为react 18 || 19与react-dom 18 || 19。这意味着React 侧的薄封装所有跨框架复用的水合核心逻辑闸门、预取、委托监听都在start-client-core中Solid Start 的客户端运行时packages/solid-start-client走的是同一条核心链路只是渲染器不同路由树的一等公民StartClient产出的AnyRouter直接来自tanstack/router-core水合后的路由实例与 SSR 阶段构建的实例共享同一套类型系统保证端到端类型安全构建与发布质量包通过publint --strict与attw --ignore-rules no-resolution校验 ESM 产物与类型声明见 package.json 的test:build脚本并针对 TypeScript 5.6 ~ 7.0 多版本做类型测试确保类型声明在广泛的 TS 版本下可用。七、小结tanstack/react-start-client用不到十个源文件完成了 React Start 在浏览器端最关键的三件事以StartClienthydrateStart拉起路由水合以Hydrate组件提供声明式的水合边界以七种策略实现从「立即水合」到「永不水合」的完整光谱。理解它就理解了 React Start 应用「服务端出 HTML、客户端按需苏醒」的运行时全貌需要继续深入时可以从 packages/react-start-client/src/hydration/ 下的各策略实现一路追到tanstack/start-client-core的闸门与预取运行时那里是整个延迟水合体系的引擎所在。【免费下载链接】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），仅供参考
