# @grapesjs/react 中文文档

规范地址：https://npmcn.com/package/%40grapesjs/react/

版本：2\.0\.0
npm 元数据更新时间：2026-03-06T15:14:03.871Z
中文译文更新时间：2026-11-16T22:34:52.090Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：46.1 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，grapesjs ^0\.22\.5，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2023-07-04T13:43:39.455Z
- 最新版本发布：2025-02-20T12:49:10.168Z
- 近 30 天下载量：360984（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 0 个）

## 中文简介

![](https://github.com/GrapesJS/react/assets/11614725/ca2cdbef-4ad2-4e5e-b0a1-c8218065efca)

## 安装

```sh
npm install @grapesjs/react
```

也可以使用：`pnpm add @grapesjs/react`、`yarn add @grapesjs/react`、`bun add @grapesjs/react`

## README

# 葡萄JS 反应

![](https://github.com/GrapesJS/react/assets/11614725/ca2cdbef-4ad2-4e5e-b0a1-c8218065efca)

> 要求葡萄JS v0.21.3 或更高

官员 [葡萄JS( 葡萄)](https://grapesjs.com/) react 的包装,允许您为编辑器构建自定义和声明UI.

这个库的目的不是提供UI组件,而是在核心葡萄JS模块周围提供简单的包装,让你定义自己的UI组件并方便地访问GrapesJS API.

> **3⁄4 ̄ ̧漯B**: 这个库并不是为了在 GrapesJS 画布中渲染出您的反应组件, 这里所有的内容都是在画布本身周围的自定义 UI .

## 安装

核心内容 `grapesjs` 库不与包件本身相捆绑,所以必须分别安装.

```sh
npm i grapesjs @grapesjs/react
```

## 兼容性

#### @grapesjs/反应 v1.X

-   反应 v18.X
-   葡萄JS v0.21.3或以上
-   下一个JS v14.X

#### @grapesjs/反应 v2.X

-   反应 v18.X 或 v19.X
-   葡萄JS v0.22.5 或更高
-   下一个JS v15.X

### 默认 UI

这是使用GrapesJS包装最简单更传统的方法,因为它依赖于GrapesJS提供的默认UI. 从React的角度来看,这种方法不太适合自定义,所有的UI定制都必须通过GrapesJS(基本上没有包装器你会怎么做)来完成.

```ts
import grapesjs, { Editor } from 'grapesjs';
import GjsEditor from '@grapesjs/react';

export default function DefaultEditor() {
  const onEditor = (editor: Editor) => {
    console.log('Editor loaded', { editor });
  };

  return (
    <GjsEditor
      // Pass the core GrapesJS library to the wrapper (required).
      // You can also pass the CDN url (eg. "https://unpkg.com/grapesjs")
      grapesjs={grapesjs}
      // Load the GrapesJS CSS file asynchronously from URL.
      // This is an optional prop, you can always import the CSS directly in your JS if you wish.
      grapesjsCss="https://unpkg.com/grapesjs/dist/css/grapes.min.css"
      // GrapesJS init options
      options={{
        height: '100vh',
        storageManager: false,
      }}
      onEditor={onEditor}
    />
  );
}
```

[生活实例](https://stackblitz.com/edit/grapesjs-react-default-ui)

### 自定义用户界面

这是使用包装器的更有力和宣示性的方法,因为它让你完全控制了编辑的UI. 使用 `<Canvas/>` 主包件中的组件会禁用核心默认的 UI .

```ts
import grapesjs, { Editor } from 'grapesjs';
import GjsEditor, { Canvas } from '@grapesjs/react';

export default function CustomEditor() {
  const onEditor = (editor: Editor) => {
    console.log('Editor loaded', { editor });
  };

  return (
    <GjsEditor
      grapesjs={grapesjs}
      grapesjsCss="https://unpkg.com/grapesjs/dist/css/grapes.min.css"
      onEditor={onEditor}
      options={{
        height: '100vh',
        storageManager: false,
      }}
    >
        <div>
        // ... use your UI components
            <Canvas /> // place the GrapesJS canvas where you wish
        // ...
        </div>
    </GjsEditor>
  );
}
```

您可以在下面找到一个很好的例子( 使用所有可用的提供者) , 通过使用自己的 React 组件, 您可以在 GrapesJS 周围构建一个完整的自定义编辑器 .

> **说明**:应用程序没有覆盖所有 [葡萄JS API](https://grapesjs.com/docs/api/) 但只是提供了一个很好的起点 来理解如何创建自己的自定义编辑器.

[生活实例](https://stackblitz.com/edit/grapesjs-react-custom-ui)

### 把编辑器放进组件

您可以轻松地访问自定义组件中的编辑器实例 `useEditor` 钩. 唯一的警告是,一旦编辑器实际创建出来,就使用它 `<WithEditor>` 作为包装的组件。 或者,你可以使用 `useEditorMaybe` 钩并亲自检查编辑器是否存在.

```ts
import GjsEditor, { WithEditor, useEditor, useEditorMaybe } from '@grapesjs/react';

function MyComponentWithUseEditor() {
    // The `editor` is always defined.
    const editor = useEditor();
    return (...);
}

function MyComponentWithUseEditorMaybe() {
    // The `editor` is not immediately available
    const editor = useEditorMaybe();
    return (
        <div>
            <div>I will be rendered immediately</div>
            <div>
                Editor: { editor ? 'created' : 'not yet created' }.
            </div>
        </div>
    );
}

export default function CustomEditor() {
  return (
    <GjsEditor ...>
        // ...
        <WithEditor>
            // This component won't be rendered until the editor is created
            <MyComponentWithUseEditor/>
        </WithEditor>
        <MyComponentWithUseEditorMaybe/>
    </GjsEditor>
  );
}
```

> 通过使用内置提供者内部的组件 `editor` 总是被定义.

## 发展

清除仓库

```sh
$ git clone https://github.com/GrapesJS/react.git
$ cd react
```

安装它

```sh
$ yarn i
```

启动 dev 服务器

```sh
$ yarn start
```

## 许可证

麻省理工学院

## 常见问题

### 如何安装 @grapesjs/react？

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

### @grapesjs/react 支持 TypeScript 吗？

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

### @grapesjs/react 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @grapesjs/react 可以商用吗？

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

### @grapesjs/react 的下载量有多少？

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

### @grapesjs/react 还在维护吗？

最新版本 2\.0\.0 发布于 2025/02/20（1\.7 年前）；至今共发布 4 个版本，其中过去 12 个月发布了 0 个；首次发布于 2023/07/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

