轻量级多端图片裁剪工具兼容：APP、微信小程序、H5

UniApp 多端图片裁剪工具 (Vue2 / SFC)

下载地址：https://ext.dcloud.net.cn/plugin?id=26841

1. 简介 (Introduction)

这是一个基于 Vue 2 (Options API) 和 UniApp 原生组件 开发的轻量级图片裁剪工具。

核心目标是解决移动端图片裁剪中常见的性能卡顿、旋转后坐标错乱以及多端兼容性问题（特别是安卓、iOS、微信小程序之间的 Canvas 差异）。

2. 核心特性 (Features)

极致性能 ：使用 movable-area 和 movable-view 原生组件实现图片的拖拽与双指缩放，避开了 JS 频繁通信导致的视图层卡顿。
多端兼容 ：完美适配 Android (10.0+) 、iOS (12.0+) 、H5 及 微信小程序。
旋转裁剪：支持每次 90° 旋转，并内置了复杂的坐标系映射算法，确保旋转后的裁剪结果与预览完全一致。
视觉适配 ：
- 自动适配 暗黑模式 (Dark Mode)。
- 适配 Pad / 宽屏设备（限制最大宽度）。
- 主色调：#EF3912。
零依赖：纯原生 API 实现，不依赖 jQuery、Cropper.js 等第三方库，包体积极小。

3. 技术栈 (Tech Stack)

框架：UniApp / Vue 2.x
API：Options API (data, methods, lifecycle)
语言：JavaScript (ES6+)
样式：CSS / Flexbox / CSS Variables

4. 快速开始 (Quick Start)

4.1 安装

由于是单文件组件，无需 npm 安装。只需将核心文件复制到项目中：

bash 复制代码

/pages
  └─ index
      └─ index.vue  <-- 将代码粘贴到此处

4.2 注册页面

在 pages.json 中添加页面配置：

json 复制代码

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "图片裁剪",
        "navigationStyle": "custom" // 建议使用自定义导航或隐藏原生导航
      }
    }
  ]
}

5. 核心逻辑与实现原理

5.1 交互架构

视图层 ：利用 movable-view 处理手势（Pan/Pinch）。
预览层 ：利用 CSS transform: rotate(90deg) 实现低成本的视觉旋转预览。
逻辑层：不实时操作 Canvas，仅在点击"确定"时进行一次性绘制。

5.2 坐标系映射 (核心算法)

当用户旋转图片后，屏幕坐标系（Screen Coords）与 Canvas 内部坐标系（Canvas Coords）会发生偏转。

本插件在 onConfirm 阶段实现了以下映射逻辑：

计算图片中心点相对于裁剪框中心的屏幕偏移向量 (diffX, diffY)。
根据旋转角度 (0, 90, 180, 270) 将向量映射到 Canvas 坐标系。

例如 90度时：Screen X+ 映射为 Canvas Y-

使用 ctx.translate 和 ctx.rotate 变换 Canvas 原点，进行最终绘制。

5.3 兼容性处理

微信小程序 ：使用 canvas-id 属性，并在 uni.createCanvasContext 时传入 this 实例，确保组件化后的上下文获取正确。
Android ：在 ctx.draw() 回调中加入 setTimeout(200ms)，解决部分安卓机型 Canvas 指令下发后未渲染完成就导出导致图片空白的问题。
H5 ：使用 uni.canvasToTempFilePath 的标准实现。

6. 参数配置 (Configuration)

目前参数为内部 data 配置，可根据需求提取为 props。

参数名	类型	默认值	说明
`cropSize`	Number	屏幕宽度的80%	裁剪框的大小（正方形），最大限制 400px
`scale-min`	Number	0.5	最小缩放倍数
`scale-max`	Number	4	最大缩放倍数
`destWidth`	Number	cropSize	输出图片的宽度（可设为 cropSize * pixelRatio 提高清晰度）

7. 目录结构示例

text 复制代码

├── pages
│   └── index
│       └── index.vue      # 核心代码文件
├── static
│   └── ...
├── App.vue
├── main.js
├── manifest.json
└── pages.json

8. 注意事项 (Notes)

Canvas 隐藏 ：Canvas 元素被放置在屏幕可视区域外 (left: -9999px)，请勿使用 display: none，否则在某些低版本真机上会导致无法绘制。
图片跨域 ：如果是 H5 环境且图片来自网络，需要确保图片服务器配置了 Access-Control-Allow-Origin，否则 Canvas 导出时会报错（Tainted canvases）。本地选择图片不受影响。
性能：处理超大分辨率图片（如 > 4000px）时，建议先进行压缩处理再传入编辑器，以免内存溢出（OOM）。