《图片添加贴纸》四、PhotoViewPicker使用指南

HarmonyOS PhotoViewPicker图片选择器使用指南效果一、概述在HarmonyOS应用开发中经常需要从用户相册中选择图片或视频。PhotoViewPicker是photoAccessHelper模块提供的系统级图片选择器具有以下优势无需申请权限PhotoViewPicker采用安全控件模式不需要声明READ_IMAGEVIDEO权限。系统级UI调用后弹出系统相册选择界面用户体验统一且流畅。灵活配置支持选择图片、视频或混合类型可设置最大选择数量。安全隔离返回的URI仅对当前应用有效不会暴露相册的其他内容。官方文档参考PhotoViewPicker - HarmonyOS开发者文档二、模块导入import{photoAccessHelper}fromkit.MediaLibraryKit;三、API详解3.1 PhotoViewPicker类classPhotoViewPicker{select(photoSelectOptions:PhotoSelectOptions):PromisePhotoSelectResult}PhotoSelectOptions 配置项属性类型说明MIMETypePhotoViewMIMETypes媒体文件类型过滤maxSelectNumbernumber最大可选择数量photoPickerInfosPhotoPickerInfo[]预选中的资源信息preselectedModePreselectedMode预选模式PhotoViewMIMETypes 枚举值枚举值说明PhotoViewMIMETypes.IMAGE_TYPE仅显示图片PhotoViewMIMETypes.VIDEO_TYPE仅显示视频PhotoViewMIMETypes.IMAGE_VIDEO_TYPE显示图片和视频PhotoSelectResult 返回值属性类型说明photoUrisstring[]选中资源的URI数组isMaxNumberReachedboolean是否达到最大选择数量3.2 创建实例letpickernewphotoAccessHelper.PhotoViewPicker();四、基础使用示例4.1 选择单张图片import{photoAccessHelper}fromkit.MediaLibraryKit;import{image}fromkit.ImageKit;import{fileIo}fromkit.CoreFileKit;EntryComponentstruct PickSingleImageDemo{StateselectedImage:image.PixelMap|undefinedundefined;asyncpickImage():Promisevoid{try{// 1. 创建选择器实例letpickernewphotoAccessHelper.PhotoViewPicker();// 2. 配置选择选项letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber1;// 3. 调起系统选择器letresultawaitpicker.select(options);// 4. 获取选中的图片URIif(result.photoUris.length0){leturiresult.photoUris[0];// 5. 读取图片数据并创建PixelMapletfilefileIo.openSync(uri);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);letimageSourceimage.createImageSource(buffer);this.selectedImageawaitimageSource.createPixelMap();}}catch(err){console.error(选择图片失败: (errasError).message);}}build(){Column({space:20}){if(this.selectedImage){Image(this.selectedImage).width(280).height(280).objectFit(ImageFit.Cover).borderRadius(12)}else{Column().width(280).height(280).borderRadius(12).border({width:2,color:#BDBDBD,style:BorderStyle.Dashed}).justifyContent(FlexAlign.Center).children([Text().fontSize(48).fontColor(#BDBDBD)])}Button(从相册选择).width(200).height(44).fontSize(16).fontColor(Color.White).backgroundColor(#0A59F7).borderRadius(22).onClick(()this.pickImage())}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}4.2 选择多张图片EntryComponentstruct PickMultipleImagesDemo{StateselectedImages:image.PixelMap[][];asyncpickMultipleImages():Promisevoid{try{letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber9;// 最多选择9张letresultawaitpicker.select(options);// 遍历所有选中的图片letpixelMaps:image.PixelMap[][];for(leturiofresult.photoUris){letfilefileIo.openSync(uri);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);letimageSourceimage.createImageSource(buffer);letpixelMapawaitimageSource.createPixelMap();pixelMaps.push(pixelMap);}this.selectedImagespixelMaps;}catch(err){console.error(选择图片失败: (errasError).message);}}build(){Column({space:16}){// 网格展示选中的图片Grid(){ForEach(this.selectedImages,(item:image.PixelMap,index:number){GridItem(){Image(item).width(100%).height(100%).objectFit(ImageFit.Cover).borderRadius(8)}},(item:image.PixelMap,index:number)index.toString())}.columnsTemplate(1fr 1fr 1fr).rowsGap(8).columnsGap(8).width(90%).height(320)Button(选择图片 (${this.selectedImages.length}/9)).onClick(()this.pickMultipleImages())}.width(100%).height(100%).padding({top:40})}}五、进阶用法5.1 读取图片为PixelMap的工具函数在实际项目中建议将图片读取逻辑封装为工具函数import{image}fromkit.ImageKit;import{fileIo}fromkit.CoreFileKit;import{photoAccessHelper}fromkit.MediaLibraryKit;/** * 通过URI读取图片并创建PixelMap * param uri 图片文件URI * returns PixelMap对象 */exportasyncfunctioncreatePixelMapFromUri(uri:string):Promiseimage.PixelMap{letfilefileIo.openSync(uri);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);letimageSourceimage.createImageSource(buffer);letpixelMapawaitimageSource.createPixelMap({editable:true// 设置为可编辑便于后续处理});returnpixelMap;}/** * 使用PhotoViewPicker从相册选择图片 * param maxCount 最大选择数量 * returns 选中的PixelMap数组 */exportasyncfunctionpickImagesFromGallery(maxCount:number1):Promiseimage.PixelMap[]{letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumbermaxCount;letresultawaitpicker.select(options);letpixelMaps:image.PixelMap[][];for(leturiofresult.photoUris){letpixelMapawaitcreatePixelMapFromUri(uri);pixelMaps.push(pixelMap);}returnpixelMaps;}5.2 结合Image组件直接展示如果不需要PixelMap可以直接使用URI展示图片性能更好EntryComponentstruct DirectURIDisplayDemo{StateimageUri:string;build(){Column({space:20}){if(this.imageUri){// 直接使用URI展示图片无需创建PixelMapImage(this.imageUri).width(280).height(280).objectFit(ImageFit.Cover).borderRadius(12)}Button(选择图片).onClick(async(){letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber1;letresultawaitpicker.select(options);if(result.photoUris.length0){this.imageUriresult.photoUris[0];}})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}5.3 在图片编辑器中替换背景图EntryComponentstruct ReplaceBackgroundDemo{StatebgImage:image.PixelMap|undefinedundefined;asyncreplaceBackground():Promisevoid{try{letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber1;letresultawaitpicker.select(options);if(result.photoUris.length0){letfilefileIo.openSync(result.photoUris[0]);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);letimageSourceimage.createImageSource(buffer);// 释放旧的PixelMapif(this.bgImage){this.bgImage.release();}this.bgImageawaitimageSource.createPixelMap({editable:true});}}catch(err){console.error(替换背景失败: (errasError).message);}}build(){Stack(){// 背景图Image(this.bgImage??$r(app.media.background)).width(300).height(300).objectFit(ImageFit.Cover).borderRadius(12)// 替换按钮Button(更换背景).position({x:35%,y:85%}).onClick(()this.replaceBackground())}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}六、注意事项无需权限声明PhotoViewPicker不需要在module.json5中声明READ_IMAGEVIDEO权限。URI有效期返回的URI仅对当前应用有效且有一定的生命周期建议尽快读取。内存管理使用完毕的PixelMap应调用release()方法释放避免内存泄漏。大图片处理对于大尺寸图片建议通过ImageSource的decodingOptions设置采样率。用户取消处理用户可能在选择器中点击取消此时photoUris为空数组需要判断处理。数量限制maxSelectNumber最大值受系统限制建议不超过200。七、PhotoViewPicker vs PhotoAccessPickerHarmonyOS中存在两种图片选择方式特性PhotoViewPickerfileIo photoAccessHelper权限声明不需要需要READ_IMAGEVIDEOUI体验系统级选择器需自行实现安全等级高临时授权需用户授权适用场景普通图片选择深度相册管理推荐对于简单的图片选择需求优先使用PhotoViewPicker。八、完整工具类封装以下是一个完整的图片选择工具类可直接在项目中使用import{image}fromkit.ImageKit;import{fileIo}fromkit.CoreFileKit;import{photoAccessHelper}fromkit.MediaLibraryKit;exportclassPhotoPickerUtil{/** * 从相册选择单张图片 */staticasyncpickSingleImage():Promiseimage.PixelMap|undefined{letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber1;letresultawaitpicker.select(options);if(result.photoUris.length0){returnundefined;}returnPhotoPickerUtil.uriToPixelMap(result.photoUris[0]);}/** * 从相册选择多张图片 */staticasyncpickMultipleImages(maxCount:number):Promiseimage.PixelMap[]{letpickernewphotoAccessHelper.PhotoViewPicker();letoptionsnewphotoAccessHelper.PhotoSelectOptions();options.MIMETypephotoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumbermaxCount;letresultawaitpicker.select(options);letpixelMaps:image.PixelMap[][];for(leturiofresult.photoUris){letpmawaitPhotoPickerUtil.uriToPixelMap(uri);pixelMaps.push(pm);}returnpixelMaps;}/** * 将URI转换为PixelMap */staticasyncuriToPixelMap(uri:string):Promiseimage.PixelMap{letfilefileIo.openSync(uri);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);letimageSourceimage.createImageSource(buffer);returnawaitimageSource.createPixelMap({editable:true});}/** * 将URI转换为ArrayBuffer */staticuriToBuffer(uri:string):ArrayBuffer{letfilefileIo.openSync(uri);letstatfileIo.statSync(file.fd);letbuffernewArrayBuffer(stat.size);fileIo.readSync(file.fd,buffer);fileIo.closeSync(file.fd);returnbuffer;}}九、总结PhotoViewPicker是HarmonyOS中从相册选择图片的最佳方案核心要点无需声明权限通过系统级选择器实现安全选图。通过PhotoSelectOptions配置选择类型和数量限制。返回的photoUris数组包含选中图片的URI可进一步转为PixelMap。注意及时释放PixelMap资源防止内存泄漏。建议封装工具类统一图片选择和处理逻辑。在图片编辑类应用中PhotoViewPicker通常用于选择背景图功能与Stack贴纸叠加、componentSnapshot截图、SaveButton保存形成完整的工作流。