# @contentful/experiences-visual-editor-react 中文文档

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

版本：4\.0\.2
npm 元数据更新时间：2026-11-12T11:19:16.643Z
中文译文更新时间：2026-11-12T11:20:38.847Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：8.5 MB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2024-03-04T16:18:36.612Z
- 最新版本发布：2026-11-12T11:19:16.353Z
- 近 30 天下载量：108334（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：853（近 12 个月 95 个）

## 中文简介

_说明_: 本软件包无意被最终用户直接使用. 这是工作室体验包的依赖。 此软件包的更改不能保证在语义化后进行,如果直接使用,可以不经通知而中断.

## 安装

```sh
npm install @contentful/experiences-visual-editor-react
```

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

## README

# @ 内容/ 经验- 视频- 编辑- 反应

## 私人软件包通知

_说明_: 本软件包无意被最终用户直接使用. 这是工作室体验包的依赖。 此软件包的更改不能保证在语义化后进行,如果直接使用,可以不经通知而中断.

### 目的

-   处理画布交互逻辑,包括拖放,打箱,放放区,重现,并与父框架沟通,以确保平滑地拖放体验.
-   请注意,此套件是React特有的框架.

### 概念

-   **结构组成部分**: 与用户体验布局有关的组件,如容器、区段和列.
-   **内建组件**: 代表用户提供内容的组件,这些组件被认为普遍有用,如图像,文本,和分隔器组件,或让用户快速启动,如按钮等. 请注意,这些组件并不是要覆盖用户可能希望拥有的每一个可能的组件. 相反,一般期望用户提供自己的一套组件来积累自己定制的经验。 例外情况一般将基于这种组件的普遍期望,例如今后卡片或木卫一组件.
-   **自定义组件**:通过经验SDK提供的定义构建的用户提供的组件.
-   **邮件**:为了让一个iFrame与其母帧进行通信,需要后信息,使两个帧能够相互通信. 共享信息的例子包括鼠标坐标或被取出并丢弃的组件.
-   **浏览器限制**:目前只有Chrome支持Click/Drag和Drop,而Safari和Firefox只允许Click和Drop.
-   **树**: 经验存储了自己版本的从真实来源中分离出来的树被存储为Contentful条目. 这是因为通过存储自己的树版,它可以为树提供UI优化和操纵,以最大限度地实现与性能有关的任务,例如当执行组件的拖放或重排时. 需要这种优化的一个具体例子是,当您将一个组件放入画布时。 没有自己的版本,组件会在基于鼠标位置的预定区域被放入之前会闪烁到其原有的被擦拭前地段.
-   **更新真相来源**: 在拖放端, iFrame 将更新自己的树后, 才会向父框发送邮件 `useCanvasInteractions`。然后,父框架将更新其树,这是真理的来源,然后发送 MSG 回信 `useEditorSubscriber` 至iFrame,确保两棵树相同,任何发现的相差之处得到解决.
-   **@hello-pangea/dnd (韩语)**: 图书馆提供HOC(更高级的订单组件),经验为拖放提供杠杆. 此库中使用的两个组件是 `Droppable` 财务报告和审定财务报表 `Draggable` 组件.
-   **区域**: Div 包装符,代表要投放的其他组件的区域. 请注意,每次只能通过一个击出箱激活一个,并且是一个单独的从 `Draggables`。 。 。 .
-   **拖动**: 允许组件取出并投放的Div包装. 请注意,这是与 `Dropzones`。 。 。 .
-   **模拟 DnD**: 自定义构造的 DND 组件, 作为将一个组件从侧边栏拖入 iFrame 时的视觉花招。 由于在点击并拖曳新组件时拖曳是在母框中启动的,因此也触发了iFrame中模拟动作,因此iFrame处于和母框一样的拖曳状态. 然后当鼠标从母框交叉进入iFrame时,需要将后信息发送到iFrame会将鼠标坐标发送到父框Frame,这样被拖走的组件图标被放在正确的位置上,而iFrame会触发适当的命中框和空投区,因为所有的命中框和空投区都生活在iFrame.
-   **组件包装**: 有几种类型的 div 包装, 如 `Dropzones` 财务报告和审定财务报表 `Draggables`然而,还有一个包装器作为自定义布尔选项提供 `Custom Components`。当此布尔值为真时,从 UI 中选择的所有样式选项都将被应用到此包装 div 中。 这样做是为了保存用户在自己的组件上的CSS样式,并屏蔽UI中选择的样式选项.

### 相关内容文件链接

-   [内容丰富的条目树数据结构](https://www.contentful.com/developers/docs/experiences/data-structures/)

## 常见问题

### @contentful/experiences-visual-editor-react 是什么？

说明: 本软件包无意被最终用户直接使用\. 这是工作室体验包的依赖。 此软件包的更改不能保证在语义化后进行,如果直接使用,可以不经通知而中断\.

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

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

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

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

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

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

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

@contentful/experiences-visual-editor-react 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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