harmony 鸿蒙Managing Media Assets

2025-06-12
浏览 (7)

Managing Media Assets

Applications can call photoAccessHelper APIs to manage media assets (images and videos).

NOTE

Before you get started, obtain a PhotoAccessHelper instance and apply for required permissions. For details, see Before You Start.

Unless otherwise specified, the PhotoAccessHelper instance obtained in Before You Start is used to call photoAccessHelper APIs. If the code for obtaining the PhotoAccessHelper instance is missing, an error will be reported to indicate that photoAccessHelper is not defined.

To ensure application running efficiency, most PhotoAccessHelper APIs are asynchronously implemented in callback or promise mode. The following examples use promise-based APIs. For details about the APIs, see Album Management.

Obtaining Media Assets

You can obtain media assets based on the specified conditions, such as the media type, date, or album name.

Use PhotoAccessHelper.getAssets with the FetchOptions object to specify the search criteria. Unless otherwise specified, all the media assets to be obtained in this document exist in the database. If no media asset is obtained, check whether the media assets exist in the database.

To obtain the object at the specified position (for example, the first one, the last one, or the one with the specified index) in the result set, use FetchResult.

Prerequisites

A PhotoAccessHelper instance is obtained.
The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see Requesting Permissions.
The dataSharePredicates module is imported.

Obtaining an Image or Video by Name

Example: Obtain the image test.jpg.

import { dataSharePredicates } from '@kit.ArkData';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

async function example() {
  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);
  }
}

Obtaining an Image or Video Thumbnail

To display images and videos in Gallery or to preview edits, applications must obtain image and video thumbnails.

The thumbnails offer a quick preview on images and videos. You can use PhotoAsset.getThumbnail with the thumbnail size specified to obtain the image or video thumbnail.

Prerequisites

A PhotoAccessHelper instance is obtained.
The application has the ohos.permission.READ_IMAGEVIDEO permission. For details, see Requesting Permissions.
The dataSharePredicates module is imported.

For example, obtain the file descriptor (FD) of an image, and decode the image into a PixelMap for display or processing. For details, see Image Decoding.

Example: Obtain the thumbnail at the size of 720 x 720 of an image.

How to Develop

Set the fetch options.
Call PhotoAccessHelper.getAssets to obtain image assets.
Call FetchResult.getFirstObject to obtain the first image from the result set.
Call PhotoAsset.getThumbnail to obtain the PixelMap of the thumbnail of the image.

import { dataSharePredicates } from '@kit.ArkData';
import { image } from '@kit.ImageKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

async function example() {
  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);
  }
}

Creating a Media Asset

Use MediaAssetChangeRequest to create a media asset change request object for a media asset, and use PhotoAccessHelper.applyChanges to apply the changes.

Prerequisites

A PhotoAccessHelper instance is obtained.
The application has the ohos.permission.WRITE_IMAGEVIDEO permission. For details, see Requesting Permissions.

Creating an Image or Video Asset (for System Applications Only)

Example: Create an image asset.

How to Develop

Set the file name and createOption for setting attributes for the image asset to create.
Call MediaAssetChangeRequest.createAssetRequest to create a media asset change request object.
Call MediaAssetChangeRequest.getWriteCacheHandler to obtain the handle of the file to write and write the content of the image asset.
Call PhotoAccessHelper.applyChanges to apply the changes to the image.

import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

async function example() {
  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 fileIoclose(fd);
    await phAccessHelper.applyChanges(assetChangeRequest);
  } catch (err) {
    console.error(`create asset failed with error: ${err.code}, ${err.message}`);
  }
}

You can also use MediaAssetChangeRequest.addResource to specify the data source information of the media asset, including the application sandbox, ArrayBuffer, and PhotoProxy.

Renaming a Media Asset

To rename a media asset, change the PhotoAsset.displayName attribute, that is, the file name (including the file name extension) displayed.

Use FetchResult to obtain the file to rename, use MediaAssetChangeRequest.setTitle to set the new name, and then use PhotoAccessHelper.applyChanges to apply the changes to the database.

Prerequisites

A PhotoAccessHelper instance is obtained.
The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see Requesting Permissions.

Example: Rename the first image in the obtained image assets.

How to Develop

Set the fetch options.
Call PhotoAccessHelper.getAssets to obtain image assets.
Call FetchResult.getFirstObject to obtain the first image from the obtained file assets.
Call MediaAssetChangeRequest.setTitle to rename the image.
Call PhotoAccessHelper.applyChanges to save the modification to the database.

import { dataSharePredicates } from '@kit.ArkData';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

async function example() {
  let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
  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}`);
  }
}

Moving a Media Asset to the Trash

You can use MediaAssetChangeRequest.deleteAssets to move files to the trash.

The file moved to the trash will be retained for 30 days before being deleted permanently. Before a file is deleted permanently from the trash, the user can restore it using the system application Files or Gallery.

Prerequisites

A PhotoAccessHelper instance is obtained.
The application has the ohos.permission.READ_IMAGEVIDEO and ohos.permission.WRITE_IMAGEVIDEO permissions. For details, see Requesting Permissions.

Example: Move the first file in the result set to the trash.

How to Develop

Set the fetch options.
Call PhotoAccessHelper.getAssets to obtain image assets.
Call FetchResult.getFirstObject to obtain the first image.
Call MediaAssetChangeRequest.deleteAssets to move the image to the trash.

import { dataSharePredicates } from '@kit.ArkData';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { common } from '@kit.AbilityKit';

// Obtain the context from the component and ensure that the return value of this.getUiContext().getHostContext() is UIAbilityContext.
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);

async function example() {
  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}`);
  }
}