OpenPencil 高级 API 全解析:用 @open-pencil/vue 底层组合式函数构建自定义编辑界面
OpenPencil 高级 API 全解析:用 @open-pencil/vue 底层组合式函数构建自定义编辑界面
本篇技术指南以 OpenPencil(开源 AI 原生设计编辑器)Vue SDK 的 Advanced APIs(高级 API) 文档为骨架,系统讲解 @open-pencil/vue 中 20 余个底层组合式函数与上下文注入函数的用途、适用场景与源码实现原理。这些 API 支撑着 CanvasRoot、ToolbarRoot、LayerTreeRoot 等公开组件与 composables,当标准控件无法满足自定义编辑器外壳、属性面板、图层树或变量编辑器等需求时,它们是构建自有界面的直接入口。读完本文,你将掌握每一类高级 API 的职责边界、参数与返回值,并了解如何结合 Vue SDK 快速上手 在自己的应用中组合它们。
什么是 Advanced API:三层 SDK 架构中的底层积木
OpenPencil 的 SDK 按 架构文档 分为三层:
@open-pencil/core—— 与框架无关的编辑器引擎(场景图、命令、渲染);@open-pencil/vue—— 为 Vue 提供的组合式函数(composables)与无样式组件;- 应用层 —— 样式、路由、文件管理与产品化 UI。
在 @open-pencil/vue 内部,公开 API 又分为三块(见 API 参考总览):
- Components:
CanvasRoot、ToolbarRoot、FontPickerRoot、NumberField等无样式组件,负责结构与交互外壳; - Composables:编辑器的状态与动作(
useEditor、useCanvas、useSelectionState、useEditorCommands等); - Advanced APIs:低层上下文与专用函数,供需要直接访问状态或低层上下文的集成场景使用。
本文的主角即第三类。按照官方文档的分组,高级 API 覆盖五大领域:画布与工具、属性与颜色、导航与编辑、变量与区域设置、剪贴板。它们大多以 use* 组合式函数形式暴露,内部通过 Vue 的 inject/provide 机制读取上层组件注入的上下文(如 CanvasRoot、ToolbarRoot),因此使用时通常要求先建立对应的组件层级。
画布与工具:上下文、光标、拖放与响应式视口
本组 API 用于构建自有画布外壳与工具栏外壳,对应官方文档的「Lienzo y herramientas」分组。
useCanvasContext:读取最近的 CanvasRoot 上下文
useCanvasContext() 返回最近的 CanvasRoot 注入的上下文,供 CanvasSurface 或其子孙组件读取画布引用与状态。其实现位于 packages/vue/src/canvas/context/index.ts:
export interface CanvasContext {
canvasRef: Ref<HTMLCanvasElement | null>
ready: Ref<boolean>
renderNow: () => void
hitTestSectionTitle: (cx: number, cy: number) => SceneNode | null
hitTestComponentLabel: (cx: number, cy: number) => SceneNode | null
hitTestFrameTitle: (cx: number, cy: number) => SceneNode | null
}
export const CANVAS_KEY: InjectionKey<CanvasContext> = Symbol('canvas')
export function useCanvasContext(): CanvasContext {
const ctx = inject(CANVAS_KEY)
if (!ctx) throw new Error('[open-pencil] useCanvasContext() called outside <CanvasRoot>')
return ctx
}
从源码可以看到三个要点:上下文通过 Symbol('canvas') 注入键提供;返回值包含 canvasRef(底层 <canvas> 元素引用)、ready(就绪标志)、renderNow()(手动触发渲染)以及三个命中测试方法(用于画布上节标题、组件标签、Frame 标题的点击检测);在 CanvasRoot 之外调用会立即抛出错误,这属于“必须在组件树内使用”的约束型 API。相关组件定义见 CanvasRoot 与 CanvasSurface。
toolCursor:工具与 CSS 光标的一一映射
toolCursor(tool, override?) 返回某工具对应的 CSS 光标值,override 参数可覆盖结果。源码位于 packages/vue/src/editor/tool-cursor/index.ts,内置映射表如下:
| 工具 | CSS 光标 |
|---|---|
SELECT |
default |
FRAME / SECTION / RECTANGLE / ELLIPSE / LINE / POLYGON / STAR / PEN |
crosshair |
TEXT |
text |
HAND |
grab |
export function toolCursor(tool: Tool, override?: string | null): string {
if (override) return override
return TOOL_CURSORS[tool] ?? 'default'
}
实现非常直白:先检查 override,再查表,未知工具回退为 default。官方文档建议在自有画布或工具栏中使用该函数,以保持光标体验一致;工具与命令体系可参考 useCanvas 与 useEditorCommands。
useCanvasDrop:把拖放事件接入编辑器导入流程
useCanvasDrop(options) 将原生 dragover、dragenter、dragleave、drop 事件与编辑器的文件/组件导入能力连接起来:把指针位置换算为画布坐标、校验受支持的类型,并在落点导入图片、SVG 或其他兼容数据。实现位于 packages/vue/src/canvas/drop/use.ts:
const RASTER_IMAGE_TYPES = new Set([
'image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/avif'
])
const COMPONENT_MIME = 'application/x-openpencil-component'
export function useCanvasDrop(
canvasRef: Ref<HTMLCanvasElement | null>,
editor: Editor,
onActivate?: () => void
) {
const isDraggingOver = ref(false)
// dragover/dragenter 中校验 hasComponentData / hasFileData,
// drop 时通过 editor.screenToCanvas() 换算坐标,
// 组件走 createInstanceFromComponent(),文件走 editor.placeFiles()
return { isDraggingOver }
}
关键细节:坐标换算是 editor.screenToCanvas(e.clientX - rect.left, e.clientY - rect.top);组件实例拖放会调用 findMoveDropTarget 寻找目标父容器,并以组件宽高的一半做居中偏移;文件导入失败会打印错误而不中断。返回值 isDraggingOver 可用于驱动拖放高亮样式。配套的剪贴板工具是 extractImageFilesFromClipboard,相关输入管线见 useCanvasInput。
useToolbar / useToolbarState:工具栏的两种使用姿势
useToolbar()返回最近的ToolbarRoot注入的上下文,供子孙组件读取工具列表、当前工具与切换动作。上下文结构定义于 packages/vue/src/primitives/Toolbar/context.ts:editor、tools、activeTool、flyoutSelections、expandedFlyout、setTool、toggleFlyout、closeFlyout。在ToolbarRoot之外调用会抛出错误。useToolbarState()则是「不需要ToolbarRoot外壳」时的替代品,它只提供工具栏状态逻辑:mobileCategory、slideDirection、hasPrev/hasNext、goPrev/goNext(移动端按 3 个类别分页,CATEGORY_COUNT = 3),以及isActive(tool, activeTool)与activeKeyForTool(...)两个判定函数,后者正确处理 flyout 子工具(见 packages/vue/src/primitives/Toolbar/useToolbarState.ts)。官方文档明确此组合式函数是「面向呈现」的,与useToolbar互补。
组件定义参考 ToolbarRoot、ToolbarItem。
useViewportKind:极简的响应式视口分类
useViewportKind() 返回 OpenPencil 响应式 UI 使用的简化视口分类,只需区分 Mobile 与 Desktop 时不必直接配置 useBreakpoints()。官方文档给出了直接可用的示例:
import { useViewportKind } from '@open-pencil/vue'
const { isMobile, isDesktop } = useViewportKind()
实现位于 packages/vue/src/editor/viewport-kind/use.ts:基于 @vueuse/core 的 useBreakpoints,以 mobile: 768 为断点——视口宽度小于 768px 时 isMobile 为真,isDesktop 为其补集。与 useCanvas 搭配可构建自适应编辑器外壳。
属性与颜色:混合值、拖拽预览与色彩模型
本组 API 面向属性面板类界面,覆盖「多选混合值检测、批量更新、拖拽修改、渐变与色彩变量绑定」等高频需求,对应官方文档「Propiedades y color」分组。
useNodeProps:属性面板的公共地基
useNodeProps() 是 useAppearance、useLayout、useTypography 三个高层组合式函数(见 useAppearance、useLayout、useTypography)的公共基础。官方文档列出四类典型场景:检测混合值、在多个对象上更新属性、编辑数组元素、分离预览与保存(支持撤销)。实现见 packages/vue/src/controls/node-props/use.ts:
export function useNodeProps() {
const store = useEditor()
const { node, nodes, isMulti, active, activeNode, prop, merged, updateAllWithUndo } =
createNodePropSelectionState(store)
const { targetNodes, updateArrayItem, removeArrayItem, toggleArrayVisibility } =
createNodePropArrayActions({ store, nodes, activeNode, isMulti })
const { updateProp, commitProp } = createNodePropScrubActions(store)
return { store, node, nodes, isMulti, active, activeNode, targetNodes,
prop, merged, updateAllWithUndo, updateArrayItem, removeArrayItem,
toggleArrayVisibility, isArrayMixed, updateProp, commitProp }
}
几个值得注意的语义:
- 混合值:当多个选中节点的某属性不一致时,返回
MIXED哨兵值(export { MIXED }),并有配套的isArrayMixed(key)检测数组属性是否混合; - 批量更新:
updateAllWithUndo在多选场景下以“带撤销”的方式统一提交; - 数组编辑:
updateArrayItem/removeArrayItem/toggleArrayVisibility面向 fills、strokes、effects 等数组型属性; - 预览与提交分离:
updateProp用于拖拽过程中的实时预览,commitProp在交互结束时写入历史记录。
usePropScrub:数值属性的拖拽预览与历史提交
usePropScrub(editor) 专门服务“拖拽修改数值属性”的控件:拖拽期间持续预览新值,松手时把最终值写入历史。实现见 packages/vue/src/controls/prop-scrub/use.ts:内部基于 useNodePreview(editor),updateProp(nodes, key, value) 以 Change ${key} 为操作名调用 preview.update(...),commitProp 调 preview.commit(),另有 cancelProp 放弃本次预览。与 useNodeProps 的 updateProp/commitProp 一脉相承。
usePropertyList:属性列表上下文(fills/strokes/effects)
usePropertyList() 返回最近的 PropertyListRoot 上下文,供子孙组件读取列表项、混合状态,并对填充、描边、效果执行动作。实现见 packages/vue/src/primitives/PropertyList/context.ts:usePropertyList() 在 Root 之外调用会抛错;另有 usePropertyListPart(propKey) 变体,会校验 propKey 与 PropertyListRoot 是否一致,不一致即报错,用于保证部件不会错配。相关组件见 PropertyListRoot、PropertyListItem。
useColorVariableBinding:为填充/描边绑定色彩变量
useColorVariableBinding(kind)(kind 取 'fills' | 'strokes')提供在填充或描边上查询、设置、删除色彩变量绑定所需的函数。实现见 packages/vue/src/controls/color-variable-binding/use.ts:底层复用 useVariableBinding,绑定路径形如 fills/{index}/color 或 strokes/{index}/color;bindVariable(nodeId, index, variableId)、unbindVariable(nodeId, index)、createAndBindVariable(nodeId, index, color, name?) 可用——后者在不存在 COLOR 类型变量集合时会自动创建一个名为 Colors、含单个默认 Mode 的集合,再生成 var:{randomHex(8)} 变量并绑定。适合接入 useFillControls 与 useStrokeControls 所驱动的变量感知颜色控件。
useGradientStops:渐变编辑器状态与动作
useGradientStops(fill, onUpdate) 托管渐变编辑器的全部核心状态:活动色标索引、渐变子类型(线性/径向/角向/菱形)、色标拖拽,以及位置、颜色、透明度变更。实现见 packages/vue/src/primitives/GradientEditor/useGradientStops.ts,值得注意的细节:
- 四种子类型
GRADIENT_LINEAR / GRADIENT_RADIAL / GRADIENT_ANGULAR / GRADIENT_DIAMOND,切换时会写入对应的默认GradientTransform(DEFAULT_TRANSFORMS); addStop()默认在两个相邻色标中点插入新色标(不足两个色标时取 0.5)并自动排序;removeStop()保证至少保留两个色标;updateStopPosition将位置限制在[0, 1],updateStopOpacity限制在[0, 1];barBackground直接产出 CSS 渐变字符串,用于渲染渐变条预览背景。
配套组件见 GradientEditorRoot、GradientEditorBar、GradientEditorStop。
useOkHCL:RGBA 与感知均匀色彩模型 OkHCL 的切换
useOkHCL() 读取并修改填充与描边的色彩模型,可启用/停用 OkHCL 并更新其各通道值,适合实现同时支持 RGBA 与感知均匀色彩模型 OkHCL 的高级取色器。实现见 packages/vue/src/controls/okhcl/use.ts,返回值包括:getFillOkHCLColor / getStrokeOkHCLColor(读取)、updateFillOkHCL / updateStrokeOkHCL(更新)、getFillPreviewInfo / getStrokePreviewInfo(预览信息)、setFillFieldFormat / setStrokeFieldFormat / getFieldFormat(按通道维护字段格式)、以及 fieldOptions(OKHCL_FIELD_OPTIONS 通道选项)。常与 useFillControls、useStrokeControls 及 ColorPickerRoot 配合。
导航与编辑:图层树、行拖拽、内联重命名与字体状态
本组 API 对应官方文档「Navegación y edición」分组,服务图层树、页面列表、字体选择器与场景派生状态等界面。
useLayerTree:图层树上下文
useLayerTree() 返回最近的 LayerTreeRoot 注入的上下文。其类型定义在 packages/vue/src/primitives/LayerTree/context.ts 中非常完整:items(树节点)、expanded(展开分支)、visibleRows(虚拟化行)、treeVersion、selectedIds、focused、indentPerLevel、draggingId / instruction / instructionTargetId(拖拽状态),以及 setupDrag、select、toggleExpand、toggleVisibility、toggleLock、rename、setVirtualizer(接虚拟滚动)等动作。在 Root 之外调用会抛错。组件定义见 LayerTreeRoot 与 LayerTreeItem。
useLayerDrag:图层行的重排与跨容器移动
useLayerDrag(options) 为图层树行提供拖拽状态与动作:计算落点目标、确定「之前/之内/之后」位置、校验变更合法性并更新层级;当对象跨容器移动时保持其视觉位置。实现位于 packages/vue/src/primitives/LayerTree/useLayerDrag.ts,底层使用 @atlaskit/pragmatic-drag-and-drop 的 draggable / dropTargetForElements / monitorForElements 与 tree-item 命中盒扩展 attachInstruction / extractInstruction:
indentPerLevel默认 16px,决定子层级缩进命中盒;- 指令类型为
reorder-above/reorder-below/make-child(见LayerDragInstruction类型); - 容器节点
block: ['reparent'],非容器节点block: ['make-child', 'reparent'],即禁止把节点作为自身/容器的子级等非法操作; canDrop拒绝拖到自身。
通过 setupItem(el, item) 把每个行元素接入拖拽管线,并在 onMakeChildDrop 回调中处理“变为子级”的额外逻辑。
useInlineRename:内联重命名的状态与键盘交互
useInlineRename(onCommit) 管理内联编辑所需的全部细节:编辑状态、聚焦、点击外部失焦、确认提交与 Escape 取消。实现见 packages/vue/src/editor/inline-rename/use.ts:
start(id, currentName)进入编辑并记录原名;focusInput在nextTick后聚焦并全选文本,同时通过onClickOutside绑定“点击外部即 blur”行为;commit(id, eventOrInput)支持直接传入 input 元素或事件对象,取value.trim(),非空且不同于原名才回调onCommit;onKeydown中Enter触发 blur(随后 commit),Escape直接取消;- 每次进入/退出编辑都会清理外部点击监听,避免内存泄漏。
官方文档明确其适用于页面列表(PageListRoot)、图层树(LayerTreeItem)等不通过对话框改名的界面。
useFontPicker:自建字体选择器的搜索与选择状态
useFontPicker(options) 管理字体族、搜索词、打开状态与当前族,当内置的 FontPickerRoot 不够用、需要完全自建选择器 UI 时使用。选项定义于 packages/vue/src/primitives/FontPicker/useFontPicker.ts:modelValue(可写的当前字体族模型)、listFamilies(异步字体族源)、localFontAccess(宿主提供的本地字体权限控制器)、onSelect(选中回调)。实现要点:
- 返回
families、searchTerm、open、filtered、loading、accessState、requestAccess、select; - 字体访问状态
FontAccessState为'unsupported' | 'prompt' | 'granted' | 'denied',打开面板时若为prompt会先申请权限再加载字体; - 过滤基于 reka-ui 的
useFilter({ sensitivity: 'base' }),大小写不敏感; - 使用
requestVersion令牌 +useRetainedActivity防止异步竞态:切换路由或组件销毁时取消过期加载; listFamilies可返回string[]或FontFamilyOption[],前者会被归一化为{ family, source: 'local' }。
字体族类型 FontFamilyOption / FontFamilySource 来自 @open-pencil/core/text。相关高层入口见 FontPickerRoot 与 useTypography。
useNodeFontStatus:缺失字体检测
useNodeFontStatus(node) 接收一个“返回文本节点的 getter”,检查该文本对象引用的字体,返回尚未加载的字体族与样式信息。实现见 packages/vue/src/shared/font-status/use.ts:仅处理 type === 'TEXT' 的节点;收集 n.fontFamily(缺省回退 DEFAULT_FONT_FAMILY)以及 n.styleRuns 中各样式段的 style.fontFamily;再通过 fontManager.isLoaded(f) 过滤出未加载族,返回 missingFonts 与 hasMissingFonts。适合在排版面板与“缺失字体”警告中使用,相关组件见 TypographyControlsRoot。
useSceneComputed:场景数据驱动的响应式派生值
useSceneComputed(fn) 是 Vue computed 的轻量包装,用于把“依赖于编辑器场景图数据”的派生值显式标记出来。实现见 packages/vue/src/internal/scene-computed/use.ts:
export function useSceneComputed<T>(fn: () => T): ComputedRef<T> {
const editor = useEditor()
return computed(() => {
void editor.state.sceneVersion
void editor.state.selectedIds
void editor.state.currentPageId
return fn()
})
}
它主动读取 sceneVersion、selectedIds、currentPageId 三个响应式信号,使依赖文档对象派生的计算结果在场景变更、选区变化、页面切换时自动失效重算。useVariables 中的 collections、variables 以及选择状态系列(useSelectionState、useSelectionCapabilities)都基于它构建。
变量与区域设置:变量编辑器与 i18n 底层
本组 API 对应官方文档「Variables y configuración regional」分组,既有变量编辑器的低层状态与动作,也有 SDK 区域设置的完整说明。
useVariables:变量编辑器的低层状态与 CRUD
useVariables() 提供变量编辑器的低层状态与动作,可在不借助现成表格或对话框的情况下直接控制集合、活动模式、过滤器以及创建、读取、更新、删除操作。官方文档列出返回的关键值:collections、activeCollection、activeModes、variables、searchTerm。实现见 packages/vue/src/variables/use.ts:
collections通过useSceneComputed(() => editor.getCollections())派生;activeCollectionId默认取首个集合,集合列表变化时自动回退;variables按activeCollectionId过滤,且支持searchTerm的名称小写匹配;- 集合动作(来自 packages/vue/src/variables/helpers.ts):
setActiveCollection、addCollection、renameCollection、removeCollection、addMode、removeMode、renameMode、setDefaultMode、duplicateMode、setActiveMode; - 值动作(
createVariableValueActions):支持COLOR/FLOAT/BOOLEAN/ 文本四类变量,addVariable(type)会为新变量生成var:{randomHex(8)}ID,并按类型提供默认值(颜色为BLACK、浮点为0、布尔为false、文本为空串)与默认名(New color/New number/New boolean/New text)。
高层入口见 useVariablesEditor,对话框与表格状态分别见下文两节。
useVariablesDialogState:集合/模式重命名的对话框状态
useVariablesDialogState() 在 useVariables() 之上叠加“重命名集合/模式 + 焦点管理”的状态,适合不需要 useVariablesEditor() 完整集成的自定义对话框。实现见 packages/vue/src/variables/dialog/use.ts:内部复用 useInlineRename 分别构建 collectionRename(提交调用 renameCollection)与 modeRename(提交调用 renameMode),并暴露 startRenameCollection(id)、startRenameMode(modeId) 两个启动入口,其余返回内容与 useVariables() 合并展开。
useVariablesTable:为变量编辑器提供 TanStack Table 列定义
useVariablesTable(options) 返回变量表格的响应式列定义(基于 @tanstack/vue-table 的 ColumnDef),适用于“行为由 SDK 提供、表格/图标/组件由应用自备”的场景;官方文档也指出,大多数情况下 useVariablesEditor 是更简单的入口。选项定义于 packages/vue/src/variables/table/helpers.ts:activeModes(模式列来源)、formatModeValue / parseVariableValue(值格式化与解析回写)、shortName、renameVariable、updateVariableValue、removeVariable,以及 ColorInput、icons、fallbackIcon、deleteIcon 组件插槽。实现中“Name”列使用 reka-ui 的 EditableRoot/EditablePreview/EditableInput 支持行内改名,每个活动模式各生成一列(id: mode-${modeId}),COLOR 类型单元格渲染 ColorInput 组件。包装组合式函数见 packages/vue/src/variables/table/use.ts。
API regionales:区域设置、消息覆盖与 t() 翻译
区域 API 允许选择 SDK 语言并覆盖个别消息,官方文档归纳为四点:
locale—— 应用偏好与回退逻辑处理后的“有效区域设置”;messages—— 已解析的消息目录;t(key, params?)—— 按 key 翻译;- 应用配置可提供自己的部分目录(partial catalogs)覆盖默认文案。
一个关键约定:key 标识符与配置名称始终保留英文,因为它们是 API 的一部分。实现层面见 packages/vue/src/i18n/locale.ts:
- 可用区域
AVAILABLE_LOCALES = ['en', 'de', 'es', 'fr', 'it', 'ja', 'pl', 'ru', 'zh-CN'],英文为基语言,其余 8 种为翻译语言; resolveBrowserLocale(languages)先做精确匹配(如es-ES匹配es),再回退到基础语言(split('-')[0]),最后回退en;setLocale(code)写入localeSetting原子(nanostores)并持久化到localStorage(key 为open-pencil-locale),启动时优先读取已保存值;- packages/vue/src/i18n/create.ts 中
createI18n以'en'为baseLocale,通过懒加载#vue/i18n/locales/{de|es|fr|it|ja|pl|ru|zh-cn}拉取翻译目录; - packages/vue/src/i18n/index.ts 统一导出
locale、localeSetting、setLocale、AVAILABLE_LOCALES、TRANSLATED_LOCALES、LOCALE_LABELS等,并导出按命名空间划分的useI18n*系列(useCommonMessages、useFontMessages、useVariableMessages等)。
应用内最常用的高层入口是 useI18n。
剪贴板:从粘贴事件提取图片文件
extractImageFilesFromClipboard(event) 从 ClipboardEvent 中提取图片文件,丢弃不支持的 File 类型。实现见 packages/vue/src/canvas/drop/use.ts:
export function extractImageFilesFromClipboard(e: ClipboardEvent): File[] {
const files = e.clipboardData?.files
return files ? Array.from(files).filter((file) => RASTER_IMAGE_TYPES.has(file.type)) : []
}
它复用了画布拖放模块的 RASTER_IMAGE_TYPES 白名单(png / jpeg / webp / gif / avif),与 useCanvasDrop 共用同一套受支持类型语义,是“图片粘贴”功能的标准实现入口;配合 useCanvasDrop 与 useCanvas 可实现「粘贴即插入画布」。注意它只负责提取,后续的坐标换算与插入仍需调用编辑器 API。
选型指南:何时使用高级 API
参考 API 参考总览 的三分法,可按下述原则决策:
| 需求 | 首选 | 何时转向 Advanced API |
|---|---|---|
| 标准控件外壳(画布、工具栏、图层树、渐变条、字体选择器) | Components(CanvasRoot、ToolbarRoot、LayerTreeRoot 等) |
需要完全自定义视觉与交互,且需要直接读上下文时用 useCanvasContext、useToolbar、useLayerTree、usePropertyList |
| 编辑器/选区/命令的状态与动作 | Composables(useEditor、useSelectionState、useEditorCommands 等) |
需要混合值检测、批量属性更新、拖拽预览提交时用 useNodeProps、usePropScrub |
| 表格、对话框等整块功能 | 高层组合式函数(useVariablesEditor 等) |
行为复用 SDK、UI 自备时用 useVariables、useVariablesDialogState、useVariablesTable |
| 拾色器、字体选择器等复合控件 | 内置组件 | 需要 RGBA/OkHCL 双模型、缺失字体警告、自建搜索选择器时用 useOkHCL、useNodeFontStatus、useFontPicker |
所有需要注入上下文的 API(useCanvasContext、useToolbar、useLayerTree、usePropertyList)都有“在对应 Root 之外调用即抛错”的约束,而依赖编辑器的 API 则要求先在组件树顶部调用 provideEditor()(实现见 packages/vue/src/editor/context/index.ts,会以 Symbol('open-pencil-editor') 注入并在缺失时抛错)。搭建最小编辑器外壳的完整流程见 Vue SDK 快速上手,其中 bun add @open-pencil/core @open-pencil/vue canvaskit-wasm 安装、createEditor({ width, height }) 创建引擎、provideEditor + useCanvas 连接画布的步骤均适用于本组 API 的落地使用。
总结
OpenPencil 的高级 API 是连接「无样式组件」与「高层组合式函数」之间的粘合层:useCanvasContext、useToolbar、useLayerTree、usePropertyList 提供上下文访问,useNodeProps、usePropScrub、useGradientStops、useOkHCL、useColorVariableBinding 承载属性面板的核心逻辑,useLayerDrag、useInlineRename、useFontPicker、useNodeFontStatus 覆盖树与文本编辑,useVariables* 系列与区域 API 支撑变量体系与国际化,useCanvasDrop 与 extractImageFilesFromClipboard 打通拖放与粘贴导入。它们均以 inject/provide 与响应式派生为基石,并在源码层面保持“上下文缺失即报错、异步竞态可取消、写操作可撤销”的一致约定。对于需要构建自定义编辑器外壳的开发者,这组 API 就是直接可用的底层工具箱——既可在 API 参考 中按需查阅每个条目的完整签名,也可深入 packages/vue/src 对应目录研读实现细节。