系列：HarmonyOS 开发入门 · 12

做头像、意见反馈、发帖、扫描材料时，经常要碰到三个动作：

1. 从相册选图；
2. 拍一张照片；
3. 保存图片到用户相册。

我的建议是：能用系统 Picker 解决的，先别急着自己申请一堆媒体权限。

1. 从相册选择图片

现在应优先使用 photoAccessHelper.PhotoViewPicker。

import { photoAccessHelper } from '@kit.MediaLibraryKit'
import { BusinessError } from '@kit.BasicServicesKit'

async function selectPhoto(): Promise<string | undefined> {
  const options = new photoAccessHelper.PhotoSelectOptions()
  options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE
  options.maxSelectNumber = 1

  const picker = new photoAccessHelper.PhotoViewPicker()

  try {
    const result = await picker.select(options)
    return result.photoUris.length > 0 ? result.photoUris[0] : undefined
  } catch (error) {
    const err = error as BusinessError
    console.error(`select photo failed: ${err.code}, ${err.message}`)
    return undefined
  }
}

这种方式由用户在系统界面主动选择图片，一般不需要为了“选一张图”先拿整个相册读取权限。

2. 拿到的是 URI，不要自己硬解析

Picker 返回的通常是媒体 URI。

不要根据字符串格式自己拆“相册路径”“文件名”，因为 URI 的语义由系统管理。

正确思路是把 URI 交给对应的文件或媒体 API 继续处理。

3. 简单拍照优先考虑 CameraPicker

如果你只是要“让用户拍一张照片然后返回结果”，不需要自定义快门、滤镜、预览流，CameraPicker 会比自己搭相机会省非常多工作。

它的优势之一就是系统相机界面由用户主动操作，在适用场景下不需要你的应用自己申请相机权限。

典型流程是：

准备可写入的目标 URI
↓
配置 PickerProfile
↓
cameraPicker.pick(...)
↓
拿到结果 URI

如果要做扫描、实时识别、美颜、直播，自定义 Camera Kit 才更合适。

4. 什么时候必须自己做相机

下面这些需求就不要硬用 CameraPicker：

• 自定义预览页面；
• 控制前后摄像头；
• 对焦、曝光、白平衡；
• 实时帧处理；
• 美颜滤镜；
• 视频直播。

这时就应该走 Camera Kit，并处理相机权限和完整会话生命周期。

5. 保存到相册不要直接理解成“复制文件”

用户媒体库不是应用自己的沙箱目录。

更合理的流程是调用 Media Library Kit 的保存媒体资源能力，让系统创建媒体资产或通过安全保存能力完成写入。

不同 API 版本下推荐接口可能变化，所以写业务时应该围绕“媒体资产保存”理解，而不是硬编码 /storage/... 路径。

6. 一个头像页面的完整业务流程

我通常会这样设计：

点击头像
↓
弹出：拍照 / 从相册选择
↓
Picker 返回 URI
↓
复制或读取到 App 可管理区域（按业务需要）
↓
压缩 / 裁剪
↓
上传服务器
↓
更新头像 URL

不是拿到 URI 就永久把它当自己的文件地址存数据库。

要先搞清楚 URI 的授权生命周期和你的长期使用需求。

7. 旧代码要注意 deprecated API

一些老文章会写：

import { picker } from '@kit.CoreFileKit'
const photoPicker = new picker.PhotoViewPicker(...)

旧版 picker.PhotoViewPicker 已经有废弃标记，新的媒体选择应该优先看 photoAccessHelper.PhotoViewPicker。

这是看 HarmonyOS 教程时特别需要留意的一点：文章年份和 API 版本很重要。

总结

图片相关入门可以先记住：

• 选图：photoAccessHelper.PhotoViewPicker；
• 简单拍照：优先考虑 CameraPicker；
• 深度相机：Camera Kit；
• 保存相册：走 Media Library Kit 的媒体保存能力；
• URI 不要自己硬解析。

下一篇继续 Picker 思路，处理 PDF、Word、ZIP 等普通文件的选择和读写。