use-canvas-drag 0.1.0 → 0.2.0

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/package.json

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