YJS 工具
@blocknote/core/yjs 导出提供了在 BlockNote 块和 YJS 协作文档之间转换的工具。当你需要在标准协作环境之外操作 YJS 文档时（例如导入已有内容或编程操作 YJS 文档），这些工具非常有用。
重要： 本包适用于需要程序化在 BlockNote 块和 YJS 文档之间转换的高级用例。大多数用例应直接使用协作功能。
导入
import {
blocksToYDoc,
blocksToYXmlFragment,
yDocToBlocks,
yXmlFragmentToBlocks,
} from "@blocknote/core/yjs";概述
YJS 工具支持双向转换：
- BlockNote 块 ↔ Y.Doc（YJS 文档）
- BlockNote 块 ↔ Y.XmlFragment（YJS XML 片段）
这些转换对以下情况很重要：
- 将已有的 BlockNote 内容导入到 YJS 文档以实现协作
- 将 YJS 文档中的内容导出回 BlockNote 块
- 在无编辑器实例的环境下，编程操作 YJS 文档
将块转换为 YJS 文档
blocksToYDoc
将 BlockNote 块转换为一个 Y.Doc。适合首次将已有内容导入 Y.Doc 的场景。
重要： 协作开始后，不应使用此方法从数据库重新生成 Y.Doc，否则所有历史记录将丢失。
function blocksToYDoc<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
blocks: PartialBlock<BSchema, ISchema, SSchema>[],
xmlFragment?: string,
): Y.Doc;参数：
editor- BlockNote 编辑器实例blocks- 需要转换的块数组xmlFragment- 可选的 XML 片段名称（默认"prosemirror"）
返回： 包含转换后块的新 Y.Doc
示例：
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const blocks = [
{
type: "paragraph",
content: "Hello, world!",
},
{
type: "heading",
props: { level: 1 },
content: "My Document",
},
];
// 将块转换为 Y.Doc
const ydoc = blocksToYDoc(editor, blocks);
// 之后可以使用这个 Y.Doc 和 YJS 提供者进行协作
const provider = new WebrtcProvider("my-room", ydoc);blocksToYXmlFragment
将 BlockNote 块转换为 Y.XmlFragment。当你希望操作 Y.Doc 中的特定 XML 片段时非常有用。
function blocksToYXmlFragment<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
blocks: Block<BSchema, ISchema, SSchema>[],
xmlFragment?: Y.XmlFragment,
): Y.XmlFragment;参数：
editor- BlockNote 编辑器实例blocks- 需要转换的块数组xmlFragment- 可选的现有 Y.XmlFragment，用于填充（若无则创建新的）
返回： 包含转换后块的 Y.XmlFragment
示例：
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYXmlFragment } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");
const blocks = [
{
type: "paragraph",
content: "Content for fragment",
},
];
// 将块转换为 XML 片段
blocksToYXmlFragment(editor, blocks, fragment);将 YJS 文档转换为块
yDocToBlocks
将 Y.Doc 转换回 BlockNote 块。适用于读取 YJS 文档中的内容。
function yDocToBlocks<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
ydoc: Y.Doc,
xmlFragment?: string,
): Block<BSchema, ISchema, SSchema>[];参数：
editor- BlockNote 编辑器实例ydoc- 要转换的 Y.DocxmlFragment- 可选的 XML 片段名称（默认"prosemirror"）
返回： BlockNote 块数组
示例：
import { BlockNoteEditor } from "@blocknote/core";
import { yDocToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const ydoc = new Y.Doc();
// ... Y.Doc 通过协作或其他方式填充 ...
// 将 Y.Doc 转换回块
const blocks = yDocToBlocks(editor, ydoc);
console.log(blocks); // BlockNote 块数组yXmlFragmentToBlocks
将 Y.XmlFragment 转换回 BlockNote 块。
function yXmlFragmentToBlocks<
BSchema extends BlockSchema,
ISchema extends InlineContentSchema,
SSchema extends StyleSchema,
>(
editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
xmlFragment: Y.XmlFragment,
): Block<BSchema, ISchema, SSchema>[];参数：
editor- BlockNote 编辑器实例xmlFragment- 要转换的 Y.XmlFragment
返回： BlockNote 块数组
示例：
import { BlockNoteEditor } from "@blocknote/core";
import { yXmlFragmentToBlocks } from "@blocknote/core/yjs";
import * as Y from "yjs";
const editor = BlockNoteEditor.create();
const doc = new Y.Doc();
const fragment = doc.getXmlFragment("my-fragment");
// ... 片段通过协作或其他方式填充 ...
// 将片段转换回块
const blocks = yXmlFragmentToBlocks(editor, fragment);循环转换
所有转换函数支持循环转换，即你可以实现块 → YJS → 块，并得到相同内容：
import { BlockNoteEditor } from "@blocknote/core";
import { blocksToYDoc, yDocToBlocks } from "@blocknote/core/yjs";
const editor = BlockNoteEditor.create();
const originalBlocks = [
{
type: "paragraph",
content: "Test content",
},
];
// 转换到 Y.Doc 并转换回
const ydoc = blocksToYDoc(editor, originalBlocks);
const convertedBlocks = yDocToBlocks(editor, ydoc);
// originalBlocks 和 convertedBlocks 结构相同
console.log(originalBlocks); // 与 convertedBlocks 结构相同