diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md index ae9065fb26bfe209b7776a4c86a1892f6076fe88..e18d80b08951def6bb3e0dd701cfd80cb203cc25 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md @@ -112,6 +112,43 @@ abilityDelegator.addAbilityMonitor(monitor).then(() => { }); ``` +### addAbilityMonitorSync10+ + +addAbilityMonitorSync(monitor: AbilityMonitor): void; + +同步添加AbilityMonitor实例 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | 是 | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor)实例 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000100 | AddAbilityMonitor failed. | +| 401 | If the input parameter is not valid parameter. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 + +**示例：** + +```ts +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; + +let monitor = { + abilityName: 'abilityname', + onAbilityCreate: onAbilityCreateCallback +}; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.addAbilityMonitorSync(monitor); +``` + ### removeAbilityMonitor9+ removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void; @@ -203,6 +240,43 @@ abilityDelegator.removeAbilityMonitor(monitor).then(() => { }); ``` +### removeAbilityMonitorSync10+ + +removeAbilityMonitorSync(monitor: AbilityMonitor): void; + +同步删除已经添加的AbilityMonitor实例 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | 是 | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor)实例 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000100 | RemoveAbilityMonitor failed. | +| 401 | If the input parameter is not valid parameter. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 + +**示例：** + +```ts +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; + +let monitor = { + abilityName: 'abilityname', + onAbilityCreate: onAbilityCreateCallback +}; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.removeAbilityMonitorSync(monitor); +``` + ### waitAbilityMonitor9+ waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void; @@ -1092,6 +1166,44 @@ abilityDelegator.addAbilityStageMonitor(monitor).then(() => { }); ``` +### addAbilityStageMonitorSync10+ + +addAbilityStageMonitorSync(monitor: AbilityStageMonitor): void; + +同步添加一个AbilityStageMonitor对象，用于监视指定abilityStage的生命周期状态更改。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | 是 | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) 实例 | +| callback | AsyncCallback\ | 是 | 表示指定的回调方法 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000100 | AddAbilityStageMonitor failed. | +| 401 | If the input parameter is not valid parameter. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 + +**示例：** + +```ts +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; + +let monitor = { + moduleName: 'moduleName', + srcEntrance: 'srcEntrance', +}; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.addAbilityStageMonitorSync(monitor); +``` + ### removeAbilityStageMonitor9+ removeAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\): void; @@ -1175,6 +1287,43 @@ abilityDelegator.removeAbilityStageMonitor(monitor).then(() => { }); ``` +### removeAbilityStageMonitorSync10+ + +removeAbilityStageMonitorSync(monitor: AbilityStageMonitor): void; + +同步从应用程序内存中删除指定的AbilityStageMonitor对象。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | 是 | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) 实例 | + +**错误码**： + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000100 | RemoveAbilityStageMonitor failed. | +| 401 | If the input parameter is not valid parameter. | + +以上错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)。 + +**示例：** + +```ts +let abilityDelegator: AbilityDelegatorRegistry.AbilityDelegator; + +let monitor = { + moduleName: 'moduleName', + srcEntrance: 'srcEntrance', +}; + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.removeAbilityStageMonitorSync(monitor); +``` + ### waitAbilityStageMonitor9+ waitAbilityStageMonitor(monitor: AbilityStageMonitor, callback: AsyncCallback\): void; diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-applicationContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-applicationContext.md index aef767e99bd639816a8c132cc435a7c3428f5c66..1786c2b643256e65234803318635a131db87817f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-applicationContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-applicationContext.md @@ -27,6 +27,10 @@ on(type: 'abilityLifecycle', callback: AbilityLifecycleCallback): **number**; 注册监听应用内生命周期 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[on(type: 'abilityLifecycleEvent', callback: AbilityLifecycleCallback): **number**](#applicationcontextontype-abilitylifecycleevent-callback-abilitylifecyclecallback10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -54,42 +58,115 @@ export default class EntryAbility extends UIAbility { console.log('MyAbility onCreate'); let AbilityLifecycleCallback = { onAbilityCreate(ability) { - console.log('AbilityLifecycleCallback onAbilityCreate ability: ${ability}'); + console.log(`AbilityLifecycleCallback onAbilityCreate ability: ${ability}`); }, onWindowStageCreate(ability, windowStage) { - console.log('AbilityLifecycleCallback onWindowStageCreate ability: ${ability}'); - console.log('AbilityLifecycleCallback onWindowStageCreate windowStage: ${windowStage}'); + console.log(`AbilityLifecycleCallback onWindowStageCreate ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageCreate windowStage: ${windowStage}`); }, onWindowStageActive(ability, windowStage) { - console.log('AbilityLifecycleCallback onWindowStageActive ability: ${ability}'); - console.log('AbilityLifecycleCallback onWindowStageActive windowStage: ${windowStage}'); + console.log(`AbilityLifecycleCallback onWindowStageActive ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageActive windowStage: ${windowStage}`); }, onWindowStageInactive(ability, windowStage) { - console.log('AbilityLifecycleCallback onWindowStageInactive ability: ${ability}'); - console.log('AbilityLifecycleCallback onWindowStageInactive windowStage: ${windowStage}'); + console.log(`AbilityLifecycleCallback onWindowStageInactive ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageInactive windowStage: ${windowStage}`); }, onWindowStageDestroy(ability, windowStage) { - console.log('AbilityLifecycleCallback onWindowStageDestroy ability: ${ability}'); - console.log('AbilityLifecycleCallback onWindowStageDestroy windowStage: ${windowStage}'); + console.log(`AbilityLifecycleCallback onWindowStageDestroy ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageDestroy windowStage: ${windowStage}`); }, onAbilityDestroy(ability) { - console.log('AbilityLifecycleCallback onAbilityDestroy ability: ${ability}'); + console.log(`AbilityLifecycleCallback onAbilityDestroy ability: ${ability}`); }, onAbilityForeground(ability) { - console.log('AbilityLifecycleCallback onAbilityForeground ability: ${ability}'); + console.log(`AbilityLifecycleCallback onAbilityForeground ability: ${ability}`); }, onAbilityBackground(ability) { - console.log('AbilityLifecycleCallback onAbilityBackground ability: ${ability}'); + console.log(`AbilityLifecycleCallback onAbilityBackground ability: ${ability}`); }, onAbilityContinue(ability) { - console.log('AbilityLifecycleCallback onAbilityContinue ability: ${ability}'); + console.log(`AbilityLifecycleCallback onAbilityContinue ability: ${ability}`); } } // 1.通过context属性获取applicationContext let applicationContext = this.context.getApplicationContext(); // 2.通过applicationContext注册监听应用内生命周期 lifecycleId = applicationContext.on('abilityLifecycle', AbilityLifecycleCallback); - console.log('registerAbilityLifecycleCallback lifecycleId: ${lifecycleId)}'); + console.log(`registerAbilityLifecycleCallback lifecycleId: ${lifecycleId)}`); + } +} +``` + +## ApplicationContext.on(type: 'abilityLifecycleEvent', callback: AbilityLifecycleCallback)10+ + +on(type: 'abilityLifecycleEvent', callback: AbilityLifecycleCallback): **number**; + +注册监听应用内生命周期 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------------ | -------- | ---- | ------------------------------ | +| type | 'abilityLifecycleEvent' | 是 | 监听事件的类型。 | +| callback | [AbilityLifecycleCallback](js-apis-app-ability-abilityLifecycleCallback.md) | 是 | 回调方法，返回注册监听事件的ID。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------ | +| number | 返回的此次注册监听生命周期的ID（每次注册该ID会自增+1，当超过监听上限数量2^63-1时，返回-1）。| + +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +let lifecycleId; + +export default class EntryAbility extends UIAbility { + onCreate() { + console.log('MyAbility onCreate'); + let AbilityLifecycleCallback = { + onAbilityCreate(ability) { + console.log(`AbilityLifecycleCallback onAbilityCreate ability: ${ability}`); + }, + onWindowStageCreate(ability, windowStage) { + console.log(`AbilityLifecycleCallback onWindowStageCreate ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageCreate windowStage: ${windowStage}`); + }, + onWindowStageActive(ability, windowStage) { + console.log(`AbilityLifecycleCallback onWindowStageActive ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageActive windowStage: ${windowStage}`); + }, + onWindowStageInactive(ability, windowStage) { + console.log(`AbilityLifecycleCallback onWindowStageInactive ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageInactive windowStage: ${windowStage}`); + }, + onWindowStageDestroy(ability, windowStage) { + console.log(`AbilityLifecycleCallback onWindowStageDestroy ability: ${ability}`); + console.log(`AbilityLifecycleCallback onWindowStageDestroy windowStage: ${windowStage}`); + }, + onAbilityDestroy(ability) { + console.log(`AbilityLifecycleCallback onAbilityDestroy ability: ${ability}`); + }, + onAbilityForeground(ability) { + console.log(`AbilityLifecycleCallback onAbilityForeground ability: ${ability}`); + }, + onAbilityBackground(ability) { + console.log(`AbilityLifecycleCallback onAbilityBackground ability: ${ability}`); + }, + onAbilityContinue(ability) { + console.log(`AbilityLifecycleCallback onAbilityContinue ability: ${ability}`); + } + } + // 1.通过context属性获取applicationContext + let applicationContext = this.context.getApplicationContext(); + // 2.通过applicationContext注册监听应用内生命周期 + lifecycleId = applicationContext.on('abilityLifecycleEvent', AbilityLifecycleCallback); + console.log(`registerAbilityLifecycleCallback lifecycleId: ${lifecycleId)}`); } } ``` @@ -100,6 +177,10 @@ off(type: 'abilityLifecycle', callbackId: **number**, callback: AsyncCallback<* 取消监听应用内生命周期 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[off(type: 'abilityLifecycleEvent', callbackId: number): **void**](#applicationcontextofftype-abilitylifecycleevent-callbackid-number10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -120,12 +201,12 @@ let lifecycleId; export default class EntryAbility extends UIAbility { onDestroy() { let applicationContext = this.context.getApplicationContext(); - console.log('stage applicationContext: ${applicationContext}'); + console.log(`stage applicationContext: ${applicationContext}`); applicationContext.off('abilityLifecycle', lifecycleId, (error, data) => { if (error) { - console.error('unregisterAbilityLifecycleCallback fail, err: ${JSON.stringify(error)}'); + console.error(`unregisterAbilityLifecycleCallback fail, err: ${JSON.stringify(error)}`); } else { - console.log('unregisterAbilityLifecycleCallback success, data: ${JSON.stringify(data)}'); + console.log(`unregisterAbilityLifecycleCallback success, data: ${JSON.stringify(data)}`); } }); } @@ -138,6 +219,10 @@ off(type: 'abilityLifecycle', callbackId: number): Promise\; 取消监听应用内生命周期 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[off(type: 'abilityLifecycleEvent', callbackId: number): **void**](#applicationcontextofftype-abilitylifecycleevent-callbackid-number10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -157,18 +242,53 @@ let lifecycleId; export default class MyAbility extends Ability { onDestroy() { let applicationContext = this.context.getApplicationContext(); - console.log('stage applicationContext: ${applicationContext}'); + console.log(`stage applicationContext: ${applicationContext}`); applicationContext.off('abilityLifecycle', lifecycleId); } } ``` +## ApplicationContext.off(type: 'abilityLifecycleEvent', callbackId: number)10+ + +off(type: 'abilityLifecycleEvent', callbackId: number): ; + +取消监听应用内生命周期 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------- | ---- | -------------------------- | +| type | 'abilityLifecycleEvent' | 是 | 取消监听事件的类型。 | +| callbackId | number | 是 | 注册监听应用内生命周期的ID。 | + +**示例：** + +```ts +import Ability from '@ohos.app.ability.UIAbility'; + +let lifecycleId; + +export default class MyAbility extends Ability { + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + console.log(`stage applicationContext: ${applicationContext}`); + applicationContext.off('abilityLifecycleEvent', lifecycleId); + } +} +``` + ## ApplicationContext.on(type: 'environment', callback: EnvironmentCallback) on(type: 'environment', callback: EnvironmentCallback): **number**; 注册对系统环境变化的监听。使用callback异步回调。 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[on(type: 'environmentEvent', callbackId: number): **number**](#applicationcontextontype-environmentevent-callback-environmentcallback10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -197,7 +317,7 @@ export default class EntryAbility extends UIAbility { globalThis.applicationContext = this.context.getApplicationContext(); let environmentCallback = { onConfigurationUpdated(config){ - console.log('onConfigurationUpdated config: ${JSON.stringify(config)}'); + console.log(`onConfigurationUpdated config: ${JSON.stringify(config)}`); }, onMemoryLevel(level){ console.log('onMemoryLevel level: ${level}'); @@ -207,7 +327,56 @@ export default class EntryAbility extends UIAbility { let applicationContext = globalThis.applicationContext; // 2.通过applicationContext注册监听系统环境变化 callbackId = applicationContext.on('environment', environmentCallback); - console.log('registerEnvironmentCallback callbackId: ${callbackId}'); + console.log(`registerEnvironmentCallback callbackId: ${callbackId}`); + } +} +``` + +## ApplicationContext.on(type: 'environmentEvent', callback: EnvironmentCallback)10+ + +on(type: 'environmentEvent', callback: EnvironmentCallback): **number**; + +注册对系统环境变化的监听。使用callback异步回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------------------ | -------- | ---- | ------------------------------ | +| type | 'environmentEvent' | 是 | 监听事件的类型。 | +| callback | [EnvironmentCallback](js-apis-app-ability-environmentCallback.md) | 是 | 回调方法，返回注册监听事件的ID。 | + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------------ | +| number | 返回的此次注册监听系统环境变化的ID（每次注册该ID会自增+1，当超过监听上限数量2^63-1时，返回-1）。| + +**示例：** + +```ts +import UIAbility from '@ohos.app.ability.UIAbility'; + +let callbackId; + +export default class EntryAbility extends UIAbility { + onCreate() { + console.log('MyAbility onCreate') + globalThis.applicationContext = this.context.getApplicationContext(); + let environmentCallback = { + onConfigurationUpdated(config){ + console.log('onConfigurationUpdated config: ${JSON.stringify(config)}'); + }, + onMemoryLevel(level){ + console.log('onMemoryLevel level: ${level}'); + } + }; + // 1.获取applicationContext + let applicationContext = globalThis.applicationContext; + // 2.通过applicationContext注册监听系统环境变化 + callbackId = applicationContext.on('environmentEvent', environmentCallback); + console.log(`registerEnvironmentCallback callbackId: ${callbackId}`); } } ``` @@ -218,6 +387,10 @@ off(type: 'environment', callbackId: **number**, callback: AsyncCallback<**void 取消对系统环境变化的监听。使用callback异步回调。 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[off(type: 'environmentEvent', callbackId: number): **void**;](#applicationcontextofftype-environmentevent-callbackid-number10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -240,9 +413,9 @@ export default class EntryAbility extends UIAbility { let applicationContext = this.context.getApplicationContext(); applicationContext.off('environment', callbackId, (error, data) => { if (error) { - console.error('unregisterEnvironmentCallback fail, err: ${JSON.stringify(error)}'); + console.error(`unregisterEnvironmentCallback fail, err: ${JSON.stringify(error)}`); } else { - console.log('unregisterEnvironmentCallback success, data: ${JSON.stringify(data)}'); + console.log(`unregisterEnvironmentCallback success, data: ${JSON.stringify(data)}`); } }); } @@ -255,6 +428,10 @@ off(type: 'environment', callbackId: **number**, callback: AsyncCallback<**void 取消对系统环境变化的监听。使用callback异步回调。 +> **说明：** +> +> 从 API version 9开始支持，从API version 10开始废弃，推荐使用[off(type: 'environmentEvent', callbackId: number): **void**](#applicationcontextofftype-environmentevent-callbackid-number10)。 + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -279,6 +456,36 @@ export default class MyAbility extends Ability { } ``` +## ApplicationContext.off(type: 'environmentEvent', callbackId: number)10+ + +off(type: 'environmentEvent', callbackId: **number**, callback: AsyncCallback<**void**>): **void**; + +取消对系统环境变化的监听。使用callback异步回调。 + +**系统能力**：SystemCapability.Ability.AbilityRuntime.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------- | ---- | -------------------------- | +| type | 'environmentEvent' | 是 | 取消监听事件的类型。 | +| callbackId | number | 是 | 注册监听系统环境变化的ID。 | + +**示例：** + +```ts +import Ability from '@ohos.app.ability.UIAbility'; + +let callbackId; + +export default class MyAbility extends Ability { + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + applicationContext.off('environmentEvent', callbackId); + } +} +``` + ## ApplicationContext.on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback)10+ on(type: 'applicationStateChange', callback: ApplicationStateChangeCallback): **void**; @@ -475,4 +682,5 @@ applicationContext.killAllProcesses(error => { console.error('killAllProcesses fail, error: ${JSON.stringify(error)}'); } }); -``` \ No newline at end of file +``` + \ No newline at end of file