1# @ohos.PiPWindow (画中画窗口)
2
3该模块提供画中画基础功能,包括判断当前系统是否开启画中画功能,以及创建画中画控制器用于启动、停止画中画等。主要用于视频播放、视频通话或视频会议场景下,以小窗(画中画)模式呈现内容。
4
5> **说明:**
6>
7> 本模块首批接口从API version 11开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8>
9> 需要在支持SystemCapability.Window.SessionManager能力的系统上使用该模块,<!--RP1-->参考[系统能力SystemCapability使用指南](../syscap.md)<!--RP1End-->。
10
11## 导入模块
12
13```ts
14import { PiPWindow } from '@kit.ArkUI';
15```
16
17## PiPWindow.isPiPEnabled
18
19isPiPEnabled(): boolean
20
21用于判断当前系统是否支持画中画功能。
22
23**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
24
25**系统能力:** SystemCapability.Window.SessionManager
26
27**返回值:**
28
29| 类型       | 说明                                  |
30|----------|-------------------------------------|
31| boolean  | 当前系统是否开启画中画功能。true表示支持,false则表示不支持。 |
32
33**示例:**
34
35```ts
36let enable: boolean = PiPWindow.isPiPEnabled();
37console.info('isPipEnabled:' + enable);
38```
39
40## PiPWindow.create
41
42create(config: PiPConfiguration): Promise&lt;PiPController&gt;
43
44创建画中画控制器,使用Promise异步回调。
45
46**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
47
48**系统能力:** SystemCapability.Window.SessionManager
49
50**参数:**
51
52| 参数名          | 类型                                       | 必填        | 说明                                                                                                                                                                                                                                     |
53|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
54| config       | [PiPConfiguration](#pipconfiguration)    | 是         | 创建画中画控制器的参数。该参数不能为空,并且构造该参数的context和componentController不能为空。构造该参数时,如果指定了templateType,需保证templateType是[PiPTemplateType](#piptemplatetype)类型;如果指定了controlGroups,需保证controlGroups与templateType匹配,详见[PiPControlGroup](#pipcontrolgroup12)。 |
55
56**返回值:**
57
58| 类型                                                         | 说明                       |
59|------------------------------------------------------------|--------------------------|
60| Promise&lt;[PiPController](#pipcontroller)&gt;  | Promise对象。返回当前创建的画中画控制器。 |
61
62**错误码:**
63
64以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
65
66| 错误码ID | 错误信息                                                                                                                                         |
67|-------|----------------------------------------------------------------------------------------------------------------------------------------------|
68| 401   | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
69| 801   | Capability not supported.Failed to call the API due to limited device capabilities.                                                       |
70
71**示例:**
72
73```ts
74import { BusinessError } from '@kit.BasicServicesKit';
75import { BuilderNode, FrameNode, NodeController, Size, UIContext } from '@kit.ArkUI';
76
77class Params {
78  text: string = '';
79  constructor(text: string) {
80    this.text = text;
81  }
82}
83
84// 开发者可以通过@Builder装饰器实现布局构建
85@Builder
86function buildText(params: Params) {
87  Column() {
88    Text(params.text)
89      .fontSize(20)
90      .fontColor(Color.Red)
91  }
92  .width('100%') // 宽度方向充满画中画窗口
93  .height('100%') // 高度方向充满画中画窗口
94}
95
96// 开发者可通过继承NodeController实现自定义UI控制器
97class TextNodeController extends NodeController {
98  private message: string;
99  private textNode: BuilderNode<[Params]> | null = null;
100  constructor(message: string) {
101    super();
102    this.message = message;
103  }
104
105  // 通过BuilderNode加载自定义布局
106  makeNode(context: UIContext): FrameNode | null {
107    this.textNode = new BuilderNode(context);
108    this.textNode.build(wrapBuilder<[Params]>(buildText), new Params(this.message));
109    return this.textNode.getFrameNode();
110  }
111
112  // 开发者可自定义该方法实现布局更新
113  update(message: string) {
114    console.log(`update message: ${message}`);
115    if (this.textNode !== null) {
116      this.textNode.update(new Params(message));
117    }
118  }
119}
120
121let pipController: PiPWindow.PiPController | undefined = undefined;
122let mXComponentController: XComponentController = new XComponentController(); // 开发者应使用该mXComponentController初始化XComponent: XComponent( {id: 'video', type: 'surface', controller: mXComponentController} ),保证XComponent的内容可以被迁移到画中画窗口。
123let nodeController: TextNodeController = new TextNodeController('this is custom UI');
124let navId: string = "page_1"; // 假设当前页面的导航id为page_1,详见PiPConfiguration定义,具体导航名称由开发者自行定义。
125let contentWidth: number = 800; // 假设当前内容宽度800px。
126let contentHeight: number = 600; // 假设当前内容高度600px。
127let config: PiPWindow.PiPConfiguration = {
128  context: getContext(this),
129  componentController: mXComponentController,
130  navigationId: navId,
131  templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY,
132  contentWidth: contentWidth,
133  contentHeight: contentHeight,
134  controlGroups: [PiPWindow.VideoPlayControlGroup.VIDEO_PREVIOUS_NEXT],
135  customUIController: nodeController, // 可选,如果需要在画中画显示内容上方展示自定义UI,可设置该参数。
136};
137
138let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config);
139promise.then((data : PiPWindow.PiPController) => {
140  pipController = data;
141  console.info(`Succeeded in creating pip controller. Data:${data}`);
142}).catch((err: BusinessError) => {
143  console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
144});
145```
146
147## PiPWindow.create<sup>12+</sup>
148
149create(config: PiPConfiguration, contentNode: typeNode.XComponent): Promise&lt;PiPController&gt;
150
151通过typeNode创建画中画控制器,使用Promise异步回调。
152
153**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
154
155**系统能力:** SystemCapability.Window.SessionManager
156
157**参数:**
158
159| 参数名          | 类型                                       | 必填        | 说明                                                                                                                                                                                                                                     |
160|--------------|------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
161| config       | [PiPConfiguration](#pipconfiguration)    | 是         | 创建画中画控制器的参数。该参数不能为空,并且构造该参数的context不能为空。构造该参数时,如果指定了templateType,需保证templateType是[PiPTemplateType](#piptemplatetype)类型;如果指定了controlGroups,需保证controlGroups与templateType匹配,详见[PiPControlGroup](#pipcontrolgroup12)。 |
162| contentNode       | [typeNode.XComponent](js-apis-arkui-frameNode.md#xcomponent12)    | 是         | 用于渲染画中画窗口中的内容。该参数不能为空。|
163
164**返回值:**
165
166| 类型                                                         | 说明                       |
167|------------------------------------------------------------|--------------------------|
168| Promise&lt;[PiPController](#pipcontroller)&gt;  | Promise对象。返回当前创建的画中画控制器。 |
169
170**错误码:**
171
172以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
173
174| 错误码ID | 错误信息                                                                                                                                         |
175|-------|----------------------------------------------------------------------------------------------------------------------------------------------|
176| 401   | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
177| 801   | Capability not supported.Failed to call the API due to limited device capabilities.                                                       |
178
179**示例:**
180
181```ts
182import { BusinessError } from '@kit.BasicServicesKit';
183import { PiPWindow, UIContext } from '@kit.ArkUI';
184import { typeNode } from '@ohos.arkui.node';
185
186let pipController: PiPWindow.PiPController | undefined = undefined;
187let xComponentController: XComponentController = new XComponentController();
188let context: UIContext | undefined = undefined; // 可传入UIContext或在布局中通过this.getUIContext()为context赋有效值
189let xComponent = typeNode.createNode(context, 'XComponent');
190xComponent.initialize({
191  id:'xcomponent',
192  type:XComponentType.SURFACE,
193  controller:xComponentController
194});
195let contentWidth: number = 800; // 假设当前内容宽度800px。
196let contentHeight: number = 600; // 假设当前内容高度600px。
197let config: PiPWindow.PiPConfiguration = {
198  context: getContext(this),
199  componentController: xComponentController,
200  templateType: PiPWindow.PiPTemplateType.VIDEO_PLAY,
201  contentWidth: contentWidth,
202  contentHeight: contentHeight
203};
204
205let promise : Promise<PiPWindow.PiPController> = PiPWindow.create(config, xComponent);
206promise.then((data : PiPWindow.PiPController) => {
207  pipController = data;
208  console.info(`Succeeded in creating pip controller. Data:${data}`);
209}).catch((err: BusinessError) => {
210  console.error(`Failed to create pip controller. Cause:${err.code}, message:${err.message}`);
211});
212```
213
214## PiPConfiguration
215
216创建画中画控制器时的参数。
217
218**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
219
220**系统能力:** SystemCapability.Window.SessionManager
221
222| 名称                  | 类型                                                                         | 必填  | 说明                                                                                                                                                                                                                                                                                                                                        |
223|---------------------|----------------------------------------------------------------------------|-----|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
224| context             | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是   | 表示上下文环境。                                                                                                                                                                                                                                                                                                                                  |
225| componentController | [XComponentController](arkui-ts/ts-basic-components-xcomponent.md)         | 是   | 表示原始[XComponent](arkui-ts/ts-basic-components-xcomponent.md)控制器。                                                                                                                                                                                                                                                                      |
226| navigationId        | string                                                                     | 否   | 当前page导航id。<br/>1、UIAbility使用[Navigation](arkui-ts/ts-basic-components-navigation.md)管理页面,需要设置Navigation控件的id属性,并将该id设置给画中画控制器,确保还原场景下能够从画中画窗口恢复到原页面。<br/>2、UIAbility使用[Router](js-apis-router.md)管理页面时,无需设置navigationId。<br/>3、UIAbility只有单页面时,无需设置navigationId,还原场景下也能够从画中画窗口恢复到原页面。 |
227| templateType        | [PiPTemplateType](#piptemplatetype)                                        | 否   | 模板类型,用以区分视频播放、视频通话或视频会议。                                                                                                                                                                                                                                                                                                                  |
228| contentWidth        | number                                                                     | 否   | 原始内容宽度,单位为px。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时,不传值则默认为1920。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时,不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的宽度。                                                                 |
229| contentHeight       | number                                                                     | 否   | 原始内容高度,单位为px。用于确定画中画窗口比例。用于确定画中画窗口比例。当[使用typeNode的方式](#pipwindowcreate12)创建PiPController时,不传值则默认为1080。当[不使用typeNode的方式](#pipwindowcreate)创建PiPController时,不传值则默认为[XComponent](arkui-ts/ts-basic-components-xcomponent.md)组件的高度。                                                                 |
230| controlGroups<sup>12+</sup>       | Array<[PiPControlGroup](#pipcontrolgroup12)>                               | 否   | 画中画控制面板的可选控件组列表,应用可以对此进行配置以决定是否显示。如果应用没有配置,面板将显示基础控件(如视频播放控件组的播放/暂停控件);如果应用选择配置,则最多可以选择三个控件。从API version 12开始支持此参数。                                                                                                                                                                                                                                                 |
231| customUIController<sup>12+</sup>      | [NodeController](js-apis-arkui-nodeController.md)           | 否   | 用于实现在画中画界面内容上方展示自定义UI功能。从API version 12开始支持此参数。                                                                                                                                                                                                                                                                                           |
232
233## PiPTemplateType
234
235画中画媒体类型枚举。
236
237**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
238
239**系统能力:** SystemCapability.Window.SessionManager
240
241| 名称            | 值   | 说明                                   |
242|---------------|-----|--------------------------------------|
243| VIDEO_PLAY    | 0   | 表示将要切换为画中画播放的媒体类型是视频,系统依此加载视频播放模板。   |
244| VIDEO_CALL    | 1   | 表示将要切换为画中画播放的媒体类型是视频通话,系统依此加载视频通话模板。 |
245| VIDEO_MEETING | 2   | 表示将要切换为画中画播放的媒体类型是视频会议,系统依此加载视频会议模板。 |
246| VIDEO_LIVE    | 3   | 表示将要切换为画中画播放的媒体类型是直播,系统依此加载直播模板。     |
247
248## PiPState
249
250画中画生命周期状态枚举。
251
252**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
253
254**系统能力:** SystemCapability.Window.SessionManager
255
256| 名称                   | 值   | 说明                    |
257|----------------------|-----|-----------------------|
258| ABOUT_TO_START       | 1   | 表示画中画将要启动。            |
259| STARTED              | 2   | 表示画中画已经启动。            |
260| ABOUT_TO_STOP        | 3   | 表示画中画将要停止。            |
261| STOPPED              | 4   | 表示画中画已经停止。            |
262| ABOUT_TO_RESTORE     | 5   | 表示画中画将从小窗播放恢复到原始播放界面。 |
263| ERROR                | 6   | 表示画中画生命周期执行过程出现了异常。   |
264
265## PiPControlGroup<sup>12+</sup>
266
267type PiPControlGroup = VideoPlayControlGroup | VideoCallControlGroup | VideoMeetingControlGroup | VideoLiveControlGroup
268
269画中画控制面板的可选控件组列表,应用可以配置是否显示可选控件。默认情况下控制面板只显示基础控件(如视频播放控件组的播放/暂停控件)。
270
271**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
272
273**系统能力:** SystemCapability.Window.SessionManager
274
275| 类型                                              | 说明          |
276|-------------------------------------------------|-------------|
277| [VideoPlayControlGroup](#videoplaycontrolgroup12)     | 视频播放控件组。 |
278| [VideoCallControlGroup](#videocallcontrolgroup12)       | 视频通话控件组。 |
279| [VideoMeetingControlGroup](#videomeetingcontrolgroup12) | 视频会议控件组。 |
280| [VideoLiveControlGroup](#videolivecontrolgroup12)     | 视频直播控件组。 |
281
282
283## VideoPlayControlGroup<sup>12+</sup>
284
285视频播放控件组枚举。仅当[PiPTemplateType](#piptemplatetype)为VIDEO_PLAY时使用。
286
287**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
288
289**系统能力:** SystemCapability.Window.SessionManager
290
291| 名称                   | 值   | 说明                    |
292|----------------------|-----|-----------------------|
293| VIDEO_PREVIOUS_NEXT       | 101   | 视频上一个/下一个控件组。<br/>与视频快进/后退控件组为互斥控件组。如添加视频快进/后退控件组,则不可添加该控件组。           |
294| FAST_FORWARD_BACKWARD    | 102   | 视频快进/后退控件组。<br/>与视频上一个/下一个控件组为互斥控件组。如添加视频上一个/下一个控件组,则不可添加该控件组。           |
295
296## VideoCallControlGroup<sup>12+</sup>
297
298视频通话控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_CALL时使用。
299
300**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
301
302**系统能力:** SystemCapability.Window.SessionManager
303
304| 名称                   | 值   | 说明                    |
305|----------------------|-----|-----------------------|
306| MICROPHONE_SWITCH       | 201   | 打开/关闭麦克风控件组。            |
307| HANG_UP_BUTTON    | 202   | 挂断控件组。           |
308| CAMERA_SWITCH    | 203   | 打开/关闭摄像头控件组。            |
309| MUTE_SWITCH    | 204   | 静音控件组。            |
310
311## VideoMeetingControlGroup<sup>12+</sup>
312
313视频会议控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_MEETING时使用。
314
315**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
316
317**系统能力:** SystemCapability.Window.SessionManager
318
319| 名称                   | 值   | 说明                    |
320|----------------------|-----|-----------------------|
321| HANG_UP_BUTTON       | 301   | 挂断控件组。          |
322| CAMERA_SWITCH    | 302   | 打开/关闭摄像头控件组。           |
323| MUTE_SWITCH    | 303   | 静音控件组。            |
324| MICROPHONE_SWITCH       | 304   | 打开/关闭麦克风控件组。            |
325
326## VideoLiveControlGroup<sup>12+</sup>
327
328视频直播控件组枚举。仅当[PiPTemplateType](#piptemplatetype) 为VIDEO_LIVE时使用。
329
330**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
331
332**系统能力:** SystemCapability.Window.SessionManager
333
334| 名称                   | 值   | 说明                    |
335|----------------------|-----|-----------------------|
336| VIDEO_PLAY_PAUSE     | 401   |   播放/暂停直播控件组   |
337| MUTE_SWITCH         | 402   | 静音控件组。            |
338
339## PiPActionEventType
340
341type PiPActionEventType = PiPVideoActionEvent | PiPCallActionEvent | PiPMeetingActionEvent | PiPLiveActionEvent
342
343画中画控制面板控件动作事件类型,支持以下四种。
344
345**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
346
347**系统能力:** SystemCapability.Window.SessionManager
348
349| 类型                                              | 说明          |
350|-------------------------------------------------|-------------|
351| [PiPVideoActionEvent](#pipvideoactionevent)     | 视频播放控制面板控件事件类型。 |
352| [PiPCallActionEvent](#pipcallactionevent)       | 视频通话控制面板控件事件类型。 |
353| [PiPMeetingActionEvent](#pipmeetingactionevent) | 视频会议控制面板控件事件类型。 |
354| [PiPLiveActionEvent](#pipliveactionevent)       | 直播控制面板控件事件类型。   |
355
356## PiPVideoActionEvent
357
358type PiPVideoActionEvent = 'playbackStateChanged' | 'nextVideo' | 'previousVideo' | 'fastForward' | 'fastBackward'
359
360视频播放控制事件类型。
361
362**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
363
364**系统能力:** SystemCapability.Window.SessionManager
365
366| 类型                         | 说明                                      |
367| ---------------------------- | ----------------------------------------- |
368| 'playbackStateChanged'       | 播放状态发生了变化。                      |
369| 'nextVideo'                  | 播放下一个视频。                          |
370| 'previousVideo'              | 播放上一个视频。                          |
371| 'fastForward'<sup>12+</sup>  | 视频进度快进。从API version 12 开始支持。 |
372| 'fastBackward'<sup>12+</sup> | 视频进度后退。从API version 12 开始支持。 |
373
374## PiPCallActionEvent
375
376type PiPCallActionEvent = 'hangUp' | 'micStateChanged' | 'videoStateChanged' | 'voiceStateChanged'
377
378视频通话控制事件类型。
379
380**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
381
382**系统能力:** SystemCapability.Window.SessionManager
383
384| 类型                | 说明               |
385| ------------------- | ------------------ |
386| 'hangUp'             | 挂断视频通话。     |
387| 'micStateChanged'   | 打开或关闭麦克风。 |
388| 'videoStateChanged' | 打开或关闭摄像头。 |
389| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。   |
390
391
392## PiPMeetingActionEvent
393
394type PiPMeetingActionEvent = 'hangUp' | 'voiceStateChanged' | 'videoStateChanged' | 'micStateChanged'
395
396视频会议控制事件类型。
397
398**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
399
400**系统能力:** SystemCapability.Window.SessionManager
401
402| 类型                | 说明               |
403| ------------------- | ------------------ |
404| 'hangUp'            | 挂断视频会议。     |
405| 'voiceStateChanged' | 静音或解除静音。   |
406| 'videoStateChanged' | 打开或关闭摄像头。 |
407| 'micStateChanged'<sup>12+</sup>   | 打开或关闭麦克风。 |
408
409
410## PiPLiveActionEvent
411
412type PiPLiveActionEvent = 'playbackStateChanged' | 'voiceStateChanged'
413
414直播控制事件类型。
415
416**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
417
418**系统能力:** SystemCapability.Window.SessionManager
419
420| 类型                   | 说明             |
421| ---------------------- | ---------------- |
422| 'playbackStateChanged' | 播放或暂停直播。 |
423| 'voiceStateChanged'<sup>12+</sup> | 静音或解除静音。   |
424
425
426## PiPControlStatus<sup>12+</sup>
427
428控制面板控件状态枚举。
429
430**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
431
432**系统能力:** SystemCapability.Window.SessionManager
433
434| 名称                   | 值   | 说明                    |
435|----------------------|-----|-----------------------|
436| PLAY       | 1   | 播放。          |
437| PAUSE    | 0   | 暂停。           |
438| OPEN    | 1   | 打开。            |
439| CLOSE       | 0   | 关闭。          |
440
441## PiPControlType<sup>12+</sup>
442
443控制面板控件类型枚举。
444
445**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
446
447**系统能力:** SystemCapability.Window.SessionManager
448
449| 名称                | 值   | 说明                                   |
450|-------------------|-----|--------------------------------------|
451| VIDEO_PLAY_PAUSE  | 0   | 播放/暂停控件。   |
452| VIDEO_PREVIOUS    | 1   | 视频上一个控件。 |
453| VIDEO_NEXT        | 2   | 视频下一个控件。 |
454| FAST_FORWARD      | 3   | 视频快进控件     |
455| FAST_BACKWARD     | 4   | 视频快退控件。   |
456| HANG_UP_BUTTON           | 5   | 挂断控件。 |
457| MICROPHONE_SWITCH | 6  | 打开/关闭麦克风控件。 |
458| CAMERA_SWITCH     | 7   | 打开/关闭摄像头控件。     |
459| MUTE_SWITCH       | 8   | 打开/关闭静音控件。     |
460
461
462## ControlPanelActionEventCallback<sup>12+</sup>
463
464type ControlPanelActionEventCallback = (event: PiPActionEventType, status?: number) => void
465
466描述画中画控制面板控件动作事件回调。
467
468**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
469
470**系统能力:** SystemCapability.Window.SessionManager
471
472**参数:**
473
474| 参数名                       | 类型           | 必填    | 说明                                |
475|--------------------------|--------------|--------------|-----------------------------------|
476| event       |  [PiPActionEventType](#pipactioneventtype)       | 是 | 回调画中画控制面板控件动作事件类型。<br/>应用依据控件动作事件做相应处理,如触发'playbackStateChanged'事件时,需要开始或停止视频。 |
477| status | number | 否 | 表示可切换状态的控件当前的状态,如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组,打开为1,关闭为0。其余控件该参数返回默认值-1。 |
478
479## ControlEventParam<sup>12+</sup>
480
481画中画控制面板控件动作回调的参数。
482
483**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
484
485**系统能力:** SystemCapability.Window.SessionManager
486
487| 名称                       | 类型           | 必填    | 说明                                                                                                                                |
488|--------------------------|--------------|--------------|-----------------------------------------------------------------------------------------------------------------------------------|
489| controlType       |  [PiPControlType](#pipcontroltype12)      | 是 | 回调画中画控制面板控件动作事件类型。应用依据控件类型做相应处理,如视频模板中暂停/播放控件被点击时,需要开始或停止视频。                                                                      |
490| status | [PiPControlStatus](#pipcontrolstatus12) | 否 | 表示可切换状态的控件当前的状态,如具备打开和关闭两种状态的麦克风控件组、摄像头控件组和静音控件组,打开为PiPControlStatus.PLAY,关闭为PiPControlStatus.PAUSE。如不具备开/关和播放/暂停状态的挂断控件默认返回值为-1。 |
491
492## PiPController
493
494画中画控制器实例。用于启动、停止画中画以及更新回调注册等。
495
496下列API示例中都需先使用[PiPWindow.create()](#pipwindowcreate)方法获取到PiPController实例,再通过此实例调用对应方法。
497
498**系统能力:** SystemCapability.Window.SessionManager
499
500### startPiP
501
502startPiP(): Promise&lt;void&gt;
503
504启动画中画,使用Promise异步回调。
505
506**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
507
508**系统能力:** SystemCapability.Window.SessionManager
509
510**返回值:**
511
512| 类型                     | 说明                 |
513|------------------------|--------------------|
514| Promise&lt;void&gt;    | 无返回结果的Promise对象。   |
515
516**错误码:**
517
518以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。
519
520| 错误码ID    | 错误信息                                                |
521|------------|--------------------------------------------------------|
522| 1300012    | The PiP window state is abnormal.                      |
523| 1300013    | Failed to create the PiP window.                       |
524| 1300014    | PiP internal error.                                    |
525| 1300015    | Repeated PiP operation.                                |
526
527**示例:**
528
529```ts
530let promise : Promise<void> = pipController.startPiP();
531promise.then(() => {
532  console.info(`Succeeded in starting pip.`);
533}).catch((err: BusinessError) => {
534  console.error(`Failed to start pip. Cause:${err.code}, message:${err.message}`);
535});
536```
537
538### stopPiP
539
540stopPiP(): Promise&lt;void&gt;
541
542停止画中画,使用Promise异步回调。
543
544**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
545
546**系统能力:** SystemCapability.Window.SessionManager
547
548**返回值:**
549
550| 类型                   | 说明                  |
551|----------------------|---------------------|
552| Promise&lt;void&gt;  | 无返回结果的Promise对象。    |
553
554**错误码:**
555
556以下错误码的详细介绍请参见[窗口错误码](errorcode-window.md)。
557
558| 错误码ID   | 错误信息                          |
559|---------|-----------------------------------|
560| 1300011 | Failed to destroy the PiP window. |
561| 1300012 | The PiP window state is abnormal. |
562| 1300015 | Repeated PiP operation.           |
563
564**示例:**
565
566```ts
567let promise : Promise<void> = pipController.stopPiP();
568promise.then(() => {
569  console.info(`Succeeded in stopping pip.`);
570}).catch((err: BusinessError) => {
571  console.error(`Failed to stop pip. Cause:${err.code}, message:${err.message}`);
572});
573```
574
575### setAutoStartEnabled
576
577setAutoStartEnabled(enable: boolean): void
578
579设置是否需要在返回桌面时自动启动画中画。
580
581**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
582
583**系统能力:** SystemCapability.Window.SessionManager
584
585**参数:**
586
587| 参数名      | 类型        | 必填    | 说明                              |
588|----------|-----------|-------|---------------------------------|
589| enable   | boolean   | 是     | 如返回桌面时需自动启动画中画,则该参数配置为true,否则为false。若设置中自动启动画中画开关为关闭状态,就算该参数配置为true,应用返回桌面时也不会自动启动画中画窗口。  |
590
591**示例:**
592
593```ts
594let enable: boolean = true;
595pipController.setAutoStartEnabled(enable);
596```
597
598### updateContentSize
599
600updateContentSize(width: number, height: number): void
601
602当媒体源切换时,向画中画控制器更新媒体源尺寸信息。
603
604**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
605
606**系统能力:** SystemCapability.Window.SessionManager
607
608**参数:**
609
610| 参数名    | 类型     | 必填  | 说明                                     |
611|--------|--------|-----|----------------------------------------|
612| width  | number | 是   | 表示媒体内容宽度,必须为大于0的数字,单位为px。用于更新画中画窗口比例。  |
613| height | number | 是   | 表示媒体内容高度,必须为大于0的数字,单位为px。用于更新画中画窗口比例。  |
614
615**错误码:**
616
617以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
618
619| 错误码ID | 错误信息                                                                                                        |
620|-------|-------------------------------------------------------------------------------------------------------------|
621| 401   | Params error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
622
623**示例:**
624
625```ts
626let width: number = 540; // 假设当前内容宽度变为540px。
627let height: number = 960; // 假设当前内容高度变为960px。
628pipController.updateContentSize(width, height);
629```
630
631### updatePiPControlStatus<sup>12+</sup>
632updatePiPControlStatus(controlType: PiPControlType, status: PiPControlStatus): void
633
634更新控制面板控件功能状态。
635
636**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
637
638**系统能力:** SystemCapability.Window.SessionManager
639
640**参数:**
641
642| 参数名    | 类型     | 必填  | 说明                                                                                                 |
643|--------|--------|-----|----------------------------------------------------------------------------------------------------|
644| controlType  | [PiPControlType](#pipcontroltype12)  | 是   | 表示画中画控制面板控件类型。目前仅支持VIDEO_PLAY_PAUSE、MICROPHONE_SWITCH、CAMERA_SWITCH和MUTE_SWITCH这几种控件类型,传入其他控件类型无效。 |
645| status | [PiPControlStatus](#pipcontrolstatus12)  | 是   | 表示画中画控制面板控件状态。                                                                                     |
646
647**错误码:**
648
649以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
650
651| 错误码ID | 错误信息                                                                                                        |
652|-------|-------------------------------------------------------------------------------------------------------------|
653| 401   | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed |
654
655**示例:**
656
657```ts
658let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。
659let status: PiPWindow.PiPControlStatus = PiPWindow.PiPControlStatus.PLAY; // 视频播放控制面板中播放/暂停控件为播放状态。
660pipController.updatePiPControlStatus(controlType, status);
661```
662
663### setPiPControlEnabled<sup>12+</sup>
664setPiPControlEnabled(controlType: PiPControlType, enabled: boolean): void
665
666更新控制面板控件使能状态。
667
668**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
669
670**系统能力:** SystemCapability.Window.SessionManager
671
672**参数:**
673
674| 参数名         | 类型     | 必填  | 说明                                     |
675|-------------|--------|-----|----------------------------------------|
676| controlType | [PiPControlType](#pipcontroltype12)  | 是   | 表示画中画控制面板控件类型。  |
677| enabled     | boolean | 是   | 表示画中画控制面板控件使能状态。true表示控件为可使用状态,false则为禁用状态。  |
678
679**错误码:**
680
681以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
682
683| 错误码ID | 错误信息                                                                                                        |
684|-------|-------------------------------------------------------------------------------------------------------------|
685| 401   | Params error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3. Parameter verification failed |
686
687**示例:**
688
689```ts
690let controlType: PiPWindow.PiPControlType = PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE; // 视频播放控制面板中播放/暂停控件。
691let enabled: boolean = false; // 视频播放控制面板中播放/暂停控件为禁用状态。
692pipController.setPiPControlEnabled(controlType, enabled);
693```
694
695### on('stateChange')
696
697on(type: 'stateChange', callback: (state: PiPState, reason: string) => void): void
698
699开启画中画生命周期状态的监听。
700
701**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
702
703**系统能力:** SystemCapability.Window.SessionManager
704
705**参数:**
706
707| 参数名        | 类型        | 必填   | 说明                                                                                                |
708|------------|-----------|------|---------------------------------------------------------------------------------------------------|
709| type       | string    | 是    | 监听事件,固定为'stateChange',即画中画生命周期状态变化事件。                                                             |
710| callback   | function  | 是    | 回调生命周期状态变化事件以及原因:<br/>state:[PiPState](#pipstate),表示当前画中画生命周期状态;<br/>reason:string,表示当前生命周期的切换原因。 |
711
712**示例:**
713
714```ts
715pipController.on('stateChange', (state: PiPWindow.PiPState, reason: string) => {
716  let curState: string = '';
717  switch (state) {
718    case PiPWindow.PiPState.ABOUT_TO_START:
719      curState = 'ABOUT_TO_START';
720      break;
721    case PiPWindow.PiPState.STARTED:
722      curState = 'STARTED';
723      break;
724    case PiPWindow.PiPState.ABOUT_TO_STOP:
725      curState = 'ABOUT_TO_STOP';
726      break;
727    case PiPWindow.PiPState.STOPPED:
728      curState = 'STOPPED';
729      break;
730    case PiPWindow.PiPState.ABOUT_TO_RESTORE:
731      curState = 'ABOUT_TO_RESTORE';
732      break;
733    case PiPWindow.PiPState.ERROR:
734      curState = 'ERROR';
735      break;
736    default:
737      break;
738  }
739  console.info('stateChange:' + curState + ' reason:' + reason);
740});
741```
742
743### off('stateChange')
744
745off(type: 'stateChange'): void
746
747关闭画中画生命周期状态的监听。
748
749**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
750
751**系统能力:** SystemCapability.Window.SessionManager
752
753**参数:**
754
755| 参数名       | 类型            | 必填    | 说明                                     |
756|-----------|---------------|-------|----------------------------------------|
757| type      | string        | 是     | 监听事件,固定为'stateChange',即画中画生命周期状态变化事件。  |
758
759**示例:**
760
761```ts
762pipController.off('stateChange');
763```
764
765### on('controlPanelActionEvent')
766
767on(type: 'controlPanelActionEvent', callback: ControlPanelActionEventCallback): void
768
769开启画中画控制面板控件动作事件的监听。推荐使用[on('controlEvent')](#oncontrolevent12)来开启画中画控制面板控件动作事件的监听。
770
771**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
772
773**系统能力:** SystemCapability.Window.SessionManager
774
775**参数:**
776
777| 参数名      | 类型         | 必填    | 说明                                                |
778|----------|------------|-------|---------------------------------------------------|
779| type     | string     | 是     | 监听事件,固定为'controlPanelActionEvent',即画中画控制面板控件动作事件。 |
780| callback | [ControlPanelActionEventCallback](#controlpanelactioneventcallback12)  | 是     | 描述画中画控制面板控件动作事件回调。                                |
781
782**示例:**
783
784```ts
785pipController.on('controlPanelActionEvent', (event: PiPWindow.PiPActionEventType, status?: number) => {
786  switch (event) {
787    case 'playbackStateChanged':
788      if (status === 0) {
789        //停止视频
790      } else if (status === 1) {
791        //播放视频
792      }
793      break;
794    case 'nextVideo':
795      // 切换到下一个视频
796      break;
797    case 'previousVideo':
798      // 切换到上一个视频
799      break;
800    case 'fastForward':
801      // 视频进度快进
802      break;
803    case 'fastBackward':
804      // 视频进度后退
805      break;
806    default:
807      break;
808  }
809  console.info('registerActionEventCallback, event:' + event);
810});
811```
812
813### on('controlEvent')<sup>12+</sup>
814
815on(type: 'controlEvent', callback: Callback&lt;ControlEventParam&gt;): void
816
817开启画中画控制面板控件动作事件的监听。
818
819**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
820
821**系统能力:** SystemCapability.Window.SessionManager
822
823**参数:**
824
825| 参数名      | 类型                                                  | 必填    | 说明                                     |
826|----------|-----------------------------------------------------|-------|----------------------------------------|
827| type     | string                                              | 是     | 监听事件,固定为'controlEvent',即画中画控制面板控件动作事件。 |
828| callback | Callback<[ControlEventParam](#controleventparam12)> | 是     | 描述画中画控制面板控件动作事件回调。                     |
829
830**示例:**
831
832```ts
833pipController.on('controlEvent', (control) => {
834  switch (control.controlType) {
835    case PiPWindow.PiPControlType.VIDEO_PLAY_PAUSE:
836      if (control.status === PiPWindow.PiPControlStatus.PAUSE) {
837        //停止视频
838      } else if (control.status === PiPWindow.PiPControlStatus.PLAY) {
839        //播放视频
840      }
841      break;
842    case PiPWindow.PiPControlType.VIDEO_NEXT:
843      // 切换到下一个视频
844      break;
845    case PiPWindow.PiPControlType.VIDEO_PREVIOUS:
846      // 切换到上一个视频
847      break;
848    case PiPWindow.PiPControlType.FAST_FORWARD:
849      // 视频进度快进
850      break;
851    case PiPWindow.PiPControlType.FAST_BACKWARD:
852      // 视频进度后退
853      break;
854    default:
855      break;
856  }
857  console.info('registerControlEventCallback, controlType:' + control.controlType + ', status' + control.status);
858});
859```
860
861### off('controlPanelActionEvent')
862
863off(type: 'controlPanelActionEvent'): void
864
865关闭画中画控制面板控件动作事件的监听。推荐使用[off('controlEvent')](#offcontrolevent12)来关闭画中画控制面板控件动作事件的监听。
866
867**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
868
869**系统能力:** SystemCapability.Window.SessionManager
870
871**参数:**
872
873| 参数名        | 类型                           | 必填   | 说明                                            |
874|------------|------------------------------|------|-----------------------------------------------|
875| type       | string                       | 是    | 监听事件,固定为'controlPanelActionEvent',即画中画控制面板控件动作事件。   |
876
877**示例:**
878
879```ts
880pipController.off('controlPanelActionEvent');
881```
882
883### off('controlEvent')<sup>12+</sup>
884
885off(type: 'controlEvent', callback?: Callback&lt;ControlEventParam&gt;): void
886
887关闭画中画控制面板控件动作事件的监听。
888
889**原子化服务API:** 从API version 12开始,该接口支持在原子化服务中使用。
890
891**系统能力:** SystemCapability.Window.SessionManager
892
893**参数:**
894
895| 参数名        | 类型                                                  | 必填 | 说明                                                     |
896|------------|-----------------------------------------------------|----|--------------------------------------------------------|
897| type       | string                                              | 是  | 监听事件,固定为'controlEvent',即画中画控制面板控件动作事件。                 |
898| callback | Callback<[ControlEventParam](#controleventparam12)> | 否  | 描述画中画控制面板控件动作事件回调。如果不传该参数时,解除type为'controlEvent'的所有回调。 |
899
900**示例:**
901
902```ts
903pipController.off('controlEvent', () => {});
904```