鸿蒙Harmony应用程序开发：画中画功能

55 0 0

场景介绍

应用在视频播放、视频会议、视频通话等场景下，可以使用画中画能力将视频内容以小窗（画中画）模式呈现。切换为小窗（画中画）模式后，用户可以进行其他界面操作，提升使用体验。

画中画的常见使用场景有以下几种：

视频播放。视频通话。视频会议。直播。

接口说明

以下是画中画功能的常用接口

接口名	描述
isPiPEnabled(): boolean	判断当前系统是否开启画中画功能。
create(config: PiPConfiguration): Promise<PiPController>	创建画中画控制器。
startPiP(): Promise<void>	启动画中画。
stopPiP(): Promise<void>	停止画中画。
setAutoStartEnabled(enable: boolean): void	设置是否需要在返回桌面时自动启动画中画。
updateContentSize(width: number, height: number): void	当媒体源切换时，向画中画控制器更新媒体源尺寸信息。
on(type: ‘stateChange’, callback: (state: PiPState, reason: string) => void): void	开启画中画控制面板控件动作事件的监听。推荐使用on(‘controlEvent’)来开启画中画控制面板控件动作事件的监听。
off(type: ‘stateChange’): void	关闭画中画控制面板控件动作事件的监听。推荐使用off(‘controlEvent’)来关闭画中画控制面板控件动作事件的监听。
on(type: ‘controlPanelActionEvent’, callback: ControlPanelActionEventCallback): void	开启画中画控制事件的监听。
off(type: ‘controlPanelActionEvent’): void	关闭画中画控制事件的监听。
updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void	更新画中画控制面板控件状态。
setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void	设置控制面板控件使能状态。
on(type: ‘controlEvent’, callback: CallBack<ControlEventParam>): void	开启画中画控制面板控件动作事件的监听。
off(type: ‘controlEvent’, callback?: CallBack<ControlEventParam>): void	关闭画中画控制面板控件动作事件的监听。

交互方式

画中画窗口提供以下交互方式：

单击画中画窗口：如果画中画控制层未显示，则显示画中画控制层，3秒后自动隐藏控制层；如果当前控制层已显示，则隐藏画中画控制层。双击画中画窗口：放大或缩小画中画窗口。拖动画中画窗口：可以将画中画窗口拖动到屏幕任意位置。如果将画中画窗口拖动到屏幕左右边缘，画中画窗口会自动隐藏；隐藏后在屏幕边缘显示画中画隐藏图标，点击该图标后画中画窗口恢复显示。画中画控制层提供以下功能：
窗口控制：包括“关闭”和“恢复全屏窗口”功能。点按“关闭”按钮后，画中画窗口关闭；点按“恢复全屏窗口”按钮后，将从画中画窗口恢复到应用原始界面。内容控制：内容控制区根据不同场景呈现不同，应用可根据实际场景需要进行设置，各场景控制层示意图如下所示。

图1 不同场景下画中画控制层的不同呈现

鸿蒙Harmony应用程序开发：画中画功能

配置画中画控制层可选控件

在使用create接口创建画中画时，可通过在PiPConfiguration中新增PiPControlGroup类型的数组配置当前画中画控制层控件。

视频播放场景可通过配置VideoPlayControlGroup来显示可选的控制层控件。

图2 视频播放场景配置控制层可选控件

鸿蒙Harmony应用程序开发：画中画功能

视频通话场景可通过配置VideoCallControlGroup来显示可选的控制层控件。示意图如下所示。

图3 视频通话场景配置控制层可选控件

鸿蒙Harmony应用程序开发：画中画功能

若不配置，视频通话模版默认不存在任何按钮，点击画中画窗口即可启动还原（见下图左，未配置任何控件的操作示意图）。下图右为配置控件的操作示意图。

鸿蒙Harmony应用程序开发：画中画功能

视频会议场景可通过配置VideoMeetingControlGroup来显示可选的控制层控件。示意图如下所示。若不配置，视频会议模版默认不存在任何按钮，点击画中画窗口即可启动还原（与视频通话模版操作示意图一致）。

图4 视频会议场景配置控制层可选控件

鸿蒙Harmony应用程序开发：画中画功能

直播场景可通过配置VideoLiveControlGroup来显示可选的控制层控件。示意图如下所示。

图5 直播场景配置控制层可选控件

鸿蒙Harmony应用程序开发：画中画功能

在画中画内容上方展示自定义UI

在使用create接口创建画中画时，可通过在PiPConfiguration中传入customUIController来显示自定义UI。注：自定义显示的UI无法响应交互事件。

图6 在画中画内容上方显示自定义UI

鸿蒙Harmony应用程序开发：画中画功能

更新画中画控制面板控件状态

应用可以使用updatePiPControlStatus接口更新控制面板控件的功能状态，如将视频播放模板下VIDEO_PLAY_PAUSE控件的播放状态更改为暂停状态，见下图。

应用也可以使用setPiPControlEnabled接口设置控制面板控件的使能状态，如将视频播放模板下VIDEO_PREVIOUS控件从可点击状态变为不可点击状态，见下图。

图7 更新控件功能状态设置控件使能状态

鸿蒙Harmony应用程序开发：画中画功能

画中画功能的开发

本文以视频播放为例，介绍画中画功能的基本开发步骤。

开发步骤

创建画中画控制器，注册生命周期事件以及控制事件回调。

通过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 { AVPlayerDemo } from './AVPlayerDemo'; // 请自行实现视频播放的相关开发


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


import { BusinessError } from '@kit.BasicServicesKit';


 


const TAG = 'Page1';


 


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));


    }


  }


}


 


@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;


  private nodeController: TextNodeController = new TextNodeController('this is custom UI');


  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: 1920, // 可选，创建画中画控制器时系统可通过XComponent组件大小设置画中画窗口比例


      contentHeight: 1080, // 可选，创建画中画控制器时系统可通过XComponent组件大小设置画中画窗口比例


      controlGroups:[PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT], // 可选，对于视频通话、视频会议和视频直播场景，可通过该属性选择对应模板类型下需显示的的控件组


      customUIController: this.nodeController, // 可选，如果需要在画中画显示内容上方展示自定义UI，可设置该参数。


    };


    // 步骤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}`);


      });


    }


  }


}

以上示例代码对应的示意图如下所示：

鸿蒙Harmony应用程序开发：画中画功能

最后

小编在之前的鸿蒙系统扫盲中，有很多朋友给我留言，不同的角度的问了一些问题，我明显感觉到一点，那就是许多人参与鸿蒙开发，但是又不知道从哪里下手，因为资料太多，太杂，教授的人也多，无从选择。有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）资料用来跟着学习是非常有必要的。

为了确保高效学习，建议规划清晰的学习路线，涵盖以下关键阶段：

→【纯血版鸿蒙全套最新学习资料】希望这一份鸿蒙学习资料能够给大家带来帮助~

鸿蒙（HarmonyOS NEXT）最新学习路线

鸿蒙Harmony应用程序开发：画中画功能

该路线图包含基础技能、就业必备技能、多媒体技术、六大电商APP、进阶高级技能、实战就业级设备开发，不仅补充了华为官网未涉及的解决方案

路线图适合人群：

IT开发人员：想要拓展职业边界
零基础小白：鸿蒙爱好者，希望从0到1学习，增加一项技能。
技术提升/进阶跳槽：发展瓶颈期，提升职场竞争力，快速掌握鸿蒙技术

2.视频学习资料+学习PDF文档

HarmonyOS Next 最新全套视频教程 （鸿蒙语法ArkTS、TypeScript、ArkUI教程……）

鸿蒙Harmony应用程序开发：画中画功能

纯血版鸿蒙全套学习资料（面试、文档、全套视频等）

鸿蒙Harmony应用程序开发：画中画功能