HarmonyOS 保存组件截图到相册 componentSnapshot 到 photoAccessHelper 完整链

两条路保存图片:"保存到 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 过程中的内部 buffer
  • PixelMap 持有图像的原始像素数据

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 行链。

相关推荐
曹一二13 分钟前
彻底搞懂 JS 对象:从字面量、构造函数到原型链与包装类
前端·javascript
澹锦汐6 小时前
纯前端秋日银杏与枫叶落叶色板智能聚类器:基于 K-Means 色彩量化与直方图自动配方提取
前端·人工智能·ai·语言模型·vue·react·k-means
Flynt13 小时前
AI 写的 Three.js 大屏,为什么越跑越卡?我在 Node 里复现了它的内存曲线
前端·ai编程·three.js
一个游离的指针15 小时前
Vue2:vue-router
前端·javascript·vue.js
火山引擎和TA的超级拍档们17 小时前
产品情报局 11 | AI 数据湖 LAS:打造大模型时代多模态数据底座
前端·后端
JavaGuide18 小时前
Gemini 真的变强了,写代码做视频的能力接近 Claude Opus5.5 了!
前端·ai编程
niceyayale18 小时前
WebRTC 延迟怎么调试:从 ICE 到 jitter buffer 的六个观测点
前端
aleimu18 小时前
Windows 11 右键打开 Cmder 2.0:从找不到菜单到默认使用 Cmder
前端·人工智能·后端