use-canvas-drag 0.1.0 → 0.2.1

package/README.md

@@ -1,37 +1,204 @@
-# use-canvas-drag
-
-Vue3 画布拖拽组合式函数，支持多种鼠标触发方式。
-
-## 安装
-
-\`\`\`bash
-npm install use-canvas-drag
-\`\`\`
-
-## 使用
-
-\`\`\`typescript
-import { useCanvasDrag } from 'use-canvas-drag'
-
-const { isPanning, handlers, stopPan } = useCanvasDrag({
-  container: '#canvas',
-  mode: 'right', // 可选: 'left' | 'right' | 'middle' | 'shift-left' | 'ctrl-left' | 'alt-left'
-})
-\`\`\`
-
-## API
-
-### useCanvasDrag(options)
-
-| 参数        | 类型                                      | 说明                   |
-| ----------- | ----------------------------------------- | ---------------------- |
-| container   | string\| HTMLElement \| () => HTMLElement | 画布容器               |
-| mode        | DragTrigger\| DragTrigger[]               | 触发方式，默认 'right' |
-| enabled     | boolean                                   | 是否启用，默认 true    |
-| onStartDrag | (e: MouseEvent) => void                   | 开始拖拽回调           |
-| onDrag      | ({x, y}) => void                          | 拖拽中回调             |
-| onEndDrag   | () => void                                | 结束拖拽回调           |
-
-## License
-
-MIT
+# use-canvas-drag
+
+![npm](https://img.shields.io/npm/v/use-canvas-drag)
+![npm](https://img.shields.io/npm/dw/use-canvas-drag)
+![GitHub](https://img.shields.io/github/license/liuruibo/use-canvas-drag)
+![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)
+
+Vue3 画布拖拽组合式函数，轻量、无依赖、TypeScript 支持，开箱即用。
+
+## 特性
+
+- 🌿 **轻量无依赖** - 仅 ~1KB，零外部依赖
+- 🔧 **多种触发方式** - 支持右键、中键、左键 + 组合键
+- 📦 **开箱即用** - 组合式函数设计，天然 Tree-Shakable
+- 🔰 **TypeScript** - 完整类型提示，IDE 友好
+- 🎯 **零外部依赖** - 不依赖任何 UI 框架
+
+## 安装
+
+```bash
+npm install use-canvas-drag
+# 或
+pnpm add use-canvas-drag
+# 或
+yarn add use-canvas-drag
+```
+
+## 快速开始
+
+```vue
+<template>
+  <div id="canvas" ref="canvasRef" class="canvas">
+    <div class="draggable-box" :style="{ left: x + 'px', top: y + 'px' }">
+      拖动我
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { useCanvasDrag } from 'use-canvas-drag'
+
+const canvasRef = ref(null)
+const x = ref(100)
+const y = ref(100)
+
+const { isPanning, stopPan } = useCanvasDrag({
+  container: canvasRef,
+  mode: 'right',
+  onDrag: ({ x: dx, y: dy }) => {
+    x.value += dx
+    y.value += dy
+  }
+})
+</script>
+
+<style scoped>
+.canvas {
+  width: 100%;
+  height: 500px;
+  border: 1px solid #ddd;
+  overflow: hidden;
+  position: relative;
+}
+.draggable-box {
+  position: absolute;
+  padding: 20px;
+  background: #4a90e2;
+  color: white;
+  cursor: grab;
+  user-select: none;
+}
+.draggable-box:active {
+  cursor: grabbing;
+}
+</style>
+```
+
+## 多按钮配置
+
+```typescript
+import { useCanvasDrag } from 'use-canvas-drag'
+
+const { handlers, stopPan } = useCanvasDrag({
+  container: '#canvas',
+  mode: ['right', 'middle'],  // 右键或中键触发
+  enabled: true,
+  onStartDrag: (e) => {
+    console.log('开始拖拽', e.clientX, e.clientY)
+  },
+  onDrag: ({ x, y, deltaX, deltaY }) => {
+    console.log(`移动了: ${deltaX}, ${deltaY}`)
+  },
+  onEndDrag: () => {
+    console.log('结束拖拽')
+  }
+})
+```
+
+## 画布平移
+
+```vue
+<template>
+  <div id="canvas" ref="canvasRef" class="canvas">
+    <div class="content" :style="{ transform: `translate(${offset.x}px, ${offset.y}px)` }">
+      <div class="item">Item 1</div>
+      <div class="item">Item 2</div>
+      <div class="item">Item 3</div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { reactive } from 'vue'
+import { useCanvasDrag } from 'use-canvas-drag'
+
+const canvasRef = ref(null)
+const offset = reactive({ x: 0, y: 0 })
+
+const { isPanning } = useCanvasDrag({
+  container: canvasRef,
+  mode: 'right',
+  onDrag: ({ deltaX, deltaY }) => {
+    offset.x += deltaX
+    offset.y += deltaY
+  }
+})
+</script>
+```
+
+## API
+
+### useCanvasDrag(options)
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `container` | `string \| HTMLElement \| () => HTMLElement` | ✅ | 画布容器，支持选择器、元素或返回元素的函数 |
+| `mode` | `'left' \| 'right' \| 'middle' \| 'shift-left' \| 'ctrl-left' \| 'alt-left' \| (Trigger)[]'` | ❌ | 触发方式，默认 `'right'` |
+| `enabled` | `boolean` | ❌ | 是否启用，默认 `true` |
+| `onStartDrag` | `(e: MouseEvent) => void` | ❌ | 开始拖拽时触发 |
+| `onDrag` | `(info: DragInfo) => void` | ❌ | 拖拽过程中触发 |
+| `onEndDrag` | `() => void` | ❌ | 结束拖拽时触发 |
+
+### DragInfo
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `x` | `number` | 相对于起始位置的 X 轴偏移 |
+| `y` | `number` | 相对于起始位置的 Y 轴偏移 |
+| `deltaX` | `number` | 相对于上一帧的 X 轴偏移 |
+| `deltaY` | `number` | 相对于上一帧的 Y 轴偏移 |
+
+### 返回值
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `isPanning` | `Ref<boolean>` | 是否正在平移 |
+| `handlers` | `object` | mousedown/mousemove/mouseup 事件处理器 |
+| `stopPan` | `() => void` | 手动停止平移 |
+| `setEnabled` | `(enabled: boolean) => void` | 动态启用/禁用 |
+
+### DragButtonConfig (类型导出)
+
+```typescript
+interface DragButtonConfig {
+  button: number;       // 鼠标按钮: 0=左键, 1=中键, 2=右键
+  ctrlKey?: boolean;    // 是否需要 Ctrl 键
+  shiftKey?: boolean;   // 是否需要 Shift 键
+  altKey?: boolean;     // 是否需要 Alt 键
+}
+```
+
+## 触发模式
+
+| 模式 | 说明 |
+|------|------|
+| `'left'` | 鼠标左键 |
+| `'right'` | 鼠标右键 |
+| `'middle'` | 鼠标中键（滚轮） |
+| `'shift-left'` | Shift + 左键 |
+| `'ctrl-left'` | Ctrl + 左键 |
+| `'alt-left'` | Alt + 左键 |
+
+## 常见问题
+
+### Q: 右键菜单被阻止了吗？
+
+A: 是的，插件会自动调用 `e.preventDefault()` 阻止默认右键菜单。
+
+### Q: 如何在拖拽时隐藏自定义鼠标指针？
+
+A: 通过 `isPanning` 控制：
+
+```vue
+<div :class="{ 'hide-cursor': isPanning }">...</div>
+```
+
+### Q: 支持多画布吗？
+
+A: 支持，只需创建多个实例即可。
+
+## License
+
+MIT

package/dist/index.esm.js

@@ -0,0 +1,81 @@
+import { computed as e, onUnmounted as t, ref as n, watch as r } from "vue";
+//#region src/useCanvasDrag.ts
+var i = ["right"], a = {
+	left: { button: 0 },
+	right: { button: 2 },
+	middle: { button: 1 },
+	"shift-left": {
+		button: 0,
+		modifiers: { shift: !0 }
+	},
+	"ctrl-left": {
+		button: 0,
+		modifiers: { ctrl: !0 }
+	},
+	"alt-left": {
+		button: 0,
+		modifiers: { alt: !0 }
+	}
+};
+function o(e) {
+	return e ? e.map((e) => typeof e == "string" ? a[e] ?? { button: -1 } : e) : i.map((e) => a[e]);
+}
+function s(i) {
+	let { container: a, enabled: s = !0, onStartDrag: c, onDrag: l, onEndDrag: u, mode: d } = i, f = n(!1), p = n({
+		x: 0,
+		y: 0,
+		scrollLeft: 0,
+		scrollTop: 0
+	}), m = e(() => o(Array.isArray(d) ? d : d ? [d] : void 0)), h = () => typeof a == "string" ? document.querySelector(a) : typeof a == "function" ? a() : a instanceof HTMLElement ? a : null, g = (e) => m.value.some((t) => {
+		if (t.button !== void 0 && t.button !== e.button) return !1;
+		if (t.modifiers) {
+			let n = t.modifiers;
+			if (n.shift && !e.shiftKey || n.ctrl && !e.ctrlKey || n.alt && !e.altKey || n.meta && !e.metaKey) return !1;
+		}
+		return !0;
+	}), _ = (e) => {
+		if (!s || !g(e)) return;
+		let t = h();
+		t && (p.value = {
+			x: e.clientX,
+			y: e.clientY,
+			scrollLeft: t.scrollLeft,
+			scrollTop: t.scrollTop
+		}, f.value = !0, t.style.cursor = "grabbing", t.style.userSelect = "none", e.preventDefault(), c?.(e), document.addEventListener("mousemove", v), document.addEventListener("mouseup", y));
+	}, v = (e) => {
+		if (!f.value) return;
+		let t = h();
+		if (!t) return;
+		let n = e.clientX - p.value.x, r = e.clientY - p.value.y;
+		t.scrollLeft = p.value.scrollLeft - n, t.scrollTop = p.value.scrollTop - r, l?.({
+			x: n,
+			y: r
+		});
+	}, y = (e) => {
+		if (!f.value) return;
+		f.value = !1;
+		let t = h();
+		t && (t.style.cursor = "auto", t.style.userSelect = ""), document.removeEventListener("mousemove", v), document.removeEventListener("mouseup", y), u?.();
+	}, b = (e) => {
+		!s || !g(e) || e.preventDefault();
+	}, x = () => {
+		if (!f.value) return;
+		f.value = !1;
+		let e = h();
+		e && (e.style.cursor = "auto", e.style.userSelect = ""), document.removeEventListener("mousemove", v), document.removeEventListener("mouseup", y), u?.();
+	};
+	return r(() => s, (e) => {
+		!e && f.value && x();
+	}), t(() => {
+		document.removeEventListener("mousemove", v), document.removeEventListener("mouseup", y);
+	}), {
+		isPanning: f,
+		handlers: {
+			onMouseDown: _,
+			onContextMenu: b
+		},
+		stopPan: x
+	};
+}
+//#endregion
+export { s as useCanvasDrag };

package/dist/index.umd.js

@@ -1 +1 @@
-(function(e){typeof define==`function`&&define.amd?define([],e):e()})(function(){});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports,require(`vue`)):typeof define==`function`&&define.amd?define([`exports`,`vue`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.UseCanvasDrag={},e.Vue))})(this,function(e,t){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var n=[`right`],r={left:{button:0},right:{button:2},middle:{button:1},"shift-left":{button:0,modifiers:{shift:!0}},"ctrl-left":{button:0,modifiers:{ctrl:!0}},"alt-left":{button:0,modifiers:{alt:!0}}};function i(e){return e?e.map(e=>typeof e==`string`?r[e]??{button:-1}:e):n.map(e=>r[e])}function a(e){let{container:n,enabled:r=!0,onStartDrag:a,onDrag:o,onEndDrag:s,mode:c}=e,l=(0,t.ref)(!1),u=(0,t.ref)({x:0,y:0,scrollLeft:0,scrollTop:0}),d=(0,t.computed)(()=>i(Array.isArray(c)?c:c?[c]:void 0)),f=()=>typeof n==`string`?document.querySelector(n):typeof n==`function`?n():n instanceof HTMLElement?n:null,p=e=>d.value.some(t=>{if(t.button!==void 0&&t.button!==e.button)return!1;if(t.modifiers){let n=t.modifiers;if(n.shift&&!e.shiftKey||n.ctrl&&!e.ctrlKey||n.alt&&!e.altKey||n.meta&&!e.metaKey)return!1}return!0}),m=e=>{if(!r||!p(e))return;let t=f();t&&(u.value={x:e.clientX,y:e.clientY,scrollLeft:t.scrollLeft,scrollTop:t.scrollTop},l.value=!0,t.style.cursor=`grabbing`,t.style.userSelect=`none`,e.preventDefault(),a?.(e),document.addEventListener(`mousemove`,h),document.addEventListener(`mouseup`,g))},h=e=>{if(!l.value)return;let t=f();if(!t)return;let n=e.clientX-u.value.x,r=e.clientY-u.value.y;t.scrollLeft=u.value.scrollLeft-n,t.scrollTop=u.value.scrollTop-r,o?.({x:n,y:r})},g=e=>{if(!l.value)return;l.value=!1;let t=f();t&&(t.style.cursor=`auto`,t.style.userSelect=``),document.removeEventListener(`mousemove`,h),document.removeEventListener(`mouseup`,g),s?.()},_=e=>{!r||!p(e)||e.preventDefault()},v=()=>{if(!l.value)return;l.value=!1;let e=f();e&&(e.style.cursor=`auto`,e.style.userSelect=``),document.removeEventListener(`mousemove`,h),document.removeEventListener(`mouseup`,g),s?.()};return(0,t.watch)(()=>r,e=>{!e&&l.value&&v()}),(0,t.onUnmounted)(()=>{document.removeEventListener(`mousemove`,h),document.removeEventListener(`mouseup`,g)}),{isPanning:l,handlers:{onMouseDown:m,onContextMenu:_},stopPan:v}}e.useCanvasDrag=a});

package/dist/src/index.d.ts

@@ -1 +1,12 @@
+/**
+ * @description 主入口文件
+ * @author lrb
+ * @date 2026-05-11 23:21:24
+ * @lastModifyTime 2026-05-11 23:21:24
+ * @lastModifyAuthor lrb
+ * @license MIT
+ * @copyright lrb
+ * @version 1.0.0
+ */
+export { useCanvasDrag } from './useCanvasDrag';
 export type { DragButtonConfig, CanvasDragOptions, DragTrigger } from './useCanvasDrag';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-canvas-drag",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Vue3 画布拖拽组合式函数，支持多种触发方式",
   "main": "./dist/index.umd.js",
   "module": "./dist/index.esm.js",