两条路保存图片:"保存到 app 沙箱 " 简单,fileIo.openSync 写一下就完;"保存到用户相册 " 要走系统的 photoAccessHelper,还得权限请求、createAsset、fd 写入 ... 一条链 50 行代码。做天象 app 想让用户把当前的"星空面板"截图分享到朋友圈时串了这条链。记录一下完整链路和踩的坑,顺便分享给有需要的朋友。
一、完整的保存流程
scss
用户点"保存到相册"
↓
请求权限 WRITE_IMAGEVIDEO
↓ 允许
componentSnapshot.get(id) → PixelMap
↓
ImagePacker.packing(pixelMap, {format: 'image/jpeg', quality: 95}) → ArrayBuffer
↓
photoAccessHelper.getPhotoAccessHelper(context) → helper
helper.createAsset(IMAGE, 'jpg') → assetUri
↓
fileIo.openSync(assetUri, READ_WRITE) → fd
fileIo.writeSync(fd, buffer) → 写入
fileIo.closeSync(fd)
↓
释放资源:packer.release(), pixelMap.release()
真实代码:
typescript
// SkySnapshot.ets
import { image } from '@kit.ImageKit'
import { photoAccessHelper } from '@kit.MediaLibraryKit'
import { fileIo } from '@kit.CoreFileKit'
import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'
import { componentSnapshot } from '@kit.ArkUI'
export class SkySnapshot {
private static async requestPermission(context: Context): Promise<boolean> {
try {
const atManager = abilityAccessCtrl.createAtManager()
const permissions: Permissions[] = ['ohos.permission.WRITE_IMAGEVIDEO']
const result = await atManager.requestPermissionsFromUser(context, permissions)
return result.authResults[0] === 0
} catch (e) {
return false
}
}
static async captureAndSave(
context: Context,
componentId: string,
): Promise<boolean> {
try {
// 1. 权限
const hasPermission = await SkySnapshot.requestPermission(context)
if (!hasPermission) return false
// 2. 截图
const pixelMap: image.PixelMap = await componentSnapshot.get(componentId)
// 3. 打 JPEG
const packer: image.ImagePacker = image.createImagePacker()
const packOpts: image.PackingOption = { format: 'image/jpeg', quality: 95 }
const jpegBuffer: ArrayBuffer = await packer.packing(pixelMap, packOpts)
// 4. 创建相册 asset
const helper = photoAccessHelper.getPhotoAccessHelper(context)
const assetUri: string = await helper.createAsset(
photoAccessHelper.PhotoType.IMAGE,
'jpg',
)
// 5. 写入 fd
const file = fileIo.openSync(assetUri, fileIo.OpenMode.READ_WRITE)
fileIo.writeSync(file.fd, jpegBuffer)
fileIo.closeSync(file)
// 6. 释放
packer.release()
pixelMap.release()
return true
} catch (err) {
console.error('SkySnapshot failed: ' + JSON.stringify(err))
return false
}
}
}
二、权限:WRITE_IMAGEVIDEO 要动态申请
typescript
import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit'
private static async requestPermission(context: Context): Promise<boolean> {
try {
const atManager = abilityAccessCtrl.createAtManager()
const permissions: Permissions[] = ['ohos.permission.WRITE_IMAGEVIDEO']
const result = await atManager.requestPermissionsFromUser(context, permissions)
return result.authResults[0] === 0
} catch (e) {
return false
}
}
几个点:
ohos.permission.WRITE_IMAGEVIDEO ------ 写入相册权限。注意:
- 和 iOS 的 "Photo Library Add" 对应
- 不包括读相册 (那是另一个权限
READ_IMAGEVIDEO) - 鸿蒙对相册权限区分读 / 写 / 更细粒度(单图授权)
createAtManager().requestPermissionsFromUser :触发系统的权限弹窗。第一次调用时弹,用户选"允许"或"拒绝"。之后再调不弹(除非用户在设置里改)。
authResults0 === 0 代表允许。authResults 是数组(和 permissions 数组对应),每个值是 int:
- 0 → 已授权
- 其他(-1 等)→ 拒绝
module.json5 要声明权限:
json
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.WRITE_IMAGEVIDEO",
"reason": "$string:write_photo_reason",
"usedScene": {
"abilities": ["EntryAbility"],
"when": "always"
}
}
]
}
}
不声明的话 requestPermissionsFromUser 直接报错,不弹对话框。
reason 要有 $string 资源 。鸿蒙上架审核会检查这个 reason 文案是不是对用户讲人话 。不要写 "我要你的权限",要写 "为了保存你截取的星空图到相册"。
三、ImagePacker 的 JPEG vs PNG 选择
typescript
const packOpts: image.PackingOption = {
format: 'image/jpeg',
quality: 95,
}
JPEG vs PNG:
| 维度 | JPEG | PNG |
|---|---|---|
| 压缩方式 | 有损 | 无损 |
| 文件大小 | 小(1080×1080 的 JPEG q95 ~ 200 KB) | 大(同样尺寸 PNG ~ 1.5 MB) |
| 适合 | 照片 / 自然场景 | UI 元素 / 图标 / 带透明度 |
| 支持透明通道 | 不支持 | 支持 |
天象 app 的星空面板是自然场景风格 (渐变、粒子、文字),JPEG 95% 质量用户看不出和原图的差别,但文件小一个数量级。
quality 95:
- 100 = 几乎无损,但文件没小多少
- 95 = 肉眼不可辨差距,文件省 30%
- 85 = 还行,再压 20%
- 70 = 开始看出细节损失
对保存到相册 + 社交分享 的场景,95 是最佳 trade-off。
什么时候必须 PNG:
- 有透明通道(二维码、logo)
- 像素精确(UI 截图要给设计师看)
- 文字特别多(JPEG 对文字边缘有伪影)
四、photoAccessHelper.createAsset
typescript
const helper = photoAccessHelper.getPhotoAccessHelper(context)
const assetUri: string = await helper.createAsset(
photoAccessHelper.PhotoType.IMAGE,
'jpg',
)
createAsset 做什么:
- 在相册的 "系统为你的 app 分配的位置" 创建一个空文件
- 返回这个文件的 URI (像
file://media/image/xxxx.jpg) - 系统自动纳入相册索引,用户在相册 app 里能看到
第一参数 PhotoType:
IMAGE→ 图片VIDEO→ 视频
第二参数文件后缀 :'jpg'、'png'、'mp4' 等。决定文件名的扩展名。
不需要指定路径 。系统决定文件放哪里(通常是 .../相册/应用名/ 下的某个子目录)。你只能通过 URI 操作这个文件。
五、fileIo.openSync 写 URI
typescript
const file = fileIo.openSync(assetUri, fileIo.OpenMode.READ_WRITE)
fileIo.writeSync(file.fd, jpegBuffer)
fileIo.closeSync(file)
几个点:
OpenMode 用 READ_WRITE,不是 WRITE_ONLY :相册 URI 的权限模型要求 READ_WRITE。只传 WRITE_ONLY 会报 "permission denied"。原因不详,可能和系统做权限验证的内部实现有关------照官方文档这么写就对了。
writeSync 接 ArrayBuffer:ImagePacker.packing 返回的就是 ArrayBuffer,直接传。
closeSync 用 file 对象(不是 fd):
fileIo.closeSync(file)✅fileIo.closeSync(file.fd)也能跑,但官方推荐传 file 对象
不要忘 close :fd 不关会泄漏文件描述符。几个还好,几百个 app 就崩了。
六、资源释放的顺序
typescript
packer.release()
pixelMap.release()
两个资源对应不同的 Native 对象:
ImagePacker持有 packing 过程中的内部 bufferPixelMap持有图像的原始像素数据
release 顺序:先 packer(已经不用了),再 pixelMap(最终资源)。
都要调:
- 没调 packer.release() → packer 占的 buffer 不释放
- 没调 pixelMap.release() → 图像像素 buffer 不释放(可能几 MB)
release 本身可能抛错:罕见但有(double release)。保险起见包 try/catch:
typescript
try { packer.release() } catch (_) {}
try { pixelMap.release() } catch (_) {}
本例的代码里没包,是因为前面是 try/catch 整个 captureAndSave 的 catch 里统一处理。但更稳的做法是分别包。
七、异常处理:throw 还是 return false
真实代码的 catch:
typescript
} catch (err) {
console.error('SkySnapshot failed: ' + JSON.stringify(err))
return false
}
选 return false 不选 throw 。因为调用方只关心"保存成功了没",不关心具体是什么错。错误细节 log 到 hilog 就够。
典型调用方:
typescript
async onSaveToAlbum(): Promise<void> {
const ok = await SkySnapshot.captureAndSave(context, 'skyPanel')
if (ok) {
this.showToast('已保存到相册')
} else {
this.showToast('保存失败,请检查权限')
}
}
用户看到的是"成功 / 失败"二元反馈。背后是权限拒绝、组件 id 不存在、磁盘满、还是别的------用户不想知道。错误细节给开发者看(hilog),用户给个粗粒度反馈。
踩坑清单
- 保存相册要先申请
WRITE_IMAGEVIDEO权限 module.json5要声明 requestPermissions + 带 reason 的 i18n 字符串requestPermissionsFromUser异步调,authResults[0] === 0代表允许componentSnapshot.get(id)要求组件挂了.id('xxx')ImagePacker.packing返回 ArrayBuffer,不是 fd- JPEG quality 95 是肉眼无差 + 文件省 30% 的 sweet spot
- UI 元素 / 文字多的 / 带透明度 的用 PNG,自然场景用 JPEG
photoAccessHelper.createAsset返回 URI,不能自己指定路径fileIo.openSync(uri, READ_WRITE)写相册 URI,不要用 WRITE_ONLY- packer / pixelMap 都要 release,顺序 packer 先 → pixelMap 后
- 用 try/catch + return false,不要 throw 给调用方
尾声
这条链看起来绕但稳 。鸿蒙的相册权限模型比 iOS/Android 严格一些------每一步都走系统认可的 API,直接 fs.writeFile(albumPath) 肯定不行。好处是用户的相册安全(恶意 app 不能偷偷写入)。
对独立开发者,封装成一个 util 复用 。每个要"保存截图到相册 "的 app 页面都调同一个 SkySnapshot.captureAndSave,省得每次都写 50 行链。