1# 管理应用窗口（FA模型） 2<!--Kit: ArkUI--> 3<!--Subsystem: Window--> 4<!--Owner: @waterwin--> 5<!--Designer: @nyankomiya--> 6<!--Tester: @qinliwen0417--> 7<!--Adviser: @ge-yafang--> 8 9## 基本概念 10 11窗口沉浸式能力：指对状态栏、导航栏等系统窗口进行控制，减少状态栏导航栏等系统界面的突兀感，从而使用户获得最佳体验的能力。 12沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下，应用子窗口（弹窗、悬浮窗口等辅助窗口）和处于自由窗口下的应用主窗口无法使用沉浸式能力。 13 14> **说明：** 15> 16> 当前沉浸式界面开发仅支持window级别的配置，暂不支持Page级别的配置。若有Page级别切换的需要，可以在页面生命周期开始，例如onPageShow中设置沉浸模式，然后在页面退出，例如onPageHide中恢复默认设置来实现。 17 18## 场景介绍 19 20在FA模型下，管理应用窗口的典型场景有： 21 22- 设置应用子窗口属性及目标页面 23 24- 体验窗口沉浸式能力 25 26以下分别介绍具体开发方式。 27 28 29## 接口说明 30 31上述场景涉及的常用接口如下表所示。更多API说明请参见[API参考](../reference/apis-arkui/arkts-apis-window.md)。 32 33| 实例名 | 接口名 | 描述 | 34| -------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 35| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | 创建子窗口。<br/>-`config`：创建窗口时的参数。 | 36| window静态方法 | findWindow(name: string): Window | 查找`name`所对应的窗口。 | 37| Window | setUIContent(path: string, callback: AsyncCallback<void>): void | 根据当前工程中某个页面的路径为窗口加载具体的页面内容。<br>其中path为要加载到窗口中的页面内容的路径，在FA模型下该路径需添加到工程的config.json文件中。 | 38| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口。 | 39| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | 设置屏幕亮度值。 | 40| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | 41| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean): Promise<void> | 设置窗口布局是否为全屏布局。 | 42| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | 设置导航栏、状态栏是否显示。 | 43| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties): Promise<void> | 设置窗口内导航栏、状态栏属性。<br/>`systemBarProperties`：导航栏、状态栏的属性集合。 | 44| Window | showWindow(callback: AsyncCallback\<void>): void | 显示当前窗口。 | 45| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | 46| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | 47 48 49## 设置应用子窗口 50 51开发者可以按需创建应用子窗口，如弹窗等，并对其进行属性设置等操作。 52 53> **说明：** 54> 以下几种场景不建议使用子窗口，建议优先考虑使用控件[overlay](../reference/apis-arkui/arkui-ts/ts-universal-attributes-overlay.md)能力实现。 55> - 移动设备（手机、在非自由模式下的平板设备）场景下子窗不能超出处于悬浮窗、分屏状态的主窗口范围，与控件一致。 56> - 分屏窗口与自由窗口模式下，主窗口位置大小发生改变时控件实时跟随变化能力优于子窗。 57> - 部分设备平台下根据实际的系统配置限制，子窗只有系统默认的动效和圆角阴影，应用无法设置，自由度低。 58 59### 开发步骤 60 611. 创建/获取子窗口对象。 62 63 - 可以通过`window.createWindow`接口创建子窗口。 64 非[自由窗口](../windowmanager/window-terminology.md#自由窗口)状态下，子窗口创建后默认是[沉浸式布局](../windowmanager/window-terminology.md#沉浸式布局)。 65 66 自由窗口状态下，子窗口参数[decorEnabled](../reference/apis-arkui/arkts-apis-window-i.md#configuration9)为false时，子窗口创建后为沉浸式布局；子窗口参数decorEnabled为true，子窗口创建后为非沉浸式布局。 67 - 也可以通过`window.findWindow`接口来查找已经创建的窗口从而得到子窗口。 68 69 ```ts 70 import { window } from '@kit.ArkUI'; 71 import { BusinessError } from '@kit.BasicServicesKit'; 72 73 let windowClass: window.Window | null = null; 74 // 方式一：创建子窗口。 75 let config: window.Configuration = { name: "subWindow", windowType: window.WindowType.TYPE_APP }; 76 window.createWindow(config, (err: BusinessError, data) => { 77 let errCode: number = err.code; 78 if (errCode) { 79 console.error(`Failed to create the subWindow. Code:${err.code}, message:${err.message}`); 80 return; 81 } 82 console.info('Succeeded in creating subWindow. Data: ' + JSON.stringify(data)); 83 windowClass = data; 84 if (!windowClass) { 85 console.error('windowClass is null'); 86 return; 87 } 88 }); 89 // 方式二：查找得到子窗口。 90 try { 91 windowClass = window.findWindow('subWindow'); 92 } catch (exception) { 93 console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception)); 94 } 95 ``` 96 972. 设置子窗口属性。 98 99 子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。 100 101 ```ts 102 // 移动子窗口位置。 103 windowClass.moveWindowTo(300, 300, (err: BusinessError) => { 104 let errCode: number = err.code; 105 if (errCode) { 106 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 107 return; 108 } 109 console.info('Succeeded in moving the window.'); 110 }); 111 // 改变子窗口大小。 112 windowClass.resize(500, 500, (err: BusinessError) => { 113 let errCode: number = err.code; 114 if (errCode) { 115 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 116 return; 117 } 118 console.info('Succeeded in changing the window size.'); 119 }); 120 ``` 121 1223. 加载显示子窗口的具体内容。 123 124 使用`setUIContent`和`showWindow`接口加载显示子窗口的具体内容。 125 126 ```ts 127 // 为子窗口加载对应的目标页面。 128 windowClass.setUIContent("pages/page2", (err: BusinessError) => { 129 let errCode: number = err.code; 130 if (errCode) { 131 console.error('Failed to load the content. Cause: ' + JSON.stringify(err)); 132 return; 133 } 134 console.info('Succeeded in loading the content.'); 135 if (!windowClass) { 136 console.error('windowClass is null'); 137 return; 138 } 139 // 显示子窗口。 140 windowClass.showWindow((err: BusinessError) => { 141 let errCode: number = err.code; 142 if (errCode) { 143 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 144 return; 145 } 146 console.info('Succeeded in showing the window.'); 147 }); 148 }); 149 ``` 150 1514. 销毁子窗口。 152 153 当不再需要某些子窗口时，可根据场景的具体实现逻辑，使用`destroyWindow`接口销毁子窗口。 154 155 ```ts 156 // 销毁子窗口。当不再需要某些子窗口时，可根据场景的具体实现逻辑，使用destroy接口销毁子窗口。 157 windowClass.destroyWindow((err: BusinessError) => { 158 let errCode: number = err.code; 159 if (errCode) { 160 console.error('Failed to destroy the subwindow. Cause:' + JSON.stringify(err)); 161 return; 162 } 163 console.info('Succeeded in destroying the subwindow.'); 164 }); 165 ``` 166 167## 体验窗口沉浸式能力 168 169在看视频、玩游戏等场景下，用户往往希望隐藏状态栏、导航栏等不必要的系统窗口，从而获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力（窗口沉浸式能力都是针对应用主窗口而言的），达到预期效果。从API version 10开始，沉浸式窗口默认配置为全屏大小并由组件模块控制布局，状态栏、导航栏背景颜色为透明，文字颜色为黑色；应用窗口调用`setWindowLayoutFullScreen`接口，设置为true表示由组件模块控制忽略状态栏、导航栏的沉浸式全屏布局，设置为false表示由组件模块控制避让状态栏、导航栏的非沉浸式全屏布局。 170 171 172### 开发步骤 173 1741. 获取主窗口对象。 175 176 > **说明：** 177 > 178 > 沉浸式能力需要在成功获取应用主窗口对象的前提下进行。 179 > 180 > 确保应用内最后显示的窗口为主窗口，然后再使用`window.getLastWindow`接口来获取得到主窗口。 181 182 ```ts 183 import { window } from '@kit.ArkUI'; 184 import { BusinessError } from '@kit.BasicServicesKit'; 185 186 let mainWindowClass: window.Window | null = null; 187 188 // 获取主窗口。 189 class BaseContext { 190 stageMode: boolean = false; 191 } 192 193 let context: BaseContext = { stageMode: false }; 194 window.getLastWindow(context, (err: BusinessError, data) => { 195 let errCode: number = err.code; 196 if (errCode) { 197 console.error('Failed to get the mainWindow. Cause: ' + JSON.stringify(err)); 198 return; 199 } 200 console.info('Succeeded in getting mainWindow. Data: ' + JSON.stringify(data)); 201 mainWindowClass = data; 202 if (!mainWindowClass) { 203 console.error('mainWindowClass is null'); 204 return; 205 } 206 }); 207 ``` 208 2092. 实现沉浸式效果。有以下两种方式： 210 211 - 方式一：应用主窗口为全屏窗口时，调用`setWindowSystemBarEnable`接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。 212 - 方式二：调用`setWindowLayoutFullScreen`接口，设置应用主窗口为全屏布局；然后调用`setWindowSystemBarProperties`接口，设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性，使之保持与主窗口显示协调一致，从而达到沉浸式效果。 213 214 ```ts 215 // 实现沉浸式效果。方式一：设置导航栏、状态栏不显示。 216 let names: Array<'status' | 'navigation'> = []; 217 mainWindowClass.setWindowSystemBarEnable(names) 218 .then(() => { 219 console.info('Succeeded in setting the system bar to be visible.'); 220 }) 221 .catch((err: BusinessError) => { 222 console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); 223 }); 224 // 实现沉浸式效果。 225 // 方式二：设置窗口为全屏布局，配合设置状态栏、导航栏的透明度、背景/文字颜色及高亮图标等属性，与主窗口显示保持协调一致。 226 let isLayoutFullScreen: boolean = true; 227 mainWindowClass.setWindowLayoutFullScreen(isLayoutFullScreen) 228 .then(() => { 229 console.info('Succeeded in setting the window layout to full-screen mode.'); 230 }) 231 .catch((err: BusinessError) => { 232 console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); 233 }); 234 let sysBarProps: window.SystemBarProperties = { 235 statusBarColor: '#ff00ff', 236 navigationBarColor: '#00ff00', 237 // 以下两个属性从API Version8开始支持。 238 statusBarContentColor: '#ffffff', 239 navigationBarContentColor: '#ffffff' 240 }; 241 mainWindowClass.setWindowSystemBarProperties(sysBarProps) 242 .then(() => { 243 console.info('Succeeded in setting the system bar properties.'); 244 }) 245 .catch((err: BusinessError) => { 246 console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); 247 }); 248 ``` 249 2503. 加载显示沉浸式窗口的具体内容。 251 252 使用`setUIContent`和`showWindow`接口加载显示沉浸式窗口的具体内容。 253 254 ```ts 255 // 为沉浸式窗口加载对应的目标页面。 256 mainWindowClass.setUIContent("pages/page3", (err: BusinessError) => { 257 let errCode: number = err.code; 258 if (errCode) { 259 console.error('Failed to load the content. Cause: ' + JSON.stringify(err)); 260 return; 261 } 262 console.info('Succeeded in loading the content.'); 263 if (!mainWindowClass) { 264 console.error('mainWindowClass is null'); 265 return; 266 } 267 // 显示沉浸式窗口。 268 mainWindowClass.showWindow((err: BusinessError) => { 269 let errCode: number = err.code; 270 if (errCode) { 271 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 272 return; 273 } 274 console.info('Succeeded in showing the window.'); 275 }); 276 }); 277 ```