1# 管理应用窗口（FA模型） 2 3## 基本概念 4 5窗口沉浸式能力：指对状态栏、导航栏等系统窗口进行控制，减少状态栏导航栏等系统界面的突兀感，从而使用户获得最佳体验的能力。 6沉浸式能力只在应用主窗口作为全屏窗口时生效。通常情况下，应用子窗口（弹窗、悬浮窗口等辅助窗口）和处于自由窗口下的应用主窗口无法使用沉浸式能力。 7 8## 场景介绍 9 10在FA模型下，管理应用窗口的典型场景有： 11 12- 设置应用子窗口属性及目标页面 13 14- 体验窗口沉浸式能力 15 16以下分别介绍具体开发方式。 17 18 19## 接口说明 20 21上述场景涉及的常用接口如下表所示。更多API说明请参见[API参考](../reference/apis/js-apis-window.md)。 22 23| 实例名 | 接口名 | 描述 | 24| -------- | -------- | -------- | 25| window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\<Window>): void | 创建子窗口。<br/>-`config`：创建窗口时的参数。 | 26| window静态方法 | findWindow(name: string): Window | 查找`name`所对应的窗口。 | 27| Window | SetUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面内容。 | 28| Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口。 | 29| Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | 设置窗口的背景色。 | 30| Window | setWindowBrightness(brightness: number, callback: AsyncCallback<void>): void | 设置屏幕亮度值。 | 31| Window | resize(width: number, height: number, callback: AsyncCallback<void>): void | 改变当前窗口大小。 | 32| Window | setWindowLayoutFullScreen(isLayoutFullScreen: boolean, callback: AsyncCallback<void>): void | 设置窗口布局是否为全屏布局。 | 33| Window | setWindowSystemBarEnable(names: Array<'status'\|'navigation'>): Promise<void> | 设置导航栏、状态栏是否显示。 | 34| Window | setWindowSystemBarProperties(systemBarProperties: SystemBarProperties, callback: AsyncCallback<void>): void | 设置窗口内导航栏、状态栏属性。<br/>`systemBarProperties`：导航栏、状态栏的属性集合。 | 35| Window | showWindow(callback: AsyncCallback\<void>): void | 显示当前窗口。 | 36| Window | on(type: 'touchOutside', callback: Callback<void>): void | 开启本窗口区域外的点击事件的监听。 | 37| Window | destroyWindow(callback: AsyncCallback<void>): void | 销毁当前窗口。 | 38 39 40## 设置应用子窗口 41 42开发者可以按需创建应用子窗口，如弹窗等，并对其进行属性设置等操作。 43 44 45### 开发步骤 46 471. 创建/获取子窗口对象。 48 49 - 可以通过`window.createWindow`接口创建子窗口。 50 - 也可以通过`window.findWindow`接口来查找已经创建的窗口从而得到子窗口。 51 52 ```js 53 import window from '@ohos.window'; 54 55 let windowClass = null; 56 // 方式一：创建子窗口。 57 let config = {name: "subWindow", windowType: window.WindowType.TYPE_APP}; 58 window.createWindow(config, (err, data) => { 59 if (err.code) { 60 console.error('Failed to create the subWindow. Cause: ' + JSON.stringify(err)); 61 return; 62 } 63 console.info('Succeeded in creating subWindow. Data: ' + JSON.stringify(data)); 64 windowClass = data; 65 }); 66 // 方式二：查找得到子窗口。 67 try { 68 windowClass = window.findWindow('subWindow'); 69 } catch (exception) { 70 console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception)); 71 } 72 ``` 73 742. 设置子窗口属性。 75 76 子窗口创建成功后，可以改变其大小、位置等，还可以根据应用需要设置窗口背景色、亮度等属性。 77 78 ```js 79 // 移动子窗口位置。 80 windowClass.moveWindowTo(300, 300, (err) => { 81 if (err.code) { 82 console.error('Failed to move the window. Cause:' + JSON.stringify(err)); 83 return; 84 } 85 console.info('Succeeded in moving the window.'); 86 }); 87 // 改变子窗口大小。 88 windowClass.resize(500, 500, (err) => { 89 if (err.code) { 90 console.error('Failed to change the window size. Cause:' + JSON.stringify(err)); 91 return; 92 } 93 console.info('Succeeded in changing the window size.'); 94 }); 95 ``` 96 973. 加载显示子窗口的具体内容。 98 99 使用`SetUIContent`和`showWindow`接口加载显示子窗口的具体内容。 100 101 ```js 102 // 为子窗口加载对应的目标页面。 103 windowClass.SetUIContent("pages/page2", (err) => { 104 if (err.code) { 105 console.error('Failed to load the content. Cause: ' + JSON.stringify(err)); 106 return; 107 } 108 console.info('Succeeded in loading the content.'); 109 // 显示子窗口。 110 windowClass.showWindow((err) => { 111 if (err.code) { 112 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 113 return; 114 } 115 console.info('Succeeded in showing the window.'); 116 }); 117 }); 118 ``` 119 1204. 销毁子窗口。 121 122 当不再需要某些子窗口时，可根据场景的具体实现逻辑，使用`destroyWindow`接口销毁子窗口。 123 124 ```js 125 // 销毁子窗口。当不再需要某些子窗口时，可根据场景的具体实现逻辑，使用destroy接口销毁子窗口。 126 windowClass.destroyWindow((err) => { 127 if (err.code) { 128 console.error('Failed to destroy the subwindow. Cause:' + JSON.stringify(err)); 129 return; 130 } 131 console.info('Succeeded in destroying the subwindow.'); 132 }); 133 ``` 134 135 136## 体验窗口沉浸式能力 137 138在看视频、玩游戏等场景下，用户往往希望隐藏状态栏、导航栏等不必要的系统窗口，从而获得更佳的沉浸式体验。此时可以借助窗口沉浸式能力（窗口沉浸式能力都是针对应用主窗口而言的），达到预期效果。 139 140 141### 开发步骤 142 1431. 获取主窗口对象。 144 145 > **说明：** 146 > 147 > 沉浸式能力需要在成功获取应用主窗口对象的前提下进行。 148 > 149 > 确保应用内最后显示的窗口为主窗口，然后再使用`window.getLastWindow`接口来获取得到主窗口。 150 151 ```js 152 import window from '@ohos.window'; 153 154 let mainWindowClass = null; 155 // 获取主窗口。 156 window.getLastWindow(this.context,(err, data) => { 157 if (err.code) { 158 console.error('Failed to get the subWindow. Cause: ' + JSON.stringify(err)); 159 return; 160 } 161 console.info('Succeeded in getting subWindow. Data: ' + JSON.stringify(data)); 162 mainWindowClass = data; 163 }); 164 ``` 165 1662. 实现沉浸式效果。有以下两种方式： 167 168 - 方式一：调用`setWindowSystemBarEnable`接口，设置导航栏、状态栏不显示，从而达到沉浸式效果。 169 - 方式二：调用`setWindowLayoutFullScreen`接口，设置应用主窗口为全屏布局；然后调用`setSystemProperties`接口，设置导航栏、状态栏的透明度、背景/文字颜色以及高亮图标等属性，使之保持与主窗口显示协调一致，从而达到沉浸式效果。 170 171 ```js 172 173 // 实现沉浸式效果。方式一：设置导航栏、状态栏不显示。 174 let names = []; 175 mainWindowClass.setWindowSystemBarEnable(names, (err) => { 176 if (err.code) { 177 console.error('Failed to set the system bar to be visible. Cause:' + JSON.stringify(err)); 178 return; 179 } 180 console.info('Succeeded in setting the system bar to be visible.'); 181 }); 182 // 实现沉浸式效果。 183 // 方式二：设置窗口为全屏布局，配合设置状态栏、导航栏的透明度、背景/文字颜色及高亮图标等属性，与主窗口显示保持协调一致。 184 let isLayoutFullScreen = true; 185 mainWindowClass.setWindowLayoutFullScreen(isLayoutFullScreen, (err) => { 186 if (err.code) { 187 console.error('Failed to set the window layout to full-screen mode. Cause:' + JSON.stringify(err)); 188 return; 189 } 190 console.info('Succeeded in setting the window layout to full-screen mode.'); 191 }); 192 let sysBarProps = { 193 statusBarColor: '#ff00ff', 194 navigationBarColor: '#00ff00', 195 // 以下两个属性从API Version8开始支持。 196 statusBarContentColor: '#ffffff', 197 navigationBarContentColor: '#ffffff' 198 }; 199 mainWindowClass.setWindowSystemBarProperties(sysBarProps, (err) => { 200 if (err.code) { 201 console.error('Failed to set the system bar properties. Cause: ' + JSON.stringify(err)); 202 return; 203 } 204 console.info('Succeeded in setting the system bar properties.'); 205 }); 206 ``` 207 2083. 加载显示沉浸式窗口的具体内容。 209 210 使用`SetUIContent`和`showWindow`接口加载显示沉浸式窗口的具体内容。 211 212 ```js 213 // 为沉浸式窗口加载对应的目标页面。 214 mainWindowClass.SetUIContent("pages/page3", (err) => { 215 if (err.code) { 216 console.error('Failed to load the content. Cause: ' + JSON.stringify(err)); 217 return; 218 } 219 console.info('Succeeded in loading the content.'); 220 // 显示沉浸式窗口。 221 mainWindowClass.showWindow((err) => { 222 if (err.code) { 223 console.error('Failed to show the window. Cause: ' + JSON.stringify(err)); 224 return; 225 } 226 console.info('Succeeded in showing the window.'); 227 }); 228 }); 229 ```