OpenPencil 高级 API 全解析:用 @open-pencil/vue 底层组合式函数构建自定义编辑界面

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

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 按 架构文档 分为三层:

  1. @open-pencil/core —— 与框架无关的编辑器引擎(场景图、命令、渲染);
  2. @open-pencil/vue —— 为 Vue 提供的组合式函数(composables)与无样式组件;
  3. 应用层 —— 样式、路由、文件管理与产品化 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 对应目录研读实现细节。

登录后查看全文
open-pencil