@wordpress/sync

最后更新：2026-10-17 10:55:29

使用 CRDT 文档在对等节点之间同步实体数据，以实现实时协作。

该软件包为 WordPress 编辑器中的实时协作提供了同步层。它构建于 Yjs 之上，这是一种 CRDT 实现，可让多个用户同时编辑共享数据而不产生冲突。

有关架构详情，请参见 CODE.md。

安装

安装该模块

npm install @wordpress/sync --save

API

Awareness

Awareness 协议不应被视为公共 API。它是一个第三方库，未来会出现破坏性变更。

通常，核心实体类型的 awareness 由 core-data 软件包实现，第三方 Yjs 提供者不应提供自己的 awareness 实现。不过，自定义实体可能需要自定义的 awareness 实现。

ConnectionErrorCode

当同步提供者的连接失败时报告的错误代码。

CRDT_DOC_META_PERSISTENCE_KEY

内存中元数据条目的键，用于将 CRDT 文档标记为已从持久化存储加载。它不会被同步或持久化。

CRDT_RECORD_MAP_KEY

用于保存实体记录数据的映射的根级键。

createSyncManager

创建同步管理器，该管理器协调实体记录同步的生命周期：它创建 Yjs 文档、连接提供者、创建 awareness 实例，并与 core-data store 协调。导出供 @wordpress/core-data 使用；插件无需使用。

Delta

用于描述富文本变更的 Quill Delta 实现。

LOCAL_EDITOR_ORIGIN

用于源自本地编辑器的 CRDT 文档变更的 origin 字符串。

LOCAL_UNDO_IGNORED_ORIGIN

用于应同步但不会记录到撤销历史中的 CRDT 文档变更的 origin 字符串（例如发布过程中的状态变更）。

retrySyncConnection

立即重试 HTTP 轮询连接，而不是等待下一次自动重试。导出供 @wordpress/core-data 使用；插件无需使用。

Y

Yjs 不应被视为公共 API。它是一个第三方库，未来会出现破坏性变更。

@wordpress/sync 是一个捆绑软件包：每个使用者都会捆绑自己的副本，WordPress 不会暴露任何 wp.sync 全局变量或 wp-sync 脚本句柄。两个 Yjs 实例同时操作同一个文档会导致静默数据损坏：

https://github.com/yjs/yjs/issues/438

因此，通过 sync.providers 过滤器注册的同步提供者不得捆绑自己的 Yjs 副本。每个提供者创建函数都会在其选项中以 Y 属性的形式接收编辑器使用的 Yjs 模块，同时还会接收 ydoc 和 awareness，并且必须通过该实例操作文档。

如果提供者捆绑了直接导入 yjs 的第三方代码（例如 y-websocket），则可以通过垫片（shim）模块共享编辑器的 Yjs 实例。该垫片会重新导出捆绑代码使用的 Yjs 符号，并在运行时从 Y 选项填充这些符号：

// yjs-shim.js
export let Doc;
export let applyUpdate;
export let encodeStateAsUpdate;
export let encodeStateVector;

export function setYjsModule( Y ) {
    ( { Doc, applyUpdate, encodeStateAsUpdate, encodeStateVector } = Y );
}

然后，构建过程会将 yjs 模块标识符设置为该垫片的别名，从而使捆绑依赖项将其 Yjs 导入解析到该垫片，而不是打包第二份副本。例如，使用 webpack 时：

resolve: {
  alias: {
    yjs: path.resolve( __dirname, 'src/yjs-shim.js' ),
  },
},

最后，提供者创建函数会在使用任何捆绑代码之前初始化该垫片：

import { WebsocketProvider } from 'y-websocket';
import { setYjsModule } from './yjs-shim';

const createProvider = async ( { awareness, ydoc, Y } ) => {
    setYjsModule( Y );

    const provider = new WebsocketProvider( url, room, ydoc, { awareness } );
    // ...
};

完整可用示例请参见 packages/e2e-tests/plugins/rtc-websocket-provider。

YJS_VERSION

由该软件包捆绑并导出的 Yjs 主版本号。第三方代码可以使用它来确保其面向兼容的 Yjs 版本。

为该软件包做贡献

这是 Gutenberg 项目中的一个独立软件包。该项目以单一代码仓库的形式组织，由多个自包含的软件包组成，每个软件包都有特定用途。此单一代码仓库中的软件包会发布到 npm，并被 WordPress 以及其他软件项目使用。

要详细了解如何为该软件包或整个 Gutenberg 项目做贡献，请阅读项目的主要贡献者指南。