# @contentful/experiences-sdk-react 中文文档

规范地址：https://npmcn.com/package/%40contentful/experiences-sdk-react/

版本：4\.0\.2
npm 元数据更新时间：2026-11-12T11:22:42.672Z
中文译文更新时间：2026-11-12T11:25:53.273Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40contentful/experiences-sdk-react
原文对照：https://npmcn.com/package/%40contentful/experiences-sdk-react/?lang=original
项目主页：https://github.com/contentful/experience-builder#readme
源码仓库：https://github.com/contentful/experience-builder

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：309 kB，116 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0，contentful \>=10\.6\.0
- 首次发布：2024-03-04T16:18:50.800Z
- 最新版本发布：2026-11-12T11:22:42.465Z
- 近 30 天下载量：107608（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：858（近 12 个月 94 个）

## 中文简介

需要反应和反应DOM 18或以后. 反应 16 和 17 消费者在安装此版本之前,必须升级两个包. SDK使用Zustand 5,它依赖于反应 18's `useSyncExternalStore` API (英语).

## 安装

```sh
npm install @contentful/experiences-sdk-react
```

也可以使用：`pnpm add @contentful/experiences-sdk-react`、`yarn add @contentful/experiences-sdk-react`、`bun add @contentful/experiences-sdk-react`

## README

# @ contentful/ experience- sdk- react

### 反应支持

需要反应和反应DOM 18或以后. 反应 16 和 17 消费者在安装此版本之前,必须升级两个包. SDK使用Zustand 5,它依赖于反应 18's `useSyncExternalStore` API (英语).

### 目的

-   要捆绑并曝光其他包中的功能,供最终用户使用. 这是用户将安装的软件包并导入到自己的React项目.
-   注意,这是针对特定反应的包. 因此,与核心软件包不同的是,在这里执行React特定兼容性,对其他前端框架的支持将导致在单独的命名空间下创建出一个新的软件包.

### 概念

-   **经验对象**:对什么是经验的通用打字定义. 包含关于组件树,无约束值,以及从内容条目中转换出的数据源的信息,这样经验包就可以使用被转换对象,处理被操纵到树上,验证其值,并将经验对象更新到内容条目中,作为用户触发并保存其更改.
-   **经验**:用户将在其反应项目中使用的主要切入点组件,在经验对象中将它作为道具。 经验对象可以通过多种方式取出. 例如,Vite反应项目的一个常见方法是使用 `useFetchBySlug/useFetchById` 钩子. 然而,对于安保部门改革,他们将使用 `fetchBySlug/fetchById` 函数。 此外,用户可以使用自定义的变换来创建自己的体验对象,并将被变换的对象作为道具传递给 `ExperienceRoot` 但物体必须符合经验类型.
-   **安全部门改革**:使SDK与SSR相容是在SDK包本身中提供的. 然而,人们正在讨论将逻辑纳入今后的核心一揽子计划.
-   **断点**:定义我们如何为每个取景口分别桌面,平板电脑和移动断点.
-   **预览 vs Live vs编辑器模式**:编辑器模式是在Contentful Web app中看到的关于组件侧边栏,可视化编辑器的经验,以及设计侧边栏中允许用户拖放组件,编辑样式,并发布更改的内容. Live模式是查看用户在已发布更改方面的经验的能力. 预览模式(Preview mode)是指能够看到用户在未发表的更改中的经历.
-   **预览交付 Root 相对于视觉编辑器 Root**: 在 `ExperienceRoot.tsx` 文档中,请注意有逻辑来渲染 `<VisualEditorRoot>` 对 `<PreviewDeliveryRoot>` 根据用户是否处于编辑器模式。 两种相容物的注释,它们都有自己通过整个构件树进行解析的方法,并将构件制成UI. 这是因为Visual编辑器必须添加可拖放的包式 divs,而Preview的发送只能按原样将组件打印到UI. 此外,"预览交付"这个名称将"活"和"预览模式"概念汇合为一个想法. 在现实中,PreviewdeliveRoot更像Live模式概念. 有计划进行平移并构建预览和重命名的第三个模式 `<PreviewDeliveryRoot>` 仅仅 `<DeliveryRoot>` 或者说 `<LiveRoot>`。 。 。 .
-   **预览 vs 交付 API**:每个体验对象将从通过Contentful的"传送"或"预览API"获取的内容条目取出其真实的来源. 用户会定义设置体验时使用的API. 这不应与“审查”或“交付/生活”模式相混淆,因为它们是独立的实体.
-   **书记官处**: 采用组件定义并将其登记到UI中 `enrichComponentDefinition` 函数将应用被组件本身定义为默认样式的样式。 这将确保用户拖曳内置或结构组件将显示由Contentful定义的默认样式.

### 相关内容文件链接

-   [构成部分定义方案a](https://www.contentful.com/developers/docs/experiences/component-definition-schema/)
-   [数据结构](https://www.contentful.com/developers/docs/experiences/data-structures/)

## 常见问题

### @contentful/experiences-sdk-react 是什么？

需要反应和反应DOM 18或以后\. 反应 16 和 17 消费者在安装此版本之前,必须升级两个包\. SDK使用Zustand 5,它依赖于反应 18's useSyncExternalStore API \(英语\)\.

### 如何安装 @contentful/experiences-sdk-react？

在项目目录运行 npm install @contentful/experiences-sdk-react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）、contentful（\>=10\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @contentful/experiences-sdk-react 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @contentful/experiences-sdk-react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @contentful/experiences-sdk-react 可以商用吗？

@contentful/experiences-sdk-react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @contentful/experiences-sdk-react 的下载量有多少？

根据 npm 官方下载统计，@contentful/experiences-sdk-react 在 2026/10/11 – 2026/11/09 这 30 天内被下载 107,608 次，日均约 3,587 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @contentful/experiences-sdk-react 还在维护吗？

最新版本 4\.0\.2 发布于 2026/11/12（今天）；至今共发布 858 个版本，其中过去 12 个月发布了 94 个；首次发布于 2024/03/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。