鸿蒙5.0版开发：UI界面-@ohos.PiPWindow (画中画窗口)

最新推荐文章于 2025-10-29 07:30:00 发布

原创

最新推荐文章于 2025-10-29 07:30:00 发布 · 1.4k 阅读

8 ·

CC 4.0 BY-SA版权

文章标签：

#harmonyos #华为 #android #前端 #ArkTS #UI

往期鸿蒙全套实战文章必看：

@ohos.PiPWindow (画中画窗口)

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

说明：

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

需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块。

导入模块

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

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍。

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

示例：

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

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 config: PiPWindow.PiPConfiguration = {
  context: getContext(this),
  componentController: mXComponentController,
  navigationId: navId,
  templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY,
  contentWidth: contentWidth,
  contentHeight: contentHeight,
  controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT],
  customUIController: nodeController, // 可选，如果需要在画中画显示内容上方展示自定义UI，可设置该参数。
};

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

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍。

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

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { PiPWindow, UIContext } from '@kit.ArkUI';
import { typeNode } from '@ohos.arkui.node';

let pipController: PiPWindow.PiPController | undef