OpenPencil 的 Vue SDK 架构解析:@open-pencil/vue 的分层设计、公共 API 边界与职责划分
OpenPencil 的 Vue SDK 架构解析:@open-pencil/vue 的分层设计、公共 API 边界与职责划分
导读
@open-pencil/vue 是 OpenPencil 项目中把无框架依赖的编辑器引擎 @open-pencil/core 接入 Vue 生态的官方 SDK 包。本文以 Architektura SDK(该文档收录于 packages/docs/pl/programmable/sdk/,另有 de/es/fr/it/ru 等多语言版本)为核心骨架,结合 packages/vue/src 的真实源码,完整解析该包的功能域划分、公共 API 设计原则、应用层与 SDK 层的职责边界,以及判断"一段代码该不该放进 SDK"的简单判定规则。读完本文,你将能在自己的 Vue 应用中正确使用 composables 与无外观结构组件,写出可复用、可换肤、不越权的 OpenPencil 编辑器集成层。
SDK 的定位:编辑器模型在 Core,Vue 层只负责"连接"
@open-pencil/vue 并不重复实现编辑器逻辑。它的全部职责,是把 @open-pencil/core 中的编辑器模型桥接到 Vue 运行时。按官方架构文档的表述,这个包只添加四类东西:
- 基于 Vue 的依赖注入(dependency injection);
- 响应式 composables(reactive composables);
- 不预设外观的结构型组件(strukturalne komponenty bez narzuconego wyglądu);
- 工作区(workspace)挂接与输入处理。
这与《Pierwsze kroki z SDK / SDK 快速上手》中描述的三层架构完全对应:
@open-pencil/core—— 与框架无关的编辑器引擎;@open-pencil/vue—— 面向 Vue 的 composables 与无外观组件;- 应用本身 —— 外观、路由、文件处理与产品界面。
从 包入口文件 packages/vue/src/index.ts 可以看到这一分工的直接证据:编辑器类型与工厂(Editor、EditorState、createEditor、EDITOR_TOOLS 等)全部从 @open-pencil/core/editor 再导出,而 Vue 专有能力(provideEditor、useCanvas、useSelectionState、各类控件 composables 与 *Root 结构组件)才是该包自己实现并导出的内容。
包结构:按功能域划分代码
架构文档强调"代码按功能域(obszary funkcjonalne)划分"。对照真实仓库,packages/vue/src/ 下的顶层目录正是这种思想的落地:
| 目录 | 功能域 |
|---|---|
canvas/ |
Canvas 挂接、表面(surface)生命周期、输入处理、拖放、覆盖层 |
controls/ |
属性面板与编辑器控件的 composables |
document/ |
文档工作区、导出 |
editor/ |
上下文注入、选中状态、命令、事件 |
primitives/ |
无外观结构组件族(Canvas、LayerTree、Toolbar 等) |
variables/ |
变量编辑器的状态连接 |
lifecycle/ |
活动保留(retention)等生命周期机制 |
internal/ |
非公共的通用辅助函数 |
shared/ |
拖拽、搜索、字体状态等跨域共享逻辑 |
i18n/ |
国际化 |
testing/ |
测试标识(test id)辅助 |
组件族(Rodziny komponentów)
架构文档列出的组件族目录为:
Canvas/、ColorPicker/、FillPicker/、FontPicker/、GradientEditor/、LayerTree/、PageList/、PropertyList/、PropertySection/、SegmentedControl/、NumberField/、Toolbar/
这些目录存放"无外观的结构组件"以及该区域的功能辅助函数。在真实源码中它们集中在 packages/vue/src/primitives/ 下,且入口文件证实它们确实存在并已公开导出:
- Canvas 族:
CanvasRoot、CanvasSurface、PlayIslands; - 拾色器族:
ColorPickerRoot、ColorInputRoot、FillRoot、FillSwatch、FontPickerRoot、GradientEditorRoot及GradientEditorBar/GradientEditorStop; - 树与列表族:
LayerTreeRoot、LayerTreeItem、PageListRoot、PropertyListRoot、PropertyListItem、PropertyGridRoot、PropertySectionRoot; - 控件族:
SegmentedControlRoot/SegmentedControlItem、NumberFieldRoot/NumberFieldInput、ToolbarRoot/ToolbarItem; - 文档文档还提到的
PositionControlsRoot、LayoutControlsRoot、AppearanceControlsRoot、ConstraintsControlRoot、TypographyControlsRoot、BindableValueRoot以及CommandPaletteRoot等,都在同一目录下按同样模式组织。
也就是说,组件族这一层级的核心契约是:组件负责结构与协调,不负责视觉。视觉层完全由消费方应用决定,这正是后续"公共 API 原则"的物理前提。
Controls:属性面板的 composables
controls/ 目录下是为属性面板和编辑器控件准备的 composables。架构文档列出的清单为:
usePositionuseLayoutuseAppearanceuseColorModeluseTypographyuseExportuseFillControlsuseStrokeControlsuseEffectsControlsuseNodePropsusePropScrubuseEditorPropertyList
这些在 入口文件 packages/vue/src/index.ts 的 "Property-panel composables" 导出段中全部可见,且真实实现分布在 packages/vue/src/controls/ 的 position/、layout/、appearance/、color-model/、typography/、fill/、stroke/、effects/、node-props/、prop-scrub/、property-list/ 等子目录。除此之外,该目录还额外提供了一批官方文档未逐一列出的同类 composables,例如:
useMask(controls/mask/use.ts);useVariableBinding、useColorVariableBinding、useNumberVariableBinding(变量绑定体系);useSharedStyleBinding(共享样式绑定);useConstraints(约束控制);useComponentProperties、useSlotAuthoring、useVariantAuthoring、useBehaviour(组件属性 / slot / 变体 / 行为状态);useOkHCL(OkHCL 色彩空间控制,配合useColorModel使用)。
以 usePropScrub 为例(见 packages/vue/src/controls/prop-scrub/use.ts),它内部基于 useNodePreview 实现了 updateProp(按节点当前状态预览数值变化)、updateEach(为每个节点分别计算变化量)、commitProp(提交预览)与 cancelProp(取消预览)四个操作——这正是"数值拖拽微调(scrub)"功能在 SDK 层的完整封装,UI 层无需接触场景图与历史记录即可实现该交互。
VariablesEditor:变量编辑器的状态连接
架构文档指出 VariablesEditor/ 包含 composables 和把"变量编辑器状态"与 Vue 连接起来的胶水代码。真实仓库中对应 packages/vue/src/variables/,入口导出 useVariables(见 index.ts 导出段)。它与 controls/ 下的变量绑定 composables(useVariableBinding 等)共同构成变量体系:前者负责变量面板的整体状态,后者负责具体属性与变量之间的绑定读写。
selection:选中派生状态
文档描述 selection/ 存放"基于选中状态计算出来的状态,以及可用操作的信息"。真实实现位于 packages/vue/src/editor/selection-state/,核心为 useSelectionState(packages/vue/src/editor/selection-state/use.ts)。它通过 useSceneComputed 把 editor.state.selectedIds 变成响应式派生状态,并对外暴露:
selectedIds、hasSelection、selectedCount、selectedNode、selectedNodeType;- 便捷判断
isInstance、isComponent、isGroup; - 能力判断
canCreateComponentSet(能否创建组件集)、canCreateSlot(能否创建 slot)。
值得注意的实现细节:这些能力判断并非硬编码在 UI 组件里,而是基于 @open-pencil/scene-graph 的 canBecomeSlot、slotOwner、slotPropertyId 等函数实时推导,验证了文档"selection 状态即派生状态"的定位。
context:Vue 依赖注入的枢纽
context/ 是整个 SDK 的 DI 心脏,真实实现见 packages/vue/src/editor/context/index.ts,只包含三样东西:
import { inject, provide } from 'vue'
import type { InjectionKey } from 'vue'
import type { Editor } from '@open-pencil/core/editor'
export const EDITOR_KEY: InjectionKey<Editor> = Symbol('open-pencil-editor')
export function provideEditor(editor: Editor) {
provide(EDITOR_KEY, editor)
}
export function useEditor(): Editor {
const editor = inject(EDITOR_KEY)
if (!editor) {
throw new Error(
'[open-pencil] useEditor() called without an injected editor. ' +
'Call provideEditor(editor) near the top of your Vue subtree first.'
)
}
return editor
}
EDITOR_KEY是类型为InjectionKey<Editor>的Symbol('open-pencil-editor'),官方注释明确建议普通使用者通过provideEditor/useEditor访问,而不是直接操作这个 Symbol;provideEditor(editor)应在编辑器外壳组件(shell)顶层调用一次;useEditor()在未注入的环境中调用会抛出带明确指引的错误信息,防止静默失败。
internal:非公共辅助函数
internal/ 存放"不属于包核心组件的公共辅助函数"。源码中的例子如 packages/vue/src/internal/scene-computed/use.ts 导出的 useSceneComputed(被 useSelectionState 内部使用)——这类工具对 SDK 内部广泛复用,但并非面向应用开发者的一等公民 API,因此被归入 internal 而非对外宣传。
公共 API 设计原则
架构文档用三个原则约束所有新增 API,源码实现完全遵循了这些约定。
原则一:逻辑与状态优先做成 composable
如果代码主要是在计算状态、管理状态或调用编辑器操作,就把它做成 composable。
这条原则的直接体现:useSelectionState 把选中相关的一切状态计算收进一个 composable;usePropScrub 把 scrub 交互的全部状态机收进一个 composable;useEditorCommands(packages/vue/src/editor/commands/use.ts)则把命令注册、快捷键元数据、执行封装为单一入口。消费方组件拿到的是一个自包含的、可测试的状态与行为单元,而不是散落的模板逻辑。
原则二:只有当"结构"有意义时才创建无外观组件
当组件需要协调结构、子元素、slots 或上下文时,才有必要存在一个主组件。
文档给出的示例组件名:
PageListRootPropertyListRootPropertySectionRootSegmentedControlRootToolbarRoot
所有这些在 packages/vue/src/primitives/ 下都有同名实现并公开导出。它们的共同模式是:*Root 负责建立局部上下文(通过 provide 一个 *Context)、组织 slot 结构、维护受控状态,而具体渲染内容完全由应用通过 slot 填充。反向推论同样重要:如果一个"组件"只是渲染一段静态 HTML 而没有结构协调职责,就不应该进入 SDK。
原则三:不要通过单个 slot 传递整个上下文
只向 slot 传递真正需要的 props,或者让消费方直接使用 composable。受控组件(如
PropertyListRoot)通过事件(emits)描述"发生了什么操作";与选中状态、撤销历史的绑定应放在 adapter 或受控 composable 中,而不是组件内部。
这条原则明确了状态流的单向性:数据从 composable 流向组件,操作由组件以事件形式上抛。以 PropertyListRoot 为例,它在 index.ts 导出段 中导出了大量 slot props 与 emits 类型(PropertyListRootProps、PropertyListRootSlotProps、PropertyListActions 等),但组件本身不持有选中状态、不直接改写场景图——增删项、可见性切换等操作以 PropertyListActions 形式暴露给上层 adapter,由 adapter 决定如何写入编辑器并归入撤销历史。这样既保证了组件的可复用性(不绑定特定编辑器实例),也保证了状态管理不被组件内部逻辑污染。
应用与 SDK 的职责边界
架构文档用一张清晰的对照表划分了"什么属于 SDK、什么属于应用",这是所有 OpenPencil 集成者做架构决策时的第一依据。
SDK 负责(@open-pencil/vue)
- 与编辑器的集成:
provideEditor/useEditor上下文、useCanvas等; - 可复用、与外观无关的逻辑:
controls/下全部属性控制 composables; - 与外观无关的界面结构:
primitives/下全部*Root结构组件; - 工作区渲染集成:
canvas/下的 CanvasKit 表面管理与渲染调度。
应用负责
- 外观(wygląd):所有视觉样式、主题;
- 页面整体布局(ogólny układ stron);
- 路由(routing);
- 打开、保存及其他文件操作;
- 通知、菜单和应用特有行为:如桌面端 Tauri 菜单、系统通知、快捷键体系等。
一个典型对照:useCanvas(packages/vue/src/canvas/surface/use.ts)负责渲染器创建、resize 时重建 surface、渲染调度以及基于渲染器的命中测试(hitTestSectionTitle、hitTestComponentLabel、hitTestFrameTitle、hitTestIssueMarker)——这是 SDK 的"工作区集成"职责;而应用只提供一个 <canvas ref> 元素、控制页面里画布放在哪,并决定菜单和文件菜单的行为。桌面端菜单、窗口与文件操作的实现证据可参见仓库根目录的 desktop/(Tauri 应用)与 src/(Web 应用壳层)——它们属于"应用层"范畴,与 SDK 包严格分离。
简单判定规则:代码该不该进 @open-pencil/vue
架构文档给出的最终判定标准只有一句话:
如果一段代码可以在不附带应用样式的情况下,被另一个基于 OpenPencil 的编辑器直接复用,那它大概率应该放进
@open-pencil/vue。
反过来推导,以下代码不应进入 SDK:
- 依赖特定设计系统、CSS 变量或主题的样式代码;
- 绑定具体页面路由、文件格式或业务菜单的代码;
- 与某个产品特有的通知、账号或协作策略耦合的逻辑。
这条规则与 快速上手文档 中的最小接线流程天然自洽:应用先 createEditor()(core 层),再在组件树顶层 provideEditor(editor),然后通过 useCanvas 挂接画布、通过 useSelectionState/useEditorCommands 等 composable 驱动 UI——全程应用层只做"外观与产品行为",不做编辑器逻辑,这就是分层边界在实践中的样子。
延伸阅读
- SDK 快速上手(Pierwsze kroki z SDK):安装、三层层级、最小配置与完整示例代码;
- SDK API 文档:
useEditor、useCanvas、useI18n等每个公开 API 的详细参考; - Vue 包入口
packages/vue/src/index.ts:完整的公共导出清单,是核对"哪些 API 是官方公开面"的第一手资料; - 上下文实现
packages/vue/src/editor/context/index.ts:EDITOR_KEY/provideEditor/useEditor的源码级实现; packages/vue/src/canvas/surface/use.ts与 选中状态实现packages/vue/src/editor/selection-state/use.ts:理解"工作区集成"与"派生状态"如何在 SDK 层落地。