Flutter 图片裁剪插件 image_cropper 最新版介绍与使用教程

在很多移动应用中，我们需要让用户选择照片并裁剪它，比如在上传头像、设置封面图、编辑照片等场景。Flutter 提供了非常方便的第三方插件 image_cropper，帮助开发者快速实现跨平台的图片裁剪功能。本文将系统介绍这个插件的特点、安装配置及实战使用方法。

📦 什么是 image_cropper

image_cropper 是一个 Flutter 插件，用于在 Android、iOS 和 Web 平台实现图片的裁剪功能。该插件不是用 Dart 在 Flutter 层直接处理图像，而是利用平台通道（Platform Channel），调用各个平台原生的裁剪库来完成操作，在性能和体验上更接近原生。

其底层依赖的原生库如下：

Android：uCrop
iOS：TOCropViewController
Web：Cropper.js（已重构支持）

✨ 主要功能特点

✅ 跨平台支持：可在 Android、iOS 和 Web 平台运行
✅ 原生裁剪界面：根据不同平台提供本地体验
✅ 支持旋转、翻转与裁剪比例控制
✅ 可自定义裁剪界面主题与 UI 设置
✅ 导出裁剪后的图片，并支持多种格式与质量设定

🧩 安装与平台配置

1. 添加依赖

打开项目根目录下的 pubspec.yaml 文件，加入 image_cropper 依赖，同时搭配 image_picker 实现图片选择功能：

yaml 复制代码

dependencies:
  flutter:
    sdk: flutter
  image_cropper: ^# 替换为最新版本
  image_picker: ^# 替换为最新版本

添加完成后，执行以下命令拉取依赖：

bash 复制代码

flutter pub get

注意：Web 平台需要额外引入 Cropper.js 的 CSS/JS 文件，具体配置可参考官方文档。

2. Android 配置

在 android/app/src/main/AndroidManifest.xml 中添加必要的权限：

xml 复制代码

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

接着，在 AndroidManifest.xml 中注册 uCrop 的 Activity，并设置主题：

xml 复制代码

<activity
    android:name="com.yalantis.ucrop.UCropActivity"
    android:screenOrientation="portrait"
    android:theme="@style/Theme.AppCompat.Light.NoActionBar"/>

3. iOS 配置

在 ios/Runner/Info.plist 中添加相册和相机的权限说明（iOS 10+ 强制要求）：

xml 复制代码

<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册来选择照片</string>
<key>NSCameraUsageDescription</key>
<string>需要访问相机来拍摄照片</string>

🚀 实战示例：从相册选择图片并裁剪

下面实现一个最常见的业务场景：从相册选择图片 → 打开裁剪界面 → 获取裁剪后的图片。

📍 Step 1：使用 image_picker 选择图片

先通过 image_picker 插件从相册选取一张图片，获取图片的本地路径：

dart 复制代码

import 'package:image_picker/image_picker.dart';

// 选择图片的方法
Future<void> pickImage() async {
  final XFile? pickedFile = await ImagePicker().pickImage(
    source: ImageSource.gallery, // 指定从相册选择
  );
  if (pickedFile == null) return; // 用户取消选择
  final String imagePath = pickedFile.path;
  // 选择成功后，调用裁剪方法
  cropSelectedImage(imagePath);
}

📍 Step 2：调用 image_cropper 裁剪图片

引入 image_cropper 插件，传入图片路径并配置裁剪参数，打开裁剪界面：

dart 复制代码

import 'package:image_cropper/image_cropper.dart';
import 'package:flutter/material.dart';

// 裁剪图片的方法
Future<void> cropSelectedImage(String imagePath) async {
  final CroppedFile? croppedFile = await ImageCropper().cropImage(
    sourcePath: imagePath,
    // 配置不同平台的 UI 样式
    uiSettings: [
      AndroidUiSettings(
        toolbarTitle: '裁剪图片',
        toolbarColor: Colors.blue, // 工具栏颜色
        toolbarWidgetColor: Colors.white, // 工具栏文字颜色
        aspectRatioPresets: [
          CropAspectRatioPreset.square, // 1:1 比例
          CropAspectRatioPreset.ratio3x2,
          CropAspectRatioPreset.original,
        ],
        initAspectRatio: CropAspectRatioPreset.original, // 初始比例
        lockAspectRatio: false, // 是否锁定比例
      ),
      IOSUiSettings(
        title: '裁剪图片',
        aspectRatioLockEnabled: false,
      ),
    ],
  );

  if (croppedFile != null) {
    // 裁剪成功，获取裁剪后的图片路径
    final String croppedPath = croppedFile.path;
    print('裁剪完成，路径：$croppedPath');
    // 后续可将图片显示在页面上，或上传到服务器
  }
}

📌 常见使用建议

🔹 裁剪比例控制

如果是头像裁剪等需要固定比例的场景，可设置 lockAspectRatio: true，并指定默认比例：

dart 复制代码

AndroidUiSettings(
  // ... 其他配置
  lockAspectRatio: true, // 锁定比例，用户无法调整
)

🔹 Web 平台裁剪注意事项

Web 平台的裁剪功能依赖 Cropper.js，需要在 web/index.html 中引入对应的 CSS 和 JS：

html 复制代码

<!-- 在 head 标签中引入 CSS -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.1/cropper.min.css">
<!-- 在 body 标签末尾引入 JS -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.6.1/cropper.min.js"></script>

🔹 处理 Android 状态栏 UI 冲突

部分 Android 版本（如 Android 15）可能会出现裁剪界面状态栏颜色与主题不匹配的问题，可通过修改 UCropActivity 的主题解决，例如使用 Material 主题：

xml 复制代码

android:theme="@style/Theme.MaterialComponents.Light.NoActionBar"

🧠 总结

image_cropper 是 Flutter 生态中最常用的图片裁剪插件之一，它通过封装各平台原生裁剪库，兼顾了性能和跨平台一致性 ，结合 image_picker 基本可以满足大部分 App 的图片裁剪需求。

如果你的项目需要更高级的功能，比如自定义裁剪 UI 、支持桌面平台 ，可以了解其他插件，例如 crop_your_image（纯 Dart 实现，可高度自定义）、croppy 等。