ArkTS 原生开发实战：打造鸿蒙原生图库组件

✅ 背景介绍

在原生应用中读取本地相册是常见需求，无论是社交 App、笔记应用还是图片工具类，都涉及到媒体文件读取、展示与权限管理。

在 HarmonyOS 中，我们可通过 @ohos.file.fs 和 @ohos.media.library 模块访问本地图片资源。

---

🧱 实战目标

• 自动获取本地相册中的图片；

• 支持图片列表展示；

• 点击图片支持查看放大；

• 实现基础权限请求。

---

🧑‍💻 核心代码演示（基于 HarmonyOS 5.0.0）

1. 引入所需模块

import mediaLibrary from '@ohos.multimedia.mediaLibrary';
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import fs from '@ohos.file.fs';

2. 请求媒体访问权限

async function requestPermission() {
  let context = getContext(this);
  let atManager = abilityAccessCtrl.createAtManager();
  let permissionName = 'ohos.permission.READ_MEDIA';
  let result = await atManager.requestPermissionsFromUser(context, [permissionName]);
  console.info('权限请求结果:', JSON.stringify(result));
}

3. 获取相册图片

async function getLocalImages(): Promise<string[]> {
  let context = getContext(this);
  let media = mediaLibrary.getMediaLibrary(context);
  let fetchOp = {
    selections: 'media_type=?',
    selectionArgs: ['1'], // 1 表示图片
    order: 'date_added DESC'
  };
  let fileAssets = await media.getFileAssets(fetchOp);
  const imagePaths: string[] = [];

  for (let i = 0; i < fileAssets.getCount(); i++) {
    let asset = await fileAssets.getFirstObject();
    let fd = await asset.open('r');
    let path = await asset.getFilePath();
    imagePaths.push(path);
  }

  return imagePaths;
}

---

4. 图片展示组件

@Component
struct Gallery {
  private images: string[] = [];

  async aboutToAppear() {
    await requestPermission.call(this);
    this.images = await getLocalImages.call(this);
  }

  build() {
    Column() {
      Text('📷 我的相册')
        .fontSize(22)
        .fontWeight(FontWeight.Bold)
        .padding(10)

      if (this.images.length === 0) {
        Text('暂无图片').padding(20)
      } else {
        Wrap() {
          ForEach(this.images, (item) => {
            Image(item)
              .width(100).height(100)
              .margin(5)
              .objectFit(ImageFit.Cover)
              .onClick(() => router.pushUrl({ url: 'viewerPage', params: { path: item } }))
          }, (item) => item)
        }
      }
    }.padding(10)
  }
}

---

⚠️ 容易出错的点

错误问题	原因	解决方式
获取不到图片	未申请权限	使用 requestPermissionsFromUser 请求
Image 显示异常	路径不合法或图片加载失败	使用 getFilePath() 而不是 uri
多次点击崩溃	未缓存 getFileAssets 结果	控制并发，避免频繁调用

---

📦 权限配置提示（config.json）

"reqPermissions": [
  {
    "name": "ohos.permission.READ_MEDIA"
  }
]

---

🚀 拓展建议

• 加入“选择图片上传”功能；

• 实现预览页图片缩放、滑动浏览；

• 添加“最近图片”“按文件夹分类”等特性；

• 接入媒体监听（新增图片实时刷新）；

---

✅ 小结

通过本篇，你已掌握如何通过 ArkTS 构建一个原生图库组件，涵盖权限申请、媒体文件读取、列表展示等核心能力，是许多高级鸿蒙应用的基础模块之一。