企业官网建设流程全解析

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

本文以@open-pencil/vue的官方 API 参考索引为主线，系统梳理 OpenPencil（AI-native 设计编辑器、开源 Figma 替代品）Vue SDK 的三层公开 API：无样式组件（Components）、编辑器 Composable（Composables）与面向深度集成的高级 API（Advanced）。读完本文，你将掌握如何为自定义编辑器界面挑选正确的 API 层级、如何通过 Vue 依赖注入接入编辑器上下文，以及每个板块下核心导出项在 packages/vue/src/index.ts 中的真实对应关系，从而独立搭建属于自己的编辑器外壳、属性面板与导航面板。

一、Vue SDK 与 API 参考的整体定位

@open-pencil/vue允许把 OpenPencil 从"独立设计应用"变成"可嵌入的编辑器能力"：你可以将其集成进自有产品、内部工具或专用编辑器中，而不必沿用应用默认界面。OpenPencil 官方应用本身只是用这套工具实现的众多界面之一，SDK 的价值正在于允许你创建自己的界面（见 packages/docs/programmable/sdk/index.md）。

SDK 提供的能力包括：

• 通过 Vue 依赖注入（dependency injection）提供编辑器上下文；
• 基于 CanvasKit 的工作区渲染；
• 面向选择、命令、菜单、属性面板与变量系统的 composable；
• 无样式结构组件，如PageListRoot、PropertyListRoot、ToolbarRoot；
• 菜单、面板、对话框的本地化（i18n）以及语言选择组件。

官方 SDK 索引页将其 API 参考（/programmable/sdk/api/）划分为三个板块：Components（无样式结构原语）、Composables（面向编辑器的状态与动作）、Advanced（低层辅助函数与专门 API）。这正是 packages/docs/programmable/sdk/api/index.md 一页的核心骨架。

设计原则

SDK 索引页明确列出了四条设计原则，也是理解 API 分层的关键：

• 无样式是刻意的选择：SDK 只提供逻辑与结构，不强制应用外观；
• 一个 composable 胜过多余的 wrapper：只要不需要协调界面结构，一个 composable 就足够；
• 公开 API 经过精心设计：稳定功能统一从packages/vue/src/index.ts导出；
• 与 Vue 紧密集成：SDK 把 Vue 与@open-pencil/core的能力绑定在一起。

两层 API 模型

SDK 由两个主要层级组成：

1. Composable提供编辑器状态与相关操作；
2. Components定义有意义的界面结构。

如果只需要编辑器的状态与操作，从 composable 入手；如果正在构建可复用的界面部件，则从组件入手。这也是下方"从哪开始"一节推荐路径的依据。

二、Components：无样式结构原语

组件板块为工作区、导航、属性面板与专门输入字段提供无样式组件。原始参考页（packages/docs/programmable/sdk/api/components/index.md）按用途将其分为四组。

工作区

• CanvasRoot：提供画布上下文的结构根组件；
• CanvasSurface：CanvasKit 渲染表面，负责实际绘制场景。

从源码看，二者统一从#vue/canvas导出（export { CanvasRoot, CanvasSurface, useCanvasContext } from '#vue/canvas'），并配套导出CanvasContext类型，供子组件读取画布上下文。

导航

• PageListRoot：页面列表与页面操作；
• LayerTreeRoot：图层面板（图层树）；
• LayerTreeItem：图层树中的单行；
• ToolbarRoot：工具栏容器；
• ToolbarItem：单个工具项。

LayerTree模块还额外导出了buildLayerTreeModel、indexLayerNodes、layerSelectionForTarget、patchLayerNode、visibleLayerRows等辅助函数，用于构建与修补图层树模型，并定义了LayerNode、LayerRow、LayerTreeContext、LayerTreeVirtualizer等类型；Toolbar模块则配套导出useToolbar与ToolbarContext（见 packages/vue/src/index.ts）。

属性面板

• PropertyListRoot：受控的属性列表；
• PropertyListItem：填充、描边或效果条目；
• PositionControlsRoot：位置与变换；
• LayoutControlsRoot：自动布局（Auto Layout）；
• AppearanceControlsRoot：不透明度、可见性与圆角；
• TypographyControlsRoot：字体与文本格式化。

PropertyList系列是属性面板的核心，源码中一并导出PropertyListAdd、PropertyListRemove、PropertyListVisibility及usePropertyList，并给出PropertyListRootProps、PropertyListRootSlotProps、PropertyListItemSlotProps等完整槽位/属性类型；LayoutControlsRoot配套useLayoutControlsContext与LayoutControlsContext类型。这些都说明该板块是"根组件 + 组合式逻辑"成对设计的。

颜色、渐变与字体

• ColorInputRoot
• ColorPickerRoot
• GradientEditorRoot
• GradientEditorBar
• GradientEditorStop
• FontPickerRoot

FontPickerRoot导出FontFamilyOption与FontPickerUI类型；GradientEditor系列导出GradientEditorStopActions、GradientEditorStopProps等类型；ColorInputRoot与ColorPickerRoot则与ChannelSliderRoot/Thumb/Track一同从#vue/primitives/ColorPicker与#vue/primitives/ChannelSlider导出。它们都属于"无样式原语 + 槽位协议"模式，外观完全由使用方决定。

三、Composable：编辑器状态与动作

Composable 板块为基于 OpenPencil 的界面提供通用状态与动作（见 packages/docs/programmable/sdk/api/composables/index.md），按功能分为四组。

编辑器与工作区

• provideEditor：把编辑器实例注入 Vue 子树；
• useEditor：从注入上下文读回编辑器；
• useCanvas：画布接线；
• useCanvasInput：画布输入事件；
• useTextEdit：文本编辑状态。

provideEditor、useEditor与EDITOR_KEY一起从#vue/editor/context导出，是"让编辑器对 Vue 子树可见、并在 composable 与无样式原语中读回"的主要入口（见 packages/vue/src/index.ts）。useCanvas对应UseCanvasOptions选项类型；useCanvasInput配套导出CanvasLabelEdit、CanvasLabelKind等类型，用于处理画布上的标签编辑。

选择与命令

• useSelectionState：当前选择状态；
• useSelectionCapabilities：选择对象的能力集；
• useEditorCommands：命令面板与编辑器命令；
• useMenuModel：菜单模型（菜单栏/上下文菜单）。

useSelectionState由createSelectedNodeState支撑，后者构造SelectedNodeState；命令体系非常完整：EDITOR_COMMAND_METADATA、editorCommandMetadata提供命令元数据注册表，formatShortcut/shortcutPlatform负责快捷键格式化与平台差异（ShortcutPlatform类型），EditorCommand/EditorCommandId定义命令签名；useMenuModel配套MenuActionNode、MenuEntry、MenuSeparatorNode等菜单节点类型。若需自建命令面板，还可直接使用CommandPaletteRoot原语及其CommandPaletteGroup、CommandPaletteItem、CommandPaletteUI等类型。

属性面板

• useAppearance：外观（不透明度、可见性、圆角）；
• usePosition：位置与变换；
• useLayout：自动布局（配套LayoutAxis、SizeLimitProp类型）；
• useTypography：字体与文本；
• useFillControls：填充控制；
• useStrokeControls：描边控制（配套isStrokeCapValue校验）；
• useEffectsControls：效果（阴影等）。

这组 composable 是自建属性面板的"逻辑层"，与上一节的无样式属性组件一一对应：逻辑与结构分离，正是 SDK 两层 API 设计的直接体现。

文档

• usePageList：页面列表；
• useVariablesEditor：设计变量编辑；
• useExport：导出（ExportFormatId、ExportFormatOption、ExportSetting类型）；
• useI18n：国际化与语言切换。

useI18n在源码中通过export * from '#vue/i18n'整体暴露，与 SDK 的本地化承诺一致；useExport则为自定义导出流程（如"导出为 PNG/PDF/其他格式"）提供统一入口。

四、Advanced：低层辅助与专门 API

高级 API 板块支撑公开组件与 composable，适用于自定义界面超出高层控件能力范围的场景（见 packages/docs/programmable/sdk/api/advanced/index.md），同样分为四组。

工作区与工具

• toolCursor：工具光标（按当前工具切换光标样式）；
• useCanvasContext：读取画布上下文；
• useCanvasDrop：画布拖放（配套extractImageFilesFromClipboard，可从剪贴板提取图片文件）；
• useToolbar：工具栏逻辑；
• useToolbarState：工具栏工具选中状态（配套getToolbarToolSelection、isToolbarToolActive）；
• useViewportKind：视口类型（如桌面/移动端）。

属性与颜色

• useNodeProps：节点属性读写（配套MIXED常量与MixedValue类型，用于表示多选时"混合值"）；
• usePropScrub：属性拖拽微调（scrub）；
• usePropertyList：受控属性列表逻辑；
• useColorVariableBinding：颜色与设计变量绑定；
• useGradientStops：渐变停止点；
• useOkHCL：OKHCL 颜色空间控制（源码中为useOkHCL，文件为 use-okhcl.md）。

颜色体系不止于此：源码还从#vue/controls/color-model导出applySolidFillColor、applySolidStrokeColor、BUILT_IN_COLOR_FORMATS、useColorModel等，并定义BuiltInColorFormat、OkHCLControls类型；变量绑定侧还有useVariableBinding、useNumberVariableBinding以及BindingProvider/BindingTarget等绑定抽象。

导航与编辑

• useLayerTree：图层树逻辑；
• useLayerDrag：图层拖拽重排（底层依赖@atlaskit/pragmatic-drag-and-drop）；
• useInlineRename：图层/节点行内重命名；
• useFontPicker：字体选择逻辑（基于 Fuse.js 模糊搜索）；
• useNodeFontStatus：节点字体加载状态；
• useSceneComputed：场景派生状态（响应式计算）。

变量与语言

• useVariables：设计变量全局状态；
• useVariablesDialogState：变量对话框状态；
• useVariablesTable：变量表格（基于@tanstack/vue-table构建）；
• Locale APIs：本地化 API。

五、从哪开始：推荐的入门路径

官方 API 索引页给出了三条明确建议（见 packages/docs/programmable/sdk/api/index.md 的 "Suggested path" 一节）：

• 在构建可复用的编辑器 UI 原语时，从Components入手；
• 在接线编辑器状态与动作时，从Composables入手；
• 仅当需要低层辅助函数或原语上下文时，才使用Advanced。

结合 SDK 索引页（packages/docs/programmable/sdk/index.md），完整的学习路径是：先阅读 getting-started.md 安装包并创建编辑器实例，再看 architecture.md 理解 composable、组件与编辑器上下文的交互方式，然后依据 custom-editor-shell.md、property-panels.md、navigation-panels.md 三篇指南动手搭建，最后回到本 API 参考逐项查证。

六、安装与运行前提

@open-pencil/vue的版本与依赖声明（见 packages/vue/package.json）值得注意：

• peerDependencies：
  • @open-pencil/core（workspace 版本，核心编辑器引擎）；
  • vue^3.5.41（要求 Vue 3.5+）；
  • canvaskit-wasm>=0.41.1（可选，未安装时画布相关能力受限）；
• 关键 dependencies：
  • @atlaskit/pragmatic-drag-and-drop及其 hitbox 扩展（图层拖拽）；
  • @tanstack/vue-table（变量表格）；
  • @vueuse/core、nanostores与@nanostores/vue（响应式状态）、@nanostores/i18n（国际化）；
  • reka-ui（底层 UI 原语）；
  • fuse.js（字体模糊搜索）。

构建命令为bunx tsdown --config tsdown.config.ts，产物通过exports映射到dist/index.js与dist/index.d.ts，属于sideEffects: false的纯 ESM 包，便于 tree-shaking。注意canvaskit-wasm为可选 peer 依赖：如果不需要画布渲染能力，可以跳过安装。

七、继续深入

• 三大板块完整索引：Components、Composables、Advanced；
• 公开 API 的权威出处：packages/vue/src/index.ts（稳定功能均由此导出）；
• SDK 架构与设计原则：architecture.md；
• 实战指南：custom-editor-shell.md、property-panels.md、navigation-panels.md。

一句话总结：需要结构就用组件，需要逻辑就用 composable，需要深度定制就下探高级 API——三者共同构成@open-pencil/vue从"官方应用"走向"任意自定义编辑器"的完整工具箱。

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