BlockSuite 预设完全上手指南：5 行代码集成 PageEditor 和 EdgelessEditor

BlockSuite 预设完全上手指南5 行代码集成 PageEditor 和 EdgelessEditor【免费下载链接】blocksuite Content editing tech stack for the web - BlockSuite is a toolkit for building editors and collaborative applications.项目地址: https://gitcode.com/GitHub_Trending/bl/blocksuite假设你要做一个既能写文档、又能开白板的协作产品从零造轮子至少要做块模型、选区、渲染管线和同步协议。BlockSuite 预设把这部分打包好了装一个blocksuite/presets建一个 Doc5 行代码挂上编辑器Notion 式的 PageEditor 和无限画布的 EdgelessEditor 都能直接跑而且两者共用同一份数据切换视图不丢内容。 一个心智模型两个编辑器只是同一棵块树的两种渲染先抓住一个类比文档是一棵块树编辑器只是渲染这棵树的一种方式。BlockSuite 里的 Doc 是一棵树根节点是affine:page下面挂着画布affine:surface和笔记块affine:note笔记块里再挂段落、列表、表格。PageEditor 把这棵树从上到下渲染成纵向滚动的页面EdgelessEditor 把同一棵树渲染成自由拖动的卡片铺在无限画布上。数据一模一样区别只在用哪套根块和视图来画。图中间就是两边共用的块树。理解了这张图预设部分只剩两个名词BlockSpec一个块的完整包包含数据结构Schema、视图组件View、业务逻辑Service三层再加斜杠菜单、工具条这类可选挂件。Specs 列表一个编辑器到底启用哪些块就是一个数组。PageEditor 用PageEditorBlockSpecsEdgelessEditor 用EdgelessEditorBlockSpecs两份列表的差异就是两种编辑器的全部秘密。先盘家底7 类预设组件各管什么事预设包presets 源码导出的东西不多但每样都有明确分工组件你能拿到什么PageEditor纵向文档编辑直接打字/唤起块菜单标题、多级列表、代码、表格都在EdgelessEditor无限画布缩放、平移、自由拖动笔记块带画框frame和画布自由文本AffineEditorContainer页面/白板一键切换的容器自带文档标题和标签区省去自己拼 TopBar 的活Outline跟随块树实时生成的侧边大纲点击标题跳到对应块doc-title / comment / frame-panel标题、行内评论、画布画框管理都是可直接插入的独立组件AI 聊天块预置的聊天消息列表组件接上自己的模型输出就是 AI 对话界面createEmptyDoc()一次调用拿到带 page 画布 笔记 段落的空文档本地演示不用手写初始化两种编辑器内置的块阵容相同段落、列表、代码、数据库表格、数据视图、分割线、图片、附件、书签外加 Figma、GitHub、YouTube、Loom、HTML、关联文档、同步文档 7 种嵌入块。区别只在根块和画布块用的是哪份 Spec。 5 行代码跑起来一个能用的编辑器一条主线走到底装依赖 → 建文档 → 挂载。第一步装三个包presets 是成品编辑器blocks 提供块定义store 是数据层pnpm add blocksuite/presets blocksuite/blocks blocksuite/store第二步在新页面的入口文件里写这 5 行import blocksuite/presets/themes/affine.css; import { createEmptyDoc, AffineEditorContainer } from blocksuite/presets; const { doc, init } createEmptyDoc(); init(); const editor new AffineEditorContainer(); editor.doc doc; document.body.append(editor);刷新页面就能打字/出斜杠菜单标题、列表、表格随手插。想把视图换成白板把导入和实例化换成EdgelessEditor即可两个视图都要且数据互通就保持用AffineEditorContainer调editor.switchEditor(edgeless)切换。不满足于最小片段的话仓库里 examples 目录 有 React、Vue、Angular、Preact、Svelte、Solid 共 11 个可直接运行的示例覆盖 IndexedDB、SQLite 本地持久化和 WebSocket 实时同步照着改比从零搭快得多。为什么拆成Specs 编辑器两层这个拆分背后是三个明确的设计取舍取舍一功能集用数组声明而不是写死在组件里。因为启用哪些块只是一个列表同一份 Doc 就能派生出页面版、白板版和只读预览版preview规格列表三套渲染。切换视图等于换数组数据零迁移——这就是上一节那张图能成立的原因。取舍二编辑器本体只是薄壳。三种编辑器组件都是 Web Component浏览器原生自定义元素不绑定任何前端框架所以丢进 React、Vue 或纯 HTML 的接法完全相同。想深度定制某个块的长相时做法不是改编辑器而是写一份自己的 BlockSpec 塞进数组里规格清单在 blocks 的 specs 目录 里能看到每种块的结构。取舍三数据层天生为协作准备。Doc 底层基于 YjsCRDT一种允许双方同时写、自动合并冲突的数据结构所以多人实时编辑不是后期加的功能而是换一个数据提供器provider的事。examples 里 IndexedDB、SQLite、WebSocket 三种接法都有现成代码。选页面、选白板还是一键切换附 4 个坑选型看产品形态你的产品选择原因纯长文写作、知识库PageEditor纵向滚动心智最顺焦点管理现成白板、脑暴、无限画布EdgelessEditor缩放平移、自由定位、画框都是内置行为AFFiNE 式文档 白板二合一AffineEditorContainer一份 Doc 切两个视图标题标签区附带实战里容易踩的 4 个坑SSR 会直接抛错。blocksuite/presets在 Node 环境 import 会主动报错同构框架Next.js 等记得把编辑器做成客户端懒加载。只能 import 一次。同一页面里重复引入 presets 会破坏单例检查控制台会给出明确告警出现时优先查打包配置。别漏主题 CSS。第一行的themes/affine.css不是装饰不导入就是无样式裸组件。Doc 没有 root 时编辑器渲染空白。render逻辑里doc.root为空就不输出任何内容所以必须先addBlock或doc.load()完成再挂载顺序反了看到的就是白屏。另外注意页面模式下没有画框和自由文本笔记块在白板模式下会渲染成可拖动卡片——这不是 bug正是两份 Specs 列表的差异所在。下一步git clone https://gitcode.com/GitHub_Trending/bl/blocksuite进 examples 目录跑一个你熟悉的框架再对照 quick-start 指南 把createEmptyDoc()换成你自己的数据源一个属于你自己的编辑器就成形了。【免费下载链接】blocksuite Content editing tech stack for the web - BlockSuite is a toolkit for building editors and collaborative applications.项目地址: https://gitcode.com/GitHub_Trending/bl/blocksuite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考