前端桌面應用AI 應用MCP 服務【免費下載鏈接】open-pencilAI-native design editor. Open-source Figma alternative.項目地址https://gitcode.com/gh_mirrors/op/open-pencil點擊查看免費下載導讀useCanvasInput是 OpenPencilAI-native 設計編輯器開源項目Vue SDK 中負責把canvas元素的指針與鼠標事件接入編輯器輸入系統(tǒng)的核心 composable。它把屏幕坐標換算成畫布坐標、統(tǒng)一調(diào)度選中、拖拽、縮放、旋轉(zhuǎn)、平移、繪圖工具與文本/矢量編輯等全部畫布交互是任何自建編輯器外殼editor shell接入畫布時必須掌握的低層 API。讀完本文你將理解useCanvasInput的完整簽名、各參數(shù)的職責、內(nèi)部交互狀態(tài)機DragState、坐標換算原理以及它在真實編輯器外殼中的調(diào)用方式能夠據(jù)此在自己構(gòu)建的 Vue 組件里正確接入 OpenPencil 畫布。本文基于倉庫中該 API 的官方文檔packages/docs/fr/programmable/sdk/api/composables/use-canvas-input.md并深入其實際源碼 packages/vue/src/canvas/useCanvasInput.ts 及配套輸入模塊展開。一、useCanvasInput 是什么根據(jù)官方文檔useCanvasInput(options)把目標元素通常是canvas的事件綁定到編輯器的輸入系統(tǒng)上覆蓋的能力清單包括指針的移動、按下與釋放mouvement, pression et relachement du pointeur選中與框選sélection et rectangle de sélection視圖平移與縮放déplacement de la vue et zoom對象拖拽glissement des objets縮放與旋轉(zhuǎn)redimensionnement et rotation形狀工具、鋼筆Plume、文本與抓手工具outils de formes, Plume, Texte et Main矢量編輯與文本編輯édition vectorielle et textuelle。文檔同時強調(diào)了兩個關鍵設計坐標換算該 composable 會把屏幕坐標轉(zhuǎn)換為畫布坐標并在一次交互的整個生命周期內(nèi)保持指針捕獲pointer capture定位這是一個低層bas niveauAPI主要面向“自己擁有畫布、希望構(gòu)建干凈界面”的編輯器外殼組件而非高層封裝。在 Vue SDK 中useCanvasInput與useCanvas負責 CanvasKit 渲染表面的創(chuàng)建與維護見 use-canvas.md和useTextEdit負責文本輸入見 use-text-edit.md三者通常搭配使用useCanvas管渲染useCanvasInput管交互useTextEdit管畫布內(nèi)文本編輯。它在 SDK 公開入口 packages/vue/src/index.ts 中被導出。二、函數(shù)簽名與參數(shù)說明雖然法語文檔以useCanvasInput(options)概括實際源碼 packages/vue/src/canvas/useCanvasInput.ts 中的簽名更為精確是理解其行為的權威依據(jù)export function useCanvasInput( canvasRef: RefHTMLCanvasElement | null, editor: Editor, hitTestSectionTitle: (cx: number, cy: number) SceneNode | null, hitTestComponentLabel: (cx: number, cy: number) SceneNode | null, hitTestFrameTitle: (cx: number, cy: number) SceneNode | null, onCursorMove?: (cx: number, cy: number) void, onActivate?: () void, isEnabled: () boolean () true )各參數(shù)含義如下參數(shù)類型說明canvasRefRefHTMLCanvasElement \| null目標畫布元素的引用所有事件都綁定在此元素上editorEditor來自open-pencil/core/editor的編輯器實例通常由createEditor創(chuàng)建、useEditor從上下文取回hitTestSectionTitle(cx, cy) SceneNode \| null命中測試給定畫布坐標返回命中的 Section 標題節(jié)點hitTestComponentLabel(cx, cy) SceneNode \| null命中測試返回命中的組件標簽節(jié)點hitTestFrameTitle(cx, cy) SceneNode \| null命中測試返回命中的 Frame 標題節(jié)點onCursorMove可選回調(diào)指針移動時回調(diào)參數(shù)為畫布坐標(cx, cy)可用于同步外部懸浮信息onActivate可選回調(diào)每次mousedown時觸發(fā)編輯器外殼用它做“激活面板”等處理isEnabled() boolean交互開關默認恒為true為false時忽略輸入多面板場景下用于區(qū)分當前活動面板返回對象包含供外殼組件消費的狀態(tài)與操作源碼 useCanvasInput.tsdrag當前拖拽狀態(tài)RefDragState | null用于驅(qū)動覆蓋層 UIcursorOverrideRefstring | null畫布上的光標覆蓋值畫布標簽Frame/Section 標題編輯canvasLabelEdit、updateCanvasLabelEdit、commitCanvasLabelEdit、cancelCanvasLabelEditAuto Layout 內(nèi)邊距編輯autoLayoutPaddingEdit、updateAutoLayoutPaddingEdit、commitAutoLayoutPaddingEdit、cancelAutoLayoutPaddingEditcleanupInteractions()取消進行中的交互、清空臨時反饋并復位修飾鍵狀態(tài)常用于面板失活或組件卸載時。注意法語文檔把參數(shù)概括為options對象德語版文檔則給出位置參數(shù)形式的調(diào)用示例見 packages/docs/de/programmable/sdk/api/composables/use-canvas-input.md源碼實現(xiàn)采用的是上面這組位置參數(shù)。三、坐標換算從屏幕坐標到畫布坐標文檔明確提及“composable 把屏幕坐標轉(zhuǎn)換成畫布坐標”。這一邏輯集中在 packages/vue/src/shared/input/geometry.ts 的getPointerCoords中export function getPointerCoords(e: MouseEvent, canvas: HTMLCanvasElement | null, editor: Editor) { if (!canvas) return { sx: 0, sy: 0, cx: 0, cy: 0 } const rect canvas.getBoundingClientRect() const sx e.clientX - rect.left const sy e.clientY - rect.top const { x: cx, y: cy } editor.screenToCanvas(sx, sy) return { sx, sy, cx, cy } }換算分兩步客戶端坐標 → 畫布像素坐標用getBoundingClientRect()減去畫布左上角得到sx/sy畫布像素坐標 → 畫布邏輯坐標通過editor.screenToCanvas(sx, sy)得到cx/cy。screenToCanvas內(nèi)部會考慮編輯器的平移pan與縮放zoom因此useCanvasInput處理的永遠是邏輯坐標縮放平移無需你手工處理。此外packages/vue/src/canvas/pointer/use.ts 的createCanvasPointer在換算基礎上又封裝了三類能力canvasToLocal畫布坐標 → 某個節(jié)點局部坐標供進入容器內(nèi)部后的命中測試使用、hitTestInScope在當前“進入的容器”或當前頁范圍內(nèi)做命中測試支持深/淺兩種模式、isInsideContainerBounds判斷某點是否落在容器邊界內(nèi)。這三者與三個標題命中測試函數(shù)一起組成了hitFns供拖拽調(diào)度與光標更新共用。四、統(tǒng)一拖拽狀態(tài)機DragStateuseCanvasInput的核心是一個dragref所有進行中的交互都歸約為統(tǒng)一的拖拽狀態(tài)聯(lián)合類型DragState定義于 packages/vue/src/shared/input/types.tsexport type DragState | DragDraw // 繪圖工具拖拽矩形、橢圓、線條…… | DragMove // 移動選中對象 | DragPan // 抓手/空格平移視圖 | DragResize // 縮放 | DragMarquee // 框選 | DragRotate // 旋轉(zhuǎn) | DragPen // 鋼筆路徑繪制 | DragTextSelect // 文本選區(qū) | DragEditNode // 矢量節(jié)點編輯 | DragEditHandle // 貝塞爾手柄編輯 | DragBendHandle // 彎曲手柄編輯 | DragGuide // 標尺/參考線拖拽以DragMove為例types.ts它記錄起點、當前位置、已應用的位移增量appliedDx/appliedDy、是否已判定為拖拽dragStarted、所有對象的原始位置以及duplicated拖拽時按住修飾鍵復制、autoLayoutParentId、brokeFromAutoLayout等自動布局相關信息。DragResizetypes.ts則保存origRect、原矢量網(wǎng)絡、填充/描邊幾何、派生文本字形等快照保證縮放預覽可隨時回滾。onMouseMoveuseCanvasInput.ts是一個集中的分發(fā)器根據(jù)drag.value.type把移動事件分別交給handlePanMove、guideInput.handleMove、handleRotateMove、handleMoveMove、applyResize、handlePenDragMove、handleNodeEditMove、handleBendHandleMove、handleDrawMove、handleMarqueeMove等實現(xiàn)。無拖拽時它仍會驅(qū)動鋼筆懸浮updatePenHover、矢量節(jié)點懸浮updateNodeEditHover、參考線懸浮與光標更新保證“僅懸停不拖拽”的場景也有即時反饋。onMouseUpuseCanvasInput.ts按類型提交結(jié)果commitResizePreview提交縮放、editor.penCommit(true)提交鋼筆路徑、editor.commitRotation提交旋轉(zhuǎn)、draw.commit()提交繪圖、setMarquee(null)結(jié)束框選。這樣所有交互都遵循“開始 → 預覽 → 提交/取消”的同一生命周期。五、指針捕獲與事件綁定文檔強調(diào)“在交互期間保持指針捕獲”。這一實現(xiàn)位于 useCanvasInput.tsfunction onPointerDown(e: PointerEvent) { if (e.pointerType ! mouse || e.button ! 0) return canvasRef.value?.setPointerCapture(e.pointerId) }pointerdown時若為鼠標主鍵立即調(diào)用setPointerCapture保證即使指針移出畫布后續(xù)的mousemove/mouseup仍派發(fā)到畫布拖拽不中斷pointerup/pointercancel時釋放捕獲并分別走“提交”與“取消”路徑。事件綁定通過useEventListener完成useCanvasInput.ts包括畫布上的pointerdown/pointerup/pointercancel/dblclick/mousedown/mousemove/mouseup/mouseleave以及 window 級的keydown/keyup追蹤 Alt/Meta/Ctrl 修飾鍵、blur失焦時復位測量修飾鍵并取消交互、捕獲階段的mouseup防止指針離開畫布后拖拽卡死和捕獲階段的Escape取消繪圖/旋轉(zhuǎn)。另外它還訂閱了編輯器的若干事件useCanvasInput.tsrotation:preview-changed、tool:changed、selection:changed、page:changed、graph:replaced。當工具切換、選區(qū)變化或頁面/圖被替換時進行中的繪圖與旋轉(zhuǎn)交互會被自動取消避免狀態(tài)錯亂組件卸載時onScopeDispose會統(tǒng)一停止監(jiān)聽并調(diào)用cancelPointerInteraction。六、工具聯(lián)動與修飾鍵語義onMouseDownuseCanvasInput.ts是交互入口先觸發(fā)onActivate再依據(jù)isEnabled判斷是否處理隨后提交可能存在的 Auto Layout 內(nèi)邊距編輯、聚焦畫布、清空懸浮節(jié)點并在參考線拖拽標尺拖出/已有參考線之后把事件交給handleToolMouseDown統(tǒng)一派發(fā)。工具與節(jié)點類型的映射TOOL_TO_NODEtypes.ts說明繪圖工具FRAME/SECTION/RECTANGLE/ELLIPSE/LINE/POLYGON/STAR/TEXT會創(chuàng)建對應類型的節(jié)點。修飾鍵在交互中有明確語義由updateModifier跟蹤useCanvasInput.ts并在移動/釋放分支中生效Shift縮放保持寬高比、旋轉(zhuǎn)按角度約束、鋼筆切線約束Alt測量模式開關配合畫布內(nèi)測量、參考線復制拖拽、節(jié)點編輯分支調(diào)整Meta/Ctrl測量模式升級為“deep”、拖拽復制、節(jié)點編輯分支的精確控制空格臨時切換到抓手平移setupPanZoom與useSpaceHeld配合實現(xiàn)。值得留意的是測量模式measurementcanMeasureuseCanvasInput.ts要求指針在畫布內(nèi)、無拖拽、處于 SELECT 工具且有選中對象、且不在文本/節(jié)點/鋼筆編輯狀態(tài)此時按住 Alt 會以shallow/deep兩種深度調(diào)用editor.setMeasurementMode驅(qū)動畫布內(nèi)測量反饋與光標覆蓋。七、真實用法EditorCanvas 外殼組件該 API 的實際調(diào)用者正是主應用中的 src/components/EditorCanvas.vue。其調(diào)用方式EditorCanvas.vue是理解各參數(shù)實戰(zhàn)含義的最佳示例const { cursorOverride, canvasLabelEdit, updateCanvasLabelEdit, commitCanvasLabelEdit, cancelCanvasLabelEdit, autoLayoutPaddingEdit, updateAutoLayoutPaddingEdit, commitAutoLayoutPaddingEdit, cancelAutoLayoutPaddingEdit, cleanupInteractions } useCanvasInput( canvasRef, store, hitTestSectionTitle, hitTestComponentLabel, hitTestFrameTitle, updatePaneCursor, activatePane, () isActivePane.value )要點三個命中測試函數(shù)hitTestSectionTitle等來自編輯器外殼自身的場景查詢邏輯把“哪里是 Section 標題”這類自定義判定交給調(diào)用方updatePaneCursor作為onCursorMove把指針畫布坐標同步給面板層activatePane作為onActivate保證點擊畫布時面板被激活isEnabled返回() isActivePane.value實現(xiàn)多面板多畫布共存時只有活動面板響應輸入外殼在面板失活watch(isActivePane)與組件卸載onUnmounted時調(diào)用cleanupInteractions()EditorCanvas.vue與useTextEdit(canvasRef, store, { isEnabled: () isActivePane.value })和useCanvasDrop一起構(gòu)成完整畫布外殼。返回的cursorOverride、autoLayoutPaddingEdit等還驅(qū)動著覆蓋層例如內(nèi)邊距編輯器的錨點坐標由paddingEditorAnchor計算EditorCanvas.vue再通過useCanvasVirtualReference定位浮層實現(xiàn)拖拽內(nèi)邊距時實時顯示數(shù)值編輯器的效果。八、相關 API 與進一步閱讀useCanvasInput通常與以下 API 配套使用useCanvas負責 CanvasKit 加載、surface 創(chuàng)建/重建、尺寸觀察、像素比調(diào)整與刷新請求是渲染側(cè)的對偶 composableuseTextEdit負責 textarea 回退的文本輸入、IME 組合、光標閃爍與樣式快捷鍵與useCanvasInput的文本編輯入口互補useEditor/provideEditor從 Vue 注入上下文取得Editor實例導出于 packages/vue/src/index.ts。若需更完整的接入方式可參考 EditorCanvas.vue 與 SDK 文檔目錄 packages/docs/fr/programmable/sdk底層坐標換算與命中測試實現(xiàn)在 packages/vue/src/shared/input/geometry.ts 與 packages/vue/src/canvas/pointer/use.ts。官方還提供了德語、西班牙語、意大利語、波蘭語等多語言版本的同主題文檔如 packages/docs/de/programmable/sdk/api/composables/use-canvas-input.md供交叉參考?？偨Y(jié)useCanvasInput是 OpenPencil Vue SDK 中畫布交互的總調(diào)度器它以統(tǒng)一的DragState狀態(tài)機覆蓋移動、縮放、旋轉(zhuǎn)、平移、框選、繪圖、鋼筆、參考線與矢量/文本編輯通過screenToCanvas完成坐標換算借助 Pointer Capture 與全局事件監(jiān)聽保證交互完整性并通過回調(diào)與isEnabled機制適配多面板編輯器外殼。結(jié)合 EditorCanvas.vue 的實戰(zhàn)用法你可以快速在自己的 Vue 組件中搭建出與 OpenPencil 主應用一致的畫布交互體驗。贊分享前端桌面應用AI 應用MCP 服務【免費下載鏈接】open-pencilAI-native design editor. Open-source Figma alternative.項目地址https://gitcode.com/gh_mirrors/op/open-pencil點擊查看免費下載相關推薦OpenPencil 的 useCanvasInput把指針事件接入編輯器畫布的 Vue ComposableOpenPencil 的 useCanvasInput把指針事件接入編輯器畫布的 Vue Composable 在 OpenPencil開源 AI 原生設計前端桌面應用AI 應用MCP 服務OpenPencil useCanvasInput 完全指南為 Vue 畫布組件接入選擇、拖拽、縮放與工具交互OpenPencil useCanvasInput 完全指南為 Vue 畫布組件接入選擇、拖拽、縮放與工具交互 useCanvasInput 是 OpenPe前端桌面應用AI 應用MCP 服務OpenPencil Vue SDK 的 useTextEdit 指南畫布文本編輯、IME 組合與 SceneGraph 同步全解析OpenPencil Vue SDK 的 useTextEdit 指南畫布文本編輯、IME 組合與 SceneGraph 同步全解析 useTextEdit前端桌面應用AI 應用MCP 服務上一篇Python模糊字符串匹配神器TheFuzz10分鐘快速入門指南下一篇Ruby爬蟲框架Wombat用優(yōu)雅DSL輕松提取結(jié)構(gòu)化數(shù)據(jù)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考