diff --git a/zh-cn/application-dev/ability/context-userguide.md b/zh-cn/application-dev/ability/context-userguide.md index f5472f3e5427dc48d1a51322b1dbec335197d053..8768b6e623c6a4a8d07f03d663a8cf8fde262375 100644 --- a/zh-cn/application-dev/ability/context-userguide.md +++ b/zh-cn/application-dev/ability/context-userguide.md @@ -11,7 +11,7 @@ ​ **FA模型** 只有app/Context中的方法属于FA模型对应的Context。该模式下，应用级别的Context和Ability级别的Context都是该类型的实例，如果在应用级别的Context里面调用了Ability级别的方法，会产生错误。所以开发者需要注意context实例所代表的实际含义。 -​ **Stage模型** 除了app/Context之外的Context都属于Stage模型，分别有application/Context、application/AbilityStageContext、application/ExtensionContext、application/AbilityContext、application/FormExtensionContext和application/ServiceExtensionContext六种Context。这些Context的介绍及使用方式将会在[Stage模型和Context详细介绍](#stage模型和context详细介绍)种进行说明。 +​ **Stage模型** 除了app/Context之外的Context都属于Stage模型，分别有application/Context、application/ApplicationContext、application/AbilityStageContext、application/ExtensionContext、application/AbilityContext、application/FormExtensionContext和application/ServiceExtensionContext七种Context。这些Context的介绍及使用方式将会在[Stage模型和Context详细介绍](#stage模型和context详细介绍)种进行说明。 ![contextIntroduction](figures/contextIntroduction.png) @@ -55,13 +55,13 @@ export default { ## Stage模型和Context详细介绍 -​ Stage模型有6大Context： +​ Stage模型有7大Context： ### application/Context **概述** -​ application/Context类型的Context是基类Context，里面提供了应用的一些基础信息：resourceManager、applicationInfo、cacheDir等，还有应用的一些基本方法：createBundleContext、switchArea等。应用级别的Context也是application/Context这种类型。 +​ application/Context类型的Context是基类Context，里面提供了应用的一些基础信息：resourceManager、applicationInfo、cacheDir等，还有应用的一些基本方法：createBundleContext、switchArea等。 **获取方法** @@ -89,15 +89,77 @@ export default class MainAbility extends Ability { ​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/Context.d.ts +### application/ApplicationContext + + **概述** + +​ application/ApplicationContext是应用级别的Context。和基类Context相比，应用级别的Context中提供了监听进程内组件的生命周期的能力，包括registerAbilityLifecycleCallback和unregisterAbilityLifecycleCallback两种方法。 + +**获取方法** + +​ 在Ability中通过context.getApplicationContext()方法获取。 + +**示例** + +```javascript +import AbilityStage from "@ohos.application.AbilityStage"; + +var lifecycleid; + +export default class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage onCreate") + let AbilityLifecycleCallback = { + onAbilityCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability)); + }, + onAbilityWindowStageCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityWindowStageCreate ability:" + JSON.stringify(ability)); + }, + onAbilityWindowStageDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityWindowStageDestroy ability:" + JSON.stringify(ability)); + }, + onAbilityDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability)); + }, + onAbilityForeground(ability){ + console.log("AbilityLifecycleCallback onAbilityForeground ability:" + JSON.stringify(ability)); + }, + onAbilityBackground(ability){ + console.log("AbilityLifecycleCallback onAbilityBackground ability:" + JSON.stringify(ability)); + }, + onAbilityContinue(ability){ + console.log("AbilityLifecycleCallback onAbilityContinue ability:" + JSON.stringify(ability)); + } + } + // 1.通过context属性获取applicationContext + let applicationContext = this.context.getApplicationContext(); + // 2.通过applicationContext注册监听应用内生命周期 + lifecycleid = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback); + console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); + } + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + applicationContext.unregisterAbilityLifecycleCallback(lifecycleid, (error, data) => { + console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); + }); + } +} +``` + +**d.ts声明** + +​ https://gitee.com/openharmony/interface_sdk-js/blob/master/api/application/ApplicationContext.d.ts + ### application/AbilityStageContext -​ **概述** + **概述** ​ application/AbilityStageContext是Hap包级别的Context。和基类Context相比，Hap包级别的Context中多了HapModuleInfo和Configuration两个信息。 **获取方法** -​ 可以直接在AbilityStage中通过context属性拿到。 +​ 可以直接在AbilityStage中通过context属性获取。 **示例** @@ -116,7 +178,7 @@ export default class MyAbilityStage extends AbilityStage { ### application/AbilityContext -​ **概述** + **概述** ​ Stage模型下，每个Ability中都包含了一个Context属性。 @@ -124,7 +186,7 @@ export default class MyAbilityStage extends AbilityStage { **获取方法** -​ 在Ability中通过context属性拿到。 +​ 在Ability中通过context属性获取。 **示例** @@ -158,7 +220,7 @@ export default class MainAbility extends Ability { ### application/ExtensionContext -​ **概述** + **概述** ​ 和FA模型不同的是，Stage模型把Service从Ability中剥离出来，单独定义了一组通用扩展类Extension用来处理等同的功能。Extension是一个基类，不承担具体业务功能。业务方根据自己的需要去扩展对应的Extension，例如：ServiceAbility扩展为了ServiceExtensionAbility，卡片扩展为了FormExtension。 @@ -174,7 +236,7 @@ export default class MainAbility extends Ability { ### application/ServiceExtensionContext -​ **概述** + **概述** ​ ServiceExtensionAbility类似于FA模型的ServiceAbility，里面只有生命周期回调相关的处理。 diff --git a/zh-cn/application-dev/ability/figures/contextIntroduction.png b/zh-cn/application-dev/ability/figures/contextIntroduction.png index a0f1f79d715377e990c4d3c3ea48bdd62aa139bb..2ab1528f753dad2fdf8e52ae992471773f56e7f4 100644 Binary files a/zh-cn/application-dev/ability/figures/contextIntroduction.png and b/zh-cn/application-dev/ability/figures/contextIntroduction.png differ diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-ability.md b/zh-cn/application-dev/reference/apis/js-apis-application-ability.md index 3432776f68e956a15536707ecac4b1f365bf0924..306be5858bbcc592b89484bb149187a67d8376cb 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-ability.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-ability.md @@ -143,7 +143,7 @@ Ability生命周期回调，在销毁时回调，执行资源清理等操作。 onForeground(): void; -Ability生命周期回调，当应用处于前台时触发。 +Ability生命周期回调，当应用从后台转到前台时触发。 **系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -162,7 +162,7 @@ Ability生命周期回调，当应用处于前台时触发。 onBackground(): void; -Ability生命周期回调，当应用处于后台时触发。 +Ability生命周期回调，当应用从前台转到后台时触发。 **系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md b/zh-cn/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md new file mode 100644 index 0000000000000000000000000000000000000000..bd4ad4df68876f68e384e639fccf9b912c21d52c --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md @@ -0,0 +1,153 @@ +# AbilityLifecycleCallback + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +应用上下文ApplicationContext的生命周期监听方法的回调类，里面提供了onAbilityCreate、onAbilityWindowStageCreate、onAbilityWindowStageDestroy等方法。 + + +## AbilityLifecycleCallback.onAbilityCreate + +onAbilityCreate(ability: Ability): void; + +注册监听应用上下文的生命周期后，在ability创建时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityWindowStageCreate + +onAbilityWindowStageCreate(ability: Ability): void; + +注册监听应用上下文的生命周期后，在windowStage创建时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityWindowStageDestroy + +onAbilityWindowStageDestroy(ability: Ability): void; + +注册监听应用上下文的生命周期后，在windowStage销毁时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityDestroy + +onAbilityDestroy(ability: Ability): void; + +注册监听应用上下文的生命周期后，在ability销毁时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityForeground + +onAbilityForeground(ability: Ability): void; + +注册监听应用上下文的生命周期后，在ability的状态从后台转到前台时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityBackground + +onAbilityBackground(ability: Ability): void; + +注册监听应用上下文的生命周期后，在ability的状态从前台转到后台时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + + +## AbilityLifecycleCallback.onAbilityContinue + +onAbilityContinue(ability: Ability): void; + +注册监听应用上下文的生命周期后，在ability迁移时触发回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | ability | [Ability](js-apis-application-ability.md#Ability) | 是 | 当前Ability对象 | + +**示例：** + + + ```js + import AbilityStage from "@ohos.application.AbilityStage"; + + export default class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage onCreate") + let AbilityLifecycleCallback = { + onAbilityCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability)); + }, + onAbilityWindowStageCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityWindowStageCreate ability:" + JSON.stringify(ability)); + }, + onAbilityWindowStageDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityWindowStageDestroy ability:" + JSON.stringify(ability)); + }, + onAbilityDestroy(ability){ + console.log("AbilityLifecycleCallback onAbilityDestroy ability:" + JSON.stringify(ability)); + }, + onAbilityForeground(ability){ + console.log("AbilityLifecycleCallback onAbilityForeground ability:" + JSON.stringify(ability)); + }, + onAbilityBackground(ability){ + console.log("AbilityLifecycleCallback onAbilityBackground ability:" + JSON.stringify(ability)); + }, + onAbilityContinue(ability){ + console.log("AbilityLifecycleCallback onAbilityContinue ability:" + JSON.stringify(ability)); + } + } + // 1.通过context属性获取applicationContext + let applicationContext = this.context.getApplicationContext(); + // 2.通过applicationContext注册监听应用内生命周期 + let lifecycleid = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback); + console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); + } + } + ``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-applicationContext.md b/zh-cn/application-dev/reference/apis/js-apis-application-applicationContext.md new file mode 100644 index 0000000000000000000000000000000000000000..aa5097904e89bb5e5612be05dfd8adc9456d6a1b --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-application-applicationContext.md @@ -0,0 +1,71 @@ +# ApplicationContext + +> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + + +提供开发者应用级别的的上下文，提供注册及取消注册应用内组件生命周期的监听接口。 + + +## 使用说明 + +在使用ApplicationContext的功能前，需要通过context的实例获取。 + +```js +let applicationContext = this.context.getApplicationContext(); +``` + + +## ApplicationContext.registerAbilityLifecycleCallback + +registerAbilityLifecycleCallback(callback: AbilityLifecycleCallback): **number**; + +注册监听应用内生命周期 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------------ | -------- | ---- | ------------------------------ | +| [AbilityLifecycleCallback](js-apis-application-abilityLifecycleCallback.md) | callback | 是 | 回调方法，返回注册监听事件的id | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------ | +| number | 返回的此次注册监听生命周期的id（每次注册该id会自增+1，当超过监听上限数量2^63-1时，返回-1）| + +**示例：** + + ```js + let applicationContext = this.context.getApplicationContext(); + console.log("stage applicationContext: " + JSON.stringify(applicationContext)); + let lifecycleid = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback); + console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); + ``` + +## ApplicationContext.unregisterAbilityLifecycleCallback + +unregisterAbilityLifecycleCallback(callbackId: **number**, callback: AsyncCallback<**void**>): **void**; + +取消监听应用内生命周期 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------- | ---- | -------------------------- | +| callbackId | number | 是 | 注册监听应用内生命周期的id | +| AsyncCallback | callback | 是 | 回调方法 | + +**示例：** + + ```js + let applicationContext = this.context.getApplicationContext(); + console.log("stage applicationContext: " + JSON.stringify(applicationContext)); + applicationContext.unregisterAbilityLifecycleCallback(lifecycleid, (error, data) => { + console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); + }); + ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-context.md b/zh-cn/application-dev/reference/apis/js-apis-application-context.md index c6d6d1d2d4291c18bbe103529c39503070fa1ba6..5aec0d2417ee41692b6b249f17bcdca5c4369412 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-context.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-context.md @@ -62,23 +62,23 @@ createBundleContext(bundleName: string): Context; ## Context.getApplicationContext -getApplicationContext(): Context; +getApplicationContext(): ApplicationContext; -获取当前context。 +获取当前applicationContext。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **返回值：** - | 类型 | 说明 | - | -------- | -------- | - | Context | 当前Context 信息。 | +| 类型 | 说明 | +| -------- | -------- | +| ApplicationContext | 当前ApplicationContext对象信息。 | **示例：** ```js // 必选项。 - let context = this.context.getApplicationContext(); + let applicationContext = this.context.getApplicationContext(); ``` @@ -91,4 +91,4 @@ getApplicationContext(): Context; | 变量 | 值 | 描述 | | --------------- | ---- | --------------- | | EL1 | 0 | 设备级加密区。 | -| EL2 | 1 | 用户凭据加密区。默认为EL2。 | \ No newline at end of file +| EL2 | 1 | 用户凭据加密区。默认为EL2。 |