1# 管理应用窗口（Stage模型） 2 3 4## 基本概念 5 6- 窗口沉浸式能力：指对状态栏、导航栏等系统窗口进行控制，减少状态栏导航栏等系统界面的突兀感，从而使用户获得最佳体验的能力。 7 沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下，应用子窗口（弹窗、悬浮窗口等辅助窗口）和处于自由窗口下的应用主窗口无法使用沉浸式能力。 8 9- 悬浮窗：全局悬浮窗口是一种特殊的应用窗口，具备在应用主窗口和对应Ability退至后台后仍然可以在前台显示的能力。 10 悬浮窗口可以用于应用退至后台后，使用小窗继续播放视频，或者为特定的应用创建悬浮球等快速入口。应用在创建悬浮窗口前，需要申请对应的权限。 11 12 13## 场景介绍 14 15在`Stage`模型下，管理应用窗口的典型场景有： 16 17- 设置应用主窗口属性及目标页面 18 19- 设置应用子窗口属性及目标页面 20 21- 体验窗口沉浸式能力 22 23- 设置悬浮窗 24 25以下分别介绍具体开发方式。 26 27 28## 接口说明 29 30上述场景涉及的常用接口如下表所示。更多API说明请参见[API参考](../reference/apis/js-apis-window.md)。 31 32| 实例名 | 接口名 | 描述 | 33| -------- | -------- | -------- | 34| WindowStage | getMainWindow(callback: AsyncCallback<Window>): void | 获取`WindowStage`实例下的主窗口。<br/>此接口仅可在`Stage`模型下使用。 | 35| WindowStage | loadContent(path: string, callback: AsyncCallback<void>): void | 为当前`WindowStage`的主窗口加载具体页面。<br/>此接口仅可在`Stage`模型下使用。 | 36| WindowStage | createSubWindow(name: string, callback: AsyncCallback<Window>): void | 创建子窗口。<br/>此接口仅可在`Stage`模型下使用。 | 37| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | 创建系统窗口。<br/>-`config`：创建窗口时的参数。 | 38| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面。 | 39| Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | 设置窗口的背景色。 | 40| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | 设置屏幕亮度值。 | 41| Window | setWindowTouchable(isTouchable: boolean, callback: AsyncCallback<void>): void | 设置窗口是否为可触状态。 | 42| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口位置。 | 43| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | 44| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | 设置窗口布局是否为全屏布局。 | 45| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | 设置导航栏、状态栏是否显示。 | 46| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | 设置窗口内导航栏、状态栏属性。<br/>`systemBarProperties`：导航栏、状态栏的属性集合。 | 47| Window | showWindow(callback: AsyncCallback\<void>): void | 显示当前窗口。 | 48| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | 49| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | 50 51 52## 设置应用主窗口 53 54在`Stage`模型下，应用主窗口由`UIAbility`创建并维护生命周期。在`UIAbility`的`onWindowStageCreate`回调中，通过`WindowStage`获取应用主窗口，即可对其进行属性设置等操作。还可以在应用配置文件中设置应用主窗口的属性，如最大窗口宽度maxWindowWidth等，详见[module.json5配置文件](../quick-start/module-configuration-file.md#abilities标签)。 55 56 57### 开发步骤 58 591. 获取应用主窗口。 60 通过`getMainWindow`接口获取应用主窗口。 61 622. 设置主窗口属性。 63 可设置主窗口的背景色、亮度值、是否可触等多个属性，开发者可根据需要选择对应的接口。本示例以设置“是否可触”属性为例。 64 653. 为主窗口加载对应的目标页面。 66 通过`loadContent`接口加载主窗口的目标页面。 67 68```ts 69import UIAbility from '@ohos.app.ability.UIAbility'; 70 71export default class EntryAbility extends UIAbility { 72 onWindowStageCreate(windowStage) { 73 // 1.获取应用主窗口。 74 let windowClass = null; 75 windowStage.getMainWindow((err, data) => { 76 if (err.code) { 77 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 78 return; 79 } 80 windowClass = data; 81 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 82 // 2.设置主窗口属性。以设置"是否可触"属性为例。 83 let isTouchable = true; 84 windowClass.setWindowTouchable(isTouchable, (err) => { 85 if (err.code) { 86 console.error('Failed to set the window to be touchable. Cause:' + JSON.stringify(err)); 87 return; 88 } 89 console.info('Succeeded in setting the window to be touchable.'); 90 }) 91 }) 92 // 3.为主窗口加载对应的目标页面。 93 windowStage.loadContent("pages/page2", (err) => { 94 if (err.code) { 95 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 96 return; 97 } 98 console.info('Succeeded in loading the content.'); 99 }); 100 } 101}; 102``` 103 104 105## 设置应用子窗口 106 107开发者可以按需创建应用子窗口，如弹窗等，并对其进行属性设置等操作。 108 109 110### 开发步骤 111 1121. 创建应用子窗口。 113 通过`createSubWindow`接口创建应用子窗口。 114 1152. 设置子窗口属性。 116 子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。 117 1183. 加载显示子窗口的具体内容。 119 通过`setUIContent`和`showWindow`接口加载显示子窗口的具体内容。 120 1214. 销毁子窗口。 122 当不再需要某些子窗口时，可根据具体实现逻辑，使用`destroyWindow`接口销毁子窗口。 123 124 ```ts 125 import UIAbility from '@ohos.app.ability.UIAbility'; 126 127 let windowStage_ = null; 128 let sub_windowClass = null; 129 export default class EntryAbility extends UIAbility { 130 showSubWindow() { 131 // 1.创建应用子窗口。 132 windowStage_.createSubWindow("mySubWindow", (err, data) => { 133 if (err.code) { 134 console.error('Failed to create the subwindow. Cause: ' + JSON.stringify(err)); 135 return; 136 } 137 sub_windowClass = data; 138 console.info('Succeeded in creating the subwindow. Data: ' + JSON.stringify(data)); 139 // 2.子窗口创建成功后，设置子窗口的位置、大小及相关属性等。 140 sub_windowClass.moveWindowTo(300, 300, (err) => { 141 if (err.code) { 142 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 143 return; 144 } 145 console.info('Succeeded in moving the window.'); 146 }); 147 sub_windowClass.resize(500, 500, (err) => { 148 if (err.code) { 149 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 150 return; 151 } 152 console.info('Succeeded in changing the window size.'); 153 }); 154 // 3.为子窗口加载对应的目标页面。 155 sub_windowClass.setUIContent("pages/page3", (err) => { 156 if (err.code) { 157 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 158 return; 159 } 160 console.info('Succeeded in loading the content.'); 161 // 3.显示子窗口。 162 sub_windowClass.showWindow((err) => { 163 if (err.code) { 164 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 165 return; 166 } 167 console.info('Succeeded in showing the window.'); 168 }); 169 }); 170 }) 171 } 172 173 destroySubWindow() { 174 // 4.销毁子窗口。当不再需要子窗口时，可根据具体实现逻辑，使用destroy对其进行销毁。 175 sub_windowClass.destroyWindow((err) => { 176 if (err.code) { 177 console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); 178 return; 179 } 180 console.info('Succeeded in destroying the window.'); 181 }); 182 } 183 184 onWindowStageCreate(windowStage) { 185 windowStage_ = windowStage; 186 // 开发者可以在适当的时机，如主窗口上按钮点击事件等，创建子窗口。并不一定需要在onWindowStageCreate调用，这里仅作展示 187 this.showSubWindow(); 188 } 189 190 onWindowStageDestroy() { 191 // 开发者可以在适当的时机，如子窗口上点击关闭按钮等，销毁子窗口。并不一定需要在onWindowStageDestroy调用，这里仅作展示 192 this.destroySubWindow(); 193 } 194 }; 195 ``` 196 197 198## 体验窗口沉浸式能力 199 200在看视频、玩游戏等场景下，用户往往希望隐藏状态栏、导航栏等不必要的系统窗口，从而获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力（窗口沉浸式能力都是针对应用主窗口而言的），达到预期效果。 201 202 203### 开发步骤 204 2051. 获取应用主窗口。 206 通过`getMainWindow`接口获取应用主窗口。 207 2082. 实现沉浸式效果。有以下两种方式： 209 - 方式一：调用`setWindowSystemBarEnable`接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。 210 - 方式二：调用`setWindowLayoutFullScreen`接口，设置应用主窗口为全屏布局；然后调用`setWindowSystemBarProperties`接口，设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性，使之保持与主窗口显示协调一致，从而达到沉浸式效果。 211 2123. 加载显示沉浸式窗口的具体内容。 213 通过`loadContent`接口加载沉浸式窗口的具体内容。 214 215 ```ts 216 import UIAbility from '@ohos.app.ability.UIAbility'; 217 218 export default class EntryAbility extends UIAbility { 219 onWindowStageCreate(windowStage) { 220 // 1.获取应用主窗口。 221 let windowClass = null; 222 windowStage.getMainWindow((err, data) => { 223 if (err.code) { 224 console.error('Failed to obtain the main window. Cause: ' + JSON.stringify(err)); 225 return; 226 } 227 windowClass = data; 228 console.info('Succeeded in obtaining the main window. Data: ' + JSON.stringify(data)); 229 230 // 2.实现沉浸式效果。方式一：设置导航栏、状态栏不显示。 231 let names = []; 232 windowClass.setWindowSystemBarEnable(names, (err) => { 233 if (err.code) { 234 console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); 235 return; 236 } 237 console.info('Succeeded in setting the system bar to be visible.'); 238 }); 239 // 2.实现沉浸式效果。方式二：设置窗口为全屏布局，配合设置导航栏、状态栏的透明度、背景/文字颜色及高亮图标等属性，与主窗口显示保持协调一致。 240 let isLayoutFullScreen = true; 241 windowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err) => { 242 if (err.code) { 243 console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); 244 return; 245 } 246 console.info('Succeeded in setting the window layout to full-screen mode.'); 247 }); 248 let sysBarProps = { 249 statusBarColor: '#ff00ff', 250 navigationBarColor: '#00ff00', 251 // 以下两个属性从API Version 8开始支持 252 statusBarContentColor: '#ffffff', 253 navigationBarContentColor: '#ffffff' 254 }; 255 windowClass.setWindowSystemBarProperties(sysBarProps, (err) => { 256 if (err.code) { 257 console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); 258 return; 259 } 260 console.info('Succeeded in setting the system bar properties.'); 261 }); 262 }) 263 // 3.为沉浸式窗口加载对应的目标页面。 264 windowStage.loadContent("pages/page2", (err) => { 265 if (err.code) { 266 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 267 return; 268 } 269 console.info('Succeeded in loading the content.'); 270 }); 271 } 272 }; 273 ``` 274 275 276## 设置悬浮窗 277 278悬浮窗可以在已有的任务基础上，创建一个始终在前台显示的窗口。即使创建悬浮窗的任务退至后台，悬浮窗仍然可以在前台显示。通常悬浮窗位于所有应用窗口之上；开发者可以创建悬浮窗，并对悬浮窗进行属性设置等操作。 279 280 281### 开发步骤 282 2831. 申请权限。 284 创建`WindowType.TYPE_FLOAT`即悬浮窗类型的窗口，需要在`module.json5`文件的`requestPermissions`对象中配置`ohos.permission.SYSTEM_FLOAT_WINDOW`权限。更多配置信息详见[module.json5配置文件](../quick-start/module-configuration-file.md)。 285 286 > **说明：** 287 > 288 > 虽然悬浮窗具备始终在前台显示的能力，但如果创建悬浮窗的应用任务被系统回收，仍然会导致悬浮窗从界面移除。如果想要保持悬浮窗口始终在前台显示，请申请[长时任务](../task-management/background-task-overview.md)。 289 290 ```json 291 { 292 "module": { 293 "requestPermissions":[ 294 { 295 "name" : "ohos.permission.SYSTEM_FLOAT_WINDOW", 296 "usedScene": { 297 "abilities": [ 298 "EntryAbility" 299 ], 300 "when":"inuse" 301 } 302 } 303 ] 304 } 305 } 306 ``` 307 3082. 创建悬浮窗。 309 通过`window.createWindow`接口创建悬浮窗类型的窗口。 310 3113. 对悬浮窗进行属性设置等操作。 312 悬浮窗窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置悬浮窗背景色、亮度等属性。 313 3144. 加载显示悬浮窗的具体内容。 315 通过`setUIContent`和`showWindow`接口加载显示悬浮窗的具体内容。 316 3175. 销毁悬浮窗。 318 319 当不再需要悬浮窗时，可根据具体实现逻辑，使用`destroyWindow`接口销毁悬浮窗。 320 321 ```ts 322 import UIAbility from '@ohos.app.ability.UIAbility'; 323 import window from '@ohos.window'; 324 325 export default class EntryAbility extends UIAbility { 326 onWindowStageCreate(windowStage) { 327 // 2. 创建悬浮窗。 328 let windowClass = null; 329 let config = {name: "floatWindow", windowType: window.WindowType.TYPE_FLOAT, ctx: this.context}; 330 window.createWindow(config, (err, data) => { 331 if (err.code) { 332 console.error('Failed to create the floatWindow. Cause: ' + JSON.stringify(err)); 333 return; 334 } 335 console.info('Succeeded in creating the floatWindow. Data: ' + JSON.stringify(data)); 336 windowClass = data; 337 // 3.悬浮窗窗口创建成功后，设置悬浮窗的位置、大小及相关属性等。 338 windowClass.moveWindowTo(300, 300, (err) => { 339 if (err.code) { 340 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 341 return; 342 } 343 console.info('Succeeded in moving the window.'); 344 }); 345 windowClass.resize(500, 500, (err) => { 346 if (err.code) { 347 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 348 return; 349 } 350 console.info('Succeeded in changing the window size.'); 351 }); 352 // 4.为悬浮窗加载对应的目标页面。 353 windowClass.setUIContent("pages/page4", (err) => { 354 if (err.code) { 355 console.error('Failed to load the content. Cause:' + JSON.stringify(err)); 356 return; 357 } 358 console.info('Succeeded in loading the content.'); 359 // 4.显示悬浮窗。 360 windowClass.showWindow((err) => { 361 if (err.code) { 362 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 363 return; 364 } 365 console.info('Succeeded in showing the window.'); 366 }); 367 }); 368 //5.销毁悬浮窗。当不再需要悬浮窗时，可根据具体实现逻辑，使用destroy对其进行销毁。 369 windowClass.destroyWindow((err) => { 370 if (err.code) { 371 console.error('Failed to destroy the window. Cause: ' + JSON.stringify(err)); 372 return; 373 } 374 console.info('Succeeded in destroying the window.'); 375 }); 376 }); 377 } 378 }; 379 ``` 380## 相关实例 381 382针对window开发（Stage模型），有以下相关实例可供参考： 383 384- [`WindowManage`：窗口（ArkTS）（API9）](https://gitee.com/openharmony/applications_app_samples/tree/OpenHarmony-3.2-Release/code/BasicFeature/WindowManagement/WindowManage) 385