更新记录

1.0.1（2026-02-04） 下载此版本

初始版本发布。支持基础裁剪、旋转、缩放。修复了旋转后的坐标偏移 Bug。

平台兼容性

uni-app(3.7.0)

uni-app x(4.61)

其他

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

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 安装。只需将核心文件复制到项目中：

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

4.2 注册页面

在 pages.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 阶段实现了以下映射逻辑：

1. 计算图片中心点相对于裁剪框中心的屏幕偏移向量 (diffX, diffY)。

2. 根据旋转角度 (0, 90, 180, 270) 将向量映射到 Canvas 坐标系。

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

3. 使用 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。

7. 目录结构示例

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

8. 注意事项 (Notes)

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