# @contentful/optimization-react-web 中文文档 规范地址：https://npmcn.com/package/%40contentful/optimization-react-web/ 版本：2\.1\.3 npm 元数据更新时间：2026-11-06T12:31:32.787Z 中文译文更新时间：2026-11-10T18:56:53.889Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40contentful/optimization-react-web 原文对照：https://npmcn.com/package/%40contentful/optimization-react-web/?lang=original 项目主页：https://github.com/contentful/optimization#readme 源码仓库：https://github.com/contentful/optimization ## 关键信息（来自 npm 元数据） - 包体积（解压后）：513 kB，86 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：next \>=13\.0\.0，react \>=18\.3\.1，react-dom \>=18\.3\.1，react-router-dom \>=6\.4\.0，@tanstack/react-router \>=1\.0\.0 - 首次发布：2026-04-01T16:16:21.835Z - 最新版本发布：2026-11-06T12:31:32.559Z - 近 30 天下载量：3944（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：19（近 12 个月 19 个） ## 中文简介 内容优化反应 SDK ## 安装 ```sh npm install @contentful/optimization-react-web ``` 也可以使用：`pnpm add @contentful/optimization-react-web`、`yarn add @contentful/optimization-react-web`、`bun add @contentful/optimization-react-web` ## README [![Contentful Logo](https://raw.githubusercontent.com/contentful/optimization/optimization-react-web-v2.1.3/contentful-icon.png "Contentful")](https://www.contentful.com/developers/docs/personalization/) # 内容个性化分析 ### 优化反应 Web SDK [指南](https://contentful.github.io/optimization/documents/Documentation.Guides.html) • 妇女 [参考文献](https://contentful.github.io/optimization) • 妇女 [捐款](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/CONTRIBUTING.md) Optimation React Web SDK 提供 React 提供者,钩子,路由器适配器,以及出入口 原始人顶上 [优化 Web SDK](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/web-sdk/README.md)反应时使用 浏览器应用程序不能管理级别较低的Web SDK实例、状态订阅、条目 并进行人工跟踪. 如果您正在整合 React 应用程序, 请从 [开始](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-getting-started),然后使用 [将优化回放Web SDK整合到一个回放应用程序中](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-react-web-sdk-in-a-react-app.html) 为分步流出. 此 README 保持软件包取向和常见设置选项的关闭 手动; 生成 [参考文件](https://contentful.github.io/optimization) 仍为 导出 API 签名的真伪来源 . > \[大 > > 从v1升级? 跟着 [v1-v2 迁移指南](https://contentful.github.io/optimization/documents/Documentation.Guides.migrating-optimization-sdk-packages-from-v1-to-v2.html) 在更改软件包版本之前. 目录 - [开始](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-getting-started) - [何时使用此软件包](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-when-to-use-this-package) - [通用配置](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-common-configuration) - [核心工作流程](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-core-workflows) - [同意](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-consent) - [提供商和钩子接入](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-provider-and-hook-access) - [供应商管理的国家订阅](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-provider-managed-state-subscriptions) - [首页决定前的工作](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-work-before-the-initial-page-decision) - [仅分析的交割](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-analytics-only-handoff) - [优化输入](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-optimizedentry) - [条目互动跟踪](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-entry-interaction-tracking) - [路由器页面事件](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-router-page-events) - [实时更新和预览](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-live-updates-and-preview) - [Web 组件](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-web-components) - [利用发展](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-development-harness) - [相关](https://npmcn.com/package/%40contentful/optimization-react-web/#readme-related) ## 开始 使用与国家预防机制兼容的软件包管理器安装,例如: ```sh pnpm install @contentful/optimization-react-web ``` 添加 `contentful` 也当 `OptimizationRoot` 将使用您的应用程序 `contentful.js` 客户端用于 正在获取管理条目. React and React DOM是应用程序拥有的同级依赖关系. SDK 已经使用 React 运行时间 由您的应用程序安装,而不是安装自己的副本. 挂载 `OptimizationRoot` 一旦接近您的反应应用程序根 : ```tsx import { OptimizationRoot } from '@contentful/optimization-react-web' function App() { return ( ) } ``` 对于获取内容条目的单一本地化应用程序,当 API的反应和事件需要使用同样的语言: ```tsx ``` ## 何时使用此软件包 使用 `@contentful/optimization-react-web` 用于需要基于提供者的 SDK 反应浏览器应用程序 初始化、钩子、路由器页面跟踪、优化条目渲染、自动交互 跟踪,并实时更新语义. 直接使用下级的 Web SDK 非反应集成 或自定义框架适配器. ## 通用配置 `OptimizationRoot` 直接接受大多数 Web SDK 配置道具并添加 React 专用道具 例如 `liveUpdates`, (中文(简体) ), `onStatesReady`, (中文(简体) ), `handoff`,以及 `hydration`网络 SDK `autoTrackEntryInteraction` 选项作为反应被曝光 `trackEntryInteraction` 道具 (英语). | Prop | 需要吗? | 默认 | 说明 | | --- | --- | --- | --- | | `spaceId` | 对 | 不详 | 用于体验和透视 API 请求的空间标识符 | | `environment` | 没有 | `'master'` | 经验与洞察 API 请求的内容环境标识符 | | `api` | 没有 | Web SDK 默认值 | API 和 Insights API 端点和请求选项 | | `app` | 没有 | `undefined` | 将事件上下文附加的应用程序元数据 | | `contentful` | 没有 | `undefined` | 注册 `contentful.js` 客户端、 默认查询和缓存 | | `locale` | 没有 | `undefined` | SDK 体验 API 和默认事件 locale | | `defaults` | 没有 | `undefined` | 配置/默认状态,如同意或持久性同意 | | `handoff` | 没有 | `undefined` | 服务器、静态或边缘 优化交接到水合物 | | `hydration` | 没有 | `handoff?.hydration` | 优化条目的内容水分展示模式 | | `prefetchManagedEntries` | 没有 | `undefined` | SDK准备完毕后 管理入场描述 | | `allowedEventTypes` | 没有 | `['identify', 'page']` | 在明确规定同意前允许的活动类型 | | `trackEntryInteraction` | 没有 | `{ views: true, clicks: true, hovers: true }` | 自动输入交互跟踪 `OptimizedEntry` 要素 | | `cookie` | 没有 | `{ domain: undefined, expires: 365 }` | 从 Web SDK 继承的匿名ID cookie 设置 | | `beforeInitialPage` | 没有 | `undefined` | 首页决定前完成的自有根回调 | | `liveUpdates` | 没有 | `false` | 是否为 `OptimizedEntry` 组件对 SDK 状态持续反应 | | `onStatesReady` | 没有 | `undefined` | 提供者管理的应用级状态订阅钩 | | `queuePolicy` | 没有 | SDK 默认 | Fush 重试行为和下行队列界限 | | `logLevel` | 没有 | `'error'` | 默认控制台槽的最低日志级别 | | `onEventBlocked` | 没有 | `undefined` | 当同意或守护逻辑阻挡事件时, 引用回调 | 使用 `OptimizationProvider` 应用程序或框架适配器需要直接提供者时直接 控制,包括提供SDK实例的集成。 用它来代替 `OptimizationRoot`, (中文(简体) ), 不在内 `OptimizationRoot`:根已经由提供方和活更新提供方组成. 嵌入提供者可以创建第二个拥有的 SDK 实例或阴影根上下文,包括 移交条目. ```tsx ``` 注射的SDK病例使儿童在初始成形。 何时 `handoff` 规定 初始渲染使用快照运行时提供商设置被注入的SDK水分. 提供者 仍然让SDK撕毁 给创造这个案例的主人. 对于服务器对浏览器状态交接,通过服务器,静态,或边缘 `OptimizationHandoff` 结束 `handoff` 打开 `OptimizationRoot` 或者说 `OptimizationProvider`。通过 `hydration` 关于同一部分 当路径需要覆盖交接的内容演示模式时. 保留 `defaults` 页:1 配置或默认状态, 如同意政策 : ```tsx ``` 过 `api.location` 通过正常 `OptimizationRoot` 或拥有 `OptimizationProvider` 配置 : ```tsx ``` 对于注入的 SDK ,配置 `api.location` 当建造SDK。 地点是 初始化范围,不是反应道具. 活动 `context.location` 优先于匹配 请求字段。 一个空的 `api.location: {}` 提供明确的空默认, 而不是 API 地理定位; 它没有清除当前配置位置或锁定位置, 覆盖以后的请求. 见 [位置输入和简介更新](https://contentful.github.io/optimization/documents/Documentation.Concepts.Profile_synchronization_between_client_and_server.html#location-inputs-and-profile-updates)。 。 。 . 对于通过此软件包的每个Web SDK选项,请使用 [Web SDK 读取器](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/web-sdk/README.md#common-configuration) 生成 [参考文件](https://contentful.github.io/optimization)。 。 。 . 在路由器、 i18n 层或应用程序配置中选择应用程序 Contentful locale 。 传过去 值直接转到内容 CDA 请求,并将相同值传递给提供者 `locale` 道具 当经验 API 响应和事件上下文需要使用相同的语言时. 见 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 为完整的地方模型. 对于从提供者/基层配置创建的 SDK 实例,修改 `locale` 道具调用 `sdk.setLocale()` 初始化之后, SDK 配置的其余部分仍然保留 初始化范围。 区域更新不获取内容或刷新配置状态; 触发您的 应用正常 `page()`, (中文(简体) ), `identify()`,路由加载器,或当本地化数据需要时 CDA 获取流量 变化. ## 核心工作流程 ### 同意 同意政策仍然是申请权。 对于未实现默认的应用政策 最终用户同意 `OptimizationRoot`数字 : ```tsx ``` 当应用程序政策取决于用户选择时,请离开 `defaults.consent` 未设置和呼叫 `setConsent()` 从 `useOptimizationActions()` 在相关控制中: ```tsx import { useOptimizationActions } from '@contentful/optimization-react-web' function ConsentButton() { const { setConsent } = useOptimizationActions() return } ``` 布尔同意呼吁控制事件排放和持久性特征的持久性,方法是 默认。 使用 `sdk.consent({ events: true, persistence: false })` 当事件被允许,但 连续性需要只保留会话。 关于跨 SDK 同意指南,见 [优化SDK套件中的同意管理](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/documentation/concepts/consent-management-in-the-optimization-sdk-suite.md)。 。 。 . ### 提供商和钩子接入 `OptimizationRoot` 拥有Web SDK生命周期. 提供者拥有的初始化运行于 React 之后 承诺,外出实现。 儿童在最初的即兴表演时,然后是布局效果 设置在正常浏览器渲染中第一个可见颜料之前初始化活的 SDK. 优化输入钩子还附加其控制器的收听器,采用当前选项,并连接 在布局阶段,这样加载或承诺的内容在涂料之前就解决。 与 `hydration="preserve-server"`,在条目输入时,服务器发送的内容仍可持续可见 采用活的 SDK 状态; 使用现有的根和条目 API . 当组件需要共同优化动作时使用专用的 React SDK 动作钩: ```tsx import { useOptimizationActions } from '@contentful/optimization-react-web' function ProductCta() { const { trackEvent } = useOptimizationActions() return } ``` 使用 `useOptimization()` 当一个组件需要直接访问 SDK 实例本身时,并选择 `useOptimizationActions()` 当组件需要可销毁的动作方法时,例如: `trackEvent()`, (中文(简体) ), `identifyUser()`, (中文(简体) ), `trackPageView()`, (中文(简体) ), `trackScreen()`, (中文(简体) ), `flushEvents()`, (中文(简体) ), `resetUser()`,或 `setConsent()`。 。 。 . 使用诸如 `useConsentState()`, (中文(简体) ), `useProfileState()`,以及 `useSelectedOptimizationsState()` 当组件需要使当前SDK状态。 喜欢那些 签名的钩子 `sdk.states.*` 直接从组件效果. 使用 `useEntryResolver()` 当一个组件需要手动解析 `OptimizedEntry` 包装 : `useOptimization()` 返回 SDK 实例本身。 将这个实例放在变量中并调用 方法从它。 不要从返回的值中解析 SDK 方法,因为这些方法依赖 在个案中 `this` 装订. ```tsx import { useOptimization } from '@contentful/optimization-react-web' function ProductCta() { const optimization = useOptimization() return } ``` 直接SDK表面也暴露出手动交互调用,例如: `trackView()`, (中文(简体) ), `trackClick()`, (中文(简体) ), `trackHover()`,以及 `trackFlagView()`。 。 。 . ```tsx // Avoid destructuring SDK methods; this loses the instance binding. const { track } = useOptimization() ``` ```tsx import { useEntryResolver } from '@contentful/optimization-react-web' function HeroEntry({ baselineEntry }) { const { resolveEntryData } = useEntryResolver() const resolvedData = resolveEntryData(baselineEntry) if (resolvedData.isEmptyVariant) return null return } ``` `resolveEntry()` 当代码仅需要解析的条目时仍然可用。 它不会暴露 空变态,所以使用 `resolveEntryData()` 或者说 `resolveOptimizedEntry()` 用于渲染 决定. 对于手动条目,在应用层中获取包含内容的条目,并在通过前使用一个 CDA 语言 他们去 `baselineEntry` 表面 。 用于管理取取,使用 `entryId` 可选 `entryQuery`,或 通过一个 `managedEntry` 对象为 `contentType`, (中文(简体) ), `slug`选项 `slugField`选择 `entryQuery`。 。 。 . `slugField` 默认为 `slug`。不要通过来自 `withAllLocales` 或者说 `locale=*`;这些API期望直接的单地域值. 见 [条目优化和变量分辨率](https://contentful.github.io/optimization/documents/Documentation.Concepts.Entry_personalization_and_variant_resolution.html#single-locale-cda-entry-contract) 进入合同和 [优化 SDK 套件中的位置处理](https://contentful.github.io/optimization/documents/Documentation.Concepts.Locale_handling_in_the_Optimization_SDK_Suite.html) 为更广泛的地方模式. 对于优化的条目内容,选择 `OptimizedEntry` 使上下文和通过 `getMergeTagValue` 进入儿童制造器: ```tsx import { OptimizedEntry } from '@contentful/optimization-react-web' function HeroEntry({ baselineEntry }) { return ( {(resolvedEntry, { getMergeTagValue }) => ( )} ) } ``` 使用 `useMergeTagResolver()` 用于在外解决合并标签的组件 `OptimizedEntry` 让道具. 如果合并标签引用本地化配置字段, 如 `location.city` 或者说 `location.country`, (中文(简体) ), 它的解析值遵循经验 API 返回的本地化配置值. ### 供应商管理的国家订阅 使用 `onStatesReady` 当应用程序代码需要作为提供者的一部分订阅 SDK 状态时 初始化。 这样可以避免与 `window.contentfulOptimization`,则可能不存在 然而,当应用程序代码运行或可能已经发布数据时,在后一效果之前 订户. ```tsx { const subscriptions = [ states.eventStream.subscribe((event) => { if (event) devToolsPanel.logEvent(event) }), states.blockedEventStream.subscribe((blocked) => { if (blocked) devToolsPanel.logBlockedEvent(blocked) }), ] return () => { subscriptions.forEach((subscription) => subscription.unsubscribe()) } }} > ``` 只收回电 `sdk.states`。当布局效果提供者设置初始化时,它会运行 活的状态表面。 初生儿童已经可以按即兴表演时间来制作 订阅仍然可以观察由路由器页面跟踪等儿童效应所释放出的事件. 对于 组件 - 本地 UI 状态, 在提供者下继续使用钩和反应效果. ### 首页决定前的工作 使用 `beforeInitialPage` 拥有的 `OptimizationRoot` 当浏览器身份或自定义体验 事件工作必须在根的初始页面决定前完成。 首页决定是 root 是发送首个浏览器页面事件或跳过它的一个选择, 因为已应用交接 拥有这条路线。 在 root 的自定义运行时间存在后, 回调会接收到接收器的安全性 `identify`, (中文(简体) ), `screen`,以及 `track` 方法,这样你就可以解构和调用它们 而不失去 SDK接收器 : ```tsx ({ properties: { route: routeKey } })} beforeInitialPage={{ run: async ({ identify }) => { await identify({ userId: visitor.id }) }, onError: reportBeforeInitialPageError, }} > ``` 一个根 `beforeInitialPage` 需求 `routeKey` 懒惰的 `buildPagePayload`,它没有 接受 `initialPagePayload`。应用程序拥有 `routeKey` 作为当前路线的稳定特征 拥有 `buildPagePayload` 作为懒于阅读当前页面数据。 根等待着返回的工作 `run` 或其监督员,为一次直接的页面尝试读取最新路线和有效载荷构建器, 以未排放初始值激活已存在的页面发送器 `skip` 标记尝试路线, 并通常为以后的路由变化而发出。 成功应用的同路交接方式可以实现 直接页决定a `skip`; 否则, 直接页面尝试使用 `emit`。 。 。 . 此根是其子树的唯一页面拥有者 。 也不要挂载反相路由器、 TanStack 路由器, Next.js App路由器,或Next.js Pages路由器自动页面跟踪器. 奥米 `beforeInitialPage` 当 a 单独的路由器跟踪器拥有页面事件。 该选项只提供给自有内容根; `OptimizationProvider`,注入提供者,以及 `OptimizationAnalyticsRoot` 不接受这一点. 何时 `maxWaitMs` 被省略,默认为3,000毫秒。 它接受积极的有限价值. `0`, (中文(简体) ), 负值, `NaN`, (中文(简体) ), `Infinity`,以及 `-Infinity` 同步掷出 `TypeError('beforeInitialPage.maxWaitMs must be a positive finite number.')` 在供应商之前, 回调、 页面或 `onError` 运行. 序为最上相. 返回必须在页前完成的所有承诺或可兑现的承诺; 火灾和遗忘的工作随着以后的活动而继续。 拒绝回电或监察到期 结束 `onError` 当供应。 虽然根仍被挂起 并且拥有相同的实时运行时间是 当前, 页面仍在尝试中 。 监视器停止等待, 但不会取消回调代码 或飞行请求。 如果根卸载或运行时间被替换,则只替换未发送的本地页面和 准备继续被压制. 在直接页面尝试开始后, 路由更改既不取消, 也不启动 竞相尝试。 根会安顿下来,并标出捕捉到的路线,然后允许 页面排放。 仅在飞行中尝试时观察到的航道没有释放;航道变化 准备就绪后正常发射 现有优化的入场期限可承诺基准内容 首先,默认 `liveUpdates={false}`,这个倒置 仍然冻结在之后 初页前的工作后来获得成功. ### 仅分析的交割 使用 `OptimizationAnalyticsRoot` 当一条路由已经在服务器上优化了内容时, 在静态生成时, ISR, 或在边缘, 浏览器只需要水合分析, page 跟踪和输入互动跟踪。 交接必须用 `hydration: 'analytics-only'`· ; 内容能力交割仍属于 `OptimizationRoot` 或者说 `OptimizationProvider`。 。 。 . ```tsx import { OptimizationAnalyticsRoot } from '@contentful/optimization-react-web' function App({ handoff, routeKey }) { return ( ) } ``` 过 `initialPagePayload` 或者说 `buildPagePayload` 当初始浏览器页面事件需要路由时 超出默认路由身份的有效载荷字段. ### 优化输入 `OptimizedEntry` 以 ID 或 一种 `managedEntry` 根时描述符 SDK 配置为 `contentful: { client }`,然后使选定的变体或基线. `baselineEntry` 仍然支持手动路径 : ```tsx import { OptimizedEntry } from '@contentful/optimization-react-web' function HeroEntry({ baselineEntry }) { return ( {(resolvedEntry, { getMergeTagValue }) => ( )} ) } ``` 模拟不同内容类型的基线和变体条目,见 [条目优化和变量分辨率](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/documentation/concepts/entry-personalization-and-variant-resolution.md)。 。 。 . 何时 `OptimizationRoot` 使用配置的 Web SDK `contentful: { client }`,反应条目 表面可以按内容类型取取和通过 `managedEntry`。 。 。 . `slugField` 当 字段名称 `slug`数字 : ```tsx function HeroEntry() { return ( } errorFallback={() => } > {(resolvedEntry) => } ) } ``` 使用 `prefetchManagedEntries` 打开 `OptimizationRoot` 或者说 `OptimizationProvider` 暖和客户端 运行 SDK 后管理入库 。 用于安全部门改革的交割,放入 `ManagedEntryHandoff[]` 数值 内 `handoff.entries`· ; `prefetchManagedEntries(runtime, descriptors)` 返回时的形状 服务器上有运行时间 。 将规范的描述符嵌入其中 `managedEntry` 并保留取入的条目 `sys.id` 内 `entryId`,因此匹配浏览器弹片 源水合物不另取取. Hooks使用相同的管理条目源: ```tsx import { useOptimizedEntry } from '@contentful/optimization-react-web' function HeroEntry() { const { entry, error, isLoading } = useOptimizedEntry({ managedEntry: { contentType: 'page', slug: 'home', entryQuery: { locale: 'en-US' }, }, }) if (isLoading) return if (error || !entry) return return } ``` `baselineEntry` 继续支持并选择手动路径。 使用 `onEntryError` 应用程序时 代码需要日志或报告管理的 CDA 失败。 使用 `errorFallback` 打开 `OptimizedEntry` 将提交 对管理的 CDA 失败的倒置 UI 。 使用 `onEntryResolved`或钩子的 `metadata` 财务报告和审定财务报表 `isResolved` 字段,当应用程序代码需要基线 ID,解析的条目 ID, 或优化跟踪属性后的背景。 成功的弹片检查报告以及 跟踪已获取的条目 `sys.id`而不是子弹. 使用 `loadingFallback`直接的孩子,包装道具, 和巢状的成分模式 必要时. 对于优化的条目,在优化未解决的情况下,立即开始加载相. 如果 状态在 5 秒后仍未解决, 组件会显示基线内容, 从而加载 而不是永远坚持下去。 没有习惯 `loadingFallback`,包装器通过隐藏 基线直到暂停。 该基准是其基准条目的第一项内容 ID,因此后期待定或失败状态无法恢复加载. 反应网络指南覆盖这些 上下文中的变体. ### 条目互动跟踪 `OptimizedEntry` 发布Web SDK的 `data-ctfl-*` 跟踪已解决条目的属性。 这个 root 配置观察到视图、单击和默认徘徊;通过 `false` 用于任何交互类型 您的申请不想遵守: ```tsx ``` 使用 `OptimizedEntry` 配置 Web SDK 条目跟踪属性的道具, 不设置 `data-ctfl-*` 手动操作元数据 : ```tsx {(resolvedEntry) => } ``` `OptimizedEntry` 生成条目ID、基线ID、优化ID、优化上下文ID、粘贴 状态、变量索引和来自已解决的条目状态的重复范围。 查看和徘徊时间使用 web SDK的固定阈值和间隔. 使用 `sdk.tracking.enableElement(...)` 从 `useOptimization()` 用于手动元素覆盖. ### 路由器页面事件 路由器适配器发射 `page()` 支持客户端路由器的事件 : | 路由器 | 导入路径 | 上载规则 | | --- | --- | --- | | 反应路由器 | `@contentful/optimization-react-web/router/react-router` | 在反应路由器数据路由器下和内部挂载 `OptimizationRoot` | | 下一个.js 页 | `@contentful/optimization-react-web/router/next-pages` | 挂载一次 `pages/_app.tsx` 内部 `OptimizationRoot` | | Next.js App路由器 | `@contentful/optimization-react-web/router/next-app` | 装入 `app/layout.tsx` 内部 `OptimizationRoot` | | TanStack 路由器 | `@contentful/optimization-react-web/router/tanstack-router` | 在 TanStack 路由器树下和内部挂起 `OptimizationRoot` | 这个 `next-pages` 追踪器仍然可用于低等Pages路由器接线。 完整 Next.js 页面 路由器 SSR 设置 `getServerSideProps`要求交接 和匿名身份饼干写, 更喜欢 [`@contentful/optimization-nextjs/pages-router`](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/frameworks/nextjs-sdk/README.md#pages-router-setup) 适配器 路径. 所有适配器都支持静态和动态的页载荷浓缩. 见 [反应网络集成指南](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-react-web-sdk-in-a-react-app.html#5-emit-page-events-with-supported-router-adapters) 用于路由器特定示例. ### 实时更新和预览 `liveUpdates` 默认为 `false`,因此优化了条目,保留了它们的第一个内容 基线条目编号。 设定 `liveUpdates` 全球或 `OptimizedEntry` 当条目必须响应配置文件、旗帜或预览时 变化 : ```tsx {(resolvedEntry) => } ``` 浏览器预览面板由 [`@contentful/optimization-web-preview-panel`](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/preview-panel/README.md)当面板是 打开, 现场更新强制为所有人 `OptimizedEntry` 组件,使作者可以检查变体 立即改变. ### Web 组件 React SDK继续渲染React组件. `OptimizedEntry` 不通过自定义渲染 元素,此软件包不导入或注册 Web 组件. 使用可选 `@contentful/optimization-web/web-components` 只在非反应应用程序或 一个刻意定制的岛屿需要香草定制元素. 围绕这些框架包装 元素必须指定复杂的 DOM 属性, 如 `baselineEntry`, (中文(简体) ), `defaults`, (中文(简体) ), `api`, (中文(简体) ), `sdk`,以及 水分后调用回调, 并倾听进入生命周期事件, 而不是试图模仿 React 制造道具。 见 [Web SDK 读取器](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/web-sdk/README.md#usage-with-web-components) 用于生 定制元素和UMD使用. ## 利用发展 软件包-本地开发工具来自 `packages/web/frameworks/react-web-sdk/dev/`发射 从回波根: ```sh pnpm --filter @contentful/optimization-react-web dev:launch ``` 利用这把带来开发软件包. 使用参考执行进行端到端整合 行为. ## 相关 - [将优化回放Web SDK整合到一个回放应用程序中](https://contentful.github.io/optimization/documents/Documentation.Guides.integrating-the-react-web-sdk-in-a-react-app.html) - 说吧 一步步前进 反应整合指南 - [优化 Web SDK](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/web-sdk/README.md) - 由这个软件包包裹的更低级浏览器SDK - [优化网络组件](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/web-sdk/README.md#usage-with-web-components) - 可选 从 Web SDK 包中曝光的香草自定义元素 - [优化网络预览面板](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/packages/web/preview-panel/README.md) - 预览面板软件包 浏览器创建工作流程 - [React Web 引用执行](https://github.com/contentful/optimization/blob/optimization-react-web-v2.1.3/implementations/react-web-sdk/README.md) - 说吧 应用程序使用提供者、路由器跟踪、优化条目、实时更新和条目跟踪 ## 常见问题 ### @contentful/optimization-react-web 是什么？ 内容优化反应 SDK ### 如何安装 @contentful/optimization-react-web？ 在项目目录运行 npm install @contentful/optimization-react-web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.3\.1）、react-dom（\>=18\.3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @contentful/optimization-react-web 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @contentful/optimization-react-web 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @contentful/optimization-react-web 可以商用吗？ @contentful/optimization-react-web 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @contentful/optimization-react-web 的下载量有多少？ 根据 npm 官方下载统计，@contentful/optimization-react-web 在 2026/10/11 – 2026/11/09 这 30 天内被下载 3,944 次，日均约 131 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @contentful/optimization-react-web 还在维护吗？ 最新版本 2\.1\.3 发布于 2026/11/06（4 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/04/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。