we-cropper 圖片裁切上傳

微信小程序的圖片裁切組件——對戶外探險的「山區網速差 + 大量上傳」場景特別有用。

為什麼需要

戶外探險旅遊小程序的挑戰 維度 1 訊號：山區網速差，原圖一張 5MB 上傳會卡死。解法是：

1. 拍完先壓縮（用原生 Canvas）→ < 200KB
2. 裁切只保留主體（用 we-cropper）→ 視覺簡潔
3. 分片上傳 + 失敗重試（自寫，配 wenaox 離線狀態管理 outbox）

we-cropper 解的是 #2 那一塊——讓客人選好照片後可以裁框、調整、再上傳。

GitHub

https://github.com/we-plus/we-cropper

900+ stars，2018 起持續維護。

對 戶外探險旅遊小程序核心功能清單 的對應

功能	we-cropper 角色
#9 活動相簿（事後上傳）	客人挑照片 → we-cropper 裁切 → Canvas 壓縮 → outbox
#6 領隊資歷頁	領隊上傳照片時用，標準頭像比例
商業上傳 / 證書類	文件照標準裁切（如保險證明）

完整上傳流程

1. wx.chooseImage() 選相片
   ↓
2. we-cropper 裁切（指定比例如 16:9 / 1:1）
   ↓
3. Canvas API 壓縮到 < 200KB（quality=0.7、寬度 800px）
   ↓
4. wenaox dispatch 寫進 outbox.photos[]
   ↓
5. 上線後 batch upload（每張獨立 wx.uploadFile）
   ↓
6. 失敗的標 retry，下次同步繼續

為什麼這個 lib 不可省

如果不用 we-cropper：

• 客人上傳的照片比例混亂（直 / 橫 / 寬幅都有），相簿頁排版難看
• 客人自己選不出好看裁切（手動拖框體驗差）
• 後台儲存原始尺寸浪費（雲端費用）

we-cropper 用一個小組件解掉。

簡化使用範例

// 在 wxml
<we-cropper
  width="{{cropperOpt.width}}"
  height="{{cropperOpt.height}}"
  cut="{{cropperOpt.cut}}"
  src="{{cropperOpt.src}}"
  bindload="cropperLoad"
  bindready="cropperReady"
></we-cropper>
 
// 在 js
chooseImage() {
  wx.chooseImage({
    count: 1,
    success: ({ tempFilePaths }) => {
      this.setData({
        "cropperOpt.src": tempFilePaths[0]
      });
    }
  });
},
 
confirmCrop() {
  this.cropper.getCropperImage((src) => {
    // src 是裁好的圖片 path
    // 接 Canvas 壓縮 → 寫 outbox
    this.compressAndQueue(src);
  });
},

安裝

npm i we-cropper

或直接拉 source 進 components/ 目錄。

戶外探險專屬注意事項

山區照片特別處理

• 預設裁切比例可選 1:1（相簿縮圖）和 4:3（行程主圖）
• 提供「保留 metadata」選項——攝影師會想留 EXIF（拍攝時間 / GPS / 設備），一般客人不在乎
• 大圖預載 placeholder（光圈動畫）避免空白等待

配 Canvas 的壓縮設定

const ctx = wx.createCanvasContext("compressCanvas");
// ...draw image...
ctx.draw(false, () => {
  wx.canvasToTempFilePath({
    canvasId: "compressCanvas",
    quality: 0.7,        // 0-1，0.7 對戶外照夠用
    fileType: "jpg",
    success: ({ tempFilePath }) => {
      // 壓縮後路徑
    }
  });
});

v2 才用

MVP 階段不上傳照片（#9 活動相簿是 v2 功能），we-cropper 跟 wenaox 同步在 v2 導入。

替代選項

選項	為什麼可能不選
wxapp-img-loader	不一樣的東西（預載而非裁切）
wxa-plugin-canvas	海報生成用，可跟 we-cropper 並存
自寫裁切	UX 差，重新發明輪子
只壓縮不裁切	照片比例還是亂

反模式

❌ 上傳原圖（網速差 + 流量爆） ❌ 客戶端不裁切，全部丟 server 處理（server 端 cost） ❌ 壓縮率太低（quality > 0.85）導致照片太大 ❌ 用 lib 但忘了 Canvas 壓縮（裁切後仍可能很大）

相關概念

強連結（戶外探險專屬）

• 小程序開發 lib 選型 — 為什麼選 we-cropper
• 戶外探險旅遊小程序核心功能清單 — #9 活動相簿核心 lib
• 戶外探險旅遊小程序的挑戰 — 訊號維度反推
• 多日離線行程設計 — 配 wenaox outbox 處理離線拍照
• wenaox 離線狀態管理 — 兩個 lib 串起來才完整

深入閱讀（外部資源）

• GitHub：https://github.com/we-plus/we-cropper

← 回到 wiki