OpenPencil Vue SDK 完全指南：用 `@open-pencil/vue` 打造自定义 AI 设计编辑器

• 前端
• 桌面应用
• AI 应用
• MCP 服务

@open-pencil/vue是 OpenPencil 官方提供的 Vue 3 SDK，它把@open-pencil/core的设计引擎能力解耦为可复用的依赖注入上下文、响应式 composable 与无样式结构组件，让开发者可以在不采用 OpenPencil 自带界面（桌面应用 仅是其中一种实现）的前提下，将设计编辑能力嵌入自有产品、内部工具或专用 AI 编辑器。读完本文，你将掌握 SDK 的架构分层、设计原则、两层 API（composable 与组件）的边界，并能够基于 快速上手文档 完成一个最小可运行的编辑器接入。

SDK 能做什么：定位与应用场景

OpenPencil 本身是一个 AI 原生的设计编辑器（开源 Figma 替代方案），而@open-pencil/vue让这项能力不再局限于独立应用形态：

• 可以构建一个完整的设计编辑器；
• 可以把编辑工作区嵌入到另一个产品的界面中；
• 可以制作内部工具、模板编辑器；
• 可以搭建带 AI 功能的专用编辑界面。

也就是说，OpenPencil 应用只是基于这套工具实现的众多界面之一，SDK 允许你创建属于自己的那一套。SDK 具体提供五类能力：

• 编辑器上下文：通过 Vue 的依赖注入（dependency injection）把编辑器实例分发给组件子树；
• 画布渲染：基于 CanvasKit 的渲染与输入集成；
• composable：覆盖选择（selection）、命令（commands）、菜单、属性面板与变量等领域的响应式状态与操作；
• 无样式结构组件：如PageListRoot、PropertyListRoot、ToolbarRoot等，只负责结构不负责外观；
• 本地化：菜单、面板与对话框的多语言支持，以及语言选择组件。

设计原则

SDK 的公共 API 遵循四条明确的设计原则：

1. 无样式是刻意选择（Senza stile per scelta）：SDK 提供逻辑与结构，但不强加任何应用外观；
2. 能用 composable 就不包多余的组件（Un composable invece di un wrapper superfluo）：如果不需要协调界面结构，一个 composable 就够了；
3. 精心设计公共 API（Un'API pubblica progettata con cura）：稳定的功能统一从 packages/vue/src/index.ts 导出；
4. 与 Vue 深度集成（Una stretta integrazione con Vue）：SDK 负责把 Vue 与@open-pencil/core的功能桥接起来。

从源码看，packages/vue/src/index.ts 首先对@open-pencil/core/editor做了 re-export（Editor、EditorState、EditorOptions、createEditor、EDITOR_TOOLS、TOOL_SHORTCUTS等），随后集中导出上下文、画布、控件、命令、变量、无样式 primitive 等全部公共符号——这正是"单一公共入口"原则的直接体现。

两层 API：composable 与组件

SDK 由两个主层级构成，理解二者的分工是使用 SDK 的关键：

1. composable：提供编辑器的状态与相关操作。如果你只需要状态与操作，从 composable 入手；
2. 组件（componenti）：定义有意义的界面结构。如果你要构建可复用的界面部件，从组件入手。

组件族（从架构文档与源码整理）

按功能区域组织，仓库中packages/vue/src/下的组件家族包括：Canvas/、ColorPicker/、FillPicker/、FontPicker/、GradientEditor/、LayerTree/、PageList/、PropertyList/、PropertySection/、SegmentedControl/、NumberField/、Toolbar/。这些目录里既有无样式结构组件，也有各区域专属的支持函数。

Controls：属性面板与编辑器控件

controls/目录集中了属性面板与编辑器控件的 composable，包括usePosition、useLayout、useAppearance、useColorModel、useTypography、useExport、useFillControls、useStrokeControls、useEffectsControls、useNodeProps、usePropScrub、useEditorPropertyList等。从 index.ts 可以看到这些 composable 与useMask、useSharedStyleBinding、useColorVariableBinding、useOkHCL等一起构成属性面板的完整工具箱。

变量（Variables）、选择（Selection）与上下文（Context）

• VariablesEditor/：变量编辑器的 composable 与状态桥接代码（useVariables、useVariablesEditor、useVariablesTable、useVariablesDialogState，见 index.ts）；
• selection/：由选择计算出的状态与可用操作信息（如useSelectionState、useSelectionCapabilities、useEditorEvent）；
• context/：通过 Vue 依赖注入提供编辑器的键与函数，即EDITOR_KEY、provideEditor、useEditor（对应源码 packages/vue/src/index.ts 的#vue/editor/context导出）；
• internal/：共享辅助函数，不属于包的主要公共组件。

公共 API 的使用原则

• 逻辑与状态用 composable：代码主要职责是计算/管理状态或执行编辑器操作时，以 composable 形式暴露；
• 仅在结构有意义时使用无样式组件：需要协调结构、子元素、间距或上下文时，才使用根组件。典型例子：PageListRoot、PropertyListRoot、PropertySectionRoot、SegmentedControlRoot、ToolbarRoot；
• 不要把整个上下文塞进一个插槽：只向插槽传递必要属性，或直接使用 composable。受控组件（如PropertyListRoot）通过语义化事件对外通信，与选择、历史的绑定应放在适配器或控制 composable 中，而非组件内部。

SDK 与应用的分工边界

SDK（@open-pencil/vue）负责：编辑器集成、可复用的无样式逻辑、可复用且不依赖样式的界面结构、画布渲染集成。

应用负责：样式、整体布局、路由、文件的打开/保存等操作、通知、菜单与应用特有行为。

规则很简单：如果一段代码能在另一个基于 OpenPencil 的编辑器中复用且不拖带应用样式，它大概率应该属于@open-pencil/vue。

三层应用架构与安装

一个基于 SDK 的应用由三层构成：

1. @open-pencil/core—— 框架无关的编辑器引擎；
2. @open-pencil/vue—— Vue 的 composable 与无样式组件；
3. 应用本身 —— 样式、路由、文件管理与产品特定界面。

安装命令（当前仓库使用 bun 作为包管理器，见 packages/vue/package.json 的构建脚本）：

bun add @open-pencil/core @open-pencil/vue canvaskit-wasm

从 package.json 可确认其 peerDependencies：@open-pencil/core（workspace）、canvaskit-wasm >= 0.41.1（可选）、vue ^3.5.41；运行时依赖还包括@open-pencil/scene-graph、@tanstack/vue-table、@vueuse/core、reka-ui、nanostores与@atlaskit/pragmatic-drag-and-drop等。

导入方式：

import { createEditor } from '@open-pencil/core/editor' import { provideEditor, useCanvas } from '@open-pencil/vue'

最小配置：三步接入

1. 创建编辑器实例

import { createEditor } from '@open-pencil/core/editor' const editor = createEditor({ width: 1200, height: 800, })

2. 通过依赖注入提供给子组件

<script setup lang="ts"> import { provideEditor } from '@open-pencil/vue' import type { Editor } from '@open-pencil/core/editor' const props = defineProps<{ editor: Editor }>() provideEditor(props.editor) </script> <template> <slot /> </template>

provideEditor()让编辑器实例对下方所有组件可见。文档直接调用该函数，因为它属于当前公共 API（源码位于 packages/vue/src/index.ts，由#vue/editor/context导出provideEditor、useEditor、EDITOR_KEY）。

3. 挂接画布

<script setup lang="ts"> import { ref } from 'vue' import { useCanvas, useEditor } from '@open-pencil/vue' const canvasRef = ref<HTMLCanvasElement | null>(null) const editor = useEditor() useCanvas(canvasRef, editor) </script> <template> <canvas ref="canvasRef" class="size-full" /> </template>

使用 composable 读写编辑器状态

调用provideEditor()之后，子组件即可读取选择并执行编辑器命令：

import { useEditorCommands, useSelectionState } from '@open-pencil/vue' const selection = useSelectionState() const commands = useEditorCommands()

一个完整的简单示例

下面的示例把画布、选择计数与一个状态栏组合成一个最小编辑器壳：

<script setup lang="ts"> import { ref } from 'vue' import { useCanvas, useEditor, useSelectionState } from '@open-pencil/vue' const canvasRef = ref<HTMLCanvasElement | null>(null) const editor = useEditor() const { selectedCount } = useSelectionState() useCanvas(canvasRef, editor, { onReady: () => { console.log('Canvas ready') }, }) </script> <template> <div class="grid h-full grid-rows-[1fr_auto]"> <canvas ref="canvasRef" class="size-full" /> <div class="border-t px-3 py-2 text-xs text-muted"> Selezionati: {{ selectedCount }} </div> </div> </template>

继续深入：文档入口与 API 分区

从 SDK 总览文档 出发，官方文档提供了四条深入路径：

• 入门：Primi passi con l'SDK —— 安装、创建编辑器实例并连接核心组件；
• 架构：Architettura dell'SDK —— composable、组件与编辑器上下文如何协作；
• 指南：自定义编辑器外壳、导航面板、属性面板；
• API 参考：API 总览，分为三块：
  • 组件：无样式组件如CanvasRoot、ToolbarRoot、FontPickerRoot、NumberField；
  • Composable：编辑器、画布、选择、命令与属性的状态与操作（如 useEditor、useCanvas、useI18n）；
  • 高级 API：面向自定义集成的底层上下文与专用函数。

选择建议：构建可复用结构与控件看组件；需要编辑器状态与动作看composable；需要直接访问底层状态或上下文看高级 API。

小结

@open-pencil/vue把 OpenPencil 的设计引擎包装成了一套对 Vue 友好的可组合 API：以provideEditor/useEditor建立上下文，以useCanvas接入 CanvasKit 渲染，以大量 controls composable 承载属性面板逻辑，以*Root系列无样式组件提供界面骨架，并以 packages/vue/src/index.ts 作为稳定的单一公共出口。遵循"逻辑走 composable、结构走组件、公共 API 收敛于 index.ts"的约定，你就能把 OpenPencil 改造成贴合自己产品形态的 AI 设计编辑器。

• 前端
• 桌面应用
• AI 应用
• MCP 服务