Flutter 鸿蒙跨端开发实战：集成三方库实现图片选择功能

本文面向鸿蒙 + Flutter 新手开发者，基于Flutter + 三方库 + 鸿蒙技术组合，搭建可直接运行的完整实战项目。通过集成成熟三方库，快速实现鸿蒙端本地相册图片选择、权限申请、图片预览完整业务功能，全程分步教学、代码全注释、环境适配鸿蒙系统，零基础也能一键复现。项目名称：Flutter 鸿蒙相册选择工具核心技术：Flutter 框架、第三方开源库、鸿蒙 Stage 模型适配核心三方库i

Ferrari805

94人浏览 · 2026-04-26 14:47:11

Ferrari805 · 2026-04-26 14:47:11 发布

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

一、前言

本文面向鸿蒙 + Flutter 新手开发者，基于Flutter + 三方库 + 鸿蒙技术组合，搭建可直接运行的完整实战项目。通过集成成熟三方库，快速实现鸿蒙端本地相册图片选择、权限申请、图片预览完整业务功能，全程分步教学、代码全注释、环境适配鸿蒙系统，零基础也能一键复现。

二、项目介绍

项目名称：Flutter 鸿蒙相册选择工具

核心技术：Flutter 框架、第三方开源库、鸿蒙 Stage 模型适配

核心三方库

image_picker：跨平台图片选择核心三方库，原生兼容鸿蒙
permission_handler：鸿蒙权限管理三方库

实现功能

鸿蒙设备动态申请相册权限
调用鸿蒙原生相册
图片选中后实时页面渲染预览
纯 Flutter 代码，兼容鸿蒙设备

三、开发环境前置要求

Flutter SDK 3.27.5-ohos 及以上（鸿蒙适配版本）
DevEco Studio 已配置鸿蒙开发环境
鸿蒙模拟器 / 鸿蒙真机设备
电脑已配置 Flutter 环境变量

四、第一步：创建 Flutter 鸿蒙项目

打开终端，执行创建项目命令

flutter create flutter_harmony_demo
cd flutter_harmony_demo

执行完成后，项目根目录自动生成 ohos 文件夹，代表项目已支持鸿蒙系统（鸿蒙适配版Flutter会自动创建，无需额外命令）。

五、第二步：引入三方库依赖

打开项目根目录 pubspec.yaml，替换依赖配置：

name: flutter_harmony_demo
description: Flutter结合三方库开发鸿蒙应用实战案例
version: 1.0.0+1

environment:
  sdk: '>=3.16.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  # 图片选择三方库 兼容鸿蒙
  image_picker: ^1.1.0
  # 权限管理三方库 适配鸿蒙权限机制
  permission_handler: ^11.3.0

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true

保存文件后，终端执行依赖安装：

flutter pub get

六、第三步：鸿蒙系统权限配置

鸿蒙系统对隐私权限强管控，必须手动配置相册读取权限。

权限配置文件路径

ohos/entry/src/main/module.json5

添加媒体读取权限

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone","tablet"],
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "$string:media_permission_desc",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

配置权限说明文案

路径：ohos/entry/src/main/resources/zh_CN/element/string.json

{
  "string": [
    {
      "name": "media_permission_desc",
      "value": "用于访问本地相册，选择展示图片"
    }
  ]
}

七、第四步：完整业务代码编写（全注释）

替换 lib/main.dart 全部代码：

// 引入Flutter基础UI组件库
import 'package:flutter/material.dart';
// 引入图片选择三方库
import 'package:image_picker/image_picker.dart';
// 引入权限管理三方库
import 'package:permission_handler/permission_handler.dart';
// 引入文件操作类
import 'dart:io';

void main() {
  // 程序入口，启动根组件
  runApp(const MyHarmonyApp());
}

// 根组件 无状态
class MyHarmonyApp extends StatelessWidget {
  const MyHarmonyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "Flutter三方库鸿蒙开发",
      theme: ThemeData(primaryColor: Colors.teal),
      debugShowCheckedModeBanner: false, // 关闭debug标识
      home: const GallerySelectPage(),
    );
  }
}

// 核心页面 有状态组件（需要动态更新图片）
class GallerySelectPage extends StatefulWidget {
  const GallerySelectPage({super.key});

  @override
  State<GallerySelectPage> createState() => _GallerySelectPageState();
}

class _GallerySelectPageState extends State<GallerySelectPage> {
  // 存储选中的本地图片文件
  File? _imageFile;
  // 实例化三方库图片选择器对象
  final ImagePicker _picker = ImagePicker();

  /// 申请鸿蒙相册权限
  Future<void> requestMediaPermission() async {
    // 调用三方库申请存储/媒体权限
    PermissionStatus status = await Permission.photos.request();
    // 权限拒绝提示
    if(status.isDenied){
      if(mounted){
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(content: Text("权限已拒绝，无法打开相册"))
        );
      }
    }
  }

  /// 调用三方库 打开鸿蒙相册选择图片
  Future<void> selectImageFromGallery() async {
    // 第一步：先申请权限
    await requestMediaPermission();

    // 第二步：调用image_picker三方库API
    final XFile? result = await _picker.pickImage(
      source: ImageSource.gallery, // 数据源：系统相册
      imageQuality: 90, // 图片压缩质量
    );

    // 第三步：判断是否选择了图片
    if(result != null){
      setState(() {
        // 更新UI，保存图片路径
        _imageFile = File(result.path);
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Flutter+三方库+鸿蒙 实战"),
        centerTitle: true,
      ),
      body: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          children: [
            // 图片展示区域
            Expanded(
              child: _imageFile != null
                  ? Image.file(
                      _imageFile!,
                      fit: BoxFit.contain,
                    )
                  : const Center(
                      child: Text(
                        "暂无选中图片\n点击下方按钮选择",
                        style: TextStyle(fontSize: 16,color: Colors.grey),
                      ),
                    ),
            ),
            const SizedBox(height: 30),
            // 触发按钮
            SizedBox(
              width: double.infinity,
              height: 50,
              child: ElevatedButton(
                onPressed: selectImageFromGallery,
                style: ElevatedButton.styleFrom(
                  backgroundColor: Colors.teal,
                  shape: RoundedRectangleBorder(
                    borderRadius: BorderRadius.circular(10)
                  )
                ),
                child: const Text(
                  "打开鸿蒙相册",
                  style: TextStyle(fontSize: 18,color: Colors.white),
                ),
              ),
            )
          ],
        ),
      ),
    );
  }
}