Uniapp 微信小程序 Canvas画框标注：拖拽缩放全攻略

Uniapp 实现高性能 Canvas 图片画框标注组件：支持绘制、拖拽、缩放与删除

1. 背景介绍

在很多业务场景中（比如 AI 视觉识别、隐患排查、票据信息提取等），我们需要在前端实现一个图片画框标注功能。用户拍完照或上传图片后，可以在图片上框选出特定的区域，并将该区域的坐标发送给后端进行处理。

在开发基于 Uniapp 的微信小程序和 H5 跨端应用时，使用 Canvas 来做图片处理是不可避免的。但如果仅仅提供"画一个框"的基础功能，用户的交互体验会非常僵硬。

为了提供最顶级的用户体验，我们对画框组件进行了深度交互优化，最终实现的功能包含：

• 图片完美适配：内置 AspectFit 算法自适应图片比例，同时处理了部分机型由于 EXIF 信息导致的图片自动旋转截断问题。
• 无缝直接画框：无需繁琐地点击"开启画框模式"按钮，只要在空白区域拖拽即可直接画新框。
• 支持拖拽平移：画完框后，手指按住框的内部，可以直接拖拽改变框的位置，且有边界约束。
• 支持自由缩放：按住框的四个角（左上、右上、左下、右下）进行拖拽，可以直接拉伸并改变框的大小。
• 悬浮删除按钮：利用同层渲染，在画框左上角动态生成一个"删除"按钮，点击即可清除当前画框。

本文将详细拆解这个功能的核心实现逻辑和状态机判断策略，并附上源码。

---

2. 核心架构设计

为了兼顾性能与全端的兼容性，我们采用了 "Canvas 绘制图像 + JS 纯数学计算实现触控判定 + DOM 悬浮按钮" 的混合架构。

• 图片与矩形框 ：通过 Canvas 绘制。因为如果在小程序里使用 DOM 来高频移动大量的节点，容易导致卡顿，而在 Canvas 中计算坐标并一并重绘，配合 type="2d" 特性体验极佳。
• 删除按钮 ：使用原生的绝对定位 <view> 节点。微信小程序 type="2d" Canvas 支持同层渲染，所以 DOM 元素可以通过设定较高的 z-index 轻易覆盖在 Canvas 上，避开了在 Canvas 中画按钮还需要监听坐标做事件代理的繁琐工作。
• 统一坐标系 ：为了适配不同分辨率的设备和不同的图片大小，我们放弃了传统的绝对像素坐标，改为采用 0-1000 的千分比坐标系统。这也是本文最核心的设计理念之一。

---

3. 核心理念：0-1000 千分比坐标体系

为什么我们不直接使用屏幕上的绝对像素（Pixel）来记录画框的位置，而是要大费周章地转换成 0-1000 的千分比结构（Permille Coordinate System）？

在前端与后端（尤其是 AI 算法服务端）进行图片标注数据交互时，屏幕碎片化和分辨率差异是最大的痛点。

• 用户的设备可能屏幕各异，设备的 DPR (Device Pixel Ratio) 也不同。
• 一张原本是 4000x3000 分辨率的高清图，在手机端可能被压缩或等比缩小（AspectFit 模式）到仅仅 300x200 像素的 Canvas 画布中展示。

如果在手机端画了一个框，坐标是 x: 50, y: 50, width: 100, height: 100（绝对像素），直接将这个数据传给后端，后端拿到这组坐标去在 4000x3000 的原始高清大图上进行处理或裁剪时，位置将产生巨大的偏差。

解决方案：归一化与千分比化

因此，我们引入了 [x_min, y_min, x_max, y_max] 的 0-1000 千分比坐标结构。

• 图片最左侧 为 x=0，最右侧为 x=1000。
• 图片最顶部 为 y=0，最底部为 y=1000。

无论图片在当前设备的 Canvas 中被缩放到多大，上下左右留白了多少，它内部的相对比例是永远恒定的。

在触摸结束（Touch End 松手）时，组件会进行如下精密的坐标换算：

function convertToPermillage(): BoxCoord {
  // offsetX, offsetY 为图片在 Canvas 中的上下左右留白偏移量
  // drawW, drawH 为图片在 Canvas 中实际渲染的宽高
  const { offsetX, offsetY, drawW, drawH } = imageInfo.value
  // currentRect.value 保存了画布上的绝对像素坐标
  const { x1, y1, x2, y2 } = currentRect.value

  const left = Math.min(x1, x2)
  const top = Math.min(y1, y2)
  const right = Math.max(x1, x2)
  const bottom = Math.max(y1, y2)

  return {
    x_min: Math.round(((left - offsetX) / drawW) * 1000),
    y_min: Math.round(((top - offsetY) / drawH) * 1000),
    x_max: Math.round(((right - offsetX) / drawW) * 1000),
    y_max: Math.round(((bottom - offsetY) / drawH) * 1000),
  }
}

这一理念带来的三大优势：

1. 解耦设备分辨率：彻底消除了 iOS、Android 平台差异，以及设备 DPR 不同带来的像素计算偏差问题。
2. 前后端对齐标准 ：后端或 AI 模型收到千分比坐标后，只需将其乘以原图的物理宽高（例如 x_min / 1000 * 原始宽度），就能 100% 精准还原用户在手机上框选的真实物理位置。
3. 数据回显极度简便：当我们需要在列表页或详情页再次渲染这个框时，无论展示用的缩略图有多小，只需按照其所在的图片容器尺寸，将千分比反向相乘，即可完美复刻画框！

---

4. 交互逻辑与状态机设计 (Hit Testing)

整个拖拽和缩放的灵魂在于如何判断用户的手指摸到了哪里 。

我们设定了一个扩展热区（HANDLE_RADIUS = 30），并在每一次触控开始（touchstart）时执行碰撞检测。

我们在组件内部维护了一个交互状态机变量 interactionMode，它包含以下几种状态：

• 'none'：无交互
• 'draw'：画新框
• 'drag'：拖拽平移
• 'resize-tl' | 'resize-tr' | 'resize-bl' | 'resize-br'：四个角的缩放

4.1 碰撞检测逻辑

function getHitTarget(x: number, y: number) {
  if (!hasBox.value) return 'none'

  // 将当前的坐标进行正规化处理（获取上下左右边界）
  const minX = Math.min(currentRect.value.x1, currentRect.value.x2)
  const maxX = Math.max(currentRect.value.x1, currentRect.value.x2)
  const minY = Math.min(currentRect.value.y1, currentRect.value.y2)
  const maxY = Math.max(currentRect.value.y1, currentRect.value.y2)

  // 1. 优先检查四个角（因为它们在边框上，如果重叠应优先响应缩放）
  if (Math.abs(x - minX) < HANDLE_RADIUS && Math.abs(y - minY) < HANDLE_RADIUS) return 'resize-tl'
  if (Math.abs(x - maxX) < HANDLE_RADIUS && Math.abs(y - minY) < HANDLE_RADIUS) return 'resize-tr'
  if (Math.abs(x - minX) < HANDLE_RADIUS && Math.abs(y - maxY) < HANDLE_RADIUS) return 'resize-bl'
  if (Math.abs(x - maxX) < HANDLE_RADIUS && Math.abs(y - maxY) < HANDLE_RADIUS) return 'resize-br'

  // 2. 检查是否在框内部（拖拽）
  if (x >= minX && x <= maxX && y >= minY && y <= maxY) return 'drag'

  // 3. 都没有命中，说明在空白区域（可以画新框）
  return 'none'
}

---

5. 触摸事件的闭环 (Start, Move, End)

有了状态机之后，我们在 Canvas 的三个生命周期事件中分别控制矩形的数据流动。

Touch Start: 分配任务

在 touchstart 时调用 getHitTarget，根据返回结果设置当前的模式。如果发现返回了 none 且坐标位于图片的有效区域内，则直接将模式设为 'draw' 开始绘制新框。

Touch Move: 更新计算

在 touchmove 中，我们根据不同的状态，对坐标数据 currentRect 做差值运算。

关键点：必须要进行边界限制（Boundary Constraint）！不论是平移还是缩放，新的计算结果决不能超过图片的可视化边界，否则保存出去的坐标会溢出。

function handleTouchMove(e: any) {
  // ...省略获取触摸坐标x, y的逻辑
  
  if (interactionMode.value === 'draw') {
    // 画框模式：固定一个对角点，跟随手势更新另一个对角点
    currentRect.value.x2 = Math.max(offsetX, Math.min(x, maxX))
    currentRect.value.y2 = Math.max(offsetY, Math.min(y, maxY))
  } 
  else if (interactionMode.value === 'drag') {
    // 拖拽模式：根据手指的移动偏移量 (dx, dy) 整体移动框
    const dx = x - dragStartX
    const dy = y - dragStartY
    // 计算边界，防止拖拽越界...
  }
  else if (interactionMode.value.startsWith('resize')) {
    // 缩放模式：以 'resize-tl' (左上角) 为例，只改变 x1 和 y1
    if (interactionMode.value === 'resize-tl') {
      newX1 = Math.max(offsetX, Math.min(initialRect.x1 + dx, newX2 - 10))
      newY1 = Math.max(offsetY, Math.min(initialRect.y1 + dy, newY2 - 10))
    }
    // ...处理其他角
  }

  render() // 触发 Canvas 重绘
}

Touch End: 抛出数据

当手指抬起时，我们将画好的框进行坐标归一化，把 Canvas 的绝对像素转为 0-1000 的千分比结构 [x_min, y_min, x_max, y_max]，并通过 emit 发送给父组件进行数据绑定。

---

6. 悬浮删除按钮的处理

这是组件设计中的一个巧思：由于用户希望有一个显著的删除按钮挂在框的左上角，我们并不直接画在 Canvas 里。而是利用 Vue 的计算属性 computed 实时的跟踪左上角的坐标。

<!-- 删除当前框按钮 -->
<view 
  v-if="hasBox && interactionMode === 'none'" 
  class="delete-box-btn" 
  :style="deleteBtnStyle"
  @touchstart.stop="clearBox"
>
  <view class="icon-close" />
</view>

const deleteBtnStyle = computed(() => {
  if (!hasBox.value) return { display: 'none' }
  let left = Math.min(currentRect.value.x1, currentRect.value.x2)
  let top = Math.min(currentRect.value.y1, currentRect.value.y2)
  
  // 防止按钮溢出屏幕被裁切
  if (left < 12) left = 12
  if (top < 12) top = 12

  return {
    position: 'absolute',
    left: `${left}px`,
    top: `${top}px`,
    zIndex: 100
  }
})

这利用了同层渲染的优势，直接解决了事件穿透和坐标偏移的问题。并且我们在交互模式 interactionMode === 'none' 时才显示，这意味着你在拖拽和缩放的瞬间，按钮会自动隐藏，不会阻挡你的视线，松手后按钮又会恰好停靠在最新的左上角。体验非常丝滑。

---

7. 组件封装的便利性与调用示例

将画框逻辑抽取为一个独立的组件（ImageDrawBox.vue）可以极大地提升前端工程的复用性和可维护性。

在业务开发中，往往有多个不同的页面需要用到图片标注（例如：隐患上报、复查页面等）。作为父组件，业务页面完全不需要关心 Canvas 的繁琐绘制、手势计算和各种机型的适配。

父组件只需要传入两个数据：

1. 图片地址 (image-src)
2. 初始框坐标 (initial-box) ------ 可选项。

💡 深度解析 initial-box 的核心必要性与状态恢复机制：

在开发微信小程序等跨端应用时，原生组件（如 Canvas、Video、Map 等）往往拥有最高的渲染层级。这会导致一个非常经典的坑：当页面上需要弹出一个普通的 DOM 弹窗、下拉选择器（Picker）时，底层的 Canvas 会无视 z-index 设置，强行穿透并遮挡在弹窗之上。

为了解决这种"原生层级穿透"问题，通常的做法是在打开弹窗的瞬间，通过 v-if="showCanvas = false" 将 Canvas 暂时销毁隐藏，等弹窗关闭后再设为 true 重新挂载。

但这又引发了新的问题：v-if 的销毁会导致 Canvas 内部画好的所有图形和组件状态全部丢失！ 当它再次出现时，好不容易画出来的框就不见了。

这就是 initial-box 最精妙的设计所在：

父组件可以在每次画完框后，通过 @box-drawn 事件把坐标存到自己的 boxCoord 变量中。当弹窗关闭、Canvas 组件因为 v-if="true" 重新挂载时，父组件直接把这组坐标通过 :initial-box="boxCoord" 再次传入。

子组件在重新加载完图片后，会自动检测这个初始值，并将其逆向映射回画布物理像素，瞬间完成重绘。这样不仅完美规避了原生层级穿透的 Bug，还让用户感知不到任何状态的丢失！

父组件只需要监听两个事件：

1. @box-drawn ------ 画框完成或框被拖拽、缩放结束时，组件抛出的最新千分比坐标。
2. @box-cleared ------ 用户点击左上角删除按钮时抛出的清除事件。

实际页面调用示例

以下是该组件在真实的业务页面（例如 remarks.vue）中的极简调用代码：

Template 部分：

<view class="image-stage__frame">
  <ImageDrawBox
    v-if="showCanvas"
    ref="drawBoxRef"
    :image-src="cameraModel.imagePath"
    :initial-box="boxCoord"
    @box-drawn="handleBoxDrawn"
    @box-cleared="handleBoxCleared"
  />
</view>

Script 部分：

<script lang="ts" setup>
import { ref } from 'vue'
import ImageDrawBox from './components/image-draw-box.vue'

// 控制组件显示与图片路径状态
const showCanvas = ref(true)
const cameraModel = ref({ imagePath: 'https://example.com/test.jpg' })

// 存储后端的千分比坐标 [x_min, y_min, x_max, y_max]
const boxCoord = ref<number[] | null>(null)

/** 画框完成或修改完成的回调 */
function handleBoxDrawn(coord: {
  x_min: number
  y_min: number
  x_max: number
  y_max: number
}) {
  // 接收到千分比坐标，直接保存，即可随时提交给后端
  boxCoord.value = [coord.x_min, coord.y_min, coord.x_max, coord.y_max]
  console.log('画框完成，收到千分比坐标:', coord)
}

/** 画框被用户清除的回调 */
function handleBoxCleared() {
  boxCoord.value = null
  console.log('画框已清除')
}
</script>

得益于高度解耦的组件设计和千分比坐标系统，外层业务逻辑变得非常干净。所有的交互、Canvas 重绘与坐标换算都被完美隔离在内部。

---

8. 总结

在 Uniapp 环境下处理 Canvas 和图片的复合交互时：

1. 不要重度依赖 DOM 节点数量：在小程序上节点如果特别多，拖拽会严重掉帧。将矩形本身放在 Canvas 里渲染是最优解。
2. 巧用同层渲染 ：一些只响应单一点击事件的附属控件（如删除按钮），使用 CSS 绝对定位配合 v-if 是成本最低且效果最好的方案。
3. 坐标系与数学：维护一套可靠的纯 JS 数学判断逻辑（即 Hit Testing 和 Boundary Checking），它不但不会受限于框架本身的生命周期，还能在各种跨端场景下保持极高的一致性。

希望这篇文章能帮你快速拿捏相关的交互开发，如果觉得有帮助，欢迎点赞收藏！