diff --git a/zh-cn/application-dev/application-models/application-context-stage.md b/zh-cn/application-dev/application-models/application-context-stage.md index f30583f28421975cdf393f5378b65e959f7a9644..181a98dcaa82c39abe23a514b11162857b469eb6 100644 --- a/zh-cn/application-dev/application-models/application-context-stage.md +++ b/zh-cn/application-dev/application-models/application-context-stage.md @@ -3,7 +3,7 @@ ## 概述 -[Context](../reference/apis/js-apis-inner-application-context.md)是应用中对象的上下文，其提供了应用的一些基础信息，例如resourceManager（资源管理）、applicationInfo（当前应用信息）、dir（应用开发路径）、area（文件分区）等，以及应用的一些基本方法，例如createBundleContext()、getApplicationContext()等。UIAbility组件和各种ExtensionAbility派生类组件都有各自不同的Context类。分别有基类Context、ApplicationContext、AbilityStageContext、UIAbilityContext、ExtensionContext、ServiceExtensionContext等Context。 +[Context](../reference/apis/js-apis-inner-application-context.md)是应用中对象的上下文，其提供了应用的一些基础信息，例如resourceManager（资源管理）、applicationInfo（当前应用信息）、dir（应用文件路径）、area（文件分区）等，以及应用的一些基本方法，例如createBundleContext()、getApplicationContext()等。UIAbility组件和各种ExtensionAbility派生类组件都有各自不同的Context类。分别有基类Context、ApplicationContext、AbilityStageContext、UIAbilityContext、ExtensionContext、ServiceExtensionContext等Context。 - 各类Context的继承关系 ![context-inheritance](figures/context-inheritance.png) @@ -68,78 +68,78 @@ 本章节通过如下典型场景来介绍Context的用法： -- [获取应用开发路径](#获取应用开发路径) +- [获取应用文件路径](#获取应用文件路径) - [获取和修改加密分区](#获取和修改加密分区) - [创建其他应用或其他Module的Context](#创建其他应用或其他module的context) - [订阅进程内UIAbility生命周期变化](#订阅进程内uiability生命周期变化) -### 获取应用开发路径 +### 获取应用文件路径 -从Context中获取的应用开发路径如下表所示。 +获取路径的能力是[基类Context](../reference/apis/js-apis-inner-application-context.md)中提供的能力，因此在ApplicationContext、AbilityStageContext、UIAbilityContext和ExtensionContext中均可以获取，在各类Context中获取到的路径会有一些差别，具体请参见[应用文件目录与应用文件路径](../file-management/app-sandbox-directory.md#应用文件目录与应用文件路径)。 -**表1** 应用开发路径说明 - -| 属性名称 | 参数类型 | 可读 | 可写 | 说明 | -| -------- | -------- | -------- | -------- | -------- | -| bundleCodeDir | string | 是 | 否 | 安装文件路径。应用在内部存储上的安装路径。 | -| cacheDir | string | 是 | 否 | 缓存文件路径。应用在内部存储上的缓存路径。
对应于“设置 > 应用管理”，找到对应应用的“存储”中的缓存内容。 | -| filesDir | string | 是 | 否 | 通用文件路径。应用在内部存储上的文件路径。
本目录下存放的文件可能会被应用迁移或者备份的时候同步到其他目录中。 | -| preferencesDir | string | 是 | 是 | 首选项文件路径。指示应用程序首选项目录。 | -| tempDir | string | 是 | 否 | 临时文件路径。
在应用卸载后，系统会删除存储在此目录中的文件。 | -| databaseDir | string | 是 | 否 | 数据库路径。获取本地数据库存储路径。 | -| distributedFilesDir | string | 是 | 否 | 分布式文件路径。 | - -获取路径的能力是基类Context中提供的能力，因此在ApplicationContext、AbilityStageContext、UIAbilityContext和ExtensionContext中均可以获取，在各类Context中获取到的路径会有一些差别，具体差别如下图所示。 - -**图1** Context中获取的应用开发路径 -![context-dir](figures/context-dir.png) +获取到的是应用文件路径的沙箱路径。其对应的绝对路径，在创建或者修改文件之后，可以在`hdc shell`中，通过`find / -name <文件名称>`命令查找获取。 - 通过ApplicationContext获取的应用级别路径。应用全局信息建议存放的路径，存放在此路径的文件内容仅在应用卸载时会被删除。 | 属性 | 路径 | | -------- | -------- | - | bundleCodeDir | {路径前缀}/el1/bundle/ | - | cacheDir | {路径前缀}/{加密等级}/base/cache/ | - | filesDir | {路径前缀}/{加密等级}/base/files/ | - | preferencesDir | {路径前缀}/{加密等级}/base/preferences/ | - | tempDir | {路径前缀}/{加密等级}/base/temp/ | - | databaseDir | {路径前缀}/{加密等级}/database/ | - | distributedFilesDir | {路径前缀}/el2/distributedFiles/ | - + | bundleCodeDir | <路径前缀>/el1/bundle/ | + | cacheDir | <路径前缀>/<加密等级>/base/cache/ | + | filesDir | <路径前缀>/<加密等级>/base/files/ | + | preferencesDir | <路径前缀>/<加密等级>/base/preferences/ | + | tempDir | <路径前缀>/<加密等级>/base/temp/ | + | databaseDir | <路径前缀>/<加密等级>/database/ | + | distributedFilesDir | <路径前缀>/el2/distributedFiles/ | + + 以获取应用级别应用文件路径为例进行说明。 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + + export default class EntryAbility extends UIAbility { + onCreate(want, launchParam) { + let applicationContext = this.context.getApplicationContext(); + let cacheDir = applicationContext.cacheDir; + let tempDir = applicationContext.tempDir; + let filesDir = applicationContext.filesDir; + let databaseDir = applicationContext.databaseDir; + let bundleCodeDir = applicationContext.bundleCodeDir; + let distributedFilesDir = applicationContext.distributedFilesDir; + let preferencesDir = applicationContext.preferencesDir; + ... + } + } + ``` + - 通过AbilityStageContext、UIAbilityContext、ExtensionContext获取的HAP级别路径。HAP对应的信息建议存放的路径，存放在此路径的文件内容会跟随HAP的卸载而删除，不会影响应用级别路径的文件内容，除非该应用的HAP已全部卸载。 | 属性 | 路径 | | -------- | -------- | - | bundleCodeDir | {路径前缀}/el1/bundle/ | - | cacheDir | {路径前缀}/{加密等级}/base/**haps/{moduleName}**/cache/ | - | filesDir | {路径前缀}/{加密等级}/base/**haps/{moduleName}**/files/ | - | preferencesDir | {路径前缀}/{加密等级}/base/**haps/{moduleName}**/preferences/ | - | tempDir | {路径前缀}/{加密等级}/base/**haps/{moduleName}**/temp/ | - | databaseDir | {路径前缀}/{加密等级}/database/**{moduleName}**/ | - | distributedFilesDir | {路径前缀}/el2/distributedFiles/**{moduleName}**/ | - -获取应用开发路径的示例代码如下所示。 - - -```ts -import UIAbility from '@ohos.app.ability.UIAbility'; - -export default class EntryAbility extends UIAbility { - onCreate(want, launchParam) { - let cacheDir = this.context.cacheDir; - let tempDir = this.context.tempDir; - let filesDir = this.context.filesDir; - let databaseDir = this.context.databaseDir; - let bundleCodeDir = this.context.bundleCodeDir; - let distributedFilesDir = this.context.distributedFilesDir; - let preferencesDir = this.context.preferencesDir; - ... + | bundleCodeDir | <路径前缀>/el1/bundle/ | + | cacheDir | <路径前缀>/<加密等级>/base/**haps/\**/cache/ | + | filesDir | <路径前缀>/<加密等级>/base/**haps/\**/files/ | + | preferencesDir | <路径前缀>/<加密等级>/base/**haps/\**/preferences/ | + | tempDir | <路径前缀>/<加密等级>/base/**haps/\**/temp/ | + | databaseDir | <路径前缀>/<加密等级>/database/**\**/ | + | distributedFilesDir | <路径前缀>/el2/distributedFiles/**\**/ | + + 以获取HAP级别应用文件路径为例进行说明。 + + ```ts + import UIAbility from '@ohos.app.ability.UIAbility'; + + export default class EntryAbility extends UIAbility { + onCreate(want, launchParam) { + let cacheDir = this.context.cacheDir; + let tempDir = this.context.tempDir; + let filesDir = this.context.filesDir; + let databaseDir = this.context.databaseDir; + let bundleCodeDir = this.context.bundleCodeDir; + let distributedFilesDir = this.context.distributedFilesDir; + let preferencesDir = this.context.preferencesDir; + ... + } } -} -``` - -> **说明：** -> -> 示例代码获取到的是应用开发路径的沙箱路径。其对应的绝对路径，在创建或者修改文件之后，可以在`hdc shell`中，通过`find / -name <文件名称>`命令查找获取。 + ``` ### 获取和修改加密分区 @@ -153,22 +153,23 @@ export default class EntryAbility extends UIAbility { > > - AreaMode.EL2：用户级加密区，设备开机，首次输入密码后才能够访问的数据区。 -要实现获取和设置当前加密分区，可以通过读写[Context的area属性](../reference/apis/js-apis-inner-application-context.md)来实现。 +要实现获取和设置当前加密分区，可以通过读写[Context](../reference/apis/js-apis-inner-application-context.md)的`area`属性来实现。 ```ts import UIAbility from '@ohos.app.ability.UIAbility'; +import contextConstant from '@ohos.app.ability.contextConstant'; export default class EntryAbility extends UIAbility { onCreate(want, launchParam) { - // 存储普通信息前，切换到EL1设备机加密 - if (this.context.area === 1) { // 获取area - this.context.area = 0; // 修改area + // 存储普通信息前，切换到EL1设备级加密 + if (this.context.area === contextConstant.AreaMode.EL2) { // 获取area + this.context.area = contextConstant.AreaMode.EL1; // 修改area } // 存储普通信息 // 存储敏感信息前，切换到EL2用户级加密 - if (this.context.area === 0) { // 获取area - this.context.area = 1; // 修改area + if (this.context.area === contextConstant.AreaMode.EL1) { // 获取area + this.context.area = contextConstant.AreaMode.EL2; // 修改area } // 存储敏感信息 } @@ -178,16 +179,17 @@ export default class EntryAbility extends UIAbility { ### 创建其他应用或其他Module的Context -基类Context提供创建其他应用或其他Module的Context的方法有[createBundleContext(bundleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatebundlecontext)、[createModuleContext(moduleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatemodulecontext)和[createModuleContext(bundleName: string, moduleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatemodulecontext-1)接口，创建其他应用或者其他Module的Context，从而通过该Context获取相应的资源信息（例如获取其他Module的[获取应用开发路径](#获取应用开发路径)信息）。 +基类Context提供创建其他应用或其他Module的Context的方法有[createBundleContext(bundleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatebundlecontext)、[createModuleContext(moduleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatemodulecontext)和[createModuleContext(bundleName: string, moduleName: string)](../reference/apis/js-apis-inner-application-context.md#contextcreatemodulecontext-1)接口，创建其他应用或者其他Module的Context，从而通过该Context获取相应的资源信息（例如获取其他Module的[获取应用文件路径](#获取应用文件路径)信息）。 -- 调用createBundleContext(bundleName:string)方法，创建其他应用的Context信息。 +- 调用`createBundleContext(bundleName:string)`方法，创建其他应用的Context信息。 > **说明：** + > > 当获取的是其他应用的Context时： - > - > - 申请`ohos.permission.GET_BUNDLE_INFO_PRIVILEGED`权限，配置方式请参见[访问控制授权申请](../security/accesstoken-guidelines.md#配置文件权限声明)。 - > + > + > - 申请`ohos.permission.GET_BUNDLE_INFO_PRIVILEGED`权限，配置方式请参见[配置文件权限声明](../security/accesstoken-guidelines.md#配置文件权限声明)。 + > > - 接口为系统接口，三方应用不支持调用。 - + 例如在桌面上显示的应用信息，包括应用名称和应用图标等，桌面应用可以通过调用上述的方法获取相应应用的Context信息从而获取到相应的应用名称、图标等资源信息。 ```ts @@ -202,8 +204,8 @@ export default class EntryAbility extends UIAbility { } } ``` - -- 调用createModuleContext(bundleName:string, moduleName:string)方法，获取指定应用指定Module的上下文信息。获取到指定应用指定Module的Context之后，即可获取到相应应用Module的资源信息。 + +- 调用`createModuleContext(bundleName:string, moduleName:string)`方法，获取指定应用指定Module的上下文信息。获取到指定应用指定Module的Context之后，即可获取到相应应用Module的资源信息。 > **说明：** > > 当获取的是其他应用的指定Module的Context时： @@ -225,7 +227,7 @@ export default class EntryAbility extends UIAbility { } ``` -- 调用createModuleContext(moduleName:string)方法，获取本应用中其他Module的Context。获取到其他Module的Context之后，即可获取到相应Module的资源信息。 +- 调用`createModuleContext(moduleName:string)`方法，获取本应用中其他Module的Context。获取到其他Module的Context之后，即可获取到相应Module的资源信息。 ```ts import UIAbility from '@ohos.app.ability.UIAbility'; diff --git a/zh-cn/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md b/zh-cn/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md index edca5e5077aee89e5f014c1c9a0cbf8b83fd1d8b..5cd0965d98f172e45a66f45041078be53c7e7467 100644 --- a/zh-cn/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md +++ b/zh-cn/application-dev/application-models/mission-set-icon-name-for-task-snapshot.md @@ -7,7 +7,7 @@ 图1 UIAbility对应的任务快照 ![](figures/mission-list-recent.png) -也可以使用[UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)和[UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法，根据需要自定义任务快照的图标和名称。例如，对于UIAbility的多实例启动模式，可以根据不同的功能配置相应的任务快照的图标和名称。 +也可以使用[`UIAbilityContext.setMissionIcon()`](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)和[`UIAbilityContext.setMissionLabel()`](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法，根据需要自定义任务快照的图标和名称。例如，对于UIAbility的多实例启动模式，可以根据不同的功能配置相应的任务快照的图标和名称。 本文将从以下两个方面介绍。 @@ -16,11 +16,15 @@ ## 设置任务快照的图标（仅对系统应用开放） -通过调用[UIAbilityContext.setMissionIcon()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)方法修改任务快照的图标。图片内容为[PixelMap](../reference/apis/js-apis-image.md#pixelmap7)类型对象。示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。 +通过调用[`UIAbilityContext.setMissionIcon()`](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionicon)方法修改任务快照的图标。 + +示例中的context的获取方式请参见[获取UIAbility的上下文信息](uiability-usage.md#获取uiability的上下文信息)。示例中的`pixelMap`的获取方式请参见[图片解码](../media/image-decoding.md)。 + ```ts -let imagePixelMap: PixelMap = undefined; // 需要获取图片PixelMap信息 +let context = ...; // UIAbilityContext +let pixelMap: PixelMap = ...; // 图片的PixelMap信息 -context.setMissionIcon(imagePixelMap, (err) => { +context.setMissionIcon(pixelMap, (err) => { if (err.code) { console.error(`Failed to set mission icon. Code is ${err.code}, message is ${err.message}`); } @@ -34,10 +38,12 @@ context.setMissionIcon(imagePixelMap, (err) => { ## 设置任务快照的名称 -通过调用[UIAbilityContext.setMissionLabel()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法修改任务快照的名称。 +通过调用[`UIAbilityContext.setMissionLabel()`](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextsetmissionlabel)方法修改任务快照的名称。 ```ts -this.context.setMissionLabel('test').then(() => { +let context = ...; // UIAbilityContext + +context.setMissionLabel('test').then(() => { console.info('Succeeded in seting mission label.'); }).catch((err) => { console.error(`Failed to set mission label. Code is ${err.code}, message is ${err.message}`); diff --git a/zh-cn/application-dev/file-management/app-sandbox-directory.md b/zh-cn/application-dev/file-management/app-sandbox-directory.md index e5ead98a48c1e53f31760686c7bc6060d35c0932..0340f8a7bc692a44018b4609780168da63b5b38b 100644 --- a/zh-cn/application-dev/file-management/app-sandbox-directory.md +++ b/zh-cn/application-dev/file-management/app-sandbox-directory.md @@ -10,8 +10,7 @@ 下图展示了应用沙箱下，应用可访问的文件范围和方式。 -**图1** 应用沙箱文件访问关系图 - +**图1** 应用沙箱文件访问关系图 ![Application sandbox file access relationship](figures/application-sandbox-file-access-relationship.png) ## 应用沙箱目录与应用沙箱路径 @@ -24,8 +23,7 @@ - 从实际物理路径推导物理路径与沙箱路径并不是1：1的映射关系，沙箱路径总是少于系统进程视角可见的物理路径。有些调试进程视角下的物理路径在对应的应用沙箱目录是无法找到的，而沙箱路径总是能够找到其对应的物理路径。 -**图2** 应用沙箱路径（不同权限与角色的进程下可见的文件路径不同） -   +**图2** 应用沙箱路径（不同权限与角色的进程下可见的文件路径不同） ![Application sandbox path](figures/application-sandbox-path.png) ## 应用文件目录与应用文件路径 @@ -36,8 +34,7 @@ 在此主要介绍应用文件目录，如下图所示。应用文件目录下某个文件或某个具体目录的路径称为应用文件路径。应用文件目录下的各个文件路径，具备不同的属性和特征。 -**图3** 应用文件目录结构图 - +**图3** 应用文件目录结构图 ![Application file directory structure](figures/application-file-directory-structure.png) 1. 一级目录data/：代表应用文件目录。 @@ -52,7 +49,7 @@ 4. 四级、五级目录： 通过ApplicationContext可以获取base下的files、cache、preferences、temp、distributedfiles等目录的应用文件路径，应用全局信息可以存放在这些目录下。 - 通过UIAbilityContext、AbilityStageContext、ExtensionContext可以获取hap级别应用文件路径。HAP信息可以存放在这些目录下，存放在此目录的文件会跟随HAP的卸载而删除，不会影响app级别目录下的文件。在开发态，一个应用包含一个或者多个HAP，详见[Stage模型应用程序包结构](../quick-start/application-package-structure-stage.md)。 + 通过UIAbilityContext、AbilityStageContext、ExtensionContext可以获取HAP级别应用文件路径。HAP信息可以存放在这些目录下，存放在此目录的文件会跟随HAP的卸载而删除，不会影响App级别目录下的文件。在开发态，一个应用包含一个或者多个HAP，详见[Stage模型应用程序包结构](../quick-start/application-package-structure-stage.md)。 Context上下文获取及上述应用文件路径的获取，详见[应用上下文Context](../application-models/application-context-stage.md)。 @@ -65,16 +62,16 @@ **表1** 应用文件路径详细说明 - | 目录名 | Context属性名称 | 类型 | 说明 | + | 目录名 | Context属性名称 | 类型 | 说明 | | -------- | -------- | -------- | -------- | - | bundle | bundleCodeDir | 安装文件路径 | 应用安装后的app的hap资源包所在目录；随应用卸载而清理。不能拼接路径访问资源文件，请使用[资源管理接口](../reference/apis/js-apis-resource-manager.md)访问资源。 | - | base | NA | 本设备文件路径 | 应用在本设备上存放持久化数据的目录，子目录包含files/、cache/、temp/和haps/；随应用卸载而清理。 | - | database | databaseDir | 数据库路径 | 应用在el1加密条件下存放通过分布式数据库服务操作的文件目录；随应用卸载而清理。 | - | distributedfiles | distributedFilesDir | 分布式文件路径 | 应用在el2加密条件下存放分布式文件的目录，应用将文件放入该目录可分布式跨设备直接访问；随应用卸载而清理。 | - | files | filesDir | 应用通用文件路径 | 应用在本设备内部存储上通用的存放默认长期保存的文件路径；随应用卸载而清理。 | - | cache | cacheDir | 应用缓存文件路径 | 应用在本设备内部存储上用于缓存下载的文件或可重新生成的缓存文件的路径，应用cache目录大小超过配额或者系统空间达到一定条件，自动触发清理该目录下文件；用户通过系统空间管理类应用也可能触发清理该目录。应用需判断文件是否仍存在，决策是否需重新缓存该文件。 | - | preferences | preferencesDir | 应用首选项文件路径 | 应用在本设备内部存储上通过数据库API存储配置类或首选项的目录；应用在本设备内部存储上通过数据库API存储配置类或首选项的目录；随应用卸载而清理。详见[通过用户首选项实现数据持久化](../database/data-persistence-by-preferences.md)。 | - | temp | tempDir | 应用临时文件路径 | 应用在本设备内部存储上仅在应用运行期间产生和需要的文件，应用退出后即清理。 | + | bundle | bundleCodeDir | 安装文件路径 | 应用安装后的App的HAP资源包所在目录；随应用卸载而清理。不能拼接路径访问资源文件，请使用[资源管理接口](../reference/apis/js-apis-resource-manager.md)访问资源。 | + | base | NA | 本设备文件路径 | 应用在本设备上存放持久化数据的目录，子目录包含files/、cache/、temp/和haps/；随应用卸载而清理。 | + | database | databaseDir | 数据库路径 | 应用在el1加密条件下存放通过分布式数据库服务操作的文件目录；随应用卸载而清理。 | + | distributedfiles | distributedFilesDir | 分布式文件路径 | 应用在el2加密条件下存放分布式文件的目录，应用将文件放入该目录可分布式跨设备直接访问；随应用卸载而清理。 | + | files | filesDir | 应用通用文件路径 | 应用在本设备内部存储上通用的存放默认长期保存的文件路径；随应用卸载而清理。 | + | cache | cacheDir | 应用缓存文件路径 | 应用在本设备内部存储上用于缓存下载的文件或可重新生成的缓存文件的路径，应用cache目录大小超过配额或者系统空间达到一定条件，自动触发清理该目录下文件；用户通过系统空间管理类应用也可能触发清理该目录。应用需判断文件是否仍存在，决策是否需重新缓存该文件。 | + | preferences | preferencesDir | 应用首选项文件路径 | 应用在本设备内部存储上通过数据库API存储配置类或首选项的目录；应用在本设备内部存储上通过数据库API存储配置类或首选项的目录；随应用卸载而清理。详见[通过用户首选项实现数据持久化](../database/data-persistence-by-preferences.md)。 | + | temp | tempDir | 应用临时文件路径 | 应用在本设备内部存储上仅在应用运行期间产生和需要的文件，应用退出后即清理。 | 对于上述各类应用文件路径，常见使用场景如下：