1# 应用上下文Context 2 3 4## 概述 5 6[Context](../reference/apis-ability-kit/js-apis-inner-application-context.md)是应用中对象的上下文，其提供了应用的一些基础信息，例如[resourceManager](../reference/apis-localization-kit/js-apis-resource-manager.md)（资源管理）、[applicationInfo](../reference/apis-ability-kit/js-apis-bundleManager-applicationInfo.md)（当前应用信息）、[dir](../reference/apis-ability-kit/js-apis-inner-application-context.md#属性)（应用文件路径）、[area](../reference/apis-ability-kit/js-apis-app-ability-contextConstant.md#areamode)（文件分区）等，以及应用的一些基本方法，例如createBundleContext()、[getApplicationContext()](../reference/apis-ability-kit/js-apis-inner-application-context.md#contextgetapplicationcontext)等。[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)组件和各种[ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md)派生类组件都有各自不同的Context类。分别有基类Context、[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)、[AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md)、[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)、[ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md)、ServiceExtensionContext等Context。 7 8- 各类Context的继承关系 9  10 11- 各类Context的持有关系 12  13 14- 各类Context的获取方式 15 - 获取[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。每个[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)中都包含了一个Context属性，提供操作应用组件、获取应用组件的配置信息等能力。 16 17 ```ts 18 import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 19 20 export default class EntryAbility extends UIAbility { 21 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 22 let uiAbilityContext = this.context; 23 //... 24 } 25 } 26 ``` 27 28 > **说明：** 29 > 30 > 页面中获取UIAbility实例的上下文信息请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。 31 - 获取特定场景[ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md)。以ServiceExtensionContext为例，表示后台服务的上下文环境，继承自ExtensionContext，提供后台服务相关的接口能力。 32 33 ```ts 34 import { ServiceExtensionAbility, Want } from '@kit.AbilityKit'; 35 36 export default class ServiceExtAbility extends ServiceExtensionAbility { 37 onCreate(want: Want) { 38 let serviceExtensionContext = this.context; 39 //... 40 } 41 } 42 ``` 43 - 获取[AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md)（Module级别的Context）。和基类Context相比，额外提供[HapModuleInfo](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md#属性)、[Configuration](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md#属性)等信息。 44 45 ```ts 46 import { AbilityStage } from '@kit.AbilityKit'; 47 48 export default class MyAbilityStage extends AbilityStage { 49 onCreate(): void { 50 let abilityStageContext = this.context; 51 //... 52 } 53 } 54 ``` 55 - 获取[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)（应用级别的Context）。ApplicationContext在基类Context的基础上提供了订阅应用内应用组件的生命周期的变化、订阅系统内存变化、订阅应用内系统环境变化、设置应用语言、设置应用颜色模式、清除应用自身数据的同时撤销应用向用户申请的权限等能力，在[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)、[ExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-extensionAbility.md)、[AbilityStage](../reference/apis-ability-kit/js-apis-app-ability-abilityStage.md)中均可以获取。 56 57 ```ts 58 import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit'; 59 60 export default class EntryAbility extends UIAbility { 61 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 62 let applicationContext = this.context.getApplicationContext(); 63 //... 64 } 65 } 66 ``` 67 68 69## Context的典型使用场景 70 71 72本章节通过如下典型场景来介绍Context的用法： 73 74- [获取应用文件路径](#获取应用文件路径) 75- [获取和修改加密分区](#获取和修改加密分区) 76- [获取本应用中其他module的context](#获取本应用中其他module的context) 77- [订阅进程内UIAbility生命周期变化](#订阅进程内uiability生命周期变化) 78 79 80### 获取应用文件路径 81 82[基类Context](../reference/apis-ability-kit/js-apis-inner-application-context.md)提供了获取应用文件路径的能力，[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)、[AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md)、[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)和[ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md)均继承该能力。不同类型的Context获取的路径可能存在差异。 83 84- 通过[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)可以获取应用级的文件路径。该路径用于存放应用全局信息，路径下的文件会跟随应用的卸载而删除。 85- 通过[AbilityStageContext](../reference/apis-ability-kit/js-apis-inner-application-abilityStageContext.md)、[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)、[ExtensionContext](../reference/apis-ability-kit/js-apis-inner-application-extensionContext.md)，可以获取[Module](../quick-start/application-package-overview.md)级的文件路径。该路径用于存放Module相关信息，路径下的文件会跟随[HAP](../quick-start/hap-package.md)/[HSP](../quick-start/in-app-hsp.md)的卸载而删除。HAP/HSP的卸载不会影响应用级路径下的文件，除非该应用的HAP/HSP已全部卸载。 86 87 - UIAbilityContext：可以获取UIAbility所在Module的文件路径。 88 - ExtensionContext：可以获取ExtensionAbility所在Module的文件路径。 89 - AbilityStageContext：由于AbilityStageContext创建时机早于UIAbilityContext和ExtensionContext，通常用于在AbilityStage中获取文件路径。 90 91>**说明：** 92> 93> 应用文件路径属于应用沙箱路径，具体请参见[应用沙箱目录](../file-management/app-sandbox-directory.md)。 94 95 **表1** 不同级别Context获取的应用文件路径说明 96 | 属性 | 说明 | ApplicationContext获取的路径 | AbilityStageContext、UIAbilityContext、ExtensionContext获取的路径 | 97 | -------- | -------- | -------- | -------- | 98 | bundleCodeDir | 安装包目录。 | <路径前缀>/el1/bundle | <路径前缀>/el1/bundle | 99 | cacheDir | 缓存目录。 | <路径前缀>/<加密等级>/base/cache | <路径前缀>/<加密等级>/base/**haps/\<module-name>**/cache | 100 | filesDir | 文件目录。 | <路径前缀>/<加密等级>/base/files | <路径前缀>/<加密等级>/base/**haps/\<module-name>**/files | 101 | preferencesDir | preferences目录。 | <路径前缀>/<加密等级>/base/preferences | <路径前缀>/<加密等级>/base/**haps/\<module-name>**/preferences | 102 | tempDir | 临时目录。 | <路径前缀>/<加密等级>/base/temp | <路径前缀>/<加密等级>/base/**haps/\<module-name>**/temp | 103 | databaseDir | 数据库目录。 | <路径前缀>/<加密等级>/database | <路径前缀>/<加密等级>/database/**\<module-name>** | 104 | distributedFilesDir | 分布式文件目录。 | <路径前缀>/el2/distributedFiles | <路径前缀>/el2/distributedFiles/ | 105 | resourceDir<sup>11+<sup> | 资源目录。<br/>**说明：**<br/> 需要开发者手动在`\<module-name>\resource`路径下创建`resfile`目录。 | 不涉及 | <路径前缀>/el1/bundle/**\<module-name>**/resources/resfile | 106 | cloudFileDir<sup>12+</sup> | 云文件目录。 | <路径前缀>/el2/cloud | <路径前缀>/el2/cloud/ | 107 108 本节以使用ApplicationContext获取filesDir为例，介绍如何获取应用文件路径，并在对应文件路径下新建文件和读写文件。示例代码如下： 109 110 ```ts 111 import { common } from '@kit.AbilityKit'; 112 import { buffer } from '@kit.ArkTS'; 113 import { fileIo, ReadOptions } from '@kit.CoreFileKit'; 114 import { hilog } from '@kit.PerformanceAnalysisKit'; 115 116 const TAG: string = '[Page_Context]'; 117 const DOMAIN_NUMBER: number = 0xFF00; 118 119 @Entry 120 @Component 121 struct Index { 122 @State message: string = 'Hello World'; 123 private context = this.getUIContext().getHostContext() as common.UIAbilityContext; 124 125 build() { 126 Row() { 127 Column() { 128 Text(this.message) 129 // ... 130 Button() { 131 Text('create file') 132 // ... 133 .onClick(() => { 134 let applicationContext = this.context.getApplicationContext(); 135 // 获取应用文件路径 136 let filesDir = applicationContext.filesDir; 137 hilog.info(DOMAIN_NUMBER, TAG, `filePath: ${filesDir}`); 138 // 文件不存在时创建并打开文件，文件存在时打开文件 139 let file = fileIo.openSync(filesDir + '/test.txt', fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE); 140 // 写入一段内容至文件 141 let writeLen = fileIo.writeSync(file.fd, "Try to write str."); 142 hilog.info(DOMAIN_NUMBER, TAG, `The length of str is: ${writeLen}`); 143 // 创建一个大小为1024字节的ArrayBuffer对象，用于存储从文件中读取的数据 144 let arrayBuffer = new ArrayBuffer(1024); 145 // 设置读取的偏移量和长度 146 let readOptions: ReadOptions = { 147 offset: 0, 148 length: arrayBuffer.byteLength 149 }; 150 // 读取文件内容到ArrayBuffer对象中，并返回实际读取的字节数 151 let readLen = fileIo.readSync(file.fd, arrayBuffer, readOptions); 152 // 将ArrayBuffer对象转换为Buffer对象，并转换为字符串输出 153 let buf = buffer.from(arrayBuffer, 0, readLen); 154 hilog.info(DOMAIN_NUMBER, TAG, `the content of file: ${buf.toString()}`); 155 // 关闭文件 156 fileIo.closeSync(file); 157 }) 158 } 159 // ... 160 } 161 // ... 162 } 163 // ... 164 } 165 } 166 ``` 167 168 169### 获取和修改加密分区 170 171应用文件加密是一种保护数据安全的方法，可以使得文件在未经授权访问的情况下得到保护。在不同的场景下，应用需要不同程度的文件保护。 172 173在实际应用中，开发者需要根据不同场景的需求选择合适的加密分区，从而保护应用数据的安全。通过合理使用不同级别的加密分区，可以有效提高应用数据的安全性。关于不同分区的权限说明，详见[ContextConstant](../reference/apis-ability-kit/js-apis-app-ability-contextConstant.md)的[AreaMode](../reference/apis-ability-kit/js-apis-app-ability-contextConstant.md#areamode)。 174 175- EL1：对于私有文件，如闹铃、壁纸等，应用可以将这些文件放到设备级加密分区（EL1）中，以保证在用户输入密码前就可以被访问。 176- EL2：对于更敏感的文件，如个人隐私信息等，应用可以将这些文件放到更高级别的加密分区（EL2）中，以保证更高的安全性。 177- EL3：对于应用中的记录步数、文件下载、音乐播放，需要在锁屏时读写和创建新文件，放在（EL3）的加密分区比较合适。 178- EL4：对于用户安全信息相关的文件，锁屏时不需要读写文件、也不能创建文件，放在（EL4）的加密分区更合适。 179- EL5：对于用户隐私敏感数据文件，锁屏后默认不可读写，如果锁屏后需要读写文件，则锁屏前可以调用[Access](../reference/apis-ability-kit/js-apis-screenLockFileManager.md#screenlockfilemanageracquireaccess)接口申请继续读写文件，或者锁屏后也需要创建新文件且可读写，放在（EL5）的应用级加密分区更合适。 180 181要实现获取和设置当前加密分区，可以通过读写[Context](../reference/apis-ability-kit/js-apis-inner-application-context.md)的`area`属性来实现。 182 183```ts 184// EntryAbility.ets 185import { UIAbility, contextConstant, AbilityConstant, Want } from '@kit.AbilityKit'; 186 187export default class EntryAbility extends UIAbility { 188 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) { 189 // 存储普通信息前，切换到EL1设备级加密 190 this.context.area = contextConstant.AreaMode.EL1; // 切换area 191 // 存储普通信息 192 193 // 存储敏感信息前，切换到EL2用户级加密 194 this.context.area = contextConstant.AreaMode.EL2; // 切换area 195 // 存储敏感信息 196 197 // 存储敏感信息前，切换到EL3用户级加密 198 this.context.area = contextConstant.AreaMode.EL3; // 切换area 199 // 存储敏感信息 200 201 // 存储敏感信息前，切换到EL4用户级加密 202 this.context.area = contextConstant.AreaMode.EL4; // 切换area 203 // 存储敏感信息 204 205 // 存储敏感信息前，切换到EL5应用级加密 206 this.context.area = contextConstant.AreaMode.EL5; // 切换area 207 // 存储敏感信息 208 } 209} 210``` 211```ts 212// Index.ets 213import { contextConstant, common } from '@kit.AbilityKit'; 214 215@Entry 216@Component 217struct Page_Context { 218 private context = this.getUIContext().getHostContext() as common.UIAbilityContext; 219 220 build() { 221 Column() { 222 //... 223 List({ initialIndex: 0 }) { 224 //... 225 ListItem() { 226 Row() { 227 //... 228 } 229 .onClick(() => { 230 // 存储普通信息前，切换到EL1设备级加密 231 if (this.context.area === contextConstant.AreaMode.EL2) { // 获取area 232 this.context.area = contextConstant.AreaMode.EL1; // 修改area 233 this.getUIContext().getPromptAction().showToast({ 234 message: 'SwitchToEL1' 235 }); 236 } 237 // 存储普通信息 238 }) 239 } 240 //... 241 ListItem() { 242 Row() { 243 //... 244 } 245 .onClick(() => { 246 // 存储敏感信息前，切换到EL2用户级加密 247 if (this.context.area === contextConstant.AreaMode.EL1) { // 获取area 248 this.context.area = contextConstant.AreaMode.EL2; // 修改area 249 this.getUIContext().getPromptAction().showToast({ 250 message: 'SwitchToEL2' 251 }); 252 } 253 // 存储敏感信息 254 }) 255 } 256 //... 257 } 258 //... 259 } 260 //... 261 } 262} 263``` 264 265 266### 获取本应用中其他Module的Context 267 268调用[createModuleContext(context: Context, moduleName: string)](../reference/apis-ability-kit/js-apis-app-ability-application.md#applicationcreatemodulecontext12)方法，获取本应用中其他Module的Context。获取到其他Module的Context之后，即可获取到相应Module的资源信息。 269 270 ```ts 271 import { common, application } from '@kit.AbilityKit'; 272 import { BusinessError } from '@kit.BasicServicesKit'; 273 274 let storageEventCall = new LocalStorage(); 275 276 @Entry(storageEventCall) 277 @Component 278 struct Page_Context { 279 private context = this.getUIContext().getHostContext() as common.UIAbilityContext; 280 281 build() { 282 Column() { 283 //... 284 List({ initialIndex: 0 }) { 285 ListItem() { 286 Row() { 287 //... 288 } 289 .onClick(() => { 290 let moduleName2: string = 'entry'; 291 application.createModuleContext(this.context, moduleName2) 292 .then((data: common.Context) => { 293 console.info(`CreateModuleContext success, data: ${JSON.stringify(data)}`); 294 if (data !== null) { 295 this.getUIContext().getPromptAction().showToast({ 296 message: ('成功获取Context') 297 }); 298 } 299 }) 300 .catch((err: BusinessError) => { 301 console.error(`CreateModuleContext failed, err code:${err.code}, err msg: ${err.message}`); 302 }); 303 }) 304 } 305 //... 306 } 307 //... 308 } 309 //... 310 } 311 } 312 ``` 313 314 315### 订阅进程内UIAbility生命周期变化 316 317在应用内的DFX统计场景中，如需要统计对应页面停留时间和访问频率等信息，可以使用订阅进程内[UIAbility](../reference/apis-ability-kit/js-apis-app-ability-uiAbility.md)生命周期变化功能。 318 319通过[ApplicationContext](../reference/apis-ability-kit/js-apis-inner-application-applicationContext.md)提供的能力，可以订阅进程内UIAbility生命周期变化。当进程内的UIAbility生命周期变化时，如创建、可见/不可见、获焦/失焦、销毁等，会触发相应的回调函数。每次注册回调函数时，都会返回一个监听生命周期的ID，此ID会自增+1。当超过监听上限数量2^63-1时，会返回-1。以[UIAbilityContext](../reference/apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)中的使用为例进行说明。 320 321 322```ts 323import { AbilityConstant, AbilityLifecycleCallback, UIAbility, Want } from '@kit.AbilityKit'; 324import { hilog } from '@kit.PerformanceAnalysisKit'; 325import { window } from '@kit.ArkUI'; 326import { BusinessError } from '@kit.BasicServicesKit'; 327 328const TAG: string = '[LifecycleAbility]'; 329const DOMAIN_NUMBER: number = 0xFF00; 330 331export default class LifecycleAbility extends UIAbility { 332 // 定义生命周期ID 333 lifecycleId: number = -1; 334 335 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 336 // 定义生命周期回调对象 337 let abilityLifecycleCallback: AbilityLifecycleCallback = { 338 // 当UIAbility创建时被调用 339 onAbilityCreate(uiAbility) { 340 hilog.info(DOMAIN_NUMBER, TAG, `onAbilityCreate uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 341 }, 342 // 当窗口创建时被调用 343 onWindowStageCreate(uiAbility, windowStage: window.WindowStage) { 344 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageCreate uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 345 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageCreate windowStage: ${JSON.stringify(windowStage)}`); 346 }, 347 // 当窗口处于活动状态时被调用 348 onWindowStageActive(uiAbility, windowStage: window.WindowStage) { 349 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageActive uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 350 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageActive windowStage: ${JSON.stringify(windowStage)}`); 351 }, 352 // 当窗口处于非活动状态时被调用 353 onWindowStageInactive(uiAbility, windowStage: window.WindowStage) { 354 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageInactive uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 355 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageInactive windowStage: ${JSON.stringify(windowStage)}`); 356 }, 357 // 当窗口被销毁时被调用 358 onWindowStageDestroy(uiAbility, windowStage: window.WindowStage) { 359 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageDestroy uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 360 hilog.info(DOMAIN_NUMBER, TAG, `onWindowStageDestroy windowStage: ${JSON.stringify(windowStage)}`); 361 }, 362 // 当UIAbility被销毁时被调用 363 onAbilityDestroy(uiAbility) { 364 hilog.info(DOMAIN_NUMBER, TAG, `onAbilityDestroy uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 365 }, 366 // 当UIAbility从后台转到前台时触发回调 367 onAbilityForeground(uiAbility) { 368 hilog.info(DOMAIN_NUMBER, TAG, `onAbilityForeground uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 369 }, 370 // 当UIAbility从前台转到后台时触发回调 371 onAbilityBackground(uiAbility) { 372 hilog.info(DOMAIN_NUMBER, TAG, `onAbilityBackground uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 373 }, 374 // 当UIAbility迁移时被调用 375 onAbilityContinue(uiAbility) { 376 hilog.info(DOMAIN_NUMBER, TAG, `onAbilityContinue uiAbility.launchWant: ${JSON.stringify(uiAbility.launchWant)}`); 377 } 378 }; 379 // 获取应用上下文 380 let applicationContext = this.context.getApplicationContext(); 381 try { 382 // 注册应用内生命周期回调 383 this.lifecycleId = applicationContext.on('abilityLifecycle', abilityLifecycleCallback); 384 } catch (err) { 385 let code = (err as BusinessError).code; 386 let message = (err as BusinessError).message; 387 hilog.error(DOMAIN_NUMBER, TAG, `Failed to register applicationContext. Code is ${code}, message is ${message}`); 388 } 389 390 hilog.info(DOMAIN_NUMBER, TAG, `register callback number: ${this.lifecycleId}`); 391 } 392 //... 393 onDestroy(): void { 394 // 获取应用上下文 395 let applicationContext = this.context.getApplicationContext(); 396 try { 397 // 取消应用内生命周期回调 398 applicationContext.off('abilityLifecycle', this.lifecycleId); 399 } catch (err) { 400 let code = (err as BusinessError).code; 401 let message = (err as BusinessError).message; 402 hilog.error(DOMAIN_NUMBER, TAG, `Failed to unregister applicationContext. Code is ${code}, message is ${message}`); 403 } 404 } 405} 406``` 407
