electron 图片缩放后无法拖动

Vue3 图片拖动缩放功能

问题描述

在一个 Vue3 + Electron 项目中，试卷查看弹窗的图片放大后无法拖动查看不同区域。用户反馈"图片拖动不生效"。

技术栈

Vue 3 + Composition API
Electron (桌面应用)
TypeScript
UnoCSS

问题分析过程

第一阶段：确认缩放功能

首先检查缩放功能是否正常工作：

typescript 复制代码

// 测试缩放
const dragZoom = useDragZoom({
  minZoom: 1.0,
  maxZoom: 3.0,
  zoomStep: 0.1,
  getBaseHeight: () => baseHeight.value,
  preventLeftDrag: false,
  zoomOptionsRange: { min: 100, max: 300, step: 10 }
})

发现 : 缩放按钮点击有输出 [useDragZoom] changeZoom called，说明缩放逻辑正常。

第二阶段：检查拖动事件

添加调试日志检查 handleMouseDown 是否被触发：

typescript 复制代码

function handleMouseDown(event: MouseEvent) {
  console.log('[useDragZoom] handleMouseDown called, zoom:', zoom.value)
  if (zoom.value > 1) {
    console.log('[useDragZoom] Starting drag')
    // ...
  }
}

发现 : 放大后点击图片，完全没有 handleMouseDown 的输出，说明点击事件根本没有触发。

第三阶段：定位事件绑定问题

在模板中添加多层事件监听来定位问题：

vue 复制代码

<div @mousedown="(e) => { console.log('[Container] mousedown'); }">
  <img @mousedown="(e) => { console.log('[Image] mousedown'); handleMouseDown(e); }" />
</div>

发现:

单纯点击图片：有 [Image] click event 输出
按住拖动：没有任何 mousedown 输出

这说明在拖动时，mousedown 事件被某种机制阻止了。

第四阶段：全局事件监听器问题

检查 onMounted 钩子：

typescript 复制代码

onMounted(() => {
  console.log('[useDragZoom] onMounted - adding event listeners')
  document.addEventListener("mousemove", handleMouseMove)
  document.addEventListener("mouseup", handleMouseUp)
})

发现 : 没有 onMounted 的输出！

原因 : useDragZoom 是在 setup 函数顶层调用的，但 onMounted 可能因为组件复用或其他原因没有正确执行。

解决方案 : 立即注册全局事件监听器，不依赖 onMounted：

typescript 复制代码

// 立即注册，而不是等待 onMounted
document.addEventListener("mousemove", handleMouseMove)
document.addEventListener("mouseup", handleMouseUp)

// 只在卸载时清理
onUnmounted(() => {
  document.removeEventListener("mousemove", handleMouseMove)
  document.removeEventListener("mouseup", handleMouseUp)
})

第五阶段：切换到 Pointer Events

尽管注册了事件监听器，但拖动依然不工作。尝试从 Mouse Events 切换到 Pointer Events：

typescript 复制代码

// 从 mousemove 改为 pointermove
document.addEventListener("pointermove", handleMouseMove)
document.addEventListener("pointerup", handleMouseUp)
document.addEventListener("pointercancel", handleMouseUp)

vue 复制代码

<!-- 模板中也改为 pointerdown -->
<div @pointerdown="(e) => handleMouseDown(e)">

发现 : 拖动开始有反应了！但 moveCount 只有 4 次，正常应该有几十上百次。

第六阶段：解决 Pointer Events 被浏览器拦截

问题根源找到了：浏览器的默认触摸/指针行为会拦截 pointer events。

最终解决方案: 添加 CSS 属性禁用浏览器默认行为：

scss 复制代码

.image-container-inner {
  touch-action: none; // 关键！防止浏览器默认行为
  // ... 其他样式
}

.image {
  user-select: none;           // 防止文本选择
  -webkit-user-drag: none;     // 防止图片拖动
  touch-action: none;          // 防止触摸行为
  pointer-events: auto;        // 确保能接收指针事件
}

vue 复制代码

<img
  @dragstart.prevent      <!-- 防止原生拖动事件 -->
  @selectstart.prevent    <!-- 防止选择事件 -->
/>

第七阶段：验证边界计算

拖动能工作后，发现"只能拖动一点距离"。检查边界计算：

typescript 复制代码

// 输出: Bounds: {minX: -30, maxX: 30, minY: -124.5, maxY: 124.5}

边界太小了！问题出在图片尺寸计算：

typescript 复制代码

// 错误的方式：使用 offsetWidth（受其他因素影响）
let imgDisplayWidth = img.offsetWidth

// 正确的方式：直接计算
const naturalWidth = img.naturalWidth
const naturalHeight = img.naturalHeight
const baseHeight = getBaseHeight()
const imgDisplayHeight = baseHeight * zoom.value
const imgDisplayWidth = (naturalWidth / naturalHeight) * imgDisplayHeight

修正后，边界值变为 {minX: -1048, maxX: 1048, minY: -830, maxY: 830}，拖动范围正常了。

第八阶段：验证最终效果

添加调试输出验证 moveCount：

typescript 复制代码

function handleMouseUp() {
  console.log('[useDragZoom] Drag ended, moveCount was:', moveCount)
}

结果:

修复前：moveCount: 4（拖动事件触发极少）
修复后：正常拖动，moveCount 几十到上百（流畅）

✅ 问题解决！

核心解决方案

1. 使用 Pointer Events 替代 Mouse Events

typescript 复制代码

// ❌ 旧方案
document.addEventListener("mousemove", handleMouseMove)
document.addEventListener("mouseup", handleMouseUp)

// ✅ 新方案
document.addEventListener("pointermove", handleMouseMove)
document.addEventListener("pointerup", handleMouseUp)
document.addEventListener("pointercancel", handleMouseUp)

原因: Pointer Events 是更现代的 API，对触摸屏、鼠标、触控笔等输入设备有更好的统一支持。

2. 添加关键 CSS 属性

scss 复制代码

.image-container-inner {
  touch-action: none; // 🔑 最关键的属性
}

.image {
  user-select: none;
  -webkit-user-drag: none;
  touch-action: none;
  pointer-events: auto;
}

touch-action: none 的作用:

禁用浏览器的默认滚动、缩放、双击等手势
让我们的自定义拖动逻辑能完全接管事件处理
这是解决 moveCount 只有 4 次的关键！

3. 立即注册全局事件监听器

typescript 复制代码

export function useDragZoom(options) {
  // ... 状态定义
  
  // ✅ 直接注册，不等待 onMounted
  document.addEventListener("pointermove", handleMouseMove)
  document.addEventListener("pointerup", handleMouseUp)
  document.addEventListener("pointercancel", handleMouseUp)
  
  onUnmounted(() => {
    document.removeEventListener("pointermove", handleMouseMove)
    document.removeEventListener("pointerup", handleMouseUp)
    document.removeEventListener("pointercancel", handleMouseUp)
  })
  
  return { /* ... */ }
}

4. 修正图片尺寸计算

typescript 复制代码

function calculateDragBounds(): DragBounds {
  const img = imageRef.value
  const container = containerRef.value
  
  // ✅ 使用 naturalWidth/Height 和 zoom 直接计算
  const naturalWidth = img.naturalWidth
  const naturalHeight = img.naturalHeight
  const baseHeight = getBaseHeight()
  const imgDisplayHeight = baseHeight * zoom.value
  const imgDisplayWidth = (naturalWidth / naturalHeight) * imgDisplayHeight
  
  // 计算超出容器的部分
  const excessWidth = Math.max(0, imgDisplayWidth - containerWidth)
  const excessHeight = Math.max(0, imgDisplayHeight - containerHeight)
  
  // 可拖动范围
  const maxX = excessWidth / 2
  const minX = -excessWidth / 2
  const maxY = excessHeight / 2
  const minY = -excessHeight / 2
  
  return { minX, maxX, minY, maxY }
}

完整代码示例

useDragZoom.ts

typescript 复制代码

import { computed, onUnmounted, ref, type Ref } from "vue"
import { debounce } from "lodash-es"

interface UseDragZoomOptions {
  minZoom?: number
  maxZoom?: number
  zoomStep?: number
  getBaseHeight?: () => number
  preventLeftDrag?: boolean
  zoomOptionsRange?: { min: number, max: number, step: number }
}

export function useDragZoom(options: UseDragZoomOptions = {}) {
  const {
    minZoom = 1.0,
    maxZoom = 3.0,
    zoomStep = 0.1,
    getBaseHeight = () => window.innerHeight - 210,
    preventLeftDrag = false,
    zoomOptionsRange = { min: 100, max: 300, step: 10 }
  } = options

  // 状态
  const zoom = ref(1.0)
  const translateX = ref(0)
  const translateY = ref(0)
  const isDragging = ref(false)
  const dragStartX = ref(0)
  const dragStartY = ref(0)
  const dragStartTranslateX = ref(0)
  const dragStartTranslateY = ref(0)

  // DOM 引用
  const imageRef = ref<HTMLImageElement | null>(null)
  const containerRef = ref<HTMLElement | null>(null)

  // 计算拖动边界
  function calculateDragBounds() {
    if (!imageRef.value || !containerRef.value || zoom.value <= 1) {
      return { minX: 0, maxX: 0, minY: 0, maxY: 0 }
    }

    const container = containerRef.value
    const img = imageRef.value
    const containerWidth = container.clientWidth
    const containerHeight = container.clientHeight

    // 计算缩放后的实际显示尺寸
    const naturalWidth = img.naturalWidth
    const naturalHeight = img.naturalHeight
    const baseHeight = getBaseHeight()
    const imgDisplayHeight = baseHeight * zoom.value
    const imgDisplayWidth = (naturalWidth / naturalHeight) * imgDisplayHeight

    // 计算可拖动范围
    const excessWidth = Math.max(0, imgDisplayWidth - containerWidth)
    const excessHeight = Math.max(0, imgDisplayHeight - containerHeight)

    return {
      minX: excessWidth > 0 ? -excessWidth / 2 : 0,
      maxX: excessWidth > 0 ? excessWidth / 2 : 0,
      minY: excessHeight > 0 ? -excessHeight / 2 : 0,
      maxY: excessHeight > 0 ? excessHeight / 2 : 0
    }
  }

  // 应用边界限制
  function applyDragBounds() {
    const bounds = calculateDragBounds()
    const safeMinX = preventLeftDrag ? Math.max(0, bounds.minX) : bounds.minX
    const safeMaxX = Math.max(bounds.maxX, bounds.minX)
    const safeMinY = bounds.minY
    const safeMaxY = Math.max(bounds.maxY, bounds.minY)

    translateX.value = Math.min(safeMaxX, Math.max(safeMinX, translateX.value))
    translateY.value = Math.min(safeMaxY, Math.max(safeMinY, translateY.value))
  }

  // 事件处理
  function handleMouseDown(event: MouseEvent) {
    if (zoom.value > 1) {
      isDragging.value = true
      dragStartX.value = event.clientX
      dragStartY.value = event.clientY
      dragStartTranslateX.value = translateX.value
      dragStartTranslateY.value = translateY.value
      event.preventDefault()
      event.stopPropagation()
    }
  }

  function handleMouseMove(event: MouseEvent) {
    if (isDragging.value && zoom.value > 1) {
      const deltaX = event.clientX - dragStartX.value
      const deltaY = event.clientY - dragStartY.value
      translateX.value = dragStartTranslateX.value + deltaX
      translateY.value = dragStartTranslateY.value + deltaY
      applyDragBounds()
    }
  }

  function handleMouseUp() {
    if (isDragging.value) {
      isDragging.value = false
    }
  }

  function setZoom(newZoom: number) {
    zoom.value = Math.max(minZoom, Math.min(maxZoom, newZoom))
    if (zoom.value === 1) {
      translateX.value = 0
      translateY.value = 0
    }
  }

  function changeZoom(delta: number) {
    setZoom(Math.round((zoom.value + delta) * 100) / 100)
  }

  // 立即注册全局事件监听器
  document.addEventListener("pointermove", handleMouseMove as any)
  document.addEventListener("pointerup", handleMouseUp as any)
  document.addEventListener("pointercancel", handleMouseUp as any)

  onUnmounted(() => {
    document.removeEventListener("pointermove", handleMouseMove as any)
    document.removeEventListener("pointerup", handleMouseUp as any)
    document.removeEventListener("pointercancel", handleMouseUp as any)
  })

  return {
    zoom,
    translateX,
    translateY,
    isDragging,
    imageRef,
    containerRef,
    currentZoomPercent: computed({
      get: () => Math.round(zoom.value * 100),
      set: (value: number) => setZoom(value / 100)
    }),
    isDraggable: computed(() => zoom.value > 1),
    changeZoom,
    debouncedChangeZoom: debounce(changeZoom, 300),
    handleMouseDown,
    getImageStyle: (baseHeight: number) => ({
      height: `calc(${baseHeight}px * ${zoom.value})`,
      transform: `translate(${translateX.value}px, ${translateY.value}px)`,
      cursor: zoom.value > 1 ? (isDragging.value ? "grabbing" : "grab") : "default"
    }),
    reset: () => {
      zoom.value = 1.0
      translateX.value = 0
      translateY.value = 0
    }
  }
}

组件使用示例

vue 复制代码

<template>
  <div class="image-viewer">
    <!-- 缩放控制 -->
    <div class="controls">
      <button @click="() => debouncedChangeZoom(-0.1)">-</button>
      <span>{{ currentZoomPercent }}%</span>
      <button @click="() => debouncedChangeZoom(0.1)">+</button>
    </div>

    <!-- 图片容器 -->
    <div
      ref="containerRef"
      class="image-container"
      :class="{ draggable: isDraggable }"
      @pointerdown="(e) => handleMouseDown(e as any)"
    >
      <img
        ref="imageRef"
        :src="imageUrl"
        class="image"
        :class="{ dragging: isDragging }"
        :style="getImageStyle(baseHeight)"
        @dragstart.prevent
        @selectstart.prevent
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import { useDragZoom } from './useDragZoom'

const imageUrl = ref('your-image-url.jpg')
const baseHeight = computed(() => window.innerHeight - 200)

const {
  translateX,
  translateY,
  isDragging,
  currentZoomPercent,
  imageRef,
  containerRef,
  debouncedChangeZoom,
  handleMouseDown,
  getImageStyle,
  isDraggable
} = useDragZoom({
  minZoom: 1.0,
  maxZoom: 3.0,
  zoomStep: 0.1,
  getBaseHeight: () => baseHeight.value
})
</script>

<style scoped lang="scss">
.image-container {
  display: flex;
  justify-content: center;
  align-items: center;
  overflow: hidden;
  position: relative;
  width: 100%;
  height: 600px;
  background-color: #f5f5f5;
  touch-action: none; // 🔑 关键属性

  &.draggable {
    cursor: grab;

    &:active {
      cursor: grabbing;
    }
  }
}

.image {
  object-fit: contain;
  display: block;
  will-change: transform;
  user-select: none;
  -webkit-user-drag: none;
  touch-action: none;
  pointer-events: auto;

  &:not(.dragging) {
    transition: transform 0.1s ease-out;
  }
}
</style>

关键知识点总结

1. Pointer Events vs Mouse Events

特性	Mouse Events	Pointer Events
触摸支持	❌ 需要单独处理 touch events	✅ 统一处理
触控笔支持	❌	✅
浏览器兼容性	✅ 所有浏览器	✅ 现代浏览器
推荐使用	仅鼠标场景	多输入设备场景

2. touch-action 属性详解

css 复制代码

touch-action: none;        /* 禁用所有手势 */
touch-action: pan-x;       /* 只允许水平滚动 */
touch-action: pan-y;       /* 只允许垂直滚动 */
touch-action: manipulation; /* 允许滚动和缩放 */

在自定义拖动场景中，必须设置 touch-action: none 来禁用浏览器默认行为。

3. 事件监听器注册时机

typescript 复制代码

// ❌ 错误：依赖 onMounted（可能不执行）
onMounted(() => {
  document.addEventListener("pointermove", handler)
})

// ✅ 正确：立即注册
document.addEventListener("pointermove", handler)

onUnmounted(() => {
  document.removeEventListener("pointermove", handler)
})

4. 防止默认行为的多层防护

vue 复制代码

<!-- HTML 层 -->
<img @dragstart.prevent @selectstart.prevent />

typescript 复制代码

// JavaScript 层
function handleMouseDown(event) {
  event.preventDefault()
  event.stopPropagation()
}

css 复制代码

/* CSS 层 */
.image {
  user-select: none;
  -webkit-user-drag: none;
  touch-action: none;
}

调试技巧

1. 添加计数器检查事件触发频率

typescript 复制代码

let moveCount = 0
function handleMouseMove(event) {
  moveCount++
  // 如果 moveCount 很小（<10），说明事件被拦截了
}

function handleMouseUp() {
  console.log('Total moves:', moveCount)
  moveCount = 0
}

2. 输出边界值检查计算逻辑

typescript 复制代码

function calculateDragBounds() {
  const bounds = { /* ... */ }
  console.log('Bounds:', bounds)
  return bounds
}

3. 使用 capture 阶段调试事件流

vue 复制代码

<div @pointerdown.capture="handler">
  <!-- capture 阶段会最先触发 -->
</div>

常见问题

Q1: 为什么 onMounted 中的事件监听器没有注册？

A: 在某些情况下（如组件复用、keep-alive 等），onMounted 可能不会按预期执行。建议在 composable 中直接注册全局事件。

Q2: 为什么拖动时 moveCount 很少？

A : 浏览器的默认手势行为拦截了 pointer events。需要添加 touch-action: none。

Q3: 图片边界计算不准确怎么办？

A : 不要使用 offsetWidth，应该用 naturalWidth 和 zoom 比例直接计算。

Q4: Electron 环境下需要特殊处理吗？

A: Electron 使用 Chromium 内核，Pointer Events 支持良好，不需要特殊处理。

性能优化建议

使用 will-change: 告诉浏览器元素将会变化

css 复制代码

.image {
  will-change: transform;
}

避免频繁的边界计算: 只在必要时计算

typescript 复制代码

// ✅ 只在拖动时计算
function handleMouseMove() {
  translateX.value = newX
  translateY.value = newY
  applyDragBounds() // 在这里计算和应用边界
}

使用 transform 而非 top/left: transform 性能更好

typescript 复制代码

// ✅ 使用 transform
transform: `translate(${translateX}px, ${translateY}px)`

// ❌ 避免使用 position
left: `${translateX}px`
top: `${translateY}px`

参考资料

总结

这次调试最大的收获是理解了浏览器默认行为如何影响自定义交互。关键点在于：

选择正确的事件 API（Pointer Events）
禁用浏览器默认行为（touch-action: none）
正确的事件监听器注册时机（立即注册，不依赖生命周期）
准确的边界计算（使用 naturalWidth 而非 offsetWidth）

希望这篇调试记录能帮助到遇到类似问题的开发者！