HarmonyOS动态照片，简易环境助力高效开发

头图
随着移动终端体验的不断提升，动态照片这种有趣味与表现力的内容形式，越来越受到用户的青睐。HarmonyOS允许用户在设备上查看和处理动态照片，这些照片不仅包含静态图像，还融合了视频片段，为用户提供更加丰富和生动的视觉体验。Media Library Kit媒体库提供动态照片的创建和管理能力，为开发者带来全新的开发场景和优化空间。

一、保存与播放动态照片
动态照片作为一种记录和分享生活瞬间的方式，广泛应用于各大社交软件中。用户通过拍摄动态照片，捕捉并分享那些稍纵即逝的美好时刻，并将浏览的精彩画面保存到本地。为了提升这一体验，Media Library Kit提供了完整的动态照片保存与播放的API接口。

1、使用安全控件保存动态照片
为支持应用保存动态照片资源，媒体库在MediaAssetChangeRequest类中提供了创建和保存动态照片的接口，应用可以灵活地将自己沙箱下的图片和视频资源保存至媒体库，涉及接口如下：

// 创建资产变更请求，需要在CreateOptions中指定subtype为动态照片
static createAssetRequest(context: Context, photoType: PhotoType, extension: string, options?: CreateOptions): MediaAssetChangeRequest;
// 通过fileUri从应用沙箱添加资源
addResource(type: ResourceType, fileUri: string): void;
// 通过ArrayBuffer添加资源
addResource(type: ResourceType, data: ArrayBuffer): void;
// 提交资产变更请求，在媒体库创建动态照片资产
applyChanges(mediaChangeRequest: MediaChangeRequest): Promise;
对没有读写权限的应用，HarmonyOS提供安全控件的方式保存媒体资源，应用可以临时获取媒体库存储权限，整个保存流程更简易。下面是使用安全控件保存动态照片的示例：

// 设置安全控件按钮属性
saveButtonOptions: SaveButtonOptions = {
icon: SaveIconStyle.FULL_FILLED,
text: SaveDescription.SAVE_IMAGE,
buttonType: ButtonType.Capsule
}
// 创建安全控件按钮
SaveButton(this.saveButtonOptions)
.onClick(async (event, result: SaveButtonOnClickResult) => {
if (result == SaveButtonOnClickResult.SUCCESS) {
let context: Context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
// 创建资产变更请求，subtype类型为动态照片
let changeRequest = photoAccessHelper.MediaAssetChangeRequest.createAssetRequest(
context, photoAccessHelper.PhotoType.IMAGE, "jpg", {
title: 'moving_photo',
subtype: photoAccessHelper.PhotoSubtype.MOVING_PHOTO
});
// 添加要保存的文件uri，文件资源位于应用沙箱
let imageUri = 'file://com.example.myapplication/data/storage/el2/base/haps/entry/files/mov_1.jpg';
let videoUri = 'file://com.example.myapplication/data/storage/el2/base/haps/entry/files/mov_1.mp4';
changeRequest.addResource(photoAccessHelper.ResourceType.IMAGE_RESOURCE, imageUri);
changeRequest.addResource(photoAccessHelper.ResourceType.VIDEO_RESOURCE, videoUri);
// 提交资产变更请求
await phAccessHelper.applyChanges(changeRequest);
}
})
2、访问和播放动态照片
媒体库为应用提供了统一的动态照片访问接口requestMovingPhoto和MovingPhoto对象，支持应用读取动态照片。同时，MovingPhotoView组件用于播放动态照片，为用户提供沉浸、流畅的动图体验。
1、MediaAssetManager-requestMovingPhoto接口：支持读取动态照片对象。
2、MovingPhoto对象：支持读取动态照片的图片和视频内容。
3、MovingPhotoViewController：控制动态照片的播放状态（如播放、停止）。

动态照片的图片部分由HarmonyOS分段式拍照统一出图，因此requestMovingPhoto接口支持按照不同图片模式请求读取动态照片对象。

// 根据不同的requestOptions模式，请求动态照片对象
requestMovingPhoto(context: Context, asset: PhotoAsset, requestOptions: RequestOptions, dataHandler: MediaAssetDataHandler): Promise
应用通过配置接口参数RequestOptions . DeliveryMode就能实现以下三种请求：
1、快速模式（DeliveryMode.FAST_MODE）：立刻为应用返回当前准备好的图片。
2、高质量模式（DeliveryMode. HIGH_QUALITY_MODE）：向应用返回全质量图。若未生成，媒体库会主动触发底层生成二阶段图片任务，并为应用返回全质量图片。
3、均衡模式（DeliveryMode. BALANCE_MODE）：若全质量图已经生成，则直接返回给应用。否则，先向应用返回低质量图，然后触发二阶段任务，待全质量图片生成后再次返回。

// 创建动态照片处理器，当请求的资源准备完成时触发回调
class MovingPhotoHandler implements photoAccessHelper.MediaAssetDataHandler<photoAccessHelper.MovingPhoto> {
async onDataPrepared(movingPhoto: photoAccessHelper.MovingPhoto) {
if (movingPhoto === undefined) {
console.error('Error occurred when preparing data');
return;
}
console.info("moving photo acquired successfully, uri: " + movingPhoto.getUri());
}
}
// 从媒体库中读取动态照片asset
let predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo(photoAccessHelper.PhotoKeys.PHOTO_SUBTYPE, photoAccessHelper.PhotoSubtype.MOVING_PHOTO);
let fetchOptions: photoAccessHelper.FetchOptions = {
fetchColumns: [],
predicates: predicates
};
let assetResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOptions);
let asset: photoAccessHelper.PhotoAsset = await assetResult.getFirstObject();
// 以FAST_MODE模式为例，请求动态照片对象
let requestOptions: photoAccessHelper.RequestOptions = { deliveryMode: photoAccessHelper.DeliveryMode.FAST_MODE, }
const handler = new MovingPhotoHandler();
try {
let requestId: string = await photoAccessHelper.MediaAssetManager.requestMovingPhoto(context, asset, requestOptions, handler);
console.info("moving photo requested successfully, requestId: " + requestId);
} catch (err) {
console.error(failed to request moving photo, error code is ${err.code}, message is ${err.message});
}
获取到MovingPhoto对象后，开发者可以利用ArkTS组件播放动态照片。HarmonyOS提供MovingPhotoView组件展示动态照片，其参数MovingPhotoViewOptions可供应用选择播放动态照片的数据源（MovingPhoto对象）和播放控制器（MovingPhotoViewController）。

MovingPhotoView(options: MovingPhotoViewOptions) // 动态照片组件
控制器用来控制动态照片的播放状态，当前可使用的状态有如下三种：
1、startPlayback()：开始播放动态照片。
2、stopPlayback()：停止播放，再次播放时从头开始。
3、refreshMovingPhoto()：强制刷新动态照片组件加载的视频和图片资源。

Media Library Kit提供了多种形式播放动态照片的示例，请参考API指南使用MovingPhotoView组件。

二、拍摄并保存动态照片
大多社交软件都为用户提供拍摄动态照片功能，方便用户随时查看和分享图片。HarmonyOS动态照片的拍摄采用分段式拍照统一出图流程，旨在让相机类应用的用户体验与系统相机一致，通过统一拍照流程提升拍照体验。在拍照过程中，相机应用的参与流程被减弱，所有操作均由底层框架进行，MediaLibrary Kit参与动态照片拍摄的具体流程图如下：

image.png

流程1

一阶段动态照片拍摄时，相机应用向相机框架下发拍摄命令，相机框架将命令传递给HAL层。相机HAL抓取两路流（图片流和视频流）并传递至相机框架。图片流由相机框架传递给媒体库，保存为一阶段80分图片。相机框架完成动态照片视频编码后，将视频传递给媒体库保存。

流程2

相机应用通过saveCameraPhoto接口保存动图，并传递用户拍摄时选择的水印和滤镜数据。媒体库接收到保存命令和编辑数据后，将原始图片、原始视频和编辑数据通过编创框架和视频编辑生成效果动态照片。

流程3

媒体库将二段式任务传递给相机框架，相机框架根据系统资源情况适时触发。二阶段图片生成后，媒体库使用100分图片替换一阶段的80分图片，并进行效果图和缩略图的刷新。在图库和三方应用访问新拍摄动态照片的场景中，媒体库会高优先级触发动态照片的二段式任务。当底层完成二段式照片的生成后，媒体库对一阶段图片进行替换，并根据编辑数据生成新的效果图。

媒体库为开发者提供saveCameraPhoto接口保存拍摄的动态照片，应用通过监听动态照片拍照输出流状态，在回调函数中保存图片。

// asset由监听动态照片输出流获得
async function example(asset: photoAccessHelper.PhotoAsset, context: Context) {
try {
let phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);
let assetChangeRequest: photoAccessHelper.MediaAssetChangeRequest = new photoAccessHelper.MediaAssetChangeRequest(asset);
assetChangeRequest.saveCameraPhoto();
// 提交保存请求
await phAccessHelper.applyChanges(assetChangeRequest);
console.info('apply saveCameraPhoto successfully');
} catch (err) {
console.error(apply saveCameraPhoto failed with error: ${err.code}, ${err.message});
}
}
更多案例:
https://github.com/sfasx120/sd/issues/1452
https://github.com/sfasx120/sd/issues/1451
https://github.com/sfasx120/sd/issues/1450
https://github.com/sfasx120/sd/issues/1449
https://github.com/sfasx120/sd/issues/1448
https://github.com/sfasx120/sd/issues/1447
https://github.com/sfasx120/sd/issues/1446
https://github.com/sfasx120/sd/issues/1445
https://github.com/sfasx120/sd/issues/1444