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<Window>): void | 获取`WindowStage`实例下的主窗口。<br/>此接口仅可在`Stage`模型下使用。 | 22| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | 为当前`WindowStage`的主窗口加载具体页面。<br>其中path为要加载到窗口中的页面内容的路径，该路径需添加到工程的main_pages.json文件中。<br/>此接口仅可在`Stage`模型下使用。 | 23| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | 创建子窗口。<br/>此接口仅可在`Stage`模型下使用。 | 24| WindowStage | on(type: 'windowStageEvent', callback: Callback<WindowStageEventType>): void | 开启WindowStage生命周期变化的监听。<br/>此接口仅可在`Stage`模型下使用。 | 25| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | 根据当前工程中某个页面的路径为窗口加载具体的页面内容。<br>其中path为要加载到窗口中的页面内容的路径，在Stage模型下该路径需添加到工程的main_pages.json文件中。 | 26| Window | setWindowPrivacyMode(isPrivacyMode: boolean, callback: AsyncCallback<void>): void | 设置窗口是否为隐私模式。 | 27| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | 28| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | 29| Window | showWindow(callback: AsyncCallback\<void>): void | 显示当前窗口。 | 30| Window | destroyWindow(callback: AsyncCallback<void>): 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 1061. 创建应用子窗口。 107 108 通过`createSubWindow`接口创建应用子窗口。 109 1102. 设置子窗口属性。 111 112 子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。 113 1143. 加载显示子窗口的具体内容。 115 116 通过`setUIContent`和`showWindow`接口加载显示子窗口的具体内容。 117 1184. 销毁子窗口。 119 120 当不再需要某些子窗口时，可根据具体实现逻辑，使用`destroyWindow`接口销毁子窗口。 121 122```ts 123import { UIAbility } from '@kit.AbilityKit'; 124import { window } from '@kit.ArkUI'; 125import { BusinessError } from '@kit.BasicServicesKit'; 126 127let windowStage_: window.WindowStage | null = null; 128let sub_windowClass: window.Window | null = null; 129 130export default class EntryAbility extends UIAbility { 131 showSubWindow() { 132 // 1.创建应用子窗口。 133 if (windowStage_ == null) { 134 console.error('Failed to create the subwindow. Cause: windowStage_ is null'); 135 } 136 else { 137 windowStage_.createSubWindow("mySubWindow", (err: BusinessError, data) => { 138 let errCode: number = err.code; 139 if (errCode) { 140 console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err)); 141 return; 142 } 143 sub_windowClass = data; 144 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 145 // 2.子窗口创建成功后，设置子窗口的位置、大小及相关属性等。 146 sub_windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 147 let errCode: number = err.code; 148 if (errCode) { 149 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 150 return; 151 } 152 console.info('Succeeded in moving the window.'); 153 }); 154 sub_windowClass.resize(500, 500, (err: BusinessError) => { 155 let errCode: number = err.code; 156 if (errCode) { 157 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 158 return; 159 } 160 console.info('Succeeded in changing the window size.'); 161 }); 162 // 3.为子窗口加载对应的目标页面。 163 sub_windowClass.setUIContent("pages/page3", (err: BusinessError) => { 164 let errCode: number = err.code; 165 if (errCode) { 166 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 167 return; 168 } 169 console.info('Succeeded in loading the content.'); 170 // 3.显示子窗口。 171 (sub_windowClass as window.Window).showWindow((err: BusinessError) => { 172 let errCode: number = err.code; 173 if (errCode) { 174 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 175 return; 176 } 177 console.info('Succeeded in showing the window.'); 178 }); 179 }); 180 }) 181 } 182 } 183 184 destroySubWindow() { 185 // 4.销毁子窗口。当不再需要子窗口时，可根据具体实现逻辑，使用destroy对其进行销毁。 186 (sub_windowClass as window.Window).destroyWindow((err: BusinessError) => { 187 let errCode: number = err.code; 188 if (errCode) { 189 console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); 190 return; 191 } 192 console.info('Succeeded in destroying the window.'); 193 }); 194 } 195 196 onWindowStageCreate(windowStage: window.WindowStage) { 197 windowStage_ = windowStage; 198 // 开发者可以在适当的时机，如主窗口上按钮点击事件等，创建子窗口。并不一定需要在onWindowStageCreate调用，这里仅作展示 199 this.showSubWindow(); 200 } 201 202 onWindowStageDestroy() { 203 // 开发者可以在适当的时机，如子窗口上点击关闭按钮等，销毁子窗口。并不一定需要在onWindowStageDestroy调用，这里仅作展示 204 this.destroySubWindow(); 205 } 206}; 207``` 208 209## 监听窗口不可交互与可交互事件 210 211应用在前台显示过程中可能会进入某些不可交互的场景，比较典型的是进入多任务界面。此时，对于一些应用可能需要选择暂停某个与用户正在交互的业务，如视频类应用暂停正在播放的视频或者相机暂停预览流等。而当该应用从多任务又切回前台时，又变成了可交互的状态，此时需要恢复被暂停中断的业务，如恢复视频播放或相机预览流等。 212 213### 开发步骤 214 215在创建WindowStage对象后可通过监听`'windowStageEvent'`事件类型，监听到窗口进入前台、后台、前台可交互、前台不可交互等事件，应用可根据这些上报的事件状态进行相应的业务处理。 216 217```ts 218import { UIAbility } from '@kit.AbilityKit'; 219import { window } from '@kit.ArkUI'; 220 221export default class EntryAbility extends UIAbility { 222 onWindowStageCreate(windowStage: window.WindowStage) { 223 try { 224 windowStage.on('windowStageEvent', (data) => { 225 console.info('Succeeded in enabling the listener for window stage event changes. Data: ' + 226 JSON.stringify(data)); 227 228 // 根据事件状态类型选择进行相应的处理 229 if (data == window.WindowStageEventType.SHOWN) { 230 console.info('current window stage event is SHOWN'); 231 // 应用进入前台，默认为可交互状态 232 // ... 233 } else if (data == window.WindowStageEventType.HIDDEN) { 234 console.info('current window stage event is HIDDEN'); 235 // 应用进入后台，默认为不可交互状态 236 // ... 237 } else if (data == window.WindowStageEventType.PAUSED) { 238 console.info('current window stage event is PAUSED'); 239 // 前台应用进入多任务，转为不可交互状态 240 // ... 241 } else if (data == window.WindowStageEventType.RESUMED) { 242 console.info('current window stage event is RESUMED'); 243 // 进入多任务后又继续返回前台时，恢复可交互状态 244 // ... 245 } 246 247 // ... 248 }); 249 } catch (exception) { 250 console.error('Failed to enable the listener for window stage event changes. Cause:' + 251 JSON.stringify(exception)); 252 } 253 } 254} 255```