HarmonyOS APP《画伴梦工厂》开发第10篇：相册选择与 PhotoViewPicker——从相册导入图片

第2.2篇：相册选择与 PhotoViewPicker——从相册导入图片

难度：⭐⭐ 进阶
前置知识：第 2.1 篇 相机开发实战
涉及源文件：products/default/src/main/ets/components/CreationComponents.ets

概述

第 2.1 篇我们学习了如何调用系统相机拍照。本篇将介绍另一种图片采集方式——通过PhotoViewPicker从相册中选择图片。与相机模式相比，相册选择不需要繁重的CAMERA权限，甚至不需要READ_MEDIA权限，这得益于 HarmonyOS 的 Scope（作用域）访问模型。两者最终共用同一套capturePhoto处理流程，保持了代码的高度复用。

一、相机 vs 相册：场景对比

二、PhotoViewPicker 的基本使用

2.1 权限检查

与相机不同，相册选择不需要READ_MEDIA权限。PermissionGuard.requestAlbum的实现非常简洁——直接返回授权成功：

// PermissionGuard.etsstaticasyncrequestAlbum(context:common.UIAbilityContext):Promise<PermissionResult>{// PhotoViewPicker grants scoped access to the selected media item.// Do not declare broad media-read permissions here; some devices reject them at install time.return{granted:true,message:''};}

设计理念：PhotoViewPicker采用 Scope 访问模式。用户通过 Picker 选中的图片，应用仅获得该特定文件的访问权限，而不是整个媒体库的读取权限。这既保护了用户隐私，又简化了开发者的权限管理工作。

2.2 创建并配置 PhotoSelectOptions

constphotoSelectOptions=newphotoAccessHelper.PhotoSelectOptions();photoSelectOptions.MIMEType=photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;photoSelectOptions.maxSelectNumber=1;photoSelectOptions.isPhotoTakingSupported=false;

配置参数说明：

2.3 调用 select 方法

constphotoViewPicker=newphotoAccessHelper.PhotoViewPicker();photoViewPicker.select(photoSelectOptions).then((result:photoAccessHelper.PhotoSelectResult)=>{if(result.photoUris.length===0){this.noticeText='未选择图片，请重新从相册导入';return;}this.capturePhoto(result.photoUris[0],'相册图片');this.noticeText='相册导入完成，已用选中图片覆盖当前预览';}).catch(()=>{this.noticeText='相册选择失败，请重新从相册导入';});

返回结果处理

PhotoSelectResult的结构：

interfacePhotoSelectResult{photoUris:string[];// 选中图片的 URI 数组isOriginalPhoto:boolean;// 是否为原图（可选字段）}

• result.photoUris[0]：因为配置了maxSelectNumber = 1，数组至多一个元素，直接取第一个。
• 空数组检查：用户可能取消选择或从选择界面返回，需要处理这种情况。
• 错误处理：catch分支处理系统 Picker 异常（如相册无法打开）。

三、openAlbum 完整方法

将以上步骤组合，得到openAlbum的完整实现：

privateasyncopenAlbum(){constcontext=getContext(this)ascommon.UIAbilityContext;constpermissionResult:PermissionResult=awaitPermissionGuard.requestAlbum(context);if(!permissionResult.granted){this.noticeText=permissionResult.message;return;}constphotoSelectOptions=newphotoAccessHelper.PhotoSelectOptions();photoSelectOptions.MIMEType=photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;photoSelectOptions.maxSelectNumber=1;photoSelectOptions.isPhotoTakingSupported=false;constphotoViewPicker=newphotoAccessHelper.PhotoViewPicker();photoViewPicker.select(photoSelectOptions).then((result:photoAccessHelper.PhotoSelectResult)=>{if(result.photoUris.length===0){this.noticeText='未选择图片，请重新从相册导入';return;}this.capturePhoto(result.photoUris[0],'相册图片');this.noticeText='相册导入完成，已用选中图片覆盖当前预览';}).catch(()=>{this.noticeText='相册选择失败，请重新从相册导入';});}

四、与相机共用同一套处理流程

无论图片来自相机还是相册，都通过capturePhoto方法统一处理：

privatecapturePhoto(uri:string='',sourceLabel:string='拍照图片'){if(uri!==''){this.capturedImageUri=uri;this.imageSourceLabel=sourceLabel;// 标记来源：'拍照图片' 或 '相册图片'}this.hasPhoto=true;this.activeStep=1;this.generationProgress=35;this.noticeText='已采集画作，可以直接生成动画';}

这种设计的好处：

• 统一状态管理：无论图片来源如何，hasPhoto、activeStep、generationProgress等状态均为一致
• 区分来源：imageSourceLabel记录了来源信息，UI 层可以展示"已使用拍照图片"或"已使用相册图片"
• 降低复杂度：后续的生成流程不需要关心图片从哪来，只需使用capturedImageUri

五、UI 层触发

在界面上，用户通过"相册导入"按钮触发：

Button('相册导入').height(46).fontSize(14).fontWeight(FontWeight.Bold).fontColor('#FFFFFF').backgroundColor(this.mint)// #42CDA3 绿色按钮.borderRadius(23).layoutWeight(1).margin({left:10}).onClick(()=>{if(!this.recognizing){this.openAlbum();}})

"拍照采集"和"相册导入"两个按钮并排显示在画作预览区下方，用户可以根据手头情况自由选择：

┌────────────────────────────────┐ │ [ 拍照采集 ] [ 相册导入 ] │ └────────────────────────────────┘

六、完整流程时序图

用户点击"相册导入" │ ▼ PermissionGuard.requestAlbum() → 直接返回 granted │ ▼ new PhotoViewPicker().select(options) │ ├── 用户取消 → noticeText 提示 → 结束 │ └── 用户选择图片 │ ▼ result.photoUris[0] 获取 URI │ ▼ capturePhoto(uri, '相册图片') │ ▼ hasPhoto = true activeStep = 1 generationProgress = 35 imageSourceLabel = '相册图片'

七、常见问题排查

7.1 图片未显示

• 确认capturedImageUri是否赋值正确
• 检查 URI 格式，PhotoViewPicker返回的 URI 可直接用于Image组件的src属性
• 确认Image组件设置了合适的objectFit（如ImageFit.Cover或ImageFit.Contain）

7.2 相册打不开

• 在真机上测试（模拟器相册功能可能受限）
• 检查@kit.MediaLibraryKit是否已在模块中正确引入

7.3 Scope URI 与文件路径

• PhotoViewPicker返回的 URI 是 Scope URI，不能直接用于fileIo等文件操作
• 如需文件操作，需通过fileIo.fopen或沙箱路径转换
• 在本项目中，URI 直接传给Image组件和后续RecognitionWaitingPage展示，无需文件级操作

总结

本文介绍了使用PhotoViewPicker从相册选择图片的方案，与第 2.1 篇的相机拍照形成互补：

两种图片采集方式覆盖了用户不同的使用场景——手中有纸质画作用相机拍，手机里已有图片从相册选。下一节我们将进入自由涂鸦模式，学习如何在 ArkUI 中实现完整的绘画体验。