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

摘要

图片选择、相机拍照是移动应用必备基础能力，image_picker 是 Flutter 生态最主流的多媒体选择三方库，支持相册选图、相机拍照、图片裁剪、格式压缩等能力，广泛用于头像上传、实名认证、内容发布等业务场景。OpenHarmony 鸿蒙系统具备独立的相机权限、相册权限、文件沙箱机制，原生 image_picker 直接接入 Flutter-OH 项目会出现相册无法打开、相机调用失败、图片返回为空、权限被拦截等兼容问题。本文基于 DevEco Studio 开发环境，从零讲解 Flutter-OH 项目搭建、image_picker 依赖引入、鸿蒙权限配置、相册 / 相机适配、完整代码编写、真机 / 模拟器运行验证全流程，归纳该库在鸿蒙平台适配的常见问题与解决方案，为 Flutter 多媒体类三方库鸿蒙化适配提供标准实操范本。

关键词

Flutter-OH；OpenHarmony；三方库适配；image_picker；图片选择；相机拍照

一、引言

1.1 三方库适配背景

OpenHarmony 生态快速扩张，Flutter-OH 作为鸿蒙定制版跨平台框架，凭借高效开发、UI 一致性强、多端复用等优势，成为企业级鸿蒙应用开发首选方案。在电商、社交、工具类应用中，头像更换、身份证上传、图片发布等需求高频出现，image_picker 凭借简洁 API、跨平台稳定、无侵入式集成，成为 Flutter 开发者首选图片选择库。

但鸿蒙系统对相机、相册、存储实行严格权限隔离，应用必须动态申请权限且遵循沙箱机制，原生 image_picker 未针对鸿蒙平台做权限与路径适配，直接接入会出现相册无法访问、相机启动闪退、获取图片为空、文件读取失败等问题，无法满足业务多媒体需求。因此落地 image_picker 完整鸿蒙适配，对 Flutter-OH 项目多媒体功能开发具备极高实用价值。

1.2 开发环境介绍

开发工具：DevEco Studio运行平台：OpenHarmony 模拟器 / 鸿蒙真机开发框架：Flutter-OH（鸿蒙定制版 Flutter）适配三方库：image_picker: ^1.0.4测试场景：相册选择图片、相机拍照、图片返回展示、文件路径读取

二、前期环境准备

2.1 创建 Flutter-OH 项目

打开 DevEco Studio，选择「新建项目」；选择 Flutter for OpenHarmony 模板，命名项目为 flutter_image_picker_oh_demo；等待项目初始化完成，生成鸿蒙标准工程目录；终端执行环境校验命令：

flutter --version
flutter devices

能正常识别 ohos 设备，代表环境配置无误。

2.2 鸿蒙核心权限配置

image_picker 依赖相机、相册、存储读写权限，是鸿蒙管控最严格的权限组。打开路径：ohos/app/src/main/module.json5，添加如下权限配置：

"requestPermissions": [
  {
    "name": "ohos.permission.CAMERA",
    "reason": "应用需要调用相机进行拍照",
    "usedScene": {
      "abilities": [".MainAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.READ_MEDIA",
    "reason": "读取相册图片文件",
    "usedScene": {
      "abilities": [".MainAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.WRITE_MEDIA",
    "reason": "保存图片至本地相册",
    "usedScene": {
      "abilities": [".MainAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.INTERNET",
    "reason": "网络上传图片",
    "usedScene": {
      "abilities": [".MainAbility"],
      "when": "inuse"
    }
  }
]

2.3 鸿蒙文件访问配置

在 module.json5 中增加文件访问配置，确保相册图片可正常读取：

"bundleType": "app",
"network": {
  "cleartextTraffic": true
}

三、image_picker 三方库引入与基础配置

3.1 引入依赖

打开项目根目录 pubspec.yaml，添加依赖：

dependencies:
  flutter:
    sdk: flutter
  image_picker: ^1.0.4

3.2 安装依赖

终端执行：

flutter pub get

无报错即为引入成功。

3.3 鸿蒙适配说明

image_picker 在 Flutter-OH 环境中可直接运行，无需修改鸿蒙原生代码。适配核心：

1. 必须配置相机、媒体读写权限；
2. 鸿蒙真机必须手动授权；
3. 模拟器不支持相机，仅支持相册模拟选择。整体适配成本低，业务层代码无需改造。

四、完整代码实现

4.1 全局图片选择工具类封装

新建 utils/image_picker_utils.dart：

import 'package:image_picker/image_picker.dart';

class ImagePickerUtils {
  static final ImagePicker _picker = ImagePicker();

  // 从相册选择图片
  static Future<XFile?> pickImageFromGallery() async {
    final XFile? image = await _picker.pickImage(
      source: ImageSource.gallery,
      imageQuality: 80,
    );
    return image;
  }

  // 相机拍照
  static Future<XFile?> takeImageFromCamera() async {
    final XFile? image = await _picker.pickImage(
      source: ImageSource.camera,
      imageQuality: 80,
    );
    return image;
  }
}

4.2 页面功能测试代码

main.dart 完整代码：

import 'package:flutter/material.dart';
import 'dart:io';
import 'utils/image_picker_utils.dart';

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

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: "ImagePicker 鸿蒙适配",
      theme: ThemeData(primarySwatch: Colors.purple),
      home: const HomePage(),
    );
  }
}

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

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  XFile? selectedImage;

  // 相册选择
  Future<void> pickGalleryImage() async {
    var image = await ImagePickerUtils.pickImageFromGallery();
    if (image != null) {
      setState(() {
        selectedImage = image;
      });
    }
  }

  // 相机拍照
  Future<void> pickCameraImage() async {
    var image = await ImagePickerUtils.takeImageFromCamera();
    if (image != null) {
      setState(() {
        selectedImage = image;
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text("OpenHarmony 图片选择适配")),
      body: Padding(
        padding: const EdgeInsets.all(20),
        child: Column(
          children: [
            ElevatedButton(
              onPressed: pickGalleryImage,
              child: const Text("从相册选择图片"),
            ),
            const SizedBox(height: 15),
            ElevatedButton(
              onPressed: pickCameraImage,
              child: const Text("打开相机拍照"),
            ),
            const SizedBox(height: 30),
            if (selectedImage != null)
              Image.file(
                File(selectedImage!.path),
                width: 300,
                height: 250,
                fit: BoxFit.cover,
              )
            else
              const Text("未选择图片", style: TextStyle(fontSize: 16)),
          ],
        ),
      ),
    );
  }
}

五、项目运行与功能验证

5.1 启动运行

启动 OpenHarmony 模拟器 / 连接真机；DevEco Studio 选择 ohos 设备运行；应用自动安装并启动。

5.2 功能测试

1. 点击相册选择，正常打开鸿蒙系统相册；
2. 选择图片后页面立即展示；
3. 真机点击拍照，正常调用相机并返回图片；
4. 无权限报错、无闪退、无空数据；
5. 图片路径可正常读取，适配完全生效。

六、鸿蒙适配常见问题与解决方案

问题 1：打开相册闪退 / 无响应解决：未添加 READ_MEDIA、WRITE_MEDIA 权限，补齐权限后重新运行。

问题 2：相机打开失败、提示权限拒绝解决：未配置 CAMERA 权限，真机必须手动在设置开启相机权限。

问题 3：选择图片后返回为空解决：鸿蒙沙箱限制，确保使用 Flutter-OH 官方稳定版，勿使用自定义修改路径。

问题 4：模拟器无法使用拍照功能解决：鸿蒙模拟器不支持相机，拍照功能必须在真机测试。

问题 5：pub get 版本冲突解决：使用 image_picker: ^1.0.4 稳定版，兼容 Flutter-OH。

七、总结

本文以 image_picker 多媒体选择库为实例，完成 Flutter-OH 在 OpenHarmony 平台的多媒体类三方库适配全流程。image_picker 无需修改鸿蒙原生代码，仅需配置相机、媒体存储权限即可稳定运行；相册选择、相机拍照、图片质量压缩等核心功能在鸿蒙平台完全兼容；鸿蒙对多媒体、相机权限实行严格管控，必须在 module.json5 声明并在真机授权；适配思路可直接复用至视频选择、文件选择、图片裁剪等同类 Flutter 三方库，为 Flutter-OH 鸿蒙多媒体开发提供通用适配范式。