大网数据广告活动
OpenHarmony 设备与应用开发

媒体资源使用指导

· 52CE 我爱测

为了保证应用的运行效率,大部分photoAccessHelper的接口调用都是异步的。示例采用Promise函数,更多方式可以查阅模块描述。

媒体资源使用指导

应用可以通过photoAccessHelper的接口,对媒体资源(图片、视频)进行相关操作。

说明:

  • 在进行功能开发前,请查阅开发准备,了解如何获取相册管理模块实例和如何申请相册管理模块功能开发相关权限。
  • 文档中使用到photoAccessHelper的地方,默认为使用开发准备中获取的对象,如果未添加此段代码,报photoAccessHelper未定义的错误,请自行添加。

为了保证应用的运行效率,大部分photoAccessHelper的接口调用都是异步的。示例采用Promise函数,更多方式可以查阅模块描述。

获取指定媒体资源

根据特定条件查询媒体资源,如类型、日期、相册等。

应用通过调用PhotoAccessHelper.getAssets获取媒体资源,并传入FetchOptions对象指定检索条件。如无特别说明,文档中涉及的待获取的资源均视为已经预置且在数据库中存在相应数据。如出现获取资源为空的情况,请确认文件是否已预置,数据库中是否存在该文件的数据。

注意: 使用PhotoAccessHelper.PhotoKeys.URI做查询条件时,仅支持使用DataSharePredicates.equalTo的方式。

如果只想获取某个位置的对象(如第一个、最后一个、指定索引等),可以通过FetchResult中的接口获取。

前提条件

指定媒体文件名获取图片或视频资源

下面以查询文件名为'test.jpg'的图片资源为例。


// ...


async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.DISPLAY_NAME, 'test.jpg');
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };
  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = 
      await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
    fetchResult.close();
    // ...
  } catch (err) {
    console.error('getAssets failed with err: ' + err);
    // ...
  }
}

获取图片和视频缩略图

在相册展示图片和视频、编辑预览时,应用需要获取图片和视频的缩略图。

通过接口PhotoAsset.getThumbnail,传入缩略图尺寸,可以获取图片和视频缩略图。缩略图常用于UI界面展示。

前提条件

参考以下示例,获取图片的文件描述符fd后,需要解码为统一的PixelMap,以便在应用中进行图片显示或图片处理,具体请参考图片解码。

下面以获取一张图片的缩略图为例,缩略图尺寸为720*720。

开发步骤

  1. 建立检索条件,用于获取图片资源。
  2. 调用PhotoAccessHelper.getAssets接口获取图片资源。
  3. 调用FetchResult.getFirstObject接口获取第一张图片。
  4. 调用PhotoAsset.getThumbnail获取图片的缩略图的PixelMap。

// ...

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };

  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = 
      await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    console.info('getAssets photoAsset.displayName : ' + photoAsset.displayName);
    let size: image.Size = { width: 720, height: 720 };
    let pixelMap: image.PixelMap =  await photoAsset.getThumbnail(size);
    let imageInfo: image.ImageInfo = await pixelMap.getImageInfo()
    console.info('getThumbnail successful, pixelMap ImageInfo size: ' + JSON.stringify(imageInfo.size));
    fetchResult.close();
    // ...
  } catch (err) {
    console.error('getThumbnail failed with err: ' + err);
    // ...
  }
}

创建媒体资源

创建MediaAssetChangeRequest媒体资产变更对象并写入媒体资源内容,然后调用PhotoAccessHelper.applyChanges接口提交创建资产的变更请求。

前提条件

创建图片或视频资源(仅向系统应用开放)

下面以创建一张图片资源为例。

开发步骤

  1. 定义文件名和创建选项,用于创建图片资源时设置属性。
  2. 调用MediaAssetChangeRequest.createAssetRequest接口创建资产变更请求。
  3. 调用MediaAssetChangeRequest.getWriteCacheHandler接口获取临时文件写句柄,并写入图片资源的内容。
  4. 调用PhotoAccessHelper.applyChanges接口提交资产变更请求。

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper, context: Context) {
  try {
    let displayName: string = 'testPhoto' + Date.now() + '.jpg';
    let createOption: photoAccessHelper.PhotoCreateOptions = {
      subtype: photoAccessHelper.PhotoSubtype.DEFAULT
    };
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(context, displayName, createOption);
    let fd: number = await assetChangeRequest.getWriteCacheHandler();
    // write date into fd.
    await fileIo.close(fd);
    await phAccessHelper.applyChanges(assetChangeRequest);
  } catch (err) {
    console.error(`create asset failed with error: ${err.code}, ${err.message}`);
  }
}

应用还可以调用MediaAssetChangeRequest.addResource接口指定媒体资源内容的数据来源,具体包括应用沙箱,ArrayBuffer和PhotoProxy。

重命名媒体资源

重命名修改的是文件的PhotoAsset.displayName属性,即文件的显示文件名,包含文件后缀。

调用MediaAssetChangeRequest.setTitle重命名后,再通过PhotoAccessHelper.applyChanges更新到数据库中完成修改。

在重命名文件之前,需要先获取文件对象,可以通过FetchResult中的接口获取对应位置的文件。

前提条件

下面以重命名标题为'oldTestPhoto'的图片为例。

开发步骤

  1. 建立检索条件,获取标题为'oldTestPhoto'的图片资源。
  2. 调用PhotoAccessHelper.getAssets接口获取目标图片资源。
  3. 调用FetchResult.getFirstObject接口获取要重命名的图片对象。
  4. 调用MediaAssetChangeRequest.setTitle接口将图片重命名。
  5. 调用PhotoAccessHelper.applyChanges接口将修改的图片属性更新到数据库中完成修改。

// ...

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper) {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  predicates.equalTo(photoAccessHelper.PhotoKeys.TITLE, 'test')
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: ['title'],
    predicates: predicates
  };
  let newTitle: string = 'newTestPhoto';

  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = 
      await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = 
      new photoAccessHelper.MediaAssetChangeRequest(photoAsset);
    assetChangeRequest.setTitle(newTitle);
    await phAccessHelper.applyChanges(assetChangeRequest);
    fetchResult.close();
    // ...
  } catch (err) {
    console.error(`rename failed with error: ${err.code}, ${err.message}`);
    // ...
  }
}

将文件放入回收站

通过MediaAssetChangeRequest.deleteAssets可以将文件放入回收站。

放入回收站的文件将保存30天,到期后自动彻底删除。在此期间,用户可以通过系统应用“文件管理”或“图库”恢复文件。

前提条件

下面以将文件检索结果中第一个文件放入回收站为例。

开发步骤

  1. 建立检索条件,用于获取图片资源。
  2. 调用PhotoAccessHelper.getAssets接口获取目标图片资源。
  3. 调用FetchResult.getFirstObject接口获取第一张图片,即要放入回收站的图片对象。
  4. 调用MediaAssetChangeRequest.deleteAssets接口将文件放入回收站。

// ...

async function example(phAccessHelper: photoAccessHelper.PhotoAccessHelper, context: Context) {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  let fetchOptions: photoAccessHelper.FetchOptions = {
    fetchColumns: [],
    predicates: predicates
  };

  try {
    let fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = 
      await phAccessHelper.getAssets(fetchOptions);
    let photoAsset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();
    await photoAccessHelper.MediaAssetChangeRequest.deleteAssets(context, [photoAsset]);
    fetchResult.close();
    // ...
  } catch (err) {
    console.error(`deleteAssets failed with error: ${err.code}, ${err.message}`);
    // ...
  }
}

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。