fluttertpc_image_cropper 在鸿蒙上的使用指南

fluttertpc_image_cropper是为鸿蒙系统适配的Flutter图片裁剪插件，基于image_cropper@2.0.0开发。主要特性包括：支持多种预设裁剪比例（正方形、16:9等）、矩形/圆形裁剪样式、JPG/PNG压缩格式，以及自定义裁剪区域和图片质量。安装时需添加Git依赖并配置网络权限。核心API提供cropImage函数，支持设置最大宽高、裁剪比例、压缩质量等参数。使用示

ntfy456

779人浏览 · 2025-12-19 22:03:16

ntfy456 · 2025-12-19 22:03:16 发布

一、插件介绍

fluttertpc_image_cropper 是基于 image_cropper@2.0.0 开发的鸿蒙系统适配版本，为 Flutter 开发者提供在鸿蒙平台上进行图片裁剪的功能。该插件支持多种裁剪比例预设、裁剪样式和图片压缩格式，帮助开发者轻松实现图片裁剪需求。

主要特性

支持多种裁剪比例预设（原始比例、正方形、16:9等）
提供矩形和圆形两种裁剪样式
支持 JPG 和 PNG 两种图片压缩格式
可自定义裁剪区域大小和图片质量
基于原生鸿蒙实现，性能优秀

二、安装与配置

1. 添加依赖

在项目的 pubspec.yaml 文件中添加以下依赖：

dependencies:
  image_cropper:
    git:
      url: "https://gitcode.com/openharmony-sig/fluttertpc_image_cropper.git"
      path: "./image_cropper"

  imagecropper_ohos:
    git:
      url: "https://gitcode.com/openharmony-sig/fluttertpc_image_cropper.git"
      path: "./image_cropper/ohos"

执行以下命令获取依赖：

flutter pub get

2. 配置权限

在 entry/src/main/module.json5 文件中添加网络权限声明：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET",
    "reason": "$string:network_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when":"inuse"
    }
  }
]

在 entry/src/main/resources/base/element/string.json 文件中添加权限说明：

{
  "string": [
    {
      "name": "network_reason",
      "value": "使用网络"
    }
  ]
}

三、API 说明

核心函数

`cropImage`

Future<CroppedFile?> cropImage(
  required String sourcePath,
  int? maxWidth,
  int? maxHeight,
  CropAspectRatio? aspectRatio,
  List<CropAspectRatioPreset> aspectRatioPresets,
  CropStyle cropStyle = CropStyle.rectangle,
  ImageCompressFormat compressFormat = ImageCompressFormat.jpg,
  int compressQuality = 90,
  List<PlatformUiSettings>? uiSettings
)

参数说明

参数名	类型	说明
sourcePath	String	要裁剪的图片路径
maxWidth	int	裁剪后图片的最大宽度
maxHeight	int	裁剪后图片的最大高度
aspectRatio	CropAspectRatio	自定义裁剪比例
aspectRatioPresets	List	裁剪比例预设列表
cropStyle	CropStyle	裁剪样式（矩形或圆形）
compressFormat	ImageCompressFormat	图片压缩格式（JPG或PNG）
compressQuality	int	图片压缩质量（0-100）

数据类型

`CropAspectRatio`

属性	类型	说明
ratioX	double	水平方向的比例
ratioY	double	竖直方向的比例

`CropAspectRatioPreset`

预设值	说明
original	原始比例
square	正方形比例
ratio3x2	3:2矩形比例
ratio5x3	5:3矩形比例
ratio4x3	4:3矩形比例
ratio5x4	5:4矩形比例
ratio7x5	7:5矩形比例
ratio16x9	16:9矩形比例

`CropStyle`

样式	说明
rectangle	矩形裁剪
circle	圆形裁剪

`ImageCompressFormat`

格式	说明
jpg	JPG格式（有损压缩）
png	PNG格式（无损压缩）

`CroppedFile`

属性	类型	说明
path	String	裁剪后文件的完整路径
_initBytes	Unit8List	裁剪操作前的原始图像字节数据

四、使用示例

完整示例代码

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

class ImageCropperDemo extends StatefulWidget {
  @override
  _ImageCropperDemoState createState() => _ImageCropperDemoState();
}

class _ImageCropperDemoState extends State<ImageCropperDemo> {
  String? _pickedFile;
  String? _croppedFile;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('图片裁剪示例')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (_croppedFile != null || _pickedFile != null)
              ConstrainedBox(
                constraints: BoxConstraints(
                  maxWidth: 300,
                  maxHeight: 300,
                ),
                child: Image.file(File(_croppedFile ?? _pickedFile!)),
              ),
            SizedBox(height: 20),
            ElevatedButton(
              onPressed: () => _pickImage(),
              child: Text('选择图片'),
            ),
            if (_pickedFile != null)
              ElevatedButton(
                onPressed: () => _cropImage(),
                child: Text('裁剪图片'),
              ),
          ],
        ),
      ),
    );
  }

  Future<void> _pickImage() async {
    final pickedFile = await ImagePicker().pickImage(source: ImageSource.gallery);
    if (pickedFile != null) {
      setState(() {
        _pickedFile = pickedFile.path;
        _croppedFile = null;
      });
    }
  }

  Future<void> _cropImage() async {
    if (_pickedFile != null) {
      try {
        final croppedFile = await ImageCropper().cropImage(
          sourcePath: _pickedFile!,
          aspectRatioPresets: [
            CropAspectRatioPreset.square,
            CropAspectRatioPreset.ratio3x2,
            CropAspectRatioPreset.ratio4x3,
            CropAspectRatioPreset.ratio16x9
          ],
          cropStyle: CropStyle.rectangle,
          compressFormat: ImageCompressFormat.jpg,
          compressQuality: 90,
          maxWidth: 800,
          maxHeight: 800,
        );

        if (croppedFile != null) {
          setState(() {
            _croppedFile = croppedFile.path;
          });
        }
      } catch (e) {
        print('裁剪失败: $e');
      }
    }
  }
}