OpenPencil Vue SDK 架构指南:Headless 设计、Composable 体系与职责边界
OpenPencil Vue SDK 架构指南:Headless 设计、Composable 体系与职责边界
@open-pencil/vue 是 OpenPencil 面向 Vue 3 的官方 SDK,它把与框架无关的 @open-pencil/core 编辑器引擎桥接到 Vue:通过依赖注入让编辑器实例在整个组件树中可用,通过 composables 暴露响应式的选区、命令与属性面板状态,并提供了不含任何内建样式的结构组件来搭建设计工具界面。本文以官方架构文档(packages/docs/ru/programmable/sdk/architecture.md)为骨架,结合仓库源码逐层拆解包结构、公共 API 设计原则以及 SDK 与应用之间的职责边界,读完即可掌握"哪些代码应该进 SDK、哪些应该留在应用层"的判断方法。
一、SDK 在 OpenPencil 三层架构中的位置
架构文档对 @open-pencil/vue 的定位有一句非常精炼的概括:@open-pencil/vue 连接 @open-pencil/core 与 Vue,而编辑器模型(editor model)仍然保留在主包中。
也就是说,场景图、文档模型、撤销历史、命令与画布渲染内核都属于 @open-pencil/core,它们不感知 Vue;SDK 只是在 core 之上叠加 Vue 专属的一层。由此,一个基于 SDK 构建的编辑器应用天然被划分为三个层次:
@open-pencil/core—— 与框架无关的编辑器引擎;@open-pencil/vue—— 面向 Vue 的组合式函数(composables)与无预设样式的组件;- 你的应用 —— 样式、页面布局、路由、文件操作与产品专属 UI。
在 core 之上,SDK 包额外提供了四类能力:
- 借助 Vue 机制完成依赖注入:用
provide/inject把编辑器实例分发给组件树; - 响应式 composables:把编辑器的选区、命令、属性等状态包装成 Vue 响应式数据;
- 结构组件:不含内建样式的组件骨架;
- 画布接入与输入处理:把真实
<canvas>与渲染器、指针/键盘输入连接起来。
二、包结构:按领域分组的源码布局
2.1 组件家族:结构组件与辅助函数
架构文档列出了 12 个组件家族目录:
Canvas/ColorPicker/FillPicker/FontPicker/GradientEditor/LayerTree/PageList/PropertyList/PropertySection/SegmentedControl/NumberField/Toolbar/
这些目录里存放的是"结构组件 + 该领域的辅助函数",二者都不含内建样式。在仓库源码中,它们对应 packages/vue/src/canvas 与 packages/vue/src/primitives 下的同名目录(FillPicker 的职责在仓库中由 primitives/Fill 下的 FillRoot/FillSwatch 承担),并由 packages/vue/src/index.ts 统一对外导出。例如:
CanvasRoot/CanvasSurface—— 画布容器结构与渲染表面;LayerTreeRoot/LayerTreeItem—— 图层树;PageListRoot—— 页面列表;PropertyListRoot/PropertyListItem/PropertyListAdd/PropertyListRemove/PropertyListVisibility—— 属性列表;PropertySectionRoot/PropertySectionHeader/PropertySectionTitle/PropertySectionActions/PropertySectionContent—— 属性分组;SegmentedControlRoot/SegmentedControlItem—— 分段控件;NumberFieldRoot/NumberFieldInput/NumberFieldValue/NumberFieldUnit/NumberFieldMenu—— 数字输入字段;ToolbarRoot/ToolbarItem—— 工具栏;ColorPickerRoot/ColorInputRoot、FontPickerRoot、GradientEditorRoot/GradientEditorBar/GradientEditorStop—— 各取色/取字体/渐变编辑器家族。
2.2 controls/:属性面板与编辑器控件 composables
controls/ 下是供属性面板与编辑器控件使用的 composables。架构文档列出了 12 个,下表补充了它们在仓库中的实际位置:
| Composable | 用途 | 源码位置 |
|---|---|---|
usePosition |
当前选区的位姿状态与动作(x/y、尺寸、旋转、对齐、翻转) | packages/vue/src/controls/position/use.ts |
useLayout |
布局相关属性 | packages/vue/src/controls/layout/use.ts |
useAppearance |
外观(圆角等)属性 | packages/vue/src/controls/appearance/use.ts |
useColorModel |
颜色模型(RGB/HSL/HSB/OkHCL 通道) | packages/vue/src/controls/color-model |
useTypography |
字体排版属性 | packages/vue/src/controls/typography/use.ts |
useExport |
导出设置与动作 | packages/vue/src/document/export/use.ts |
useFillControls |
填充控件 | packages/vue/src/controls/fill/use.ts |
useStrokeControls |
描边控件 | packages/vue/src/controls/stroke/use.ts |
useEffectsControls |
效果(阴影等)控件 | packages/vue/src/controls/effects/use.ts |
useNodeProps |
节点属性读写(支持 MIXED 混合值) |
packages/vue/src/controls/node-props/use.ts |
usePropScrub |
数值拖拽微调(update/commit/cancel 三段式) | packages/vue/src/controls/prop-scrub/use.ts |
useEditorPropertyList |
把受控的 PropertyList 接到选区与撤销历史 | packages/vue/src/controls/property-list/use.ts |
以 usePosition 为例,可以看到这类 composable 的典型形态(见 packages/vue/src/controls/position/use.ts):它通过 useEditor() 取回注入的编辑器实例,用 useNodeProps() 拿到当前选区节点集合,用 usePropScrub() 提供数值编辑的 update/commit/cancel;x/y/rotation 的读数来自 core 的 panelPosition/panelRotation 几何函数,以保证与 Figma 面板的显示口径一致;对齐、翻转、旋转则直接调用 editor.alignNodes / editor.flipNodes / editor.rotateNodes。整个实现只关心"当前选区下的状态与动作",完全不接触任何样式。
2.3 VariablesEditor/ 与 selection/:变量编辑器与选区派生状态
- 变量编辑器:
VariablesEditor/在源码中对应 packages/vue/src/variables,包含连接变量编辑器状态与 Vue 的 composables(对外导出useVariables)。 - 选区(selection/):在源码中对应 packages/vue/src/editor/selection-state,包含计算得到的选区状态与可用操作信息。
useSelectionState()对外暴露selectedIds、hasSelection、selectedCount、selectedNodeType、isInstance/isComponent/isGroup、canCreateComponentSet、canCreateSlot等响应式结果(见 packages/vue/src/editor/selection-state/use.ts),UI 直接消费这些派生状态即可,无需在每个组件里手动读取图数据。
2.4 context/:依赖注入三件套
context/ 是 SDK 注入机制的核心,对外导出三个成员:EDITOR_KEY、provideEditor、useEditor。实现集中在 packages/vue/src/editor/context/index.ts:
// packages/vue/src/editor/context/index.ts(要点摘录)
import { inject, provide, type InjectionKey } from 'vue'
import type { Editor } from '@open-pencil/core/editor'
/** Injection key for the current OpenPencil editor instance. */
export const EDITOR_KEY: InjectionKey<Editor> = Symbol('open-pencil-editor')
/** Provides an OpenPencil editor instance to the current Vue subtree. */
export function provideEditor(editor: Editor) {
provide(EDITOR_KEY, editor)
}
/** Returns the current injected OpenPencil 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 是一个以 Symbol('open-pencil-editor') 标识的 InjectionKey<Editor>;provideEditor(editor) 本质上就是对 Vue provide(EDITOR_KEY, editor) 的封装;useEditor() 在子树中 inject,若在未提供编辑器的子树外调用,会抛出带有明确修复提示的错误。官方文档建议直接在组件树的顶部调用 provideEditor(),因为它正是当前公共 API 的正式入口。
2.5 internal/:内部服务代码
internal/(源码 packages/vue/src/internal)存放通用的内部工具函数,例如 create-context.ts 与 scene-computed(useSceneComputed 依赖的派生计算)。架构文档特别强调:这些代码不属于包的主要组件集合,使用者不应把它们当作一级公共 API 对待。
三、公共 API 的三条设计原则
3.1 逻辑与状态一律走 composable
原则一:如果代码主要是在计算状态、管理状态或调用编辑器动作,就应当以 composable 的形式提供。这条原则保证了逻辑可以在任意组件树位置被复用,并且天然获得 Vue 的响应式能力。前面列举的 usePosition、useSelectionState、useEditorCommands 等都是这一原则的直接产物。
3.2 只在结构重要的地方提供无样式组件
原则二:只有当一个根组件需要管理结构、子元素、插槽或上下文时,才需要组件。文档给出的典型示例是:
PageListRootPropertyListRootPropertySectionRootSegmentedControlRootToolbarRoot
这类 Root 组件只负责结构编排,把样式完全留给宿主应用——这正是 @open-pencil/vue 被定义为 headless SDK 的含义(README 中也明确写道:"The SDK is headless by design: it provides logic and structure, while your app owns styling and product-specific UI.")。
3.3 不要通过单个 slot 传递整个上下文
原则三:不要用一个大 slot 把整个上下文塞给子组件。具体要求有三点:
- 通过 slot 只传递必要的最小属性,或者干脆让使用者直接调用 composable;
- 受控组件(如
PropertyListRoot)通过**语义事件(semantic events)**上报动作,而不是暴露编辑器内部对象; - 与选区、撤销历史的绑定必须放在适配器(adapter)或管理型 composable 中,绝不能写进这类结构组件内部。
这条原则在仓库中的落地非常典型:PropertyListRoot 本身对编辑器一无所知,是受控且与编辑器无关的;真正把列表项与 editor.undo、editor.beginInteractiveEdit、editor.updateNodeWithUndo 连接起来的是 useEditorPropertyList(),它负责批量撤销、多选更新、可见性切换与重排(见 packages/vue/src/controls/property-list/use.ts)。README 中的表述与之完全一致:"PropertyListRoot is controlled and editor-agnostic; OpenPencil panels connect it to selection and undo through useEditorPropertyList()"。
四、SDK 与应用的职责边界
架构文档对"谁该做什么"给出了明确分工:
SDK(@open-pencil/vue)负责:
- 与编辑器的集成(editor integration);
- 可复用的、不绑定样式的逻辑;
- 可复用的、不依赖样式的界面结构;
- 画布渲染的集成。
应用(Application)负责:
- 样式(styling);
- 页面的整体布局(page layout);
- 路由(routing);
- 打开、保存及其他文件操作;
- 通知、菜单,以及只有特定应用才有的行为。
这份边界表可以作为开发时的自查清单:凡是"画布怎么渲染、选区怎么算、面板逻辑怎么写"这类问题,答案都应尽量在 SDK 层解决;凡是"按钮长什么样、页面怎么排、文件怎么存取"这类问题,都是应用层的职责。
五、判断代码归属的"简单规则"
架构文档在结尾给出了一条极具实操价值的判断标准:
如果一段代码可以在不使用本应用样式的前提下,被另一个基于 OpenPencil 的编辑器复用,那么它大概率应该放进
@open-pencil/vue。
这条规则把"是否绑定应用样式"当作分水岭:
- 代码脱离样式可复用 → 放进 SDK;
- 代码绑定了特定应用样式、布局或路由 → 留在应用层。
在写属性面板、工具栏或自定义编辑器外壳时,都可以先拿这条规则过一遍,避免把本该沉淀进 SDK 的可复用逻辑写成应用里的"一次性代码"。
六、画布接入速览:对应"画布接入与输入处理"
架构文档在开头把"подключение холста и обработка ввода"(画布接入与输入处理)列为 SDK 的核心能力之一。在仓库源码中,它由两套互补的 API 承担:
- composable 级:
useCanvas(canvasRef, editor)把一个真实<canvas>元素与编辑器连接起来,负责渲染器(CanvasKit)创建、尺寸变化时的 surface 重建、渲染调度以及基于渲染器的命中测试(见 packages/vue/src/canvas/surface/use.ts);更上层的useCanvasInput()/useTextEdit()处理指针、键盘与文本输入。 - 结构组件级:
CanvasRoot+CanvasSurface提供无样式的画布容器结构。
配套的完整上手流程见 SDK 快速开始 与 packages/vue/README.md,其最小骨架为:
// 1. 创建编辑器(core 包)
const editor = createEditor({ width: 1200, height: 800 })
// 2. 在组件树顶部注入
provideEditor(editor)
// 3. 在画布组件里绑定 canvas
const canvasRef = ref<HTMLCanvasElement | null>(null)
useCanvas(canvasRef, editor)
// 4. 任意后代组件消费状态
const { selectedCount } = useSelectionState()
const commands = useEditorCommands()
需要说明的是:@open-pencil/vue 的依赖约束以 packages/vue/package.json 为准——peerDependencies 要求 @open-pencil/core、vue ^3.5.41,而 canvaskit-wasm >=0.41.1 是可选 peer 依赖(提供 CanvasKit 渲染时必需)。
七、继续阅读
- SDK 快速开始(getting-started):安装、三层架构、最小可运行示例
- API 参考:组件(Components)、composables 与底层 API 三部分参考
- packages/vue/README.md:包定位、核心概念、公共 API 分层与示例模式
- packages/vue/package.json:peerDependencies 与构建脚本
- 源码入口:packages/vue/src/index.ts(全部公开导出)、packages/vue/src/editor/context/index.ts(依赖注入三件套)