# v2-drag-zoom

**Repository Path**: ericfang/v2-drag-zoom

## Basic Information

- **Project Name**: v2-drag-zoom
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-16
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# V2 Drag Zoom

一个轻量、高效的缩放拖拽组件（Vue 2版本），帮助开发人员快速实现类似地图缩放拖拽等功能。

**[📖 中文文档](https://gitee.com/ericfang/v2-drag-zoom/blob/master/README.zh-CN.md)** | **[📖 English Documentation](https://gitee.com/ericfang/v2-drag-zoom/blob/master/README.md)**

> 需要 Vue 3 版本？查看 [**v3-drag-zoom**](https://www.npmjs.com/package/v3-drag-zoom)

## 🚀 特性

- ✅ 支持拖拽和缩放功能
- ✅ 支持多种对齐模式（cover、contain、auto）
- ✅ 支持跟随鼠标缩放
- ✅ 支持固定大小的子元素
- ✅ 支持自定义标记点
- ✅ TypeScript 支持
- ✅ 响应式设计，自动适应容器大小变化
- ✅ 平滑动画过渡效果
- ✅ 支持加载状态显示

## 📦 安装

```bash
npm install v2-drag-zoom
```

## 🎯 用途介绍

V2 Drag Zoom 是一个专为 Vue 2 设计的交互式缩放拖拽组件，适用于需要实现以下功能的场景：

- **地图应用**：实现地图的缩放和平移功能
- **图片查看器**：支持图片的放大缩小和拖拽浏览
- **图表交互**：允许用户缩放和移动复杂的数据可视化图表
- **设计工具**：提供画布的缩放和拖拽能力
- **文档预览**：支持大型文档或图纸的局部查看

## 🏗️ 架构介绍

该组件采用模块化设计，主要包含两个核心组件：

### V2DragZoomContainer
主容器组件，负责管理整体的缩放和拖拽逻辑，包括：
- 容器尺寸检测和自适应
- 缩放计算和动画控制
- 鼠标事件处理
- 子组件协调

### V2DragZoomItem
子项组件，用于在可缩放容器内放置可交互的元素，如：
- 标记点
- 注释
- 图标
- 其他自定义内容

组件间通过 Vue 的 provide/inject 机制进行通信，确保良好的解耦和可扩展性。

## 💻 使用指南

### 全局注册

```javascript
import Vue from 'vue';
import V2DragZoom from 'v2-drag-zoom';

Vue.use(V2DragZoom);
```

### 组件使用

```vue
<template>
  <div style="width: 800px; height: 600px;">
    <v2-drag-zoom-container
      ref="dragRef"
      align="contain"
      :follow-pointer="true"
      @onMove="handleMove"
      @onZoom="handleZoom"
    >
      <!-- 主要内容 -->
      <img src="/test1.jpeg" alt="示例图片" />
      
      <!-- 标记点 -->
      <v2-drag-zoom-item
        :position="{ x: 50, y: 50 }"
        :draggable="true"
        :fixed-size="false"
        @onMove="handleItemMove"
      >
        <span>标记点</span>
      </v2-drag-zoom-item>
    </v2-drag-zoom-container>
  </div>
</template>

<script>
export default {
  methods: {
    handleMove(event) {
      console.log('容器移动:', event);
    },
    handleZoom(event) {
      console.log('容器缩放:', event);
    },
    handleItemMove(position) {
      console.log('项目移动:', position);
    }
  }
}
</script>
```

### 完整示例

```vue
<template>
  <div class="app">
    <h1>V2 Drag Zoom 演示</h1>
    
    <div class="controls">
      <button @click="resetView">重置视图</button>
      <button @click="zoomIn">放大</button>
      <button @click="zoomOut">缩小</button>
    </div>
    
    <v2-drag-zoom-container
      ref="container"
      align="contain"
      :max-zoom="5"
      :min-zoom="0.1"
      :follow-pointer="true"
      :animate-duration="300"
      style="width: 100%; height: 600px; border: 1px solid #ccc;"
    >
      <img src="/map.jpg" alt="地图" style="max-width: 100%;" />
      
      <!-- 多个标记点 -->
      <v2-drag-zoom-item
        v-for="(marker, index) in markers"
        :key="index"
        :position="marker.position"
        :draggable="true"
        :fixed-size="false"
        @onMove="updateMarkerPosition(index, $event)"
      >
        <div class="marker">
          {{ marker.label }}
        </div>
      </v2-drag-zoom-item>
    </v2-drag-zoom-container>
  </div>
</template>

<script>
export default {
  data() {
    return {
      markers: [
        { position: { x: 20, y: 30 }, label: '地点A' },
        { position: { x: 60, y: 40 }, label: '地点B' },
        { position: { x: 40, y: 70 }, label: '地点C' }
      ]
    };
  },
  methods: {
    resetView() {
      this.$refs.container.reset();
    },
    zoomIn() {
      this.$refs.container.zoom(0.2); // 放大20%
    },
    zoomOut() {
      this.$refs.container.zoom(-0.2); // 缩小20%
    },
    updateMarkerPosition(index, newPosition) {
      this.markers[index].position = newPosition;
    }
  }
};
</script>

<style scoped>
.marker {
  background: red;
  color: white;
  padding: 5px 10px;
  border-radius: 15px;
  font-size: 12px;
  cursor: pointer;
}

.controls {
  margin-bottom: 10px;
}

.controls button {
  margin-right: 10px;
  padding: 5px 15px;
}
</style>
```

## 📚 API 参考

### V2DragZoomContainer Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| autoResize | 根据父元素自动调整大小 | boolean | true |
| followPointer | 缩放时是否跟随鼠标 | boolean | true |
| maxZoom | 最大缩放比例 | number | 100 |
| minZoom | 最小缩放比例 | number | 0.01 |
| align | 显示模式 | 'cover' \| 'contain' \| 'auto' | 'contain' |
| zoomFactor | 缩放因子 | number | 0.1 |
| draggable | 是否可拖拽 | boolean | true |
| zoomable | 是否可缩放 | boolean | true |
| loading | 加载中状态 | boolean | false |
| animateDuration | 缩放动画时长（毫秒） | number | 200 |

### V2DragZoomContainer Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| onMove | 移动过程中触发 | ContainerEvent |
| onMoveFinished | 移动结束时触发 | ContainerEvent |
| onZoom | 缩放时触发 | ContainerEvent |

### V2DragZoomContainer Methods

| 方法名 | 说明 | 参数 |
|--------|------|------|
| reset | 重置到初始位置和大小 | - |
| zoom | 手动缩放 | zoom: number (缩放因子) |

### V2DragZoomContainer Slots

| Slot | 说明 |
|------|------|
| default | 放置主要内容（图片、图表等） |
| loading | 自定义加载状态显示内容 |

### V2DragZoomItem Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| position | 位置（百分比） | { x: number, y: number } | 必填 |
| offset | 偏移量百分比 | [number, number] | [-50, -50] |
| fixedSize | 是否固定大小 | boolean | false |
| rotate | 旋转角度 | number | 0 |
| draggable | 是否可拖拽 | boolean | false |

### V2DragZoomItem Events

| 事件名 | 说明 | 回调参数 |
|--------|------|----------|
| onMove | 移动过程中触发 | Position |
| onMoveFinished | 移动结束时触发 | Position |
| update:position | 位置更新时触发（支持 v-model） | Position |

### V2DragZoomItem Slots

| Slot | 说明 |
|------|------|
| default | 放置标记点或其他内容 |

## 🔧 开发

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建
npm run build
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个项目。

## 📄 License

MIT