欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net

前言

在 Flutter 跨平台适配鸿蒙生态的开发过程中，图片相关功能是移动端应用最常用的基础能力之一。相比于从零编写图片选择、缩放、预览逻辑，合理使用成熟稳定的 Flutter 三方库，能够显著提升开发效率，同时保证在鸿蒙设备上的运行体验。

本文基于 Flutter + 鸿蒙6.0（API20+） 环境，从零实现一款功能完整的图片预览管理APP，实现相册图片选取、相机拍照录入、网格列表展示、高清手势缩放预览、长按删除等实用功能。全文步骤清晰、代码规范、原创度高，非常适合作为 Flutter 接入鸿蒙生态的入门实战案例。

一、开发环境准备

在开始开发前，需要搭建好 Flutter 与鸿蒙协同开发环境，确保项目能够正常编译运行。

• Flutter SDK：3.16.0 及以上稳定版本
• DevEco Studio：5.0.1 及以上版本
• 鸿蒙 SDK：API20（HarmonyOS 6.0）
• 设备支持：鸿蒙6.0 真机或系统模拟器

启用 Flutter 对鸿蒙平台的支持：

flutter config --enable-openharmony
flutter doctor

出现 OpenHarmony 相关项即表示环境配置成功。

二、Flutter 项目创建与鸿蒙配置

2.1 新建 Flutter 项目

在命令行执行指令，创建支持鸿蒙平台的 Flutter 项目：

flutter create flutter_harmony_image_manager
cd flutter_harmony_image_manager

2.2 鸿蒙平台版本适配

打开 openharmony/app/build.gradle 文件，修改 SDK 版本配置，确保最低适配鸿蒙6.0：

openharmony {
    compileSdkVersion 20
    defaultConfig {
        minSdkVersion 20
        targetSdkVersion 20
        versionCode 1
        versionName "1.0.0"
    }
}

三、鸿蒙兼容三方库引入

为保证在鸿蒙系统上稳定运行，本项目选用经过大量实践验证的三方库，避免兼容性问题。

三方库名称	版本号	主要功能
image_picker	^1.0.4	鸿蒙平台相册选取、相机拍照
photo_view	^0.14.0	图片手势缩放、双击放大、预览
fluttertoast	^8.2.8	鸿蒙风格轻量提示
cached_network_image	^3.3.0	图片缓存优化，提升加载体验

在 pubspec.yaml 文件中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  image_picker: ^1.0.4
  photo_view: ^0.14.0
  fluttertoast: ^8.2.8
  cached_network_image: ^3.3.0

执行命令安装三方库：

flutter pub get

四、完整功能代码实现

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

void main() {
  runApp(const MainApp());
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter鸿蒙图片管理器',
      theme: ThemeData(
        primarySwatch: Colors.blueGrey,
        useMaterial3: true,
      ),
      home: const ImageManagerPage(),
      debugShowCheckedModeBanner: false,
    );
  }
}

class ImageManagerPage extends StatefulWidget {
  const ImageManagerPage({super.key});

  @override
  State<ImageManagerPage> createState() => _ImageManagerPageState();
}

class _ImageManagerPageState extends State<ImageManagerPage> {
  final ImagePicker _picker = ImagePicker();
  final List<File> _imageList = [];

  // 从相册选择图片
  Future<void> pickGalleryImage() async {
    final XFile? file = await _picker.pickImage(
      source: ImageSource.gallery,
      imageQuality: 80,
    );
    if (file != null) {
      setState(() {
        _imageList.add(File(file.path));
      });
      Fluttertoast.showToast(msg: "图片选取成功");
    }
  }

  // 相机拍照
  Future<void> takeCameraImage() async {
    final XFile? file = await _picker.pickImage(
      source: ImageSource.camera,
      imageQuality: 85,
    );
    if (file != null) {
      setState(() {
        _imageList.add(File(file.path));
      });
      Fluttertoast.showToast(msg: "拍照完成");
    }
  }

  // 进入图片预览页面
  void toPreviewPage(File image) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (ctx) => ImagePreviewPage(image: image),
      ),
    );
  }

  // 删除选中图片
  void deleteImage(int index) {
    setState(() {
      _imageList.removeAt(index);
    });
    Fluttertoast.showToast(msg: "已删除该图片");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Flutter+鸿蒙 图片管理器"),
      ),
      body: Column(
        children: [
          Padding(
            padding: const EdgeInsets.symmetric(horizontal: 20, vertical: 10),
            child: Row(
              mainAxisAlignment: MainAxisAlignment.spaceAround,
              children: [
                ElevatedButton(
                  onPressed: pickGalleryImage,
                  child: const Text("相册选择"),
                ),
                ElevatedButton(
                  onPressed: takeCameraImage,
                  child: const Text("相机拍照"),
                ),
              ],
            ),
          ),
          const Divider(),
          Expanded(
            child: _imageList.isEmpty
                ? const Center(
                    child: Text(
                      "暂无图片，请添加图片",
                      style: TextStyle(fontSize: 16, color: Colors.grey),
                    ),
                  )
                : GridView.builder(
                    padding: const EdgeInsets.all(8),
                    gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
                      crossAxisCount: 3,
                      crossAxisSpacing: 6,
                      mainAxisSpacing: 6,
                    ),
                    itemCount: _imageList.length,
                    itemBuilder: (context, index) {
                      return GestureDetector(
                        onTap: () => toPreviewPage(_imageList[index]),
                        onLongPress: () => deleteImage(index),
                        child: ClipRRect(
                          borderRadius: BorderRadius.circular(8),
                          child: Image.file(
                            _imageList[index],
                            fit: BoxFit.cover,
                          ),
                        ),
                      );
                    },
                  ),
          ),
        ],
      ),
    );
  }
}

// 独立图片预览组件
class ImagePreviewPage extends StatelessWidget {
  final File image;

  const ImagePreviewPage({super.key, required this.image});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("预览")),
      body: PhotoView(
        imageProvider: FileImage(image),
        minScale: PhotoViewComputedScale.contained * 0.8,
        maxScale: PhotoViewComputedScale.covered * 2.5,
        backgroundDecoration: const BoxDecoration(color: Colors.black),
      ),
    );
  }
}

五、鸿蒙6.0 权限配置

图片选择与相机功能需要在鸿蒙平台配置对应权限，否则无法正常使用。
在 openharmony/app/src/main/module.json5 中添加：

"requestPermissions": [
  {
    "name": "ohos.permission.READ_MEDIA",
    "reason": "读取相册图片"
  },
  {
    "name": "ohos.permission.CAMERA",
    "reason": "调用相机进行拍摄"
  },
  {
    "name": "ohos.permission.WRITE_MEDIA",
    "reason": "存储图片资源"
  }
]

六、项目运行与效果展示

1. 连接鸿蒙6.0 设备或启动模拟器
2. 执行运行指令：

flutter run -d 设备ID

实现功能清单：

• 支持从鸿蒙相册选取图片
• 支持相机实时拍照并展示
• 九宫格布局整齐展示图片
• 点击进入高清预览，支持手势缩放
• 长按快速删除图片
• 适配鸿蒙全面屏与交互逻辑
• 三方库在鸿蒙平台运行稳定

七、常见问题及解决方案

1. 三方库在鸿蒙设备无法使用
   执行 flutter pub upgrade 更新库至最新版本，确保兼容 API20。

2. 无法访问相册或相机
   检查 module.json5 权限是否配置完整，并在设备设置中手动开启权限。

3. 图片显示拉伸或模糊
   使用 BoxFit.cover 保持图片比例，避免拉伸变形。

八、总结

本文通过完整实战，实现了 Flutter 集成三方库开发鸿蒙6.0 图片预览管理APP，从环境搭建、项目创建、三方库引入，到功能实现、鸿蒙平台适配、权限配置，覆盖了 Flutter 接入鸿蒙生态的全流程。

借助 image_picker、photo_view 等成熟三方库，快速实现了图片选择、预览、缩放等核心功能，同时严格遵循鸿蒙系统规范，保证应用在鸿蒙设备上流畅运行。项目结构清晰、代码规范、可直接用于学习、实训或毕业设计，具有较高的学习与实用价值。