react-easy-crop介绍

react-easy-crop 是一个 React 的图片/视频裁剪组件，提供了一个可交互的裁剪区域，支持缩放、拖拽、旋转等操作，常用于头像裁剪、封面编辑、图片预览裁剪等场景。

1. 核心功能

图片或视频裁剪
- 支持矩形或圆形裁剪框
拖拽、缩放、旋转
- 用户可以拖动图片，调整裁剪区域
响应式支持
- 裁剪区域可以自动适应容器大小
实时回调
- 拖动或缩放时，能实时拿到裁剪数据（croppedArea 和 croppedAreaPixels）
只负责 UI，不导出最终图片
- 它只负责提供裁剪坐标，最终裁剪的图片需配合 Canvas 或其他方法生成

2. 安装

npm install react-easy-crop

3. 基本用法

最常见的场景：头像裁剪

import React, { useState } from "react";
import Cropper from "react-easy-crop";

function ImageCropper({ imageUrl }) {
  const [crop, setCrop] = useState({ x: 0, y: 0 })
  const [zoom, setZoom] = useState(1)
  const [croppedArea, setCroppedArea] = useState(null)

  const onCropComplete = (croppedArea, croppedAreaPixels) => {
    // croppedArea 是百分比
    // croppedAreaPixels 是像素坐标
    setCroppedArea(croppedAreaPixels)
    console.log('裁剪区域像素:', croppedAreaPixels)
  }

  return (
    <div style={{ position: "relative", width: 400, height: 300 }}>
      <Cropper
        image={imageUrl}             // 图片地址
        crop={crop}                  // 当前裁剪位置
        zoom={zoom}                  // 缩放比例
        aspect={4 / 3}               // 裁剪框比例，例如 1/1 = 正方形
        onCropChange={setCrop}       // 拖拽回调
        onZoomChange={setZoom}       // 缩放回调
        onCropComplete={onCropComplete} // 裁剪完成时回调
      />
    </div>
  )
}

export default ImageCropper

上面例子只提供了裁剪 UI，如果要导出裁剪后的图片，需要结合 Canvas：

4. 获取裁剪后的图片

官方推荐自己用 Canvas 处理，例如：

import { createImage, getCroppedImg } from './cropUtils'

// cropUtils.js
export const getCroppedImg = async (imageSrc, crop) => {
  const image = await createImage(imageSrc)
  const canvas = document.createElement('canvas')
  const ctx = canvas.getContext('2d')

  canvas.width = crop.width
  canvas.height = crop.height

  ctx.drawImage(
    image,
    crop.x, crop.y, crop.width, crop.height, // 源图裁剪区域
    0, 0, crop.width, crop.height            // 目标画布区域
  )

  return canvas.toDataURL('image/jpeg')
}

function createImage(url) {
  return new Promise((resolve, reject) => {
    const img = new Image()
    img.src = url
    img.crossOrigin = "anonymous"
    img.onload = () => resolve(img)
    img.onerror = reject
  })
}

结合 onCropComplete 的 croppedAreaPixels，即可导出最终裁剪图。

5. 常用 Props

Prop	说明
`image`	图片地址（必填）
`video`	视频地址（可选）
`crop`	裁剪位置 `{x, y}`
`zoom`	缩放比例（默认 1）
`rotation`	旋转角度（0~360）
`aspect`	裁剪框宽高比（默认自由）
`onCropChange`	裁剪位置变化回调
`onZoomChange`	缩放变化回调
`onRotationChange`	旋转变化回调
`onCropComplete`	裁剪完成时触发，返回像素和百分比区域
`cropShape`	`"rect"` 或 `"round"`，圆形常用于头像
`showGrid`	是否显示裁剪辅助网格线

6. 典型应用场景

用户头像上传与裁剪
社交 App 选择封面图
图片编辑工具的裁剪功能
视频封面或缩略图裁剪

总结：

react-easy-crop 是专注裁剪 UI 的库，支持拖拽、缩放、旋转
优点：轻量、交互自然、支持像素级精度
缺点：不直接导出裁剪后的图片，需要自己配合 Canvas 处理