OpenPencil SDK 架构解析:@open-pencil/vue 的包结构、公共 API 边界与组合模式
OpenPencil SDK 架构解析:@open-pencil/vue 的包结构、公共 API 边界与组合模式
@open-pencil/vue 是 OpenPencil 设计编辑器面向 Vue 3 的官方 SDK 层,它本身不拥有编辑器模型,而是将 @open-pencil/core 的编辑器适配为 Vue 依赖注入、响应式 Composables、无样式(headless)结构组件以及画布与输入绑定。本文以 SDK Architecture 文档 为骨架,结合 packages/vue 的真实源码与 README,系统讲解该包的目录划分、公开 API 设计原则,以及"哪些逻辑属于 SDK、哪些属于应用"的职责边界,帮助你快速判断在自建 OpenPencil 编辑器中应复用哪些能力、如何组织自己的代码。
一、包定位:Vue 之上的薄适配层
架构文档开篇即给出核心定位:@open-pencil/vue 连接 @open-pencil/core 与 Vue,但编辑器模型始终属于 core。该包只负责四类适配工作:
- 基于 Vue 的依赖注入(Dependency Injection);
- 响应式 Composables;
- 无外观预设的结构性组件(headless structural primitives);
- 工作区(Canvas)与输入处理的绑定。
这一分层在源码中有直接印证。packages/vue/src/index.ts 的第一段导出即从 @open-pencil/core/editor 转发 createEditor、EDITOR_TOOLS、TOOL_SHORTCUTS 及 Editor、EditorState、EditorOptions 等类型,说明编辑器内核完全外置于 SDK;而 packages/vue/package.json 也将 @open-pencil/core 声明为 peerDependencies("workspace:*"),消费方需自行安装 core 与 Vue(当前开发版要求 vue ^3.5.41,可选 CanvasKit 对等依赖 canvaskit-wasm >=0.41.1),SDK 本身不内嵌编辑器实现。
从依赖清单(如 @tanstack/vue-table、@vueuse/core、reka-ui、nanostores 等)可以看出,SDK 还负责把表格、拖拽、弹层等基础交互能力封装成可复用的编辑器控件,而不是把这些细节暴露给应用层。
二、按功能域组织的包结构
架构文档明确"代码按功能区域(domain)划分"。逐一对应该目录即可理解每个区域的服务对象。
2.1 组件家族(Component families)
以下 12 个目录存放结构性/无样式原语及其局部辅助函数:
Canvas/ColorPicker/FillPicker/FontPicker/GradientEditor/LayerTree/PageList/PropertyList/PropertySection/SegmentedControl/NumberField/Toolbar/
在源码中,这些家族大多位于 packages/vue/src/primitives(如 LayerTree/、PageList/、PropertyList/、PropertySection/、SegmentedControl/、NumberField/、Toolbar/、FontPicker/、GradientEditor/、Fill/),画布家族则在 packages/vue/src/canvas(CanvasRoot.vue、CanvasSurface.vue、useCanvasInput.ts 等)。它们只协调结构、子组件、插槽与上下文,不携带任何外观样式——这正是"headless"的含义。
2.2 Controls:属性面板与编辑器控件组合式函数
controls/ 目录存放面向属性面板(Properties Panel)与编辑器控件的 Composables,架构文档列出 13 个:
usePosition:读取/写入选中节点的 x、y、宽高、旋转,并提供对齐(align)、翻转(flip)、旋转(rotate)等动作;useLayout:轴向上的尺寸调整(Hug / Fill / Fixed 等模式);useAppearance:外观属性(如圆角、不透明度、独立角半径);useColorModel:场景颜色与 UI 控件的桥接(RGB/HSL/HSB/OkHCL);useTypography:文本与字体排版属性;useExport:文档导出;useFillControls:填充控制;useStrokeControls:描边控制;useEffectsControls:效果(阴影、模糊等)控制;useNodeProps:节点属性的统一读写入口;usePropScrub:拖拽微调(scrub)时的暂存/提交/取消语义;useEditorPropertyList:把受控的PropertyListRoot连接到选区与 Undo 历史。
以 usePosition 的实现 为例,可以清晰看到这些 Composables 的组合方式:usePosition 内部调用 useEditor() 拿到注入的编辑器实例,再组合 useNodeProps() 获取 nodes/node/active/isMulti/prop,用 usePropScrub(editor) 获得 updateProp/commitProp/cancelProp 三段式修改流程,最后把 x、y、width、height、rotation 暴露为 computed 响应式值,并向上层暴露 align、flip、rotate 动作(内部转调 editor.alignNodes、editor.flipNodes、editor.rotateNodes)。这验证了架构文档"如果代码主要是控制逻辑、状态派生或编辑器动作,就应该提供为 Composable"的原则。
2.3 Variables、Selection 与 Context
VariablesEditor/:变量(Variables)域的 Composables 与状态接线,源码位于 packages/vue/src/variables,导出useVariables、useVariablesEditor、useVariablesTable、useVariablesDialogState等。selection/:由当前选区派生出的编辑器状态与可用能力。对应源码为 useSelectionState(hasSelection、selectedCount、selectedNodeType、isInstance、isComponent、isGroup、canCreateComponentSet等)以及useSelectionCapabilities。context/:通过 Vue 依赖注入提供编辑器的三个核心入口:EDITOR_KEY、provideEditor、useEditor。
Context 的真实实现见 packages/vue/src/editor/context/index.ts:EDITOR_KEY 是一个类型为 InjectionKey<Editor> 的 Symbol('open-pencil-editor');provideEditor(editor) 仅做一次 provide;而 useEditor() 在未注入的子树中调用会直接抛错,错误信息提示"请先在 Vue 子树顶部调用 provideEditor(editor)"——这是一个非常典型的"快速失败"设计,让接线错误在开发期即可暴露。
2.4 Internal:跨领域内部工具
internal/ 存放跨领域的共享辅助函数,不属于面向消费者的主结构原语。架构文档特意强调这一点:应用开发者不应把这些文件当作公共 API 来依赖。源码中如 internal/scene-computed/use.ts 提供场景派生状态的订阅能力,虽然通过 index.ts 导出(如 useSceneComputed),但其定位仍是内部实现细节。
三、公共 API 设计哲学
架构文档将公开 API 的取舍浓缩为三条原则,这些原则直接决定了一个功能应该以什么形态暴露给消费方。
3.1 首选 Composables
如果问题的核心是控制逻辑、状态派生或编辑器动作,就暴露为 Composable。 理由很实际:Composable 不依赖组件树结构即可复用,天然适配 Vue 的响应式体系,也便于在属性面板、工具栏、弹出层等不同位置重复调用。前述 usePosition、useSelectionState 都是这一原则的落地案例。
3.2 仅在有意义的结构时提供无样式组件
只有当一个根组件确实在协调结构、子组件、插槽或上下文时,才值得提供组件。 架构文档给出的根组件示例与源码逐一对应:
PageListRoot(packages/vue/src/primitives/PageList/PageListRoot.vue)PropertyListRoot(packages/vue/src/primitives/PropertyList/PropertyListRoot.vue)PropertySectionRoot(packages/vue/src/primitives/PropertySection/PropertySectionRoot.vue)SegmentedControlRoot(packages/vue/src/primitives/SegmentedControl/SegmentedControlRoot.vue)ToolbarRoot(packages/vue/src/primitives/Toolbar/ToolbarRoot.vue)
它们的共同形态是"受控组件":只接收数据与回调,通过**语义化事件(semantic events)**向上报告动作,而不是直接操作编辑器。以 PropertyListRoot.vue 为例,它声明的 emit 全部是领域语义事件:add、remove、update、patch、toggleVisibility、reorder,同时通过 providePropertyList 把 items、isMixed、disabled、keyOf、actions 下发给后代部件(PropertyListItem、PropertyListAdd、PropertyListRemove、PropertyListVisibility)。组件本身完全不感知选区与 Undo 历史。
3.3 避免"Context 大礼包"式插槽
不要向插槽一次性倾倒整个上下文对象(避免 v-slot="ctx" 的巨大载荷),只传递所需 Props,或让消费者直接使用 Composable。 架构文档同时给出了一条重要的职责边界:
受控组件(如
PropertyListRoot)通过语义事件报告动作;编辑器选区与 Undo 历史的接线属于 Adapter 或控制型 Composable,而不是组件本身。
这正是 useEditorPropertyList() 存在的意义——它位于 packages/vue/src/controls/property-list/use.ts,作为"Adapter"把受控的 PropertyListRoot 与当前选区、Undo 批次连接起来。应用层因此在获得完整功能的同时,仍可保持组件与编辑器内核的解耦。
四、应用与 SDK 的职责边界
架构文档用两栏清单清晰划定了责任,这是理解整个包设计的分水岭:
SDK 拥有
- 编辑器集成(editor integration);
- 可复用、与外观无关的逻辑;
- 不预设样式的可复用 UI 结构;
- 工作区渲染集成(canvas rendering integration)。
应用拥有
- 样式(styling);
- 页面级布局外壳(layout shells);
- 路由(routing);
- 产品化文件流程(打开、保存等文件操作);
- Toast 提示、菜单与特定于应用的用户体验。
从 packages/vue/README.md 对公共 API 的分层也能印证:SDK 提供的核心 API 集中在"Context 与画布"(provideEditor/useEditor/useCanvas/useCanvasInput/useTextEdit)、"选区与命令"(useSelectionState/useSelectionCapabilities/useEditorCommands/useMenuModel)、"属性面板"(usePosition/useLayout/useAppearance/useTypography/useExport/useFillControls/useStrokeControls/useEffectsControls 等)以及"变量、导航与本地化"(useVariablesEditor/usePageList/useI18n);而应用只需要在此基础上写样式、拼布局、接路由与文件流程。
五、判断归属的实用准则
架构文档最后给出了一条简洁而可操作的"拇指规则":
如果一段逻辑能在不携带应用样式的前提下,被复用到另一个基于 OpenPencil 的编辑器中,那么它大概率应该属于
@open-pencil/vue。
反向推导同样成立:凡是被当前应用的视觉体系、路由或产品流程所污染的逻辑,都不应下沉到 SDK。这一准则同时回答了"组件该放哪"与"Composable 该放哪"两个问题——判断标准不是代码量,而是可复用性是否依赖外观。
六、快速上手:把各层组合起来
SDK 的快速开始示例(见 packages/vue/README.md)演示了各层如何组合:用 createDefaultEditorState + createEditor 创建编辑器(core 层),用 new SceneGraph() 管理场景图(scene-graph 层),再通过 provideEditor(editor) 注入(vue 层),最后用无样式原语 CanvasRoot + CanvasSurface 搭建工作区。其中 getViewportSize 应返回真实画布容器尺寸,场景图本身保持框架中立,而编辑器状态可传入 reactive() 以便 Vue 控件响应式读取。
七、延伸阅读
- SDK 快速上手:安装、迁移与首个编辑器示例;
- SDK API 参考:各 Composable 与组件的完整类型与参数说明;
- packages/vue/README.md:包安装方式(
bun add @open-pencil/vue @open-pencil/core @open-pencil/scene-graph canvaskit-wasm)、公共 API 分层与各原语能力速览; - packages/vue/src/index.ts:SDK 全部公开导出的权威清单,是判断"某个能力是否属于公共 API"的第一手依据。