BlockSuite Playground Apps 应用目录全解析在线演示、E2E 测试入口与示例工程【免费下载链接】blocksuite Content editing tech stack for the web - BlockSuite is a toolkit for building editors and collaborative applications.项目地址: https://gitcode.com/GitHub_Trending/bl/blocksuiteBlockSuite Playground Apps 是 BlockSuite 仓库中为在线演示站点Playground准备的应用入口目录它既是以完整能力调用 BlockSuite 全量功能的综合示例也是仓库执行 E2E端到端测试用例的启动页面。阅读本文后你将掌握 Playground 的两大应用default与starter的启动流程、URL 参数体系、内置示例数据集以及如何在本机运行 Playground 并把它当作 BlockSuite 二次开发与调试的试验台。一、目录定位Playground 是什么Playground Apps 位于仓库的 packages/playground/apps 目录。按照该目录下 README.md 的官方定义该目录包含用于在线站点BlockSuite playground的应用入口它们作为利用 BlockSuite 全部能力的综合示例comprehensive examples而存在同时它们也充当执行 E2E 测试用例的入口点the entry point for executing E2E test cases。从目录结构看apps 下包含两个应用入口default/与starter/以及被二者共享的公共模块_common/公共组件、同步实现、模板、Mock 服务和 Vite 辅助脚本。Playground 的包定义为blocksuite/playground见 packages/playground/package.json其脚本包括脚本命令用途devvite --host启动本地开发服务器5173 端口dev:hmrWC_HMR1 vite开启组件级 HMR 的开发模式buildtsc nx vite:build类型检查并构建build:sizenx vite:build -c vite.config.size.ts构建并输出产物体积报告previewnx vite:preview预览构建产物4173 端口仓库根目录 package.json 也提供了对外的便捷命令pnpm dev对应pnpm --filter blocksuite/playground devpnpm preview对应pnpm --filter blocksuite/playground previewpnpm build:playground负责构建 Playground。二、两大应用入口default 与 starter2.1 default 应用最小化完整编辑器default/main.ts 是default应用的入口逻辑非常精炼async function main() { if (window.collection) return; setupEdgelessTemplate(); const collection await createDefaultDocCollection(); await initDefaultDocCollection(collection); await mountDefaultDocEditor(collection); } main().catch(console.error);它的职责分为三步setupEdgelessTemplate()—— 来自 _common/setup.ts向EdgelessTemplatePanel注入 Playground 自带的白板模板分类例如 Paws and pals模板数据在 _common/templates/stickers.ts并实现基于 LCS最长公共子序列的模板搜索、列表与分类接口。创建并初始化 DocCollection—— 见 default/utils/collection.ts核心要点注册AffineSchemas全部 Affine 块模型到Schema使用IdGeneratorType.NanoID生成文档 ID本地持久化主源为IndexedDBDocSourceblob 主源为IndexedDBBlobSource(quickEdgeless)若 URL 带room参数则先尝试连接 WebSocket 服务WebSocketDocSourceWebSocketAwarenessSource连接失败时降级为BroadcastChannelDocSource/BroadcastChannelAwarenessSource同标签页广播便于多标签页协作演示支持以enable_*开头的 URL 参数覆写defaultFlags如enable_synced_doc_block、enable_pie_menu、enable_lasso_tool、enable_color_picker。挂载编辑器—— 见 default/utils/editor.ts创建AffineEditorContainer设置pageSpecs/edgelessSpecs注入mockDocModeService、mockNotificationService、mockQuickSearchService等 Mock 服务并挂载左侧面板、文档面板与快速白板菜单。default应用还带有一个specs-examples目录default/specs-examples/index.ts通过?exampleSpecURL 参数演示自定义 Spec?exampleSpecattachment自定义 Attachment 服务将上传文件上限改为 100MB见 custom-attachment.ts?exampleSpeclatex演示 inline 层 LaTeX 扩展为 delta 增加latex属性并渲染为自定义节点见 latex.ts 与 latex-node.ts。2.2 starter 应用功能最全的演示沙盒starter/main.ts 是 E2E 测试真正访问的入口逻辑比 default 复杂async function main() { if (window.collection) return; setupEdgelessTemplate(); const params new URLSearchParams(location.search); const room params.get(room) ?? Math.random().toString(16).slice(2, 8); const isE2E room.startsWith(playwright); const collection createStarterDocCollection(); if (isE2E) { Object.defineProperty(window, $blocksuite, { value: Object.freeze({ store, blocks, global: { utils: globalUtils }, editor, }), }); return; // 测试模式下不再挂载 UI } await initStarterDocCollection(collection); await mountDefaultDocEditor(collection); }关键行为通过room参数决定协作房间当room以playwright开头时应用进入E2E 测试模式不挂载编辑器 UI而是在window.$blocksuite上冻结导出store、blocks、global/utils、editorpresets四组 API供测试脚本直接访问非测试模式下先initStarterDocCollection初始化数据再mountDefaultDocEditor挂载编辑器。starter 的编辑器挂载starter/utils/editor.ts展示了比 default 更完整的 BlockSuite 集成姿势使用PageEditorBlockSpecs/EdgelessEditorBlockSpecs标准 Spec 集合通过patchPageRootSpec在affine:pageSpec 的mounted钩子里注入通知服务、快速搜索服务并通过widgetConnected监听格式化工具栏AffineFormatBarWidget连接事件调用toolbarDefaultConfig(formatBar)配置额外挂载大纲面板/查看器CustomOutlinePanel/CustomOutlineViewer、帧面板CustomFramePanel、侧边面板SidePanel、左面板LeftSidePanel、文档面板DocsPanel、评论面板CommentPanel、自定义聊天面板CustomChatPanel与调试菜单DebugMenu设置editor.slots.docLinkClicked与editor.slots.docUpdated实现文档间跳转与模式同步。2.3 公共模块_common两个应用共享的_common目录包含模块说明components自定义面板组件custom-chat-panel、custom-frame-panel、custom-outline-panel、custom-outline-viewer、debug-menu、docs-panel、left-side-panel、quick-edgeless-menu、side-panel、start-panelsync同步实现blob/mock-server.ts提供 Mock 的 Blob 服务端websocket/下实现WebSocketDocSourcedoc 更新推送/拉取与WebSocketAwarenessSource在线状态感知通信基于 JSON 消息协议templates/stickers.ts白板贴纸模板数据mock-services.ts一组 Mock 服务mockDocModeService页面/白板模式切换持久化到 localStorage 的playground:docMode、mockNotificationServicetoast/confirm/prompt/notify、mockQuickSearchService按标题或 URL 搜索文档setup.ts注入 Edgeless 模板面板三、E2E 测试如何驱动 PlaygroundPlayground Apps 是 E2E 测试的入口。仓库的 Playwright 测试位于根目录 tests配置文件为 tests/playwright.config.tswebServer.command在 CI 下为pnpm -w preview端口 4173本地为pnpm -w dev端口 5173即测试前会自动拉起 Playground测试用例如 tests/basic.spec.ts、tests/clipboard/clipboard.spec.ts 等通过 tests/utils/actions/misc.ts 中的enterPlaygroundRoom()进入http://localhost:5173/starter/并附带room、init等查询参数。测试辅助层 tests/utils/playwright.ts 还为每个测试上下文注入了 Istanbul 覆盖率收集脚本CI 或COVERAGE环境变量下启用配合 tests/utils/actions/misc.ts 中enterPlaygroundRoom的随机room分配保证每个测试用例在独立的协作房间中运行互不干扰。四、URL 参数速查表结合源码Playground尤其 starter支持以下查询参数参数取值示例作用源码依据roomabc123、playwright-xxx协作房间标识room以playwright开头时进入 E2E 测试模式同 room 的多标签页通过 BroadcastChannel 同步starter/main.ts、starter/utils/collection.tsinitpreset、empty、heavy、database、linked、synced、embed、multiple-editor、heavy-whiteboard、pending-structs、version-mismatch选择内置的初始数据生成函数详见下节默认presetstarter/utils/collection.tsmodepage/edgeless强制指定编辑器的初始模式starter/utils/editor.tscount数字heavy/heavy-whiteboard示例中生成块/元素的数量data/heavy.ts、data/heavy-whiteboard.tsblobSourcemock,idb为 blob 源追加 shadowsmock走 MockServerBlobSourceidb走 IndexedDBBlobSourcestarter/utils/collection.tsenable_*enable_color_pickertrue覆写defaultFlags特性开关default/utils/collection.ts、starter/utils/collection.tsexampleSpecattachment、latexdefault 应用切换自定义 Spec 示例default/specs-examples/index.tsinit缺省但传room且无init—不调用内置 init等待远端/广播数据注入协作模式starter/utils/collection.ts五、内置示例数据集InitFn 机制starter 的初始化数据全部实现为InitFn接口定义于 data/utils.tsexport interface InitFn { (collection: DocCollection, docId: string): Promisevoid | void; id: string; displayName: string; description: string; }每个 InitFn 附带idURL 参数名、displayName与description由 data/index.ts 统一导出。initStarterDocCollection会在运行时动态import(../data/index.js)按init参数查表并执行对应函数starter/utils/collection.ts。各示例文件与说明init 值文件演示内容presetdata/preset.ts默认友好入门页通过MarkdownTransformer.importMarkdown导入一段介绍文本emptydata/empty.ts空编辑器仅 page surface note paragraphheavydata/heavy.ts压力测试默认生成 1000 个段落块可用count调整heavy-whiteboarddata/heavy-whiteboard.ts白板压力测试默认 100 个随机图形元素rect/triangle/ellipse/diamonddatabasedata/database.ts数据库块示例列预设、视图预设、数据库初始化linkeddata/linked.ts链接文档包含doc:linked-page与doc:linked-edgeless等子文档synceddata/synced.ts同步块演示Page 视图与 Edgeless 视图的 synced blockembeddata/embed.ts各种 embed 块示例multiple-editor/multiple-editor-verticaldata/multiple-editor.ts同一页面挂载多个AffineEditorContainer水平/垂直布局pending-structsdata/pending-structs.ts构造含 pending structs未完整同步的 Yjs 结构的文档测试加载健壮性version-mismatchdata/version-mismatch.ts手动把块版本号sys:version加一后合并更新演示版本不匹配时的错误边界这些示例直接使用 BlockSuite 的公共 APIdoc.addBlock、DocCollection.Y、MarkdownTransformer、columnPresets/viewPresets等因此也是学习 BlockSuite 编程模型的最小可运行范例。六、本地运行与调试Playground 依赖 pnpm workspace仓库根目录 pnpm-workspace.yamlNode 版本要求为18.19.0 21.0.0见根目录 package.json。常用操作# 安装依赖仓库根目录 pnpm install # 启动 Playground 开发服务器默认 http://localhost:5173 pnpm dev # 或仅启动 blocksuite/playground 包 pnpm --filter blocksuite/playground dev # 构建全部包并构建 Playground pnpm build # 运行 E2E 测试自动拉起 dev/preview 服务 pnpm test启动后可在浏览器地址栏直接拼参数验证功能例如http://localhost:5173/starter/?initheavy—— 生成 1000 段落的压力示例http://localhost:5173/starter/?initdatabase—— 数据库块示例http://localhost:5173/starter/?initsynced—— 同步块示例http://localhost:5173/starter/?modeedgeless—— 直接以白板模式打开http://localhost:5173/starter/?roommyroom—— 开两个标签页进入同一房间体验 BroadcastChannel 协同http://localhost:5173/?exampleSpeclatex—— default 应用的 LaTeX inline 扩展示例default 应用首页位于http://localhost:5173/。七、调试辅助window 全局对象与 DevTools 格式化器Playground 在两个应用的入口都向window暴露了一组调试全局对象类型声明见 apps/env.d.ts全局变量类型用途window.collectionDocCollection当前文档集合window.docDoc当前文档window.editorAffineEditorContainer编辑器容器实例window.blockSchemas注册的块 Schema调试块模型window.jobJob数据导入导出工具window.YYjs 命名空间底层 CRDT 操作window.hostEditorHost当前 editor-host 元素globalThisgetterwindow.stdBlockStd编辑器标准实例globalThisgetterwindow.testUtilsTestUtils测试辅助工具window.$blocksuite冻结的包导出E2E 模式下暴露的store/blocks/global/editorAPI此外apps/dev-format.ts 注册了一个浏览器 DevTools 自定义格式化器在控制台打印 BlockModel 对象时会以Block { flavour, id }的紧凑形式显示并可展开查看全部属性极大方便在控制台中对文档树进行调试。八、总结Playground Apps 目录是 BlockSuite 的一站式试验场default应用提供最小化完整编辑器并支持自定义 Spec 示例starter应用汇聚了从空文档、数据库、同步块、多编辑器到压力测试、版本兼容等十余种场景数据并通过room/init等 URL 参数构建了灵活的演示与测试开关。更重要的是它承担着整个仓库 E2E 测试入口的职责——理解了playwright房间模式、window.$blocksuite暴露与InitFn机制你便同时掌握了「如何为 BlockSuite 编写测试」与「如何快速验证 BlockSuite 各项能力」的两把钥匙。无论是学习 BlockSuite API、调试编辑器行为还是贡献新测试用例从 packages/playground/apps 开始都是最直接的路径。【免费下载链接】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），仅供参考