第49篇｜从系统相册导入：photoAccessHelper 与沙箱复制-洪萨配资

第49篇｜从系统相册导入：photoAccessHelper 与沙箱复制

相机项目只会拍照还不够，用户已经存在系统相册里的照片也应该能进入作品流。第 49 篇聚焦“导入”这件事：系统相册负责选择，应用负责复制、建模、刷新和后续复用。

双镜记忆相机的相册记录不是一条图片路径，而是一份带地点、时间、标题、可见性和双图字段的GalleryMoment。所以导入系统照片时，最关键的不是拿到photoUri，而是把外部媒体变成项目自己的稳定记录。

这一篇继续围绕 21 天「智能相机开发实战」训练营展开。阅读时可以先看界面效果，再顺着函数名回到 DevEco Studio 定位实现，最后把成功态、取消态和失败态串成一个可复现闭环。

本篇目标

掌握PhotoViewPicker选择系统照片的入口。
理解为什么外部 Uri 需要复制到应用沙箱。
把导入照片转换为GalleryMoment并刷新相册状态。
处理取消选择、空 Uri、复制失败和批量导入结果。

对应源码位置

entry/src/main/ets/pages/Index.ets
entry/src/main/ets/services/GalleryRecordService.ets

一、导入不是引用外部 Uri，而是建立项目记录

系统相册返回的是外部媒体 Uri，它适合读取，不适合长期作为项目内部数据源直接保存。用户后续可能移动、删除或权限变化，应用如果只保存外部 Uri，详情页、导出、分享和云同步都会变得不稳定。

项目的做法是先打开系统相册选择器，再把选中的照片复制到沙箱目录，最后用本地路径创建GalleryMoment。这样后续相册列表、详情页、地图、保险箱和分享都读取同一份项目数据。

导入能力在项目相册页中的使用位置和数据流向

二、选择器只限制图片类型和数量

buildPhotoSelectOptions很短，但它划清了入口职责：选择器只关心“让用户选图片”和“最多选几张”。真正的数据建模、复制和刷新不放在这里，避免入口函数变成业务大杂烩。

训练营里建议把系统能力入口写得克制一点。因为它通常是权限、设备能力和用户取消操作最多的地方，业务逻辑越薄，后面排查越容易。

PhotoSelectOptions 限定图片类型和最大选择数

private buildPhotoSelectOptions(maxSelectNumber: number): photoAccessHelper.PhotoSelectOptions { const options = new photoAccessHelper.PhotoSelectOptions(); options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE; options.maxSelectNumber = maxSelectNumber; return options; } private buildImportedPhotoFilePath(createdAt: number, index: number, sourceUri: string): string { const extension = this.getExportFileExtension(sourceUri); return `${this.ensureCaptureDirectory()}/import_${createdAt}_${index}.${extension}`; }

这里的maxSelectNumber传参也给后续扩展留下空间。普通导入可以是 9 张，头像导入可以是 1 张，入口配置复用同一套函数。

三、复制到沙箱后再参与相册闭环

copyPickedPhotoToSandbox用文件读写完成复制，并在finally中关闭源文件和目标文件。相册导入属于 I/O 密集操作，任何一个句柄泄漏都可能在批量导入时放大成稳定性问题。

复制失败时抛出带业务含义的错误，页面层可以直接展示“导入系统照片失败”，用户知道问题发生在导入环节，而不是看到一段无法理解的底层异常。

外部照片 Uri 被复制到应用沙箱文件

private async copyPickedPhotoToSandbox(sourceUri: string, targetPath: string): Promise<void> { let sourceFile: fs.File | undefined = undefined; let targetFile: fs.File | undefined = undefined; try { sourceFile = await fs.open(sourceUri, fs.OpenMode.READ_ONLY); targetFile = fs.openSync( targetPath, fs.OpenMode.CREATE | fs.OpenMode.WRITE_ONLY | fs.OpenMode.TRUNC ); await fs.copyFile(sourceFile.fd, targetFile.fd); } catch (error) { const err = error as BusinessError; throw new Error(`导入系统照片失败：${err.message ?? err.code ?? 'unknown'}`); } finally { this.closeFileQuietly(sourceFile, 'picked photo source'); this.closeFileQuietly(targetFile, 'picked photo target'); } }

这一步完成后，照片就从“系统相册里的外部资源”变成“当前应用可以稳定管理的项目资源”。

四、导入后补齐地点、标题和可见性

主流程先记录当前位置快照，再循环处理每个selectedUri。每张照片都有独立createdAt、目标文件路径和记录 ID，批量导入不会互相覆盖。

导入结果最终通过persistGalleryRecords写入本地记录，并调用refreshGalleryMediaStateAfterMutation刷新页面。用户看到的是相册更新，工程里完成的是文件、模型、状态和 UI 的闭环。

importSystemAlbumPhotos 把选中照片写成 GalleryMoment

private async importSystemAlbumPhotos(scope: 'gallery' | 'vault'): Promise<void> { if (this.mediaImportBusy) { return; } const vaultHadRecords = this.getVaultRecords().length > 0; const vaultWasUnlocked = this.vaultUnlocked; this.mediaImportBusy = true; this.updateRecordExportStatus(scope, '正在打开系统相册...'); try { const picker = new photoAccessHelper.PhotoViewPicker(); const result = await picker.select(this.buildPhotoSelectOptions(9)); const selectedUris = result.photoUris ?? []; if (selectedUris.length === 0) { this.updateRecordExportStatus(scope, '已取消导入'); return; } const locationSnapshot = await this.buildCaptureLocationSnapshot(); const importedRecords: Array<GalleryMoment> = []; const basePairCount = this.galleryRecords.length; const baseCreatedAt = Date.now(); for (let index = 0; index < selectedUris.length; index++) { const sourceUri = selectedUris[index]; if (!sourceUri || sourceUri.trim().length === 0) { continue; } const createdAt = baseCreatedAt + index; const targetPath = this.buildImportedPhotoFilePath(createdAt, index, sourceUri); await this.copyPickedPhotoToSandbox(sourceUri, targetPath); const record = GalleryRecordService.createRecord({ id: `import_${createdAt}_${index}`, createdAt: createdAt, pairIndex: basePairCount + index + 1, place: locationSnapshot.place, memoryTitle: locationSnapshot.memoryTitle, latitude: locationSnapshot.latitude, longitude: locationSnapshot.longitude, backPath: targetPath, frontPath: targetPath, watermarkStyle: 'none', watermarkText: '' }); const readyRecord = GalleryRecordService.applyLocalInsight(record); readyRecord.visibility = scope === 'vault' ? 'private' : 'public'; importedRecords.push(readyRecord); } if (importedRecords.length === 0) { this.updateRecordExportStatus(scope, '没有可导入的照片'); return; } const importedIds = importedRecords.map((record: GalleryMoment) => record.id); const nextRecords = importedRecords.concat( this.galleryRecords.filter((record: GalleryMoment) => !importedIds.includes(record.id)) ); await this.persistGalleryRecords(nextRecords); await this.refreshGalleryMediaStateAfterMutation(importedRecords[0].id, scope); if (scope === 'vault') { this.cloudSyncStatusText = this.cloudSyncIdentity ? '保险箱照片已保存，正在同步' : '登录华为账号后同步保险箱'; this.vaultSelectedId = importedRecords[0].id; this.vaultUnlocked = vaultWasUnlocked || !vaultHadRecords; this.vaultStatusText = this.vaultUnlocked ? `已导入 ${importedRecords.length} 张私密照片` : `已导入 ${importedRecords.length} 张私密照片，解锁后查看`; } else { this.gallerySelectedId = importedRecords[0].id; this.selectedGalleryGroupKey = this.buildGalleryRecordGroupKey(importedRecords[0]); this.galleryNoticeText = `已导入 ${importedRecords.length} 张系统相册照片`; }

注意readyRecord.visibility的写入位置。第 50 篇会继续沿着这个点讲普通相册和保险箱如何共用同一个导入口。