1# 管理应用窗口(原子化服务)
2
3## 场景介绍
4
5管理应用窗口的典型场景有:
6
7- 设置应用主窗口属性及目标页面
8
9- 设置应用子窗口属性及目标页面
10
11- 监听窗口不可交互与可交互事件
12
13以下分别介绍具体开发方式。
14
15## 接口说明
16
17上述场景涉及的常用接口如下表所示。更多API说明请参见[@ohos.window (窗口)](../reference/apis-arkui/js-apis-window.md)。
18
19| 实例名         | 接口名                                                       | 描述                                                         |
20| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
21| WindowStage    | getMainWindow(callback: AsyncCallback&lt;Window&gt;): void   | 获取`WindowStage`实例下的主窗口。<br/>此接口仅可在`Stage`模型下使用。 |
22| WindowStage    | loadContent(path: string, callback: AsyncCallback&lt;void&gt;): void | 为当前`WindowStage`的主窗口加载具体页面。<br>其中path为要加载到窗口中的页面内容的路径,该路径需添加到工程的main_pages.json文件中。<br/>此接口仅可在`Stage`模型下使用。 |
23| WindowStage    | createSubWindow(name: string, callback: AsyncCallback&lt;Window&gt;): void | 创建子窗口。<br/>此接口仅可在`Stage`模型下使用。             |
24| WindowStage    | on(type: 'windowStageEvent', callback: Callback&lt;WindowStageEventType&gt;): void | 开启WindowStage生命周期变化的监听。<br/>此接口仅可在`Stage`模型下使用。 |
25| Window         | setUIContent(path: string, callback: AsyncCallback&lt;void&gt;): void | 根据当前工程中某个页面的路径为窗口加载具体的页面内容。<br>其中path为要加载到窗口中的页面内容的路径,在Stage模型下该路径需添加到工程的main_pages.json文件中。                                     |
26| Window         | setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback&lt;void&gt;): void | 设置窗口是否为隐私模式。                                             |
27| Window         | moveWindowTo(x: number, y: number, callback: AsyncCallback&lt;void&gt;): void | 移动当前窗口位置。                                           |
28| Window         | resize(width: number, height: number, callback: AsyncCallback&lt;void&gt;): void | 改变当前窗口大小。                                           |
29| Window         | showWindow(callback: AsyncCallback\<void>): void             | 显示当前窗口。                                               |
30| Window         | destroyWindow(callback: AsyncCallback&lt;void&gt;): void     | 销毁当前窗口。                                               |
31
32
33## 设置应用主窗口
34
35应用主窗口由`UIAbility`创建并维护生命周期。在`UIAbility`的`onWindowStageCreate`回调中,通过`WindowStage`获取应用主窗口,即可对其进行属性设置等操作。还可以在应用配置文件中设置应用主窗口的属性,如最大窗口宽度maxWindowWidth等,详见[module.json5配置文件](../quick-start/module-configuration-file.md#abilities标签)。
36
37### 开发步骤
38
39**前提条件:** `setWindowPrivacyMode` 即设置窗口隐私模式,适用于禁止截屏/录屏的场景。该接口使用时需要申请`ohos.permission.PRIVACY_WINDOW`权限,配置方式请参见[配置文件](../quick-start/module-configuration-file.md#配置文件标签)中requestPermissions字段。
40
411. 获取应用主窗口。
42
43   通过`getMainWindow`接口获取应用主窗口。
44
452. 设置窗口隐私模式属性。
46
47   通过`setWindowPrivacyMode`接口设置主窗口为隐私模式的窗口,窗口内容将无法被截屏或录屏。此接口可用于禁止截屏/录屏的场景。
48
493. 为主窗口加载对应的目标页面。
50
51   通过`loadContent`接口加载主窗口的目标页面。
52
53```ts
54import { UIAbility } from '@kit.AbilityKit';
55import { window } from '@kit.ArkUI';
56import { BusinessError } from '@kit.BasicServicesKit';
57
58export default class EntryAbility extends UIAbility {
59  onWindowStageCreate(windowStage: window.WindowStage) {
60    // 1.获取应用主窗口。
61    let windowClass: window.Window | null = null;
62    windowStage.getMainWindow((err: BusinessError, data) => {
63      let errCode: number = err.code;
64      if (errCode) {
65        console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err));
66        return;
67      }
68      windowClass = data;
69      console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data));
70      // 2.设置为隐私模式的窗口
71      let isPrivacyMode: boolean = true;
72      try {
73        windowClass.setWindowPrivacyMode(isPrivacyMode, (err: BusinessError) => {
74          const errCode: number = err.code;
75          if(errCode) {
76            console.error('Failed to set the window to privacy mode. Cause:' +
77          JSON.stringify(err));
78            return;
79          }
80          console.info('Succeeded in setting the window to privacy mode.');
81        });
82      } catch (exception) {
83        console.error('Failed to set the window to privacy mode. Cause:' +
84      JSON.stringify(exception));
85      }
86    })
87    // 3.为主窗口加载对应的目标页面。
88    windowStage.loadContent("pages/page2", (err: BusinessError) => {
89      let errCode: number = err.code;
90      if (errCode) {
91        console.error('Failed to load the content. Cause:' + JSON.stringify(err));
92        return;
93      }
94      console.info('Succeeded in loading the content.');
95    });
96  }
97};
98```
99
100## 设置应用子窗口
101
102开发者可以按需创建应用子窗口,如弹窗等,并对其进行属性设置等操作。
103
104> **说明:**
105> 由于以下几种情况,移动设备场景下不推荐使用子窗口,优先推荐使用控件[overlay](../reference/apis-arkui/arkui-ts/ts-universal-attributes-overlay.md)能力实现。
106> - 移动设备场景下子窗不能超出主窗口范围,与控件一致。
107> - 分屏窗口与自由窗口模式下,主窗口位置大小发生改变时控件实时跟随变化能力优于子窗。
108> - 部分设备平台下根据实际的系统配置限制,子窗只有系统默认的动效和圆角阴影,应用无法设置,自由度低。
109
110### 开发步骤
111
1121. 创建应用子窗口。
113
114   通过`createSubWindow`接口创建应用子窗口。
115
1162. 设置子窗口属性。
117
118   子窗口创建成功后,可以改变其大小、位置等,还可以根据应用需要设置窗口背景色、亮度等属性。
119
1203. 加载显示子窗口的具体内容。
121
122   通过`setUIContent`和`showWindow`接口加载显示子窗口的具体内容。
123
1244. 销毁子窗口。
125
126   当不再需要某些子窗口时,可根据具体实现逻辑,使用`destroyWindow`接口销毁子窗口。
127
128```ts
129import { UIAbility } from '@kit.AbilityKit';
130import { window } from '@kit.ArkUI';
131import { BusinessError } from '@kit.BasicServicesKit';
132
133let windowStage_: window.WindowStage | null = null;
134let sub_windowClass: window.Window | null = null;
135
136export default class EntryAbility extends UIAbility {
137  showSubWindow() {
138    // 1.创建应用子窗口。
139    if (windowStage_ == null) {
140      console.error('Failed to create the subwindow. Cause: windowStage_ is null');
141    }
142    else {
143      windowStage_.createSubWindow("mySubWindow", (err: BusinessError, data) => {
144        let errCode: number = err.code;
145        if (errCode) {
146          console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err));
147          return;
148        }
149        sub_windowClass = data;
150        console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data));
151        // 2.子窗口创建成功后,设置子窗口的位置、大小及相关属性等。
152        sub_windowClass.moveWindowTo(300, 300, (err: BusinessError) => {
153          let errCode: number = err.code;
154          if (errCode) {
155            console.error('Failed to move the window. Cause:' + JSON.stringify(err));
156            return;
157          }
158          console.info('Succeeded in moving the window.');
159        });
160        sub_windowClass.resize(500, 500, (err: BusinessError) => {
161          let errCode: number = err.code;
162          if (errCode) {
163            console.error('Failed to change the window size. Cause:' + JSON.stringify(err));
164            return;
165          }
166          console.info('Succeeded in changing the window size.');
167        });
168        // 3.为子窗口加载对应的目标页面。
169        sub_windowClass.setUIContent("pages/page3", (err: BusinessError) => {
170          let errCode: number = err.code;
171          if (errCode) {
172            console.error('Failed to load the content. Cause:' + JSON.stringify(err));
173            return;
174          }
175          console.info('Succeeded in loading the content.');
176          // 3.显示子窗口。
177          (sub_windowClass as window.Window).showWindow((err: BusinessError) => {
178            let errCode: number = err.code;
179            if (errCode) {
180              console.error('Failed to show the window. Cause: ' + JSON.stringify(err));
181              return;
182            }
183            console.info('Succeeded in showing the window.');
184          });
185        });
186      })
187    }
188  }
189
190  destroySubWindow() {
191    // 4.销毁子窗口。当不再需要子窗口时,可根据具体实现逻辑,使用destroy对其进行销毁。
192    (sub_windowClass as window.Window).destroyWindow((err: BusinessError) => {
193      let errCode: number = err.code;
194      if (errCode) {
195        console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err));
196        return;
197      }
198      console.info('Succeeded in destroying the window.');
199    });
200  }
201
202  onWindowStageCreate(windowStage: window.WindowStage) {
203    windowStage_ = windowStage;
204    // 开发者可以在适当的时机,如主窗口上按钮点击事件等,创建子窗口。并不一定需要在onWindowStageCreate调用,这里仅作展示
205    this.showSubWindow();
206  }
207
208  onWindowStageDestroy() {
209    // 开发者可以在适当的时机,如子窗口上点击关闭按钮等,销毁子窗口。并不一定需要在onWindowStageDestroy调用,这里仅作展示
210    this.destroySubWindow();
211  }
212};
213```
214
215## 监听窗口不可交互与可交互事件
216
217应用在前台显示过程中可能会进入某些不可交互的场景,比较典型的是进入多任务界面。此时,对于一些应用可能需要选择暂停某个与用户正在交互的业务,如视频类应用暂停正在播放的视频或者相机暂停预览流等。而当该应用从多任务又切回前台时,又变成了可交互的状态,此时需要恢复被暂停中断的业务,如恢复视频播放或相机预览流等。
218
219### 开发步骤
220
221在创建WindowStage对象后可通过监听`'windowStageEvent'`事件类型,监听到窗口进入前台、后台、前台可交互、前台不可交互等事件,应用可根据这些上报的事件状态进行相应的业务处理。
222
223```ts
224import { UIAbility } from '@kit.AbilityKit';
225import { window } from '@kit.ArkUI';
226
227export default class EntryAbility extends UIAbility {
228  onWindowStageCreate(windowStage: window.WindowStage) {
229    try {
230      windowStage.on('windowStageEvent', (data) => {
231        console.info('Succeeded in enabling the listener for window stage event changes. Data: ' +
232          JSON.stringify(data));
233
234        // 根据事件状态类型选择进行相应的处理
235        if (data == window.WindowStageEventType.SHOWN) {
236          console.info('current window stage event is SHOWN');
237          // 应用进入前台,默认为可交互状态
238          // ...
239        } else if (data == window.WindowStageEventType.HIDDEN) {
240          console.info('current window stage event is HIDDEN');
241          // 应用进入后台,默认为不可交互状态
242          // ...
243        } else if (data == window.WindowStageEventType.PAUSED) {
244          console.info('current window stage event is PAUSED');
245          // 前台应用进入多任务,转为不可交互状态
246          // ...
247        } else if (data == window.WindowStageEventType.RESUMED) {
248          console.info('current window stage event is RESUMED');
249          // 进入多任务后又继续返回前台时,恢复可交互状态
250          // ...
251        }
252
253        // ...
254      });
255    } catch (exception) {
256      console.error('Failed to enable the listener for window stage event changes. Cause:' +
257        JSON.stringify(exception));
258    }
259  }
260}
261```