小程序图片裁剪 we-cropper 集成指南：改好两个文件就能用
【免费下载链接】we-cropper微信小程序图片裁剪工具项目地址: https://gitcode.com/gh_mirrors/we/we-cropper
先看一下目录：一行装好 → 参数过一遍 → 最小集成 → 图片进、路径出 → canvas2d → 高频坑 → 文档与示例位置。
we-cropper 是一款面向微信小程序的轻量级图片裁剪工具，核心逻辑全在 canvas 上：把图片放上画布、框出裁剪区，用户双指缩放拖动，最终拿到裁剪后图片的临时路径。集成只动 WXML 和 JS 两个文件，参数十几个，全部过完就能开工。
一行 npm 装好，二次开发再克隆
小程序工程已用 npm 构建依赖的话，执行npm install we-cropper --save即可。构建完成后把 we-cropper 的源文件拷进项目固定目录，WXML 里按相对路径引用。
需要读源码或二次开发时，直接克隆仓库：git clone https://gitcode.com/gh_mirrors/we/we-cropper。仓库里的 example/ 是一套完整示例，按场景找最接近的起点改，比对着文档从头写省时间。
先把裁剪器参数过一遍
WeCropper 的所有配置都集中在传给构造器的 cropperOpt 对象里，常用的就这几个：
id：手势展示用的 canvas 标识符（canvas-id），必填，对应模板里第一个 canvas。targetId：出图用的 canvas 标识符，必填。这个 canvas 藏在屏幕外，只负责生成结果截图。pixelRatio：设备像素比，用wx.getSystemInfoSync()取，别写死；漏传会让高分屏上的出图发虚。width/height：画布容器宽高，单位 px，模板内 canvas 的尺寸由这里决定。scale：最大缩放倍数，默认 2.5。zoom：缩放系数，取值 1 ~ 10，默认 5，数值越大缩放步进越细。cut：裁剪框{x, y, width, height}，单位 px，不传则整个画布都是裁剪区。做小程序头像裁剪这类固定比例场景，把 width 和 height 设成想要的比例即可，比如 1:1。
改好两个文件就能裁剪
WXML 端只有两件事：引入模板、使用模板，放到需要裁剪的页面里：
<import src="../we-cropper/we-cropper.wxml"/> <view class="cropper-wrapper"> <template is="we-cropper" data="{{...cropperOpt}}"/> </view>模板内部带了两个 canvas，一个显示、一个离屏出图，别删别挪；src 路径以 we-cropper 文件实际存放位置为准。
JS 端做两件事：实例化、订阅事件：
import WeCropper from '../we-cropper/we-cropper.js' const device = wx.getSystemInfoSync() Page({ data: { cropperOpt: { id: 'cropper', // 手势操作的 canvas 标识 targetId: 'targetCropper', // 生成截图的 canvas 标识 pixelRatio: device.pixelRatio, // 设备像素比 width: device.windowWidth, height: device.windowWidth, scale: 2.5, // 最大缩放倍数 zoom: 8, // 缩放系数 cut: { x: 0, y: 0, width: 200, height: 200 } // 裁剪框，单位 px } }, onLoad() { this.cropper = new WeCropper(this.data.cropperOpt) .on('imageLoad', () => console.log('图片已加载')) } })事件订阅支持 ready、beforeImageLoad、imageLoad、beforeDraw 四个，按需监听。手势这边在 Page 里补上 touchStart、touchMove、touchEnd 三个方法，各自一行把事件对象 e 转给实例同名方法即可，模板里 canvas 上的触摸绑定会自动生效。选图同样一句话：wx.chooseImage选完在 success 回调里把res.tempFilePaths[0]交给this.cropper.pushOrign(src)载入，本地临时文件、存储文件、网络图片地址都可以。
图片进来，路径出去
pushOrign 之后，beforeImageLoad 和 imageLoad 两个事件适合用来开关 loading 提示，前者弹 toast，后者收起。用户调好位置后调用this.cropper.getCropperImage(callback)，回调收到裁剪后图片路径和异常两个参数：路径非空即可交给wx.uploadFile上传服务端，或wx.previewImage当场预览。该方法返回 Promise，习惯 then/catch 的写法也可以。
什么时候该切 canvas2d
基础库 2.9.0 以上可以上 canvas2d 模式，取 canvas 的方式变了：用this.createSelectorQuery()按 id 选中 canvas，fields 里加node: true, size: true，回调里从结果取 node，再canvas.getContext('2d')拿到上下文。高分屏处理三步不能省：canvas 的 width 和 height 乘以像素比，ctx.scale按同比例缩放，然后把 canvas 与 ctx 塞进 cropperOpt 再实例化。切过去之后不再需要 targetId，截图走同一个 canvas。完整写法在 example/canvas2d/ 有现成页面。
三个高频坑
⚠️ 触摸事件没绑全。页面能显示图片，但缩放拖动毫无反应，先检查 Page 里 touchStart、touchMove、touchEnd 是否都定义了并且真的转给了实例。
width/height 与 canvas 实际尺寸不一致。模板里 canvas 的尺寸由构造参数写入，再用 wxss 覆盖它、或后续改动参数不同步，遮罩和裁剪框就会错位，出图被切掉一块。
把 targetId 的 canvas 当冗余删掉。它是刻意用负偏移放到屏幕外的，职责只有截图；删掉或加 display:none，getCropperImage 就出不了图。
文档和示例在哪找
完整参数表、方法、事件说明在 官方文档 docs/，速查看 docs/api.md。example/ 下每个场景都有一页可跑：normal 基础裁剪，avatarUpload 小程序头像裁剪流程，watermark 裁剪时加水印，network 网络图片裁剪，canvas2d 新画布模式。工程是 TypeScript 的话，types/ 目录下的 .d.ts 可以顺手接上做类型检查。
【免费下载链接】we-cropper微信小程序图片裁剪工具项目地址: https://gitcode.com/gh_mirrors/we/we-cropper
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
