企业官网建设流程全解析

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

toolCursor(tool, override?)是@open-pencil/vue包对外暴露的一个轻量级辅助函数，负责把编辑器的活动工具（Tool）映射为对应的 CSS 光标字符串，同时保留调用方显式覆盖的能力。当你需要搭建自定义画布外壳（canvas shell）或自定义工具栏 UI 时，用它能让光标行为与 OpenPencil 内置编辑器保持一致。读完本文，你将掌握toolCursor的完整签名、内置工具-光标映射表、override覆盖机制、源码实现原理，以及如何在自建编辑界面中正确接入它。

toolCursor 是什么

在 OpenPencil 的 SDK 中，toolCursor属于 Advanced API 层级：这类 API 是公开的，但比主组件和主组合式函数（composable）表面更底层、更专用。它解决的是一个非常具体的问题——让画布上的鼠标指针随当前工具自动变化。

官方英文文档对其定位的表述是：

toolCursor(tool, override?)maps an editor tool to the cursor the SDK should use, while still allowing an explicit override. Use it when building custom canvas shells or tool UIs that need consistent cursor behavior.

也就是说，它承担两件事：

1. 解析：把一个编辑器工具解析成 SDK 认为应该使用的光标字符串；
2. 覆盖：允许调用方传入显式的光标值来替换解析结果。

从源码结构看，它是 Editor-shell utilities（编辑器外壳工具集）的一员，与useLayerDrag、useInlineRename、useCanvasDrop、useViewportKind等并列，专为那些"自己拼装编辑器外壳"的二次开发场景服务。

函数签名与参数说明

toolCursor的 TypeScript 签名如下（取自 packages/vue/src/editor/tool-cursor/index.ts）：

export function toolCursor(tool: Tool, override?: string | null): string

返回值是合法的 CSScursor值（如'default'、'crosshair'、'text'、'grab'），可直接用于元素的cursor样式。

需要注意override的判断是基于真值的：源码中if (override) return override，因此空字符串''也会被视为"无覆盖"而走默认映射逻辑。如果希望"清除覆盖并回落到工具映射"，传入null即可。

Tool 类型：支持的全部工具

toolCursor的第一个参数tool来自@open-pencil/core的编辑器类型定义。完整联合类型定义于 packages/core/src/editor/types.ts：

export type Tool = | 'SELECT' | 'FRAME' | 'SECTION' | 'RECTANGLE' | 'ELLIPSE' | 'LINE' | 'POLYGON' | 'STAR' | 'TEXT' | 'PEN' | 'HAND'

这 11 个工具基本覆盖了一个设计编辑器的主要创建与导航工具：选择（SELECT）、画板与区块（FRAME/SECTION）、基础形状（RECTANGLE/ELLIPSE/LINE/POLYGON/STAR）、文本（TEXT）、钢笔路径（PEN）以及抓手平移（HAND）。

在同仓库的Toolbar组件实现中，活动工具由编辑器共享状态store.state.activeTool提供（类型即上述Tool），因此toolCursor可以直接与编辑器的工具状态无缝对接。

内置工具-光标映射表

toolCursor的解析逻辑非常直白：它内部维护了一张Record<Tool, string>映射表，然后在没有override时按工具名查找。完整映射来自 packages/vue/src/editor/tool-cursor/index.ts：

const TOOL_CURSORS: Record<Tool, string> = { SELECT: 'default', FRAME: 'crosshair', SECTION: 'crosshair', RECTANGLE: 'crosshair', ELLIPSE: 'crosshair', LINE: 'crosshair', POLYGON: 'crosshair', STAR: 'crosshair', TEXT: 'text', PEN: 'crosshair', HAND: 'grab' }

这套映射遵循设计工具的通感习惯：所有"创建形状"类工具统一使用crosshair，文本用text，抓手用grab，选择用default。你不需要为每个工具单独写一份映射，SDK 已经替你收敛了这些约定。

override 机制与完整源码

toolCursor的全部实现只有几行，完整源码如下（packages/vue/src/editor/tool-cursor/index.ts）：

import type { Tool } from '@open-pencil/core/editor' const TOOL_CURSORS: Record<Tool, string> = { /* ...上表... */ } export function toolCursor(tool: Tool, override?: string | null): string { if (override) return override return TOOL_CURSORS[tool] ?? 'default' }

两个细节值得注意：

1. 优先级：override优先于工具映射。也就是说，覆盖是"最终决定权"——即使工具是TEXT，只要你传入override: 'crosshair'，返回的就是crosshair。
2. 兜底值：TOOL_CURSORS[tool] ?? 'default'表明，如果传入的tool不在映射表中（例如未来新增工具而映射未同步更新），函数会安全回落到'default'，保证 UI 永远不会出现cursor: undefined或空值导致的样式异常。这是一个值得借鉴的"防御式兜底"写法。

从类型角度，override允许string | null，而兜底逻辑保证返回的永远是合法的 CSS 光标字符串，因此可以放心把它直接绑定到样式上。

在自定义画布外壳中使用

toolCursor的正确使用场景是自己实现画布外壳或工具栏 UI，而不是直接使用 OpenPencil 现成的编辑界面。官方文档给出的核心建议是：

Use it when building custom canvas shells or tool UIs that need consistent cursor behavior.

也就是说，当你通过@open-pencil/vue的底层 API（如useCanvas）自建渲染画布，而不是直接嵌入内置编辑器组件时，用toolCursor统一光标行为。

基础用法示例

import { toolCursor } from '@open-pencil/vue' // 默认解析：SELECT 工具 -> 'default' const cursor = toolCursor('SELECT') // 'default' // 创建类工具 -> 'crosshair' const cursor2 = toolCursor('RECTANGLE') // 'crosshair' // 文本工具 -> 'text' const cursor3 = toolCursor('TEXT') // 'text' // 抓手 -> 'grab' const cursor4 = toolCursor('HAND') // 'grab' // 显式覆盖：无论工具是什么，都强制使用指定的光标 const cursor5 = toolCursor('SELECT', 'copy') // 'copy' // 传入 null 与不传等价：走工具映射 const cursor6 = toolCursor('HAND', null) // 'grab'

toolCursor在 packages/vue/src/index.ts 中作为公共导出提供，因此可以从@open-pencil/vue直接导入，无需深入到子路径：

import { toolCursor } from '@open-pencil/vue'

与 Vue 响应式状态结合

在 Vue 组件中，最自然的用法是把它包进一个computed，让光标随活动工具响应式变化。下面的模式与 OpenPencil 仓库自身的EditorCanvas.vue组件一致——先基于当前活动工具解析出光标，再绑定到画布元素的style.cursor：

<script setup lang="ts"> import { computed } from 'vue' import { toolCursor, useEditor } from '@open-pencil/vue' const editor = useEditor() // 假设你的 editor 暴露了 activeTool 响应式状态 const cursor = computed(() => toolCursor(editor.state.activeTool)) </script> <template> <canvas :style="{ cursor }" class="size-full touch-none" /> </template>

这样，用户切换工具时，光标会立即随之改变，与内置编辑器的体验保持一致。

仓库中的真实调用：EditorCanvas 的覆盖链路

toolCursor并非仅供外部二次开发使用——OpenPencil 自身的主编辑界面也直接依赖它。在 src/components/EditorCanvas.vue 中可以看到完整的生产级调用：

const cursor = computed(() => toolCursor(store.state.activeTool, issueMarkerCursor.value ?? cursorOverride.value) )

然后该cursor被绑定到画布容器的内层<canvas>元素上（src/components/EditorCanvas.vue）：

<canvas ref="canvasRef" :data-pane-id="paneId" >import { ref } from 'vue' import { useCanvas, useEditor } from '@open-pencil/vue' const canvasRef = ref<HTMLCanvasElement | null>(null) const editor = useEditor() useCanvas(canvasRef, editor, { showRulers: true, onReady: () => { console.log('Renderer ready') }, })

而useEditorCommands负责菜单/命令驱动 UI：

import { useEditorCommands } from '@open-pencil/vue' const { commands, menuItem, runCommand } = useEditorCommands() const editMenu = [ menuItem('edit.undo', '⌘Z'), menuItem('edit.redo', '⇧⌘Z'), { separator: true }, menuItem('selection.delete'), ]

一个典型的自建编辑界面工作流是：useEditorCommands提供命令与菜单模型 → 用户选择工具 → 编辑器状态中的activeTool更新 →toolCursor(activeTool, override?)解析出光标 → 绑定到useCanvas管理的画布元素上。

关键要点速览

• toolCursor(tool, override?)是@open-pencil/vue导出的底层辅助函数，返回合法的 CSS 光标字符串；
• 内置映射覆盖全部 11 种Tool：创建类工具统一为crosshair，TEXT为text，HAND为grab，SELECT为default；
• override具有最高优先级，null或不传时走工具映射，未知工具安全回落'default'；
• 生产级用法见 src/components/EditorCanvas.vue：以issueMarkerCursor ?? cursorOverride作为覆盖参数，将解析结果绑定到画布<canvas>的style.cursor；
• 适合与 useCanvas、useEditorCommands 组合，构建行为一致的自定义画布外壳与工具栏 UI。

如果只是接入 OpenPencil 内置编辑器组件，通常无需直接使用toolCursor；一旦你开始基于@open-pencil/vue自建画布外壳，它就是保证光标体验与内置编辑器完全一致的最简方案。

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