场景介绍
应用在视频播放、视频会议、视频通话等场景下,可以使用画中画能力将视频内容以小窗(画中画)模式呈现。切换为小窗(画中画)模式后,用户可以进行其他界面操作,提升使用体验。
画中画的常见使用场景有以下几种:
- 视频播放。
- 视频通话。
- 视频会议。
- 直播。
约束与限制
- 需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块,参考系统能力SystemCapability使用指南。
- 仅支持以XComponent作为媒体流播放组件的界面进入画中画模式,XComponent的type必须为’surface’或者XComponentType.SURFACE。
- UIAbility使用Navigation管理页面时,需要设置Navigation控件的id属性,并将该id传递给画中画控制器,确保还原时可以正常恢复原页面。
- UIAbility使用页面路由router管理页面时(不推荐),启动画中画后,UIAbility不要切换到其他页面,否则还原时无法恢复到原页面。
- 基于安全考虑,应用处于后台时不允许通过startPiP启动画中画。针对应用返回后台时需要启动画中画的场景,建议使用setAutoStartEnabled(true)实现自动启动。
接口说明
以下是画中画功能的常用接口,更多接口及使用参考@ohos.PiPWindow (画中画窗口)。
交互方式
画中画窗口提供以下交互方式:
- 单击画中画窗口:如果画中画控制层未显示,则显示画中画控制层,3秒后自动隐藏控制层;如果当前控制层已显示,则隐藏画中画控制层。
- 双击画中画窗口:放大或缩小画中画窗口。
- 拖动画中画窗口:可以将画中画窗口拖动到屏幕任意位置。如果将画中画窗口拖动到屏幕左右边缘,画中画窗口会自动隐藏;隐藏后在屏幕边缘显示画中画隐藏图标,点击该图标后画中画窗口恢复显示。
- 画中画控制层提供以下功能:
- 窗口控制:包括“关闭”和“恢复全屏窗口”功能。点按“关闭”按钮后,画中画窗口关闭;点按“恢复全屏窗口”按钮后,将从画中画窗口恢复到应用原始界面。
- 内容控制:内容控制区根据不同场景呈现不同,应用可根据实际场景需要进行设置,各场景控制层示意图如下所示。
图1不同场景下画中画控制层的不同呈现
配置画中画控制层可选控件
在使用create接口创建画中画时,可通过在PiPConfiguration中新增PiPControlGroup类型的数组配置当前画中画控制层控件。
-
视频播放场景可通过配置VideoPlayControlGroup来显示可选的控制层控件。
图2视频播放场景配置控制层可选控件
-
视频通话场景可通过配置VideoCallControlGroup来显示可选的控制层控件。示意图如下所示。
图3视频通话场景配置控制层可选控件
若不配置,视频通话模版默认不存在任何按钮,点击画中画窗口即可启动还原(见下图左,未配置任何控件的操作示意图)。下图右为配置控件的操作示意图。
-
视频会议场景可通过配置VideoMeetingControlGroup来显示可选的控制层控件。示意图如下所示。若不配置,视频会议模版默认不存在任何按钮,点击画中画窗口即可启动还原(与视频通话模版操作示意图一致)。
图4视频会议场景配置控制层可选控件
直播场景可通过配置VideoLiveControlGroup来显示可选的控制层控件。示意图如下所示。
图5直播场景配置控制层可选控件
在画中画内容上方展示自定义UI
在使用create接口创建画中画时,可通过在PiPConfiguration中传入customUIController来显示自定义UI。注:自定义显示的UI无法响应交互事件。
图6在画中画内容上方显示自定义UI