# @automattic/isolated-block-editor 中文文档

规范地址：https://npmcn.com/package/%40automattic/isolated-block-editor/

版本：2\.31\.0
npm 元数据更新时间：2026-11-06T18:39:07.452Z
中文译文更新时间：2026-11-07T07:04:05.307Z
软件包许可：GPL-2\.0-or-later

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

原始 npm 页面：https://www.npmjs.com/package/%40automattic/isolated-block-editor
原文对照：https://npmcn.com/package/%40automattic/isolated-block-editor/?lang=original
项目主页：https://github.com/Automattic/isolated-block-editor/blob/trunk/README.md
源码仓库：https://github.com/Automattic/isolated-block-editor

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

- 包体积（解压后）：6.3 MB，571 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14
- 运行依赖：58 个
- 首次发布：2021-07-20T08:26:56.213Z
- 最新版本发布：2026-10-21T06:24:33.661Z
- 近 30 天下载量：3001（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 2 个）

## 中文简介

将古腾堡的编辑操场重新包装为多功能编辑.

## 安装

```sh
npm install @automattic/isolated-block-editor
```

也可以使用：`pnpm add @automattic/isolated-block-editor`、`yarn add @automattic/isolated-block-editor`、`bun add @automattic/isolated-block-editor`

## README

# 孤立块编辑器

将Gutenberg的编辑操场重新包装为不需要WordPress的全功能多功能编辑器.

主要特点是:

-   扩展 Gutenberg 游乐场编辑器以匹配完整的编辑器
-   允许多个屏幕实例与数据存储和键盘处理器
-   撤消历史

和完整的特征列表:

-   动态地转换数据库,以便与第三方块相兼容
-   工作尺寸小于全屏
-   区块允许和不允许列表,每个实例
-   首选项( 保存到本地Storage) 和选项( 保存到内存), 每一个实例
-   超过 Gutenberg 关键存储功能
-   模式、可重复使用的块、组和模板支持
-   弹出式中块插入器
-   弹道巡查员
-   建入工具栏, 并带有显示更多菜单、 块检查器和块按钮的选项
-   全屏模式( 需要额外的 CSS)
-   预览模式(需要额外的CSS和JS)
-   视觉和代码编辑器
-   PHP( WordPress) 代码以装入 wp-admin 以外的编辑器
-   自定义链接的菜单
-   WordPress API 请求的路由调整

孤立块编辑器有三种形式:

-   ES6模块
-   通用JS模块
-   独立 JavaScript 文件, 用于任何浏览器页面

这个库只与下文所列举的古腾堡的具体版本相配合.

要求: Gutenberg 16.9

实例:

-   [纯文本编辑器](https://github.com/Automattic/isolated-block-editor/blob/trunk/src/browser/README.md) - 独立的JS和CSS文件,可以取代任何 `textarea` 带有完整 Gutenberg 编辑器的任何页面
-   [区块](https://github.com/Automattic/blocks-everywhere/) - WordPress插件,用于将Gutenberg添加到注释,WP管理页面,bbPress,和BuddyPress中
-   [Gutenberg Chrome 扩展](https://github.com/Automattic/gutenberg-everywhere-chrome/) - 允许Gutenberg用于任何一页的Chrome扩展
-   [古腾堡桌面](https://github.com/Automattic/gutenberg-desktop/) - 支持 HTML 和 Markdown 文件加载和保存的桌面编辑器
-   [临2](https://wordpress.com/p2/) - WordPress作为协作工作空间(即将自我主持)
-   编辑器块 - 允许编辑器被添加到页面中的块( 即将到来)

你在自己的项目里用这个吗? 告诉我们!

## 我为什么要用这个?

Gutenberg 已经提供了一个游乐场,允许它用于WordPress之外. 这实际上被用作孤立块编辑器的基础.

然而,它提供了有限的一组特性,将其更进一步地扩展到一个可用的编辑器中可以需要一些努力. 例如,它不包括任何倒行逆施的历史.

"孤立的块"编辑器是一个处理许多这些复杂问题的全编辑器. 它不应被视为古腾堡游乐场的取而代之,而更像是顶上有观点的地层.

这应被视为试验性的,并可能有所改变.

## 捆绑和文字新闻

孤立块编辑器旨在提供一个尽可能与WordPress隔离的编辑器. 然而,它仍然可以在WordPress网站上使用,决定下到捆绑:

-   没有Gutenberg的 Bundled - 如果在WordPress网站上使用,那么您可以使用已经包含在WordPress中的Gutenberg代码. 您需要工作 WordPress 网站, 但不需要将 Gutenberg 包含在您的编辑中
-   与 Gutenberg - Gutenberg 一同被包含在编辑器中, 并且不依赖 WordPress 或 PHP

提供了这两种情况的例子(见A/CN.9/WG.III/WP.III/WP.48) [纯文本编辑器](https://npmcn.com/package/%40automattic/isolated-block-editor/examples/plain-text-editor/README.md) 用于捆绑和 [区块](https://github.com/Automattic/gutenberg-everywhere/) 以无结为分.

关键区别在于Webpack配置. 如果你不想让Gutenberg 和你的编辑捆绑在一起 那你就可以用 `DependencyExtractionWebpackPlugin` 插件 :

```js
plugins: [
    new DependencyExtractionWebpackPlugin( { injectPolyfill: true } )
]
```

或者你可以用这个 [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/packages/packages-scripts/) 自动运行的构建系统 `DependencyExtractionWebpackPlugin`数字 :

`wp-scripts start`

你可以使用提供 [`iso-gutenberg.php`](https://npmcn.com/package/%40automattic/isolated-block-editor/examples/wordpress-php/README.md) 在 WordPress 站点上使用孤立的Block编辑器时需要帮助的文件。 它会装入古腾堡 并设置你的配置.

## 独立模块

你可以使用提供 `isolated-block-editor.js`, (中文(简体) ), `core.css`,以及 `isolated-block-editor.css` 任何网页上的文件,无论是否在WordPress上。 它将提供两个全球功能,可以使 `textarea` 变成块编辑器。 举个例子:

```js
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="isolated-block-editor.js"></script>
<link rel="stylesheet" href="core.css" />
<link rel="stylesheet" href="isolated-block-editor.css" />

<body>
    <textarea id="editor"></textarea>

    <script>
        wp.attachEditor( document.getElementById( 'editor' ) );
    </script>
</body>

```

注意在装入编辑器前必须装入 React .

您可以在 [`src/browser/index.html`](https://npmcn.com/package/%40automattic/isolated-block-editor/src/browser/index.html)。 。 。 .

## 支助科

如果您在 WordPress 网站上使用, WordPress 将加载核心 Gutenberg CSS 作为其中的一部分 [`iso-gutenberg.php`](https://npmcn.com/package/%40automattic/isolated-block-editor/examples/wordpress-php/README.md) 剧本.

如果您没有在 WordPress 网站上使用, 您需要亲自加载核心 CSS 。 您可以通过包含以下模块并直接导入来做到这一点:

-   `@wordpress/components`
-   `@wordpress/block-editor`
-   `@wordpress/block-library`
-   `@wordpress/format-library`

```scss
@import '@wordpress/components/build-style/style.css';
@import '@wordpress/block-editor/build-style/style.css';
@import '@wordpress/block-library/build-style/style.css';
@import '@wordpress/block-library/build-style/editor.css';
@import '@wordpress/block-library/build-style/theme.css';
@import '@wordpress/format-library/build-style/style.css';
```

或者您可以直接导入捆绑 `build-browser/core.css` CSS: 请检查DATE=中的日期值 (帮助) CSS:

```js
import '@automattic/isolated-block-editor/build-browser/core.css';
```

## 使用

该模块目前只在Github上提供,可添加:

`npm install @automattic/isolated-block-editor@1.2.0 --save` (何处) `1.2.0` 是您要使用的版本)

## 未来

这里的代码处理两种问题:

-   给古腾堡游乐场增加一些功能 - 这些已经由古腾堡提供, 但在这里为你包装
-   给古腾堡添加工作变通——这些都是古腾堡不提供功能,或者不输出功能的情形,所以需要工作变通.

人们希望,大部分工作可以迁移回古腾堡,以便不再需要这些工作。 有时,这些变通办法涉及复制古滕贝格的部分,这是不理想的. 可能不再需要孤立块编辑器作为隔离实体.

## 发展

如果多个编辑器在屏幕上,那么 `IsolatedBlockEditor` 将确保 `wp` global 指的是当前重点突出的实例。 这将使它更能兼容插件和使用该插件的第三方代码 `wp` 全球.

### 使用量

包含 `IsolatedBlockEditor` 模块,然后创建实例:

```js

import IsolatedBlockEditor from '@automattic/isolated-block-editor';

render(
    <IsolatedBlockEditor
        settings={ settings }
        onSaveContent={ ( html ) => saveContent( html ) }
        onLoad={ ( parse ) => loadInitialContent( parse ) }
        onError={ () => document.location.reload() }
    >
    </IsolatedBlockEditor>,
    document.querySelector( '#editor' )
);
```

这个 `IsolatedBlockEditor` 还出口下列支助部分:

-   `EditorLoaded` - 包括在编辑器装入和装入时通知
-   `DocumentSection` - 将一个组件包装在检查员的文件标签上
-   `ToolbarSlot` - 将内容插入工具栏
-   `FooterSlot` - 在页脚中插入内容
-   `EditorHeadingSlot` - 在编辑区域开头插入内容。 适合标题.
-   `ActionArea` - 在动作边栏中插入内容

```js

import IsolatedBlockEditor, { EditorLoaded, DocumentSection, ToolbarSlot } from 'isolated-block-editor';

render(
    <IsolatedBlockEditor
        settings={ settings }
        onSaveContent={ ( html ) => saveContent( html ) }
        onLoad={ ( parse ) => loadInitialContent( parse ) }
        onError={ () => document.location.reload() }
    >
        <EditorLoaded onLoaded={ () => {} } onLoading={ () => {} } />
        <DocumentSection>Extra Information</DocumentSection>

        <ToolbarSlot>
            <button>Beep!</button>
        </ToolbarSlot>
    </IsolatedBlockEditor>,
    document.querySelector( '#editor' )
);
```

还提供以下职能:

-   `initializeEditor` 如果在使用前需要完成, 请使用此程序初始化编辑器 .

### 道具

#### 设置

-   _实值_ `[object]` - 孤立的Block编辑器设置对象
    
-   _a. 首选项_ `[string|null]` - 首选项 默认为禁用无效
    
-   _默认偏好_ {对象} - 默认偏好
    
-   _永久键_ `[string|null]` - 坚持键。 默认为禁用无效
    
-   _a. 海关仓库_ `[array]` - 以适合去古腾堡的形态排列的仓库物品 `createReduxStore`
    
-   _障碍_ `[object]` - 封锁限制
    
-   _a. blocks. allow Blocks (英语)_ `[string[]]` - 允许的块名列表,默认为无
    
-   _iso.blocks.disallow Blocks (英语)_ `[string[]]` - 不允许的块名列表,默认为无
    
-   _a. disallow Embed (英语)_ `[string[]]` - 要删除的嵌入式名称列表, 默认为无.
    
-   _工具栏_ `[Object]` - 工具栏设置
    
-   _iso.toolbar. 导航_ `[boolean]` - 启用或禁用工具栏导航按钮,默认为 `false`
    
-   _a. 工具栏. undo_ `[boolean]` - 启用或禁用工具栏撤销/重做按钮,默认为 `true`
    
-   _iso.toolbar.文档检查者_ `[string|null]` - 设置为字符串,以显示为检查员的新标签并填充 `DocumentSection`,否则默认为没有新标签
    
-   _a. 边栏_ `[Object]` - 边栏设置
    
-   _iso. sidebar. 插入器_ `[boolean]` - 启用或禁用侧边栏块插入器,默认为 `true`
    
-   _iso.sidebar. 督察员_ `[boolean]` - 启用或禁用侧边栏块检查器,默认为 `false`
    
-   _o. sidebar. 客户兼容程序_ `[function]` - 函数返回自定义侧边栏组件,或无法使用默认侧边栏
    
-   _(原始内容存档于2017-03-21). Iso. More Menu_ `[Object]` - 更多菜单设置
    
-   _更多梅努编辑器_ `[boolean]` - 启用或禁用编辑器子菜单(视频/代码编辑),默认为 `false`
    
-   _iso. more Menu. 全屏幕_ `[boolean]` - 启用或禁用全屏选项,默认为 `false`
    
-   _iso.moreMenu. 预览_ `[boolean]` - 启用或禁用预览选项,默认为 `false`
    
-   _iso. more Menu.top Toolbar 页面存档备份,存于互联网档案馆_ `[boolean]` - 启用或禁用“ 顶端工具栏” 选项, 默认为 `false`
    
-   _iso.link 梅诺_ `[array]` - 链接菜单设置。 矩阵 `title` 财务报告和审定财务报表 `url`,默认为无
    
-   _等离子体_ `[string]` - 起始模式,默认为无
    
-   _iso.allow Api (英语)_ `[boolean]` - 允许 API 请求,默认为 `false`
    
-   _编辑器_ `[object]` - Gutenberg 设置对象
    

一个包含孤立的Block编辑器以及Gutenberg的所有设置的设置对象. 未提供的任何设置都将使用默认值 .

该块允许和不允许列表的工作如下:

-   允许所有区块,除非 `allowBlocks` 选项设定定义允许的块列表
-   里面的东西 `disallowBlocks` 列表从允许的块列表中删除.

#### 保存状态

-   _内容_ - 要保存的内容, 作为 HTML 字符串

保存将内容保存为 HTML 字符串的回调 。 编辑器内容的每次更改都会被调用.

#### 保存锁定

-   _块_ `[Array]` - 要保存的块
-   _忽略内容_ `[Array]`\- 可忽略内容的 HTML 字符串阵列

保存提供块列表和被忽略内容列表的回调 。 这让更多的控制比 `onSaveContent`,如果想要过滤所保存的块,则使用。 譬如说, 如果您正在使用模板, 它将出现在 `ignoredContent`,然后你可以忽略 `onSaveBlocks` 如果符合,请打电话 `blocks`。 。 。 .

#### 登录

-   _剖析_ `[string]` - 古腾堡 `parse` 函数将 HTML 解析为字符串并返回块

将初始内容装入编辑器 。 这是一个在编辑器创建后运行的回调, 并且提供 `parse` 此编辑器实例所特有的函数。 这应该 用于提供合适的区块.

#### 实验性 Undo 管理器

编辑器要使用的替代历史撤销/重写管理器 。 对象通过时必须包含 `undo` (单位:千美元) `redo` 方法,以及 `undoStack` (单位:千美元) `redoStack` 包含相应历史的数组属性。 如果不提供,则使用默认历史管理. 这种地产是实验性的,可以随时改变或取出.

#### ——关于投入的实验

一个可选的回调,如果提供,将传递给古腾堡编辑器. 这种地产是实验性的,可以随时改变或取出.

#### ——关于变化的实验

一个可选的回调,如果提供,将传递给古腾堡编辑器. 这种地产是实验性的,可以随时改变或取出.

#### 实验价值

编辑器要显示的可选值( 块) 。 如果提供,它将作为显示的内部值/块. 这种地产是实验性的,可以随时改变或取出.

#### 实验性选择

在编辑器中选择更改时会调用的可选回调 。 唯一传递到回调的参数将是新选择值.

#### 错误

发生错误时回电 .

#### 类Name

编辑器附加的类名.

#### 制作多梅努

-   _菜单设置_ `[object]` - 此特定编辑器的设置
-   _关闭_ `[func]` - 回电关闭更多菜单

在菜单中添加组件 .

注:这需要改进或取而代之的是更加灵活的做法

#### 儿童

添加任何组件来自定义编辑器 。 这些组件可以访问编辑器的Redux商店.

#### 媒体上传器

如果您想要使用媒体上传器和媒体库, 您必须使用 `editor.MediaUpload` 过滤器。 例如,如果你想使用Gutenberg的媒体库,这将:

```js
import { MediaUpload } from '@wordpress/media-utils';

addFilter( 'editor.MediaUpload', 'your-namespace/media-upload', () => MediaUpload );
```

您还需要通过媒体上传器作为编辑器设置的一部分:

```js
import { mediaUpload } from '@wordpress/editor';

const settings = { your settings };

settings.editor.mediaUpload = mediaUpload;
```

在早于2.21.0的版本中,这是自动完成的,但这意味着你无法修改或禁用.

### 自定义设置侧边栏

默认情况下, 编辑器会使用 Gutenberg 设置侧边栏 。 这提供了块和文档检查员标签以及相关内容.

如果您想要自定义此侧边栏, 您可以使用 `iso.sidebar.customComponent` 设置并传递返回 React 组件的函数.

您需要自行管理侧边栏的显示, 包括是否显示 。 可能帮助我们看看 [已存在的侧边栏代码](https://npmcn.com/package/%40automattic/isolated-block-editor/src/components/block-editor/sidebar.js) 供参考.

例如:

```js
sidebar: {
    customComponent: () => <div>My custom sidebar</div>
},
```

### 扩展

自定义行为可以通过儿童成分来添加. 这些组成部分将可进入 `isolated/editor` 以及编辑器实例版本 `core/block-editor`。 。 。 .

### 古腾堡要求

Gutenberg 使用 iframes 来显示编辑器的各个部分, 它使用全球 `window.__editorAssets` 以存储将添加到此 iframe 中的样式和脚本。 你也许还需要 用这个.

默认为:

`window.__editorAssets = { styles: '', scripts: '' }`

数值应当完整 `<link>` 财务报告和审定财务报表 `<script>` 标签.

## 释放

为了释放你,确保你在树干分支。 不更新版本编号 `package.json` - 释放过程会为你做这个。 然后运行 :

`GITHUB_TOKEN=<TOKEN> yarn dist`

## 常见问题

如果故事书抱怨不同的ES6问题,那么有时可以用 `npx yarn-deduplicate --scopes @babel`

## 常见问题

### @automattic/isolated-block-editor 是什么？

将古腾堡的编辑操场重新包装为多功能编辑\.

### 如何安装 @automattic/isolated-block-editor？

在项目目录运行 npm install @automattic/isolated-block-editor，或使用 pnpm add / yarn add / bun add。

### @automattic/isolated-block-editor 支持 TypeScript 吗？

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

### @automattic/isolated-block-editor 支持 ESM 还是 CommonJS？

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

### @automattic/isolated-block-editor 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @automattic/isolated-block-editor 可以商用吗？

@automattic/isolated-block-editor 使用 GPL-2\.0-or-later 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @automattic/isolated-block-editor 的下载量有多少？

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

### @automattic/isolated-block-editor 还在维护吗？

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