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> 由于以下几种情况,移动设备场景下不推荐使用子窗口,优先推荐使用控件[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```