操作区块
BlockNote 采用了基于区块的架构，所有内容都组织成离散的区块。理解如何操作这些区块是高效使用 BlockNote 的基础。
基于区块的架构
在 BlockNote 中，一切都是区块。段落是一个区块，标题是一个区块，列表项是一个区块，甚至像表格这样的复杂结构也是由区块组成。这种统一的方法使文档操作保持一致且可预测。
核心区块操作
BlockNote 提供了一套全面的区块操作，所有操作均在区块级别进行：
读取区块
- 获取整个文档 - 获取所有顶层区块
- 获取特定区块 - 通过 ID 或引用访问单个区块
- 导航关系 - 查找上一个、下一个或父级区块
- 遍历所有区块 - 遍历整个文档结构
// 获取整个文档
const document: Block[] = editor.document;
// 获取特定区块
const block = editor.getBlock(blockId);
// 获取上一个区块
const previousBlock = editor.getPreviousBlock(blockId);
// 获取下一个区块
const nextBlock = editor.getNextBlock(blockId);创建区块
- 插入新区块 - 在已有区块前后添加区块
- 创建复杂结构 - 构建嵌套区块，如列表和表格
- 程序化生成区块 - 根据数据或用户输入创建区块
// 插入一个简单的段落区块
editor.insertBlocks(
[{ type: "paragraph", content: "Hello, world!" }],
referenceBlock,
);
// 创建复杂区块结构
editor.insertBlocks(
[
{ type: "heading", content: "My Heading" },
{ type: "paragraph", content: "Some content" },
{ type: "bulletListItem", content: "List item 1" },
{ type: "bulletListItem", content: "List item 2" },
],
referenceBlock,
);修改区块
- 更新已有区块 - 更改区块类型、内容或属性
- 替换区块 - 用新区块替换一个或多个区块
- 移动区块 - 通过上下移动调整区块顺序
- 嵌套和取消嵌套 - 通过缩进或取消缩进改变层级关系
// 更改区块类型
editor.updateBlock(blockId, { type: "heading" });
// 更新区块内容和属性
editor.updateBlock(blockId, {
content: "Updated content",
props: { level: 2 },
});删除区块
- 删除特定区块 - 移除单个或多个区块
- 清除选区 - 基于用户选择移除区块
// 删除特定区块
editor.removeBlocks([blockId1, blockId2]);
// 用新区块替换旧区块
editor.replaceBlocks(
[oldBlockId],
[{ type: "paragraph", content: "New content" }],
);操作光标和选区
- 读取光标位置 - 获取光标所在位置的信息
- 设置光标位置 - 移动光标到指定区块
- 读取选区 - 访问用户当前选择的区块
- 设置选区 - 程序化选中区块范围
// 获取光标位置信息
const cursorPosition = editor.getTextCursorPosition();
// 将光标设置到指定区块
editor.setTextCursorPosition(blockId, "start");
// 获取当前选区
const selection = editor.getSelection();
// 程序化设置选区
editor.setSelection(startBlockId, endBlockId);最佳实践
- 使用区块引用操作 - 利用已有区块作为新建区块的位置参考
- 优雅处理错误 - 操作可能因区块不存在或无效而失败
- 考虑用户体验 - 思考区块操作如何影响用户流程
- 组合相关操作 - 利用事务将多次区块变更组合成一次撤销/重做操作
后续步骤
本概述涵盖了 BlockNote 中区块操作的基本概念。详细的 API 参考和具体示例，请参阅：