@ohos.multimedia.movingphotoview (动态照片)(系统接口)

用于播放动态照片文件并控制其播放状态的组件。

说明：

• 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 当前页面仅包含本模块的系统接口，其他公开接口参见@ohos.multimedia.movingphotoview (动态照片)。

MovingPhotoViewOptions

定义动态照片视图选项。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	类型	只读	可选	说明
movingPhotoFormat14+	PixelMapFormat	否	是	设置动态照片组件封面图片的解码格式。 系统接口：此接口为系统接口。
dynamicRangeMode14+	DynamicRangeMode	否	是	设置动态照片组件封面图片的RangeMode样式。 系统接口：此接口为系统接口。
playWithMask19+	boolean	否	是	带有水印的动态照片播放时是否保留水印显示。 默认值：false。 false：播放时保持宽高比撑满组件，不展示水印信息。 true：播放时不遮挡封面照片的水印，展示水印信息。 系统接口：此接口为系统接口。

PixelMapFormat¹⁴⁺

动态照片组件封面图片的解码格式。

系统接口：此接口为系统接口。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
UNKNOWN	0	未知格式。
RGBA_8888	1	格式为RGBA_8888。
NV21	2	格式为NV21。
RGBA_1010102	3	格式为RGBA_1010102。
YCBCR_P010	4	格式为YCBCR_P010。
YCRCB_P010	5	格式为YCRCB_P010。

DynamicRangeMode¹⁴⁺

动态照片组件封面图片的可使用的扩展范围，决定了图片的显示效果。

系统接口：此接口为系统接口。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

名称	值	说明
HIGH	0	允许图像内容使用不受限制的扩展范围，显示HDR效果，建议使用的解码格式YCBCR_P010。
CONSTRAINT	1	允许图像内容使用一些扩展范围。
STANDARD	2	允许图像内容动态单位限制在标准范围内，显示SDR效果，需要使用的解码格式UNKNOWN或者RGBA_8888。

MovingPhotoViewAttribute

定义动态照片的属性函数。

setPlaybackStrategy²³⁺

setPlaybackStrategy(strategy: media.PlaybackStrategy): MovingPhotoViewAttribute

设置动态照片边播边处理策略。

系统接口： 此接口为系统接口。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

参数：

参数名	类型	必填	说明
strategy	media.PlaybackStrategy	是	设置动态照片边播边处理策略。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

示例：

系统应用可以同时设置动态照片解码格式、HDR效果格式和边播边处理策略。

// 该示例只展示参数用法，具体可以执行用例参考动态照片公开接口文档。
// API version 21及之前版本导入方式：import { photoAccessHelper, MovingPhotoView, MovingPhotoViewController, MovingPhotoViewAttribute } from '@kit.MediaLibraryKit';
// API version 22及之后版本导入方式如下：
import { photoAccessHelper, MovingPhotoView, MovingPhotoViewController, PixelMapFormat, DynamicRangeMode } from '@kit.MediaLibraryKit';
import { media } from '@kit.MediaKit';

let data: photoAccessHelper.MovingPhoto
async function loading(context: Context) {
  try {
    // 需要确保imageFileUri和videoFileUri对应的资源在应用沙箱存在。
    let imageFileUri = 'file://{bundleName}/data/storage/el2/base/haps/entry/files/xxx.jpg';
    let videoFileUri = 'file://{bundleName}/data/storage/el2/base/haps/entry/files/xxx.mp4';
    data = await photoAccessHelper.MediaAssetManager.loadMovingPhoto(context, imageFileUri, videoFileUri);
    console.info('load moving photo successfully');
  } catch (err) {
    console.error(`load moving photo failed with error: ${err.code}, ${err.message}`);
  }
}
@Entry
@Component
struct Index {
  controller: MovingPhotoViewController = new MovingPhotoViewController();
  format: undefined | PixelMapFormat = PixelMapFormat.YCBCR_P010;
  mode: undefined | DynamicRangeMode = DynamicRangeMode.HIGH;
  playbackstrategy: media.PlaybackStrategy = {enableCameraPostprocessing: true};
  private uiContext: UIContext = this.getUIContext()
  aboutToAppear(): void {
    loading(this.uiContext.getHostContext()!)
  }

  build() {
    NavDestination() {
      Column() {
        Stack({ alignContent: Alignment.BottomStart }) {
          MovingPhotoView({
            movingPhoto: data,
            controller: this.controller,
            movingPhotoFormat: this.format,
            dynamicRangeMode: this.mode,
            playWithMask: false
          })
          .setPlaybackStrategy(this.playbackstrategy)
        }
      }
    }
  }
}

MovingPhotoViewController

一个MovingPhotoViewController对象可以控制一个MovingPhotoView，可用视频播放实例请参考媒体业务模块描述相关功能。

pausePlayback²⁰⁺

pausePlayback()

停止播放时显示当前帧，再次播放时从当前帧开始播放。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

reset²⁰⁺

reset()

重置播放时显示封面帧，再次播放时从头开始播放。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

restart²⁰⁺

restart()

重启播放视频，继承当前播放区间和播放模式参数。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

setPlaybackPeriod²⁰⁺

setPlaybackPeriod(startTime: number, endTime: number)

设置播放区间，再次播放时生效。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

参数名	类型	必填	说明
startTime	number	是	区间播放开始时间，单位：ms。取值范围：大于等于0。
endTime	number	是	区间播放结束时间，单位：ms。取值范围：大于startTime。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

enableTransition²⁰⁺

enableTransition(enabled: boolean)

关闭视频启动播放时的放大效果，再次播放时生效。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

参数名	类型	必填	说明
enabled	boolean	是	是否开启放大过渡效果。true表示开启，false表示不开启。 默认值：true。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

enableAutoPlay²⁰⁺

enableAutoPlay(enabled: boolean)

控制动态照片数据中视频是否能够自动播放并自动播放一次。

系统接口： 该接口为系统接口。

原子化服务API： 从API version 20开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

参数名	类型	必填	说明
enabled	boolean	是	是否能够自动播放。true表示能自动播放，false表示不能自动播放。 默认值：false。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.

notifyMovingPhotoTransition²³⁺

notifyMovingPhotoTransition(): void

通知组件执行封面图的过渡动效。

系统接口： 此接口为系统接口。

原子化服务API： 从API version 23开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.FileManagement.PhotoAccessHelper.Core

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Non-system applications are not allowed to use system APIs.