OpenPencil 的 Vue SDK 架构解析:@open-pencil/vue 的分层设计、公共 API 边界与职责划分

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

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 快速上手》中描述的三层架构完全对应:

  1. @open-pencil/core —— 与框架无关的编辑器引擎;
  2. @open-pencil/vue —— 面向 Vue 的 composables 与无外观组件;
  3. 应用本身 —— 外观、路由、文件处理与产品界面。

从 包入口文件 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。架构文档列出的清单为:

  • usePosition
  • useLayout
  • useAppearance
  • useColorModel
  • useTypography
  • useExport
  • useFillControls
  • useStrokeControls
  • useEffectsControls
  • useNodeProps
  • usePropScrub
  • useEditorPropertyList

这些在 入口文件 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 或上下文时,才有必要存在一个主组件。

文档给出的示例组件名:

  • PageListRoot
  • PropertyListRoot
  • PropertySectionRoot
  • SegmentedControlRoot
  • ToolbarRoot

所有这些在 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——全程应用层只做"外观与产品行为",不做编辑器逻辑,这就是分层边界在实践中的样子。

延伸阅读

登录后查看全文
open-pencil