openharmony 鸿蒙 js-apis-pipWindow

2025-06-12 浏览 (1)

@ohos.PiPWindow (画中画窗口)

该模块提供画中画基础功能，包括判断当前系统是否支持画中画功能，以及创建画中画控制器用于启动或停止画中画等。适用于视频播放、视频通话或视频会议场景下，以小窗（画中画）模式呈现内容。

说明：

本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

该模块应在支持SystemCapability.Window.SessionManager能力的系统上使用，参考系统能力SystemCapability使用指南。

导入模块

import { PiPWindow } from '@kit.ArkUI';

PiPWindow.isPiPEnabled

isPiPEnabled(): boolean

判断当前系统是否支持画中画功能。

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

系统能力： SystemCapability.Window.SessionManager

返回值：

类型说明
boolean当前系统是否支持画中画功能。true表示支持，false则表示不支持。

示例：

let enable: boolean = PiPWindow.isPiPEnabled();
console.info('isPipEnabled:' + enable);

PiPWindow.create

create(config: PiPConfiguration): Promise<PiPController>

创建画中画控制器，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
configPiPConfiguration是创建画中画控制器的参数。该参数不能为空，并且构造该参数的context和componentController不能为空。构造该参数时，如果指定了templateType，需保证templateType是PiPTemplateType类型；如果指定了controlGroups，需保证controlGroups与templateType匹配，详见PiPControlGroup。

返回值：

类型说明
Promise<PiPController>Promise对象。返回当前创建的画中画控制器。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
801Capability not supported.Failed to call the API due to limited device capabilities.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { BuilderNode, FrameNode, NodeController, UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

class Params {
  text: string = '';
  constructor(text: string) {
    this.text = text;
  }
}

// 开发者可以通过@Builder装饰器实现布局构建
@Builder
function buildText(params: Params) {
  Column() {
    Text(params.text)
      .fontSize(20)
      .fontColor(Color.Red)
  }
  .width('100%') // 宽度方向充满画中画窗口
  .height('100%') // 高度方向充满画中画窗口
}

// 开发者可通过继承NodeController实现自定义UI控制器
class TextNodeController extends NodeController {
  private message: string;
  private textNode: BuilderNode<[Params]>|null = null;
  constructor(message: string) {
    super();
    this.message = message;
  }

  // 通过BuilderNode加载自定义布局
  makeNode(context: UIContext): FrameNode|null {
    this.textNode = new BuilderNode(context);
    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message));
    return this.textNode.getFrameNode();
  }

  // 开发者可自定义该方法实现布局更新
  update(message: string) {
    console.log(`update message: ${message}`);
    if (this.textNode !== null) {
      this.textNode.update(new Params(message));
    }
  }
}

let pipController: PiPWindow.PiPController|undefined = undefined;
let mXComponentController: XComponentController = new XComponentController(); // 开发者应使用该mXComponentController初始化XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} )，保证XComponent的内容可以被迁移到画中画窗口。
let nodeController: TextNodeController = new TextNodeController('this is custom UI');
let navId: string = "page_1"; // 假设当前页面的导航id为page_1，详见PiPConfiguration定义，具体导航名称由开发者自行定义。
let contentWidth: number = 800; // 假设当前内容宽度800px。
let contentHeight: number = 600; // 假设当前内容高度600px。
let para: Record<string, number> = { 'PropA': 47 };
let localStorage: LocalStorage = new LocalStorage(para);
let res: boolean = localStorage.setOrCreate('PropB', 121);
let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext; //请在组件内获取context，确保this.getUIContext().getHostContext()返回的结果为UIAbilityContext
let defaultWindowSize: number = 1; //指定画中画第一次拉起窗口为小窗口
let config: PiPWindow.PiPConfiguration = {
  context: ctx,
  componentController: mXComponentController,
  navigationId: navId,
  templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY,
  contentWidth: contentWidth,
  contentHeight: contentHeight,
  controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT],
  customUIController: nodeController, // 可选，如果需要在画中画显示内容上方展示自定义UI，可设置该参数。
  localStorage: localStorage, // 可选，如果需要跟踪主窗实例，可设置此参数。
  defaultWindowSizeType: defaultWindowSize //可选， 如果需要配置默认启动窗口档位，可设置此参数。
};

let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(config);
promise.then((data: PiPWindow.PiPController) => {
  pipController = data;
  console.info(`Succeeded in creating pip controller. Data:${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
});

PiPWindow.create12+

create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise<PiPController>

通过typeNode创建画中画控制器，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
configPiPConfiguration是创建画中画控制器的参数。该参数不能为空，并且构造该参数的context不能为空。构造该参数时，如果指定了templateType，需保证templateType是PiPTemplateType类型；如果指定了controlGroups，需保证controlGroups与templateType匹配，详见PiPControlGroup。
contentNodetypeNode.XComponent是用于渲染画中画窗口中的内容。该参数不能为空。

返回值：

类型说明
Promise<PiPController>Promise对象。返回当前创建的画中画控制器。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
801Capability not supported.Failed to call the API due to limited device capabilities.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { PiPWindow, typeNode, UIContext } from '@kit.ArkUI';
import { common } from '@kit.AbilityKit';

let pipController: PiPWindow.PiPController|undefined = undefined;
let xComponentController: XComponentController = new XComponentController();
let ctx = this.getUIContext().getHostContext() as common.UIAbilityContext; //请在组件内获取context，确保this.getUIContext().getHostContext()返回的结果为UIAbilityContext
let options: XComponentOptions = {
  type: XComponentType.SURFACE,
  controller: xComponentController
}
let xComponent = typeNode.createNode(this.getUIContext(), 'XComponent', options);
let contentWidth: number = 800; // 假设当前内容宽度800px。
let contentHeight: number = 600; // 假设当前内容高度600px。
let config: PiPWindow.PiPConfiguration = {
  context: ctx,
  componentController: xComponentController,
  templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY,
  contentWidth: contentWidth,
  contentHeight: contentHeight
};

let promise: Promise<PiPWindow.PiPController> = PiPWindow.create(config, xComponent);
promise.then((data: PiPWindow.PiPController) => {
  pipController = data;
  console.info(`Succeeded in creating pip controller. Data:${data}`);
}).catch((err: BusinessError) => {
  console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
});

PiPConfiguration

创建画中画控制器时的参数。

系统能力： SystemCapability.Window.SessionManager

名称类型必填说明
contextBaseContext是表示上下文环境。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
componentControllerXComponentController是表示原始XComponent控制器。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
navigationIdstring否当前page导航id，不传值则默认不需要缓存页面。
1、UIAbility使用Navigation管理页面，需要设置Navigation控件的id属性，并将该id设置给画中画控制器，确保还原场景下能够从画中画窗口恢复到原页面。
2、UIAbility使用Router管理页面时，无需设置navigationId。
3、UIAbility只有单页面时，无需设置navigationId，还原场景下也能够从画中画窗口恢复到原页面。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
templateTypePiPTemplateType否模板类型，用以区分视频播放、视频通话或视频会议，不传值则默认为视频播放模板。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
contentWidthnumber否原始内容宽度，单位为px。用于确定画中画窗口比例。当使用typeNode的方式创建PiPController时，不传值则默认为1920。当不使用typeNode的方式创建PiPController时，不传值则默认为XComponent组件的宽度。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
contentHeightnumber否原始内容高度，单位为px。用于确定画中画窗口比例。当使用typeNode的方式创建PiPController时，不传值则默认为1080。当不使用typeNode的方式创建PiPController时，不传值则默认为XComponent组件的高度。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
controlGroups12+Array<PiPControlGroup>否画中画控制面板的可选控件组列表，应用可以对此进行配置以决定是否显示。应用未配置时，面板显示基础控件（如视频播放控件组的播放/暂停控件）；应用选择配置时，则最多可以选择三个控件。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
customUIController12+NodeController否用于实现在画中画界面内容上方展示自定义UI功能，不传值则默认不使用自定义UI功能。
原子化服务API： 从API version 12开始，该接口支持在原子化服务中使用。
localStorage17+LocalStorage否页面级别的UI状态存储单元。多实例下可用来跟踪主窗实例的UI状态存储对象，不传值则无法通过画中画窗口获取主窗的UI状态存储对象。
原子化服务API： 从API version 17开始，该接口支持在原子化服务中使用。
defaultWindowSizeType19+number否画中画第一次拉起窗口大小。
0：代表不设置大小。按照上次画中画关闭前的大小启动；
1：代表小窗；
2：代表大窗；
不传值则为默认值0。
原子化服务API： 从API version 19开始，该接口支持在原子化服务中使用。

PiPWindowSize15+

画中画窗口大小。

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

系统能力： SystemCapability.Window.SessionManager

名称类型可读可写说明
widthnumber是否窗口宽度，单位为px，该参数应为正整数，不大于屏幕宽。
heightnumber是否窗口高度，单位为px，该参数应为正整数，不大于屏幕高。
scalenumber是否窗口缩放比，显示大小相对于width和height的缩放比，该参数为浮点数，取值范围大于0.0，小于等于1.0。等于1表示与width和height一样大。

PiPWindowInfo15+

画中画窗口信息。

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

系统能力： SystemCapability.Window.SessionManager

名称类型可读可写说明
windowIdnumber是否画中画窗口ID。
sizePiPWindowSize是否画中画窗口大小。

PiPTemplateType

画中画媒体类型枚举。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
VIDEO_PLAY0表示将要切换为画中画播放的媒体类型是视频，系统依此加载视频播放模板。
VIDEO_CALL1表示将要切换为画中画播放的媒体类型是视频通话，系统依此加载视频通话模板。
VIDEO_MEETING2表示将要切换为画中画播放的媒体类型是视频会议，系统依此加载视频会议模板。
VIDEO_LIVE3表示将要切换为画中画播放的媒体类型是直播，系统依此加载直播模板。

PiPState

画中画生命周期状态枚举。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
ABOUT_TO_START1表示画中画将要启动。
STARTED2表示画中画已经启动。
ABOUT_TO_STOP3表示画中画将要停止。
STOPPED4表示画中画已经停止。
ABOUT_TO_RESTORE5表示画中画将从小窗播放恢复到原始播放界面。
ERROR6表示画中画生命周期执行过程出现了异常。

PiPControlGroup12+

type PiPControlGroup = VideoPlayControlGroup|VideoCallControlGroup|VideoMeetingControlGroup|VideoLiveControlGroup

画中画控制面板的可选控件组列表，应用可以配置是否显示可选控件。默认情况下控制面板只显示基础控件（如视频播放控件组的播放/暂停控件）。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
VideoPlayControlGroup视频播放控件组。
VideoCallControlGroup视频通话控件组。
VideoMeetingControlGroup视频会议控件组。
VideoLiveControlGroup视频直播控件组。

VideoPlayControlGroup12+

视频播放控件组枚举。仅当PiPTemplateType为VIDEO_PLAY时使用。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
VIDEO_PREVIOUS_NEXT101视频上一个/下一个控件组。
与视频快进/后退控件组为互斥控件组。如添加视频快进/后退控件组，则不可添加该控件组。
FAST_FORWARD_BACKWARD102视频快进/后退控件组。
与视频上一个/下一个控件组为互斥控件组。如添加视频上一个/下一个控件组，则不可添加该控件组。

VideoCallControlGroup12+

视频通话控件组枚举。仅当PiPTemplateType 为VIDEO_CALL时使用。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
MICROPHONE_SWITCH201打开/关闭麦克风控件组。
HANG_UP_BUTTON202挂断控件组。
CAMERA_SWITCH203打开/关闭摄像头控件组。
MUTE_SWITCH204静音控件组。

VideoMeetingControlGroup12+

视频会议控件组枚举。仅当PiPTemplateType 为VIDEO_MEETING时使用。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
HANG_UP_BUTTON301挂断控件组。
CAMERA_SWITCH302打开/关闭摄像头控件组。
MUTE_SWITCH303静音控件组。
MICROPHONE_SWITCH304打开/关闭麦克风控件组。

VideoLiveControlGroup12+

视频直播控件组枚举。仅当PiPTemplateType 为VIDEO_LIVE时使用。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
VIDEO_PLAY_PAUSE401播放/暂停直播控件组。
MUTE_SWITCH402静音控件组。

PiPActionEventType

type PiPActionEventType = PiPVideoActionEvent|PiPCallActionEvent|PiPMeetingActionEvent|PiPLiveActionEvent

画中画控制面板控件动作事件类型，支持以下四种。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
PiPVideoActionEvent视频播放控制面板控件事件类型。
PiPCallActionEvent视频通话控制面板控件事件类型。
PiPMeetingActionEvent视频会议控制面板控件事件类型。
PiPLiveActionEvent直播控制面板控件事件类型。

PiPVideoActionEvent

type PiPVideoActionEvent = 'playbackStateChanged'|'nextVideo'|'previousVideo'|'fastForward'|'fastBackward'

视频播放控制事件类型。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
'playbackStateChanged'播放状态发生了变化。
'nextVideo'播放下一个视频。
'previousVideo'播放上一个视频。
'fastForward'12+视频进度快进。从API version 12 开始支持。
'fastBackward'12+视频进度后退。从API version 12 开始支持。

PiPCallActionEvent

type PiPCallActionEvent = 'hangUp'|'micStateChanged'|'videoStateChanged'|'voiceStateChanged'

视频通话控制事件类型。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
'hangUp'挂断视频通话。
'micStateChanged'打开或关闭麦克风。
'videoStateChanged'打开或关闭摄像头。
'voiceStateChanged'12+静音或解除静音。

PiPMeetingActionEvent

type PiPMeetingActionEvent = 'hangUp'|'voiceStateChanged'|'videoStateChanged'|'micStateChanged'

视频会议控制事件类型。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
'hangUp'挂断视频会议。
'voiceStateChanged'静音或解除静音。
'videoStateChanged'打开或关闭摄像头。
'micStateChanged'12+打开或关闭麦克风。

PiPLiveActionEvent

type PiPLiveActionEvent = 'playbackStateChanged'|'voiceStateChanged'

直播控制事件类型。

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

系统能力： SystemCapability.Window.SessionManager

类型说明
'playbackStateChanged'播放或暂停直播。
'voiceStateChanged'12+静音或解除静音。

PiPControlStatus12+

控制面板控件状态枚举。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
PLAY1播放。
PAUSE0暂停。
OPEN1打开。
CLOSE0关闭。

PiPControlType12+

控制面板控件类型枚举。

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

系统能力： SystemCapability.Window.SessionManager

名称值说明
VIDEO_PLAY_PAUSE0播放/暂停控件。
VIDEO_PREVIOUS1视频上一个控件。
VIDEO_NEXT2视频下一个控件。
FAST_FORWARD3视频快进控件
FAST_BACKWARD4视频快退控件。
HANG_UP_BUTTON5挂断控件。
MICROPHONE_SWITCH6打开/关闭麦克风控件。
CAMERA_SWITCH7打开/关闭摄像头控件。
MUTE_SWITCH8打开/关闭静音控件。

ControlPanelActionEventCallback12+

type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void

描述画中画控制面板控件动作事件回调。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
eventPiPActionEventType是回调画中画控制面板控件动作事件类型。
应用依据控件动作事件做相应处理，如触发'playbackStateChanged'事件时，需要开始或停止视频。
statusnumber否表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为1，关闭为0。其余控件该参数返回默认值-1。

ControlEventParam12+

画中画控制面板控件动作回调的参数。

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

系统能力： SystemCapability.Window.SessionManager

名称类型必填说明
controlTypePiPControlType是回调画中画控制面板控件动作事件类型。应用依据控件类型做相应处理，如视频模板中暂停/播放控件被点击时，需要开始或停止视频。
statusPiPControlStatus否表示可切换状态的控件当前的状态，如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组，打开为PiPControlStatus.PLAY，关闭为PiPControlStatus.PAUSE。如不具备开/关和播放/暂停状态的挂断控件默认返回值为-1。

PiPController

画中画控制器实例。用于启动、停止画中画以及更新回调注册等。

下列API示例中都需先使用PiPWindow.create()方法获取到PiPController实例，再通过此实例调用对应方法。

系统能力： SystemCapability.Window.SessionManager

startPiP

startPiP(): Promise<void>

启动画中画，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见窗口错误码。

错误码ID错误信息
1300012The PiP window state is abnormal.
1300013Failed to create the PiP window.
1300014PiP internal error.
1300015Repeated PiP operation.

示例：

let promise : Promise<void> = pipController.startPiP();
promise.then(() => {
  console.info(`Succeeded in starting pip.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`);
});

stopPiP

stopPiP(): Promise<void>

停止画中画，使用Promise异步回调。

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

系统能力： SystemCapability.Window.SessionManager

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见窗口错误码。

错误码ID错误信息
1300011Failed to destroy the PiP window.
1300012The PiP window state is abnormal.
1300015Repeated PiP operation.

示例：

let promise : Promise<void> = pipController.stopPiP();
promise.then(() => {
  console.info(`Succeeded in stopping pip.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`);
});

setAutoStartEnabled

setAutoStartEnabled(enable: boolean): void

设置是否在返回桌面时自动启动画中画，默认不自动拉起。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
enableboolean是如返回桌面时需自动启动画中画，则该参数配置为true，否则为false。若设置中自动启动画中画开关为关闭状态，就算该参数配置为true，应用返回桌面时也不会自动启动画中画窗口。

示例：

let enable: boolean = true;
pipController.setAutoStartEnabled(enable);

updateContentSize

updateContentSize(width: number, height: number): void

当媒体源切换时，向画中画控制器更新媒体源尺寸信息。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
widthnumber是表示媒体内容宽度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。
heightnumber是表示媒体内容高度，必须为大于0的数字，单位为px。用于更新画中画窗口比例。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.

示例：

let width: number = 540; // 假设当前内容宽度变为540px。
let height: number = 960; // 假设当前内容高度变为960px。
pipController.updateContentSize(width, height);

updatePiPControlStatus12+

updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void

更新画中画控制面板控件功能状态。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
controlTypePiPControlType是表示画中画控制面板控件类型。目前仅支持VIDEO_PLAY_PAUSE、MICROPHONE_SWITCH、CAMERA_SWITCH和MUTE_SWITCH这几种控件类型，传入其他控件类型无效。
statusPiPControlStatus是表示画中画控制面板控件状态。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed

示例：

let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。
let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // 视频播放控制面板中播放/暂停控件为播放状态。
pipController.updatePiPControlStatus(controlType, status);

updateContentNode18+

updateContentNode(contentNode: typeNode.XComponent): Promise<void>

更新画中画节点内容。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
contentNodetypeNode.XComponent是用于渲染画中画窗口中的内容。该参数不能为空。

返回值：

类型说明
Promise<void>无返回结果的Promise对象。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed
801Capability not supported.Failed to call the API due to limited device capabilities.
1300014PiP internal error.

示例：

import { typeNode, UIContext } from '@kit.ArkUI';

let context: UIContext|undefined = undefined; // 可传入UIContext或在布局中通过this.getUIContext()为context赋有效值

try {
  let contentNode = typeNode.createNode(context, "XComponent");
  pipController.updateContentNode(contentNode);
} catch (exception) {
  console.error(`Failed to update content node. Cause: ${exception.code}, message: ${exception.message}`);
}

setPiPControlEnabled12+

setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void

更新控制面板控件使能状态。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
controlTypePiPControlType是表示画中画控制面板控件类型。
enabledboolean是表示画中画控制面板控件使能状态。true表示控件为可使用状态，false则为禁用状态。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed

示例：

let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。
let enabled: boolean = false; // 视频播放控制面板中播放/暂停控件为禁用状态。
pipController.setPiPControlEnabled(controlType, enabled);

getPiPWindowInfo15+

getPiPWindowInfo(): Promise<PiPWindowInfo>

获取画中画窗口信息。

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

系统能力： SystemCapability.Window.SessionManager

返回值：

类型说明
Promise<PiPWindowInfo>Promise对象，返回当前画中画窗口信息。

错误码：

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

错误码ID错误信息
801Capability not supported. Failed to call the API due to limited device capabilities.
1300014PiP internal error.

示例：

let pipWindowInfo: PiPWindow.PiPWindowInfo|undefined = undefined;
try {
  let promise : Promise<PiPWindow.PiPWindowInfo> = pipController.getPiPWindowInfo();
  promise.then((data) => {
    pipWindowInfo = data;
    console.info('Success in get pip window info. Info: ' + JSON.stringify(data));
  }).catch((err: BusinessError) => {
    console.error(`Failed to get pip window info. Cause code: ${err.code}, message: ${err.message}`);
  });
} catch (exception) {
  console.error(`Failed to get pip window info. Cause code: ${exception.code}, message: ${exception.message}`);
}

on('stateChange')

on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void

开启画中画生命周期状态的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。
callbackfunction是回调生命周期状态变化事件以及原因。
state：PiPState，表示当前画中画生命周期状态。
reason：string，表示当前生命周期的切换原因。

示例：

pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => {
  let curState: string = '';
  switch (state) {
    case PiPWindow.PiPState.ABOUT_TO_START:
      curState = 'ABOUT_TO_START';
      break;
    case PiPWindow.PiPState.STARTED:
      curState = 'STARTED';
      break;
    case PiPWindow.PiPState.ABOUT_TO_STOP:
      curState = 'ABOUT_TO_STOP';
      break;
    case PiPWindow.PiPState.STOPPED:
      curState = 'STOPPED';
      break;
    case PiPWindow.PiPState.ABOUT_TO_RESTORE:  
      curState = 'ABOUT_TO_RESTORE';
      break;
    case PiPWindow.PiPState.ERROR:
      curState = 'ERROR';
      break;
    default:
      break;
  }
  console.info('stateChange:' + curState + ' reason:' + reason);
});

off('stateChange')

off(type: 'stateChange'): void

关闭画中画生命周期状态的监听。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'stateChange'，即画中画生命周期状态变化事件。

示例：

pipController.off('stateChange');

on('controlPanelActionEvent')

on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void

开启画中画控制面板控件动作事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。推荐使用on('controlEvent')来开启画中画控制面板控件动作事件的监听。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。
callbackControlPanelActionEventCallback是描述画中画控制面板控件动作事件回调。

示例：

pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => {
  switch (event) {
    case 'playbackStateChanged':
      if (status === 0) {
        //停止视频
      } else if (status === 1) {
        //播放视频
      }
      break;
    case 'nextVideo':
      // 切换到下一个视频
      break;
    case 'previousVideo':
      // 切换到上一个视频
      break;
    case 'fastForward':
      // 视频进度快进
      break;
    case 'fastBackward':
      // 视频进度后退
      break;
    default:
      break;
  }
  console.info('registerActionEventCallback, event:' + event);
});

on('controlEvent')12+

on(type: 'controlEvent', callback: Callback<ControlEventParam>): void

开启画中画控制面板控件动作事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。
callbackCallback<ControlEventParam>是描述画中画控制面板控件动作事件回调。

示例：

pipController.on('controlEvent', (control) => {
  switch (control.controlType) {
    case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE:
      if (control.status === PiPWindow.PiPControlStatus.PAUSE) {
        //停止视频
      } else if (control.status === PiPWindow.PiPControlStatus.PLAY) {
        //播放视频
      }
      break;
    case PiPWindow.PiPControlType.VIDEO_NEXT:
      // 切换到下一个视频
      break;
    case PiPWindow.PiPControlType.VIDEO_PREVIOUS:
      // 切换到上一个视频
      break;
    case PiPWindow.PiPControlType.FAST_FORWARD:
      // 视频进度快进
      break;
    case PiPWindow.PiPControlType.FAST_BACKWARD:
      // 视频进度后退
      break;
    default:
      break;
  }
  console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status);
});

off('controlPanelActionEvent')

off(type: 'controlPanelActionEvent'): void

关闭画中画控制面板控件动作事件的监听。推荐使用off('controlEvent')来关闭画中画控制面板控件动作事件的监听。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'controlPanelActionEvent'，即画中画控制面板控件动作事件。

示例：

pipController.off('controlPanelActionEvent');

off('controlEvent')12+

off(type: 'controlEvent', callback?: Callback<ControlEventParam>): void

关闭画中画控制面板控件动作事件的监听。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'controlEvent'，即画中画控制面板控件动作事件。
callbackCallback<ControlEventParam>否描述画中画控制面板控件动作事件回调。如果不传该参数时，解除type为'controlEvent'的所有回调。

示例：

pipController.off('controlEvent', () => {});

on('pipWindowSizeChange')15+

on(type: 'pipWindowSizeChange', callback: Callback<PiPWindowSize>): void

开启画中画窗口尺寸变化事件的监听，建议在不需要使用时关闭监听，否则可能存在内存泄漏。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。
callbackCallback<PiPWindowSize>是回调函数。返回当前画中画窗口的尺寸。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801Capability not supported.Failed to call the API due to limited device capabilities.
1300014PiP internal error.

示例：

try {
  pipController.on('pipWindowSizeChange', (size: PiPWindow.PiPWindowSize) => {
    console.info('Succeeded in enabling the listener for pip window size changes. size: ' + JSON.stringify(size));
  });
} catch (exception) {
  console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

off('pipWindowSizeChange')15+

off(type: 'pipWindowSizeChange', callback?: Callback<PiPWindowSize>): void

关闭画中画窗口尺寸变化事件的监听。

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

系统能力： SystemCapability.Window.SessionManager

参数：

参数名类型必填说明
typestring是监听事件，固定为'pipWindowSizeChange'，即画中画窗口尺寸变化事件。
callbackCallback<PiPWindowSize>否回调函数。返回当前画中画窗口的尺寸。如果传入参数，则关闭该监听。如果未传入参数，解除type为'pipWindowSizeChange'的所有回调。

错误码：

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

错误码ID错误信息
401Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed.
801Capability not supported.Failed to call the API due to limited device capabilities.
1300014PiP internal error.

示例：

const callback = (size: PiPWindow.PiPWindowSize) => {
  // ...
}
try {
  // 通过on接口开启监听
  pipController.on('pipWindowSizeChange', callback);
} catch (exception) {
  console.error(`Failed to enable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

try {
  // 关闭指定callback的监听
  pipController.off('pipWindowSizeChange', callback);
  // 如果通过on开启多个callback进行监听，同时关闭所有监听：
  pipController.off('pipWindowSizeChange');
} catch (exception) {
  console.error(`Failed to disable the listener for pip window size changes. Cause code: ${exception.code}, message: ${exception.message}`);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkUI（方舟UI框架）

harmony 鸿蒙ARKUI_TextPickerCascadeRangeContent

harmony 鸿蒙ARKUI_TextPickerRangeContent

harmony 鸿蒙ArkUI_AnimateCompleteCallback

harmony 鸿蒙ArkUI_AttributeItem

harmony 鸿蒙ArkUI_ColorStop

harmony 鸿蒙ArkUI_ContextCallback

harmony 鸿蒙ArkUI_EventModule

harmony 鸿蒙ArkUI_ExpectedFrameRateRange

harmony 鸿蒙ArkUI_IntOffset

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/pk6Mke