场景介绍
应用在视频播放、视频会议、视频通话等场景下，可以使用画中画能力将视频内容以小窗（画中画）模式呈现。切换为小窗（画中画）模式后，用户可以进行其他界面操作，提升使用体验。
画中画的常见使用场景有以下几种：
- 视频播放。
- 视频通话。
- 视频会议。
- 直播。
约束与限制
- 需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块，参考 系统能力SystemCapability使用指南 。
- 仅支持以 XComponent 作为媒体流播放组件的界面进入画中画模式，XComponent的type必须为’surface’或者XComponentType.SURFACE。
- UIAbility使用 Navigation 管理页面时，需要设置Navigation控件的id属性，并将该id传递给画中画控制器，确保还原时可以正常恢复原页面。
- UIAbility使用 页面路由router 管理页面时（不推荐），启动画中画后，UIAbility不要切换到其他页面，否则还原时无法恢复到原页面。
接口说明
以下是画中画功能的常用接口，更多接口及使用参考 @ohos.PiPWindow (画中画窗口) 。
| 接口名 | 描述 |
|---|---|
| isPiPEnabled(): boolean | 判断当前系统是否开启画中画功能。 |
| create(config: PiPConfiguration): Promise | 创建画中画控制器。 |
| startPiP(): Promise | 启动画中画。 |
| stopPiP(): Promise | 停止画中画。 |
| setAutoStartEnabled(enable: boolean): void | 设置是否需要在返回桌面时自动启动画中画。 |
| updateContentSize(width: number, height: number): void | 当媒体源切换时，向画中画控制器更新媒体源尺寸信息。 |
| on(type: ‘stateChange’, callback: (state: PiPState, reason: string) => void): void | 开启画中画生命周期状态的监听。 |
| off(type: ‘stateChange’): void | 关闭画中画生命周期状态的监听。 |
| on(type: ‘controlPanelActionEvent’, callback: ControlPanelActionEventCallback): void | 开启画中画控制事件的监听。 |
| off(type: ‘controlPanelActionEvent’): void | 关闭画中画控制事件的监听。 |
交互方式
画中画窗口提供以下交互方式：
-
单击画中画窗口：如果画中画控制层未显示，则显示画中画控制层，3秒后自动隐藏控制层；如果当前控制层已显示，则隐藏画中画控制层。
-
双击画中画窗口：放大或缩小画中画窗口。
-
拖动画中画窗口：可以将画中画窗口拖动到屏幕任意位置。如果将画中画窗口拖动到屏幕左右边缘，画中画窗口会自动隐藏；隐藏后在屏幕边缘显示画中画隐藏图标，点击该图标后画中画窗口恢复显示。
-
画中画控制层提供以下功能：
- 窗口控制：包括“关闭”和“恢复全屏窗口”功能。点按“关闭”按钮后，画中画窗口关闭；点按“恢复全屏窗口”按钮后，将从画中画窗口恢复到应用原始界面。
- 内容控制：内容控制区根据不同场景呈现不同，应用可根据实际场景需要进行设置，各场景控制层示意图如下所示。
**图1 **不同场景下画中画控制层的不同呈现
配置画中画控制层可选控件
在使用 create 接口创建画中画时，可通过在 PiPConfiguration 中新增 PiPControlGroup 类型的数组配置当前画中画控制层控件。
- 视频播放场景可通过配置 VideoPlayControlGroup 来显示可选的控制层控件。
**图2 **视频播放场景配置控制层可选控件
- 视频通话场景可通过配置 VideoCallControlGroup 来显示可选的控制层控件。示意图如下所示。
**图3 **视频通话场景配置控制层可选控件
若不配置，视频通话模版默认不存在任何按钮，点击画中画窗口即可启动还原（见下图左，未配置任何控件的操作示意图）。下图右为配置控件的操作示意图。
- 视频会议场景可通过配置 VideoMeetingControlGroup 来显示可选的控制层控件。示意图如下所示。若不配置，视频会议模版默认不存在任何按钮，点击画中画窗口即可启动还原（与视频通话模版操作示意图一致）。
**图4 **视频会议场景配置控制层可选控件
画中画功能的开发
本文以视频播放为例，介绍画中画功能的基本开发步骤。
开发步骤
- 创建画中画控制器，注册生命周期事件以及控制事件回调。
- 通过create接口创建画中画控制器实例。
- 通过画中画控制器实例的setAutoStartEnabled接口设置是否需要在应用返回桌面时自动启动画中画。
- 通过画中画控制器实例的on(‘stateChange’)接口注册生命周期事件回调。
- 通过画中画控制器实例的on(‘controlPanelActionEvent’)接口注册控制事件回调。
- 启动画中画。
创建画中画控制器实例后，通过startPiP接口启动画中画。
- 更新媒体源尺寸信息。
画中画媒体源更新后（如切换视频），通过画中画控制器实例的updateContentSize接口更新媒体源尺寸信息，以调整画中画窗口比例。
- 关闭画中画。
当不再需要显示画中画时，可根据业务需要，通过画中画控制器实例的stopPiP接口关闭画中画。
// Index.ets
// 该页面用于展示Navigation在画中画场景的使用。如果UIAbility是单页面，则无需使用Navigation
import { Page1 } from './Page1'
@Entry
@Component
struct Index {
@Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack();
private navId: string = 'navId';
@Builder
PageMap(name: string) {
if (name === 'pageOne') {
Page1({navId: this.navId});
}
}
build() {
Navigation(this.pageInfos) {
Column() {
Button('pushPath', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pageInfos.pushPath({ name: 'pageOne' }) // 将name指定的NavDestination页面信息入栈
})
.stateStyles({
pressed: {
.backgroundColor(Color.Red);
},
normal: {
.backgroundColor(Color.Blue);
}
})
}
}.title('NavIndex').navDestination(this.PageMap)
.id(this.navId) // 设置Navigation组件的id属性
}
}
示例中的视频播放需要使用AVPlayer，具体示例可参考 视频播放 。
// Page1.ets
// 该页面用于展示画中画功能的基本使用
import { PiPWindow } from '@kit.ArkUI'; // 引入PiPWindow模块
import { AVPlayerDemo } from './AVPlayerDemo'; // 请自行实现视频播放的相关开发
import { BusinessError } from '@kit.BasicServicesKit';
const TAG = 'Page1';
@Component
export struct Page1 {
@Consume('pageInfos') pageInfos: NavPathStack;
private surfaceId: string = ''; // surfaceId，用于关联XComponent与视频播放器
private mXComponentController: XComponentController = new XComponentController();
private player?: AVPlayerDemo = undefined;
private pipController?: PiPWindow.PiPController = undefined;
navId: string = '';
build() {
NavDestination() {
Column() {
// XComponent控件，用于播放视频流
XComponent({ id: 'pipDemo', type: 'surface', controller: this.mXComponentController })
.onLoad(() => {
this.surfaceId = this.mXComponentController.getXComponentSurfaceId();
// 需要设置AVPlayer的surfaceId为XComponentController的surfaceId
this.player = new AVPlayerDemo(this.surfaceId);
this.player.avPlayerFdSrcDemo();
})
.onDestroy(() => {
console.info(`[${TAG}] XComponent onDestroy`);
})
.size({ width: '100%', height: '800px' })
Row({ space: 20 }) {
Button('start') // 启动画中画
.onClick(() => {
this.startPip();
})
.stateStyles({
pressed: {
.backgroundColor(Color.Red);
},
normal: {
.backgroundColor(Color.Blue);
}
})
Button('stop') // 停止画中画
.onClick(() => {
this.stopPip();
})
.stateStyles({
pressed: {
.backgroundColor(Color.Red);
},
normal: {
.backgroundColor(Color.Blue);
}
})
Button('updateSize') // 更新视频尺寸
.onClick(() => {
// 此处设置的宽高应为媒体内容宽高，需要通过媒体相关接口或回调获取
// 例如使用AVPlayer播放视频时，可通过videoSizeChange回调获取媒体源更新后的尺寸
this.updateContentSize(900, 1600);
})
.stateStyles({
pressed: {
.backgroundColor(Color.Red);
},
normal: {
.backgroundColor(Color.Blue);
}
})
}
.size({ width: '100%', height: 60 })
.justifyContent(FlexAlign.SpaceAround)
}
.justifyContent(FlexAlign.Center)
.height('100%')
.width('100%')
}
}
startPip() {
if (!PiPWindow.isPiPEnabled()) {
console.error(`picture in picture disabled for current OS`);
return;
}
let config: PiPWindow.PiPConfiguration = {
context: getContext(this),
componentController: this.mXComponentController,
// 当前page导航id
// 1、UIAbility使用Navigation管理页面，需要设置Navigation控件的id属性，并将该id设置给画中画控制器，确保还原场景下能够从画中画窗口恢复到原页面
// 2、UIAbility使用Router管理页面时（画中画场景不推荐该导航方式），无需设置navigationId。注意：该场景下启动画中画后，不要进行页面切换，否则还原场景可能出现异常
// 3、UIAbility只有单页面时，无需设置navigationId，还原场景下也能够从画中画窗口恢复到原页面
navigationId: this.navId,
templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY, // 对于视频通话、视频会议等场景，需要设置相应的模板类型
contentWidth: 800, // 可选，创建画中画控制器时系统可通过XComponent组件大小设置画中画窗口比例
contentHeight: 600, // 可选，创建画中画控制器时系统可通过XComponent组件大小设置画中画窗口比例
controlGroups:[PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], // 可选，对于视频通话、视频会议和视频直播场景，可通过该属性选择对应模板类型下需显示的的控件组
};
// 步骤1：创建画中画控制器，通过create接口创建画中画控制器实例
let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config);
promise.then((controller : PiPWindow.PiPController) => {
this.pipController = controller;
// 步骤1：初始化画中画控制器
this.initPipController();
// 步骤2：通过startPiP接口启动画中画
this.pipController.startPiP().then(() => {
console.info(`Succeeded in starting pip.`);
}).catch((err: BusinessError) => {
console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`);
});
}).catch((err: BusinessError) => {
console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
});
}
initPipController() {
if (!this.pipController) {
return;
}
// 步骤1：通过setAutoStartEnabled接口设置是否需要在应用返回桌面时自动启动画中画，注册stateChange和controlPanelActionEvent回调
this.pipController.setAutoStartEnabled(false /*or true if necessary*/); // 默认为false
this.pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => {
this.onStateChange(state, reason);
});
this.pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => {
this.onActionEvent(event, status);
});
}
onStateChange(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(`[${TAG}] onStateChange: ${curState}, reason: ${reason}`);
}
onActionEvent(event: PiPWindow.PiPActionEventType, status?: number) {
switch (event) {
case 'playbackStateChanged':
// 开始或停止视频
if (status === 0) {
// 停止视频
} else if (status === 1) {
// 播放视频
}
break;
case 'nextVideo':
// 播放上一个视频
break;
case 'previousVideo':
// 播放下一个视频
break;
default:
break;
}
}
// 步骤3：视频内容变化时，向画中画控制器更新视频尺寸信息，用于调整画中画窗口比例
updateContentSize(width: number, height: number) {
if (this.pipController) {
this.pipController.updateContentSize(width, height);
}
}
// 步骤4：当不再需要显示画中画时，通过stopPiP接口关闭画中画
stopPip() {
if (this.pipController) {
let promise : Promise<void> = this.pipController.stopPiP();
promise.then(() => {
console.info(`Succeeded in stopping pip.`);
this.pipController?.off('stateChange'); // 如果已注册stateChange回调，停止画中画时取消注册该回调
this.pipController?.off('controlPanelActionEvent'); // 如果已注册controlPanelActionEvent回调，停止画中画时取消注册该回调
}).catch((err: BusinessError) => {
console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`);
});
}
}
}
以上示例代码对应的示意图如下所示：
鸿蒙全栈开发全新学习指南
有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以要有一份实用的鸿蒙（HarmonyOS NEXT）学习路线与学习文档用来跟着学习是非常有必要的。
针对一些列因素，整理了一套纯血版鸿蒙（HarmonyOS Next）全栈开发技术的学习路线，包含了鸿蒙开发必掌握的核心知识要点，内容有（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、WebGL、元服务、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony驱动开发、系统定制移植等等）鸿蒙（HarmonyOS NEXT）技术知识点。
本路线共分为四个阶段：
第一阶段：鸿蒙初中级开发必备技能
第二阶段：鸿蒙南北双向高工技能基础：gitee.com/MNxiaona/733GH
第三阶段：应用开发中高级就业技术
第四阶段：全网首发-工业级南向设备开发就业技术：gitee.com/MNxiaona/733GH
《鸿蒙 (Harmony OS)开发学习手册》（共计892页）
如何快速入门？
1.基本概念
2.构建第一个ArkTS应用
3.……
开发基础知识:gitee.com/MNxiaona/733GH
1.应用基础知识
2.配置文件
3.应用数据管理
4.应用安全管理
5.应用隐私保护
6.三方应用调用管控机制
7.资源分类与访问
8.学习ArkTS语言
9.……
基于ArkTS 开发
1.Ability开发
2.UI开发
3.公共事件与通知
4.窗口管理
5.媒体
6.安全
7.网络与链接
8.电话服务
9.数据管理
10.后台任务(Background Task)管理
11.设备管理
12.设备使用信息统计
13.DFX
14.国际化开发
15.折叠屏系列
16.……
鸿蒙开发面试真题（含参考答案）:gitee.com/MNxiaona/733GH
鸿蒙入门教学视频：
美团APP实战开发教学：gitee.com/MNxiaona/733GH
写在最后
- 如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：
- 点赞，转发，有你们的 『点赞和评论』，才是我创造的动力。
- 关注小编，同时可以期待后续文章ing🚀，不定期分享原创知识。
- 想要获取更多完整鸿蒙最新学习资源，请移步前往小编：
gitee.com/MNxiaona/733GH
623
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
