OpenPencil Vue SDK 架构指南:Headless 设计、Composable 体系与职责边界

原创2026-10-09 09:14:061,667 阅读
文章标签:桌面应用开发工具前端人工智能AI 应用MCP 服务代码生成CLI插件系统

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 构建的编辑器应用天然被划分为三个层次:

  1. @open-pencil/core —— 与框架无关的编辑器引擎;
  2. @open-pencil/vue —— 面向 Vue 的组合式函数(composables)与无预设样式的组件;
  3. 你的应用 —— 样式、页面布局、路由、文件操作与产品专属 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 只在结构重要的地方提供无样式组件

原则二:只有当一个根组件需要管理结构、子元素、插槽或上下文时,才需要组件。文档给出的典型示例是:

  • PageListRoot
  • PropertyListRoot
  • PropertySectionRoot
  • SegmentedControlRoot
  • ToolbarRoot

这类 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 承担:

  1. composable 级:useCanvas(canvasRef, editor) 把一个真实 <canvas> 元素与编辑器连接起来,负责渲染器(CanvasKit)创建、尺寸变化时的 surface 重建、渲染调度以及基于渲染器的命中测试(见 packages/vue/src/canvas/surface/use.ts);更上层的 useCanvasInput() / useTextEdit() 处理指针、键盘与文本输入。
  2. 结构组件级: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 渲染时必需)。

七、继续阅读

登录后查看全文
open-pencil