企业官网建设流程全解析

三步跑通 BlockSuite 预设编辑器：从页面到画布的完整接入路径

【免费下载链接】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 是面向 Web 的内容编辑技术栈，presets 包把块架构沉淀为一组预设组件：PageEditor 与 EdgelessEditor 各是一个可挂载的 Web Component，分别对应文档式页面与无限画布两种形态，解决的是"从零装配块规格太繁琐"的问题。这里直接给出从挂载、模式切换到规格定制的完整路径。

📌 预设组件解决什么问题

BlockSuite 的编辑能力建立在"块"之上：段落、列表、代码、画布元素都是独立块，每个块由 schema、model、service、渲染组件四部分构成。只用 blocks 包时，需要自己声明用哪些块、如何注册 schema、按什么顺序挂载服务，工作量不小且容易漏配。

预设组件把这层装配固化成两个现成元素：PageEditor 默认注入 PageEditorBlockSpecs，EdgelessEditor 默认注入 EdgelessEditorBlockSpecs，装配逻辑写在组件内部，给组件一个 doc，页面就渲染出来。做成 Web Component 而不是纯函数，是因为编辑器生命周期、主题样式和视口滚动都需要一个持久的 DOM 容器来承载。

🧱 读懂共用骨架：一个 editor-host，两套 BlockSpecs

打开 预设编辑器源码，两个组件的实现高度对称：都用 Lit 定义自定义元素，都暴露 doc 属性，render 时都只挂载一个 editor-host，差异仅在传入的 specs 与外层视口策略——PageEditor 的视口允许纵向滚动，EdgelessEditor 的视口则裁剪内容（overflow: clip），把缩放与平移交给画布自身处理。

这种"一个宿主加一套规格"的结构意味着，PageEditor 与 EdgelessEditor 可以挂在同一应用里，甚至共享同一个 Doc 实例：数据只有一份，只是呈现方式不同，这正是页面与白板双形态编辑器的基础。

⚡ 三步把预设编辑器挂进前端项目

以仓库自带的 react-basic 示例为例，完整流程分三步：

const schema = new Schema().register(AffineSchemas); const collection = new DocCollection({ schema }); collection.meta.initialize(); const doc = collection.createDoc({ id: 'page1' }); doc.load(() => doc.addBlock('affine:page', {})); const editor = new AffineEditorContainer(); editor.doc = doc; document.body.appendChild(editor);

第一步注册 schema，把 AffineSchemas 挂到 Schema 实例上；第二步用 DocCollection 建出文档，并在 load 回调里写入 page 根块；第三步实例化编辑器元素并赋值 doc。因为它是自定义元素，与框架无关，在 Vue、Svelte 或原生 JS 里写法一致。另外还要引入主题样式 '@blocksuite/presets/themes/affine.css'，否则字体和配色是裸的。

🔁 从页面到画布：模式切换如何实现

需要同时支持页面与白板时，用 AffineEditorContainer 替代单独的 PageEditor。它内部用 signal 保存 mode 与 pageSpecs、edgelessSpecs 两组规格，render 时以 rootModel.id + mode 作为 keyed 指令的键来渲染 editor-host：mode 一变，整个宿主重新渲染并换装规格，但因为共享同一个 doc 的根块，块数据原地保留，只有呈现形态发生切换，不会出现"切换后内容清空"的问题。

如何定制两套规格

切换机制之外，两套规格都可以整体替换：

import { PageEditorBlockSpecs } from '@blocksuite/blocks'; editor.pageSpecs = [ ...PageEditorBlockSpecs, myCustomBlockSpec, ];

pageSpecs 与 edgelessSpecs 各自独立，可以只给页面侧加块而不影响画布侧，定制粒度是整个规格集合。

🎛️ 接入之后要注意的三个边界

预设组件也划清了自己的边界：包入口在服务端环境会直接抛错，SSR 暂不支持；重复 import 时控制台会告警，因为二次引入会破坏块 model 的构造器检查；PageEditor 的 hasViewport 属性控制是否自带滚动容器，嵌入已有滚动布局时可以关掉。从这三个入口出发，可以先在 playground 里跑通完整示例，再按需替换规格，把预设编辑器变成自家产品的编辑底座。

【免费下载链接】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