diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 32c2d5b1d1d7d78c1247a375cf17d53505050478..ac000a8f0c1e7039b6aea2c213d85a768aaeb723 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -1,64 +1,132 @@ # APIs - [API Reference Document Description](development-intro.md) + - Ability Framework - - FA Model - - [@ohos.ability.featureAbility](js-apis-featureAbility.md) - - [@ohos.ability.particleAbility](js-apis-particleAbility.md) - - ability/[dataAbilityHelper](js-apis-dataAbilityHelper.md) - - app/[context](js-apis-Context.md) - - Stage Model - - [@ohos.application.Ability](js-apis-application-ability.md) - - [@ohos.application.AbilityConstant](js-apis-application-abilityConstant.md) - - [@ohos.application.AbilityStage](js-apis-application-abilitystage.md) - - [@ohos.application.abilityLifecycleCallback](js-apis-application-abilityLifecycleCallback.md) + - Stage Model (Recommended) + - [@ohos.app.ability.Ability](js-apis-app-ability-ability.md) + - [@ohos.app.ability.AbilityConstant](js-apis-app-ability-abilityConstant.md) + - [@ohos.app.ability.abilityLifecycleCallback](js-apis-app-ability-abilityLifecycleCallback.md) + - [@ohos.app.ability.AbilityStage](js-apis-app-ability-abilityStage.md) + - [@ohos.app.ability.common](js-apis-app-ability-common.md) + - [@ohos.app.ability.contextConstant](js-apis-app-ability-contextConstant.md) + - [@ohos.app.ability.EnvironmentCallback](js-apis-app-ability-environmentCallback.md) + - [@ohos.app.ability.ExtensionAbility](js-apis-app-ability-extensionAbility.md) + - [@ohos.app.ability.ServiceExtensionAbility](js-apis-app-ability-serviceExtensionAbility.md) + - [@ohos.app.ability.StartOptions](js-apis-app-ability-startOptions.md) + - [@ohos.app.ability.UIAbility](js-apis-app-ability-uiAbility.md) + - [@ohos.app.form.FormExtensionAbility](js-apis-app-form-formExtensionAbility.md) - [@ohos.application.DataShareExtensionAbility](js-apis-application-DataShareExtensionAbility.md) - - [@ohos.application.EnvironmentCallback](js-apis-application-EnvironmentCallback.md) - - [@ohos.application.FormExtension](js-apis-formextension.md) - - [@ohos.application.ServiceExtensionAbility](js-apis-service-extension-ability.md) - - [@ohos.application.StartOptions](js-apis-application-StartOptions.md) - [@ohos.application.StaticSubscriberExtensionAbility](js-apis-application-staticSubscriberExtensionAbility.md) - - [@ohos.application.WindowExtensionAbility](js-apis-application-WindowExtensionAbility.md) - - application/[AbilityContext](js-apis-ability-context.md) - - application/[ApplicationContext](js-apis-application-applicationContext.md) - - application/[AbilityStageContext](js-apis-abilitystagecontext.md) - - application/[Context](js-apis-application-context.md) - - application/[ExtensionContext](js-apis-extension-context.md) - - application/[FormExtensionContext](js-apis-formextensioncontext.md) - - application/[PermissionRequestResult](js-apis-permissionrequestresult.md) - - application/[ServiceExtensionContext](js-apis-service-extension-context.md) - - FA and Stage Models - - [@ohos.ability.dataUriUtils](js-apis-DataUriUtils.md) + - Stage Model (To Be Deprecated Soon) + - [@ohos.application.Ability](js-apis-application-ability.md) + - [@ohos.application.AbilityConstant](js-apis-application-abilityConstant.md) + - [@ohos.application.AbilityLifecycleCallback](js-apis-application-abilityLifecycleCallback.md) + - [@ohos.application.AbilityStage](js-apis-application-abilityStage.md) + - [@ohos.application.context](js-apis-application-context.md) + - [@ohos.application.EnvironmentCallback](js-apis-application-environmentCallback.md) + - [@ohos.application.ExtensionAbility](js-apis-application-extensionAbility.md) + - [@ohos.application.FormExtension](js-apis-application-formExtension.md) + - [@ohos.application.ServiceExtensionAbility](js-apis-application-serviceExtensionAbility.md) + - [@ohos.application.StartOptions](js-apis-application-startOptions.md) + - FA Model + - [@ohos.ability.ability](js-apis-ability-ability.md) + - [@ohos.ability.featureAbility](js-apis-ability-featureAbility.md) + - [@ohos.ability.particleAbility](js-apis-ability-particleAbility.md) + - Both Models (Recommended) + - [@ohos.app.ability.abilityDelegatorRegistry](js-apis-app-ability-abilityDelegatorRegistry.md) + - [@ohos.app.ability.abilityManager](js-apis-app-ability-abilityManager.md) + - [@ohos.app.ability.appManager](js-apis-app-ability-appManager.md) + - [@ohos.app.ability.appRecovery](js-apis-app-ability-appRecovery.md) + - [@ohos.app.ability.Configuration](js-apis-app-ability-configuration.md) + - [@ohos.app.ability.ConfigurationConstant](js-apis-app-ability-configurationConstant.md) + - [@ohos.app.ability.errorManager](js-apis-app-ability-errorManager.md) + - [@ohos.app.ability.missionManager](js-apis-app-ability-missionManager.md) + - [@ohos.app.ability.quickFixManager](js-apis-app-ability-quickFixManager.md) + - [@ohos.app.ability.Want](js-apis-app-ability-want.md) + - [@ohos.app.ability.wantAgent](js-apis-app-ability-wantAgent.md) + - [@ohos.app.ability.wantConstant](js-apis-app-ability-wantConstant.md) + - [@ohos.app.form.formBindingData](js-apis-app-form-formBindingData.md) + - [@ohos.app.form.formHost](js-apis-app-form-formHost.md) + - [@ohos.app.form.formInfo](js-apis-app-form-formInfo.md) + - [@ohos.app.form.formProvider](js-apis-app-form-formProvider.md) + - Both Models (To Be Deprecated Soon) + - [@ohos.ability.dataUriUtils](js-apis-ability-dataUriUtils.md) - [@ohos.ability.errorCode](js-apis-ability-errorCode.md) - [@ohos.ability.wantConstant](js-apis-ability-wantConstant.md) - - [@ohos.application.abilityDelegatorRegistry](js-apis-abilityDelegatorRegistry.md) + - [@ohos.application.abilityDelegatorRegistry](js-apis-application-abilityDelegatorRegistry.md) - [@ohos.application.abilityManager](js-apis-application-abilityManager.md) - - [@ohos.application.appManager](js-apis-appmanager.md) - - [@ohos.application.errorManager](js-apis-errorManager.md) - - [@ohos.application.formBindingData](js-apis-formbindingdata.md) - - [@ohos.application.formError](js-apis-formerror.md) - - [@ohos.application.formHost](js-apis-formhost.md) - - [@ohos.application.formInfo](js-apis-formInfo.md) - - [@ohos.application.formProvider](js-apis-formprovider.md) - - [@ohos.application.missionManager](js-apis-missionManager.md) - - [@ohos.application.quickFixManager](js-apis-application-quickFixManager.md) - - [@ohos.application.Want](js-apis-application-Want.md) - - [@ohos.continuation.continuationManager](js-apis-continuation-continuationManager.md) + - [@ohos.application.appManager](js-apis-application-appManager.md) + - [@ohos.application.Configuration](js-apis-application-configuration.md) + - [@ohos.application.ConfigurationConstant](js-apis-application-configurationConstant.md) + - [@ohos.application.errorManager)](js-apis-application-errorManager.md) + - [@ohos.application.formBindingData](js-apis-application-formBindingData.md) + - [@ohos.application.formError](js-apis-application-formError.md) + - [@ohos.application.formHost](js-apis-application-formHost.md) + - [@ohos.application.formInfo](js-apis-application-formInfo.md) + - [@ohos.application.formProvider](js-apis-application-formProvider.md) + - [@ohos.application.missionManager](js-apis-application-missionManager.md) + - [@ohos.application.Want](js-apis-application-want.md) - [@ohos.wantAgent](js-apis-wantAgent.md) - - application/[abilityDelegator](js-apis-application-abilityDelegator.md) - - application/[abilityDelegatorArgs](js-apis-application-abilityDelegatorArgs.md) - - application/[abilityMonitor](js-apis-application-abilityMonitor.md) - - application/[AbilityRunningInfo](js-apis-abilityrunninginfo.md) - - application/[ExtensionRunningInfo](js-apis-extensionrunninginfo.md) - - application/[MissionSnapshot](js-apis-application-MissionSnapshot.md) - - application/[ProcessRunningInformation](js-apis-processrunninginformation.md) - - application/[shellCmdResult](js-apis-application-shellCmdResult.md) - - continuation/[continuationExtraParams](js-apis-continuation-continuationExtraParams.md) - - continuation/[ContinuationResult](js-apis-continuation-continuationResult.md) + - Dependent Elements and Definitions + - ability + - [abilityResult](js-apis-inner-ability-abilityResult.md) + - [connectOptions](js-apis-inner-ability-connectOptions.md) + - [dataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) + - [dataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md) + - [dataAbilityResult](js-apis-inner-ability-dataAbilityResult.md) + - [startAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) + - [want](js-apis-inner-ability-want.md) + - app + - [appVersionInfo](js-apis-inner-app-appVersionInfo.md) + - [context](js-apis-inner-app-context.md) + - [processInfo](js-apis-inner-app-processInfo.md) + - application + - [AbilityContext](js-apis-ability-context.md) + - [abilityDelegator](js-apis-inner-application-abilityDelegator.md) + - [abilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md) + - [abilityMonitor](js-apis-inner-application-abilityMonitor.md) + - [AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md) + - [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) + - [AbilityStateData](js-apis-inner-application-abilityStateData.md) + - [abilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) + - [ApplicationContext](js-apis-inner-application-applicationContext.md) + - [ApplicationStateObserver](js-apis-inner-application-applicationStateObserver.md) + - [AppStateData](js-apis-inner-application-appStateData.md) + - [BaseContext](js-apis-inner-application-baseContext.md) + - [Context](js-apis-inner-application-context.md) + - [ContinueCallback](js-apis-inner-application-continueCallback.md) + - [ContinueDeviceInfo](js-apis-inner-application-continueDeviceInfo.md) + - [ErrorObserver](js-apis-inner-application-errorObserver.md) + - [ExtensionContext](js-apis-inner-application-extensionContext.md) + - [ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo.md) + - [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) + - [MissionCallbacks](js-apis-inner-application-missionCallbacks.md) + - [MissionDeviceInfo](js-apis-inner-application-missionDeviceInfo.md) + - [MissionInfo](js-apis-inner-application-missionInfo.md) + - [MissionListener](js-apis-inner-application-missionListener.md) + - [MissionParameter](js-apis-inner-application-missionParameter.md) + - [MissionSnapshot](js-apis-inner-application-missionSnapshot.md) + - [PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md) + - [ProcessData](js-apis-inner-application-processData.md) + - [ProcessRunningInfo](js-apis-inner-application-processRunningInfo.md) + - [ProcessRunningInformation](js-apis-inner-application-processRunningInformation.md) + - [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) + - [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) + - [shellCmdResult](js-apis-inner-application-shellCmdResult.md) + - wantAgent + - [triggerInfo](js-apis-inner-wantAgent-triggerInfo.md) + - [wantAgentInfo](js-apis-inner-wantAgent-wantAgentInfo.md) + - Continuation + - [@ohos.continuation.continuationManager (continuationManager)](js-apis-continuation-continuationManager.md) + - continuation + - [continuationExtraParams](js-apis-continuation-continuationExtraParams.md) + - [continuationResult](js-apis-continuation-continuationResult.md) + - Common Event and Notification - [@ohos.events.emitter](js-apis-emitter.md) - [@ohos.notification](js-apis-notification.md) - - application/[EventHub](js-apis-eventhub.md) + - application/[EventHub](js-apis-inner-application-eventHub.md) - Bundle Management - [@ohos.bundle.appControl](js-apis-appControl.md) - [@ohos.bundle.bundleManager](js-apis-bundleManager.md) @@ -69,19 +137,20 @@ - [@ohos.bundle.installer](js-apis-installer.md) - [@ohos.bundle.launcherBundleManager](js-apis-launcherBundleManager.md) - [@ohos.zlib](js-apis-zlib.md) - - bundleManager/[abilityInfo](js-apis-bundleManager-abilityInfo.md) - - bundleManager/[applicationInfo](js-apis-bundleManager-applicationInfo.md) - - bundleManager/[bundleInfo](js-apis-bundleManager-bundleInfo.md) - - bundleManager/[dispatchInfo](js-apis-bundleManager-dispatchInfo.md) - - bundleManager/[elementName](js-apis-bundleManager-elementName.md) - - bundleManager/[extensionAbilityInfo](js-apis-bundleManager-extensionAbilityInfo.md) - - bundleManager/[hapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) - - bundleManager/[launcherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo.md) - - bundleManager/[metadata](js-apis-bundleManager-metadata.md) - - bundleManager/[packInfo](js-apis-bundleManager-packInfo.md) - - bundleManager/[permissionDef](js-apis-bundleManager-permissionDef.md) - - bundleManager/[remoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md) - - bundleManager/[shortcutInfo](js-apis-bundleManager-shortcutInfo.md) + - bundleManager + - [abilityInfo](js-apis-bundleManager-abilityInfo.md) + - [applicationInfo](js-apis-bundleManager-applicationInfo.md) + - [bundleInfo](js-apis-bundleManager-bundleInfo.md) + - [dispatchInfo](js-apis-bundleManager-dispatchInfo.md) + - [elementName](js-apis-bundleManager-elementName.md) + - [extensionAbilityInfo](js-apis-bundleManager-extensionAbilityInfo.md) + - [hapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) + - [launcherAbilityInfo](js-apis-bundleManager-launcherAbilityInfo.md) + - [metadata](js-apis-bundleManager-metadata.md) + - [packInfo](js-apis-bundleManager-packInfo.md) + - [permissionDef](js-apis-bundleManager-permissionDef.md) + - [remoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md) + - [shortcutInfo](js-apis-bundleManager-shortcutInfo.md) - UI Page - [@ohos.animator](js-apis-animator.md) - [@ohos.mediaquery](js-apis-mediaquery.md) @@ -89,16 +158,19 @@ - [@ohos.router](js-apis-router.md) - Graphics - [@ohos.animation.windowAnimationManager](js-apis-windowAnimationManager.md) + - [@ohos.application.WindowExtensionAbility](js-apis-application-windowExtensionAbility.md) - [@ohos.display ](js-apis-display.md) - [@ohos.effectKit](js-apis-effectKit.md) - [@ohos.graphics.colorSpaceManager](js-apis-colorSpaceManager.md) - [@ohos.screen](js-apis-screen.md) - [@ohos.screenshot](js-apis-screenshot.md) - [@ohos.window](js-apis-window.md) - - [webgl](js-apis-webgl.md) - - [webgl2](js-apis-webgl2.md) + - webgl + - [webgl](js-apis-webgl.md) + - [webgl2](js-apis-webgl2.md) - Media - [@ohos.multimedia.audio](js-apis-audio.md) + - [@ohos.multimedia.avsession](js-apis-avsession.md) - [@ohos.multimedia.camera](js-apis-camera.md) - [@ohos.multimedia.image](js-apis-image.md) - [@ohos.multimedia.media](js-apis-media.md) @@ -173,7 +245,7 @@ - Basic Features - [@ohos.accessibility](js-apis-accessibility.md) - [@ohos.accessibility.config](js-apis-accessibility-config.md) - - [@ohos.application.AccessibilityExtensionAbility](js-apis-application-AccessibilityExtensionAbility.md) + - [@ohos.application.AccessibilityExtensionAbility](js-apis-application-accessibilityExtensionAbility.md) - [@ohos.faultLogger](js-apis-faultLogger.md) - [@ohos.hichecker](js-apis-hichecker.md) - [@ohos.hidebug](js-apis-hidebug.md) @@ -181,6 +253,7 @@ - [@ohos.hiSysEvent](js-apis-hisysevent.md) - [@ohos.hiTraceChain](js-apis-hitracechain.md) - [@ohos.hiTraceMeter](js-apis-hitracemeter.md) + - [@ohos.hiviewdfx.hiAppEvent](js-apis-hiviewdfx-hiappevent.md) - [@ohos.inputMethod](js-apis-inputmethod.md) - [@ohos.inputMethodEngine](js-apis-inputmethodengine.md) - [@ohos.inputmethodextensionability](js-apis-inputmethod-extension-ability.md) @@ -190,6 +263,7 @@ - [@ohos.systemTime](js-apis-system-time.md) - [@ohos.systemTimer](js-apis-system-timer.md) - [@ohos.wallpaper](js-apis-wallpaper.md) + - [@ohos.web.webview](js-apis-webview.md) - [console](js-apis-logs.md) - [Timer](js-apis-timer.md) - application/[AccessibilityExtensionContext](js-apis-accessibility-extension-context.md) @@ -249,15 +323,14 @@ - [@ohos.worker](js-apis-worker.md) - [@ohos.xml](js-apis-xml.md) - Test - - [@ohos.application.testRunner](js-apis-testRunner.md) + - [@ohos.application.testRunner](js-apis-application-testRunner.md) - [@ohos.uitest](js-apis-uitest.md) -- APIs No Longer Maintained +- APIs No Longer Maintained - [@ohos.backgroundTaskManager](js-apis-backgroundTaskManager.md) - [@ohos.bundle](js-apis-Bundle.md) - [@ohos.bundle.innerBundleManager](js-apis-Bundle-InnerBundleManager.md) - [@ohos.bundleState](js-apis-deviceUsageStatistics.md) - [@ohos.bytrace](js-apis-bytrace.md) - - [@ohos.commonEvent](js-apis-commonEvent.md) - [@ohos.data.storage](js-apis-data-storage.md) - [@ohos.data.distributedData](js-apis-distributed-data.md) - [@ohos.distributedBundle](js-apis-Bundle-distributedBundle.md) @@ -287,17 +360,17 @@ - [@system.sensor](js-apis-system-sensor.md) - [@system.storage](js-apis-system-storage.md) - [@system.vibrator](js-apis-system-vibrate.md) - - application/[ProcessRunningInfo](js-apis-processrunninginfo.md) - - bundle/[abilityInfo](js-apis-bundle-AbilityInfo.md) - - bundle/[applicationInfo](js-apis-bundle-ApplicationInfo.md) - - bundle/[bundleInfo](js-apis-bundle-BundleInfo.md) - - bundle/[bundleInstaller](js-apis-bundle-BundleInstaller.md) - - bundle/[bundleStatusCallback](js-apis-Bundle-BundleStatusCallback.md) - - bundle/[customizeData](js-apis-bundle-CustomizeData.md) - - bundle/[elementName](js-apis-bundle-ElementName.md) - - bundle/[hapModuleInfo](js-apis-bundle-HapModuleInfo.md) - - bundle/[launcherAbilityInfo](js-apis-bundle-LauncherAbilityInfo.md) - - bundle/[moduleInfo](js-apis-bundle-ModuleInfo.md) - - bundle/[PermissionDef](js-apis-bundle-PermissionDef.md) - - bundle/[remoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md) - - bundle/[shortcutInfo](js-apis-bundle-ShortcutInfo.md) + - bundle + - [abilityInfo](js-apis-bundle-AbilityInfo.md) + - [applicationInfo](js-apis-bundle-ApplicationInfo.md) + - [bundleInfo](js-apis-bundle-BundleInfo.md) + - [bundleInstaller](js-apis-bundle-BundleInstaller.md) + - [bundleStatusCallback](js-apis-Bundle-BundleStatusCallback.md) + - [customizeData](js-apis-bundle-CustomizeData.md) + - [elementName](js-apis-bundle-ElementName.md) + - [hapModuleInfo](js-apis-bundle-HapModuleInfo.md) + - [launcherAbilityInfo](js-apis-bundle-LauncherAbilityInfo.md) + - [moduleInfo](js-apis-bundle-ModuleInfo.md) + - [PermissionDef](js-apis-bundle-PermissionDef.md) + - [remoteAbilityInfo](js-apis-bundle-remoteAbilityInfo.md) + - [shortcutInfo](js-apis-bundle-ShortcutInfo.md) diff --git a/en/application-dev/reference/apis/js-apis-ability-ability.md b/en/application-dev/reference/apis/js-apis-ability-ability.md new file mode 100644 index 0000000000000000000000000000000000000000..37554c90b6a7667815095b91032b72844e4ca04d --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-ability-ability.md @@ -0,0 +1,39 @@ +# Ability + +The **Ability** module provides all level-2 module APIs for developers to export. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the FA model. + +## Modules to Import + +```ts +import ability from '@ohos.ability.ability' +``` + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| DataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | No | Level-2 module **DataAbilityHelper**. | +| PacMap | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#PacMap) | No | Level-2 module **PacMap**.| +| DataAbilityOperation | [DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md) | No | Level-2 module **DataAbilityOperation**.| +| DataAbilityResult | [DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md) | No | Level-2 module **DataAbilityResult**.| +| AbilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | No | Level-2 module **AbilityResult**.| +| ConnectOptions | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No | Level-2 module **ConnectOptions**.| +| StartAbilityParameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | No | Level-2 module **StartAbilityParameter**.| + +**Example** +```ts +import ability from '@ohos.ability.ability'; + +let dataAbilityHelper: ability.DataAbilityHelper; +let pacMap: ability.PacMap; +let dataAbilityOperation: ability.DataAbilityOperation; +let dataAbilityResult: ability.DataAbilityResult; +let abilityResult: ability.AbilityResult; +let connectOptions: ability.ConnectOptions; +let startAbilityParameter: ability.StartAbilityParameter; +``` diff --git a/en/application-dev/reference/apis/js-apis-ability-context.md b/en/application-dev/reference/apis/js-apis-ability-context.md index 40110bb6f928b5d76a9f916340cc7fce07975152..f77fd415a1bb7dd8a7d8968f96dce2718f2873ed 100644 --- a/en/application-dev/reference/apis/js-apis-ability-context.md +++ b/en/application-dev/reference/apis/js-apis-ability-context.md @@ -32,7 +32,7 @@ class MainAbility extends Ability { | -------- | -------- | -------- | -------- | -------- | | abilityInfo | AbilityInfo | Yes| No| Ability information.| | currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.| -| config | [Configuration](js-apis-configuration.md) | Yes| No| Configuration information.| +| config | [Configuration](js-apis-application-configuration.md) | Yes| No| Configuration information.| ## AbilityContext.startAbility @@ -46,15 +46,15 @@ Starts an ability. This API uses an asynchronous callback to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -95,16 +95,16 @@ Starts an ability with the start options specified. This API uses an asynchronou | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -148,8 +148,8 @@ Starts an ability. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | No| Parameters used for starting the ability.| **Return value** @@ -161,8 +161,8 @@ Starts an ability. This API uses a promise to return the result. | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -206,15 +206,15 @@ Starts an ability. This API uses an asynchronous callback to return the result w | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| callback | AsyncCallback<[AbilityResult](js-apis-featureAbility.md#abilityresult)> | Yes| Callback used to return the result.| +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -248,7 +248,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; -Starts an ability with start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. +Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -256,16 +256,16 @@ Starts an ability with start options specified. This API uses an asynchronous ca | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| -| callback | AsyncCallback<[AbilityResult](js-apis-featureAbility.md#abilityresult)> | Yes| Callback used to return the result.| +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | Yes| Parameters used for starting the ability.| +| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -311,22 +311,22 @@ Starts an ability. This API uses a promise to return the result when the ability | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | No| Parameters used for starting the ability.| **Return value** | Type| Description| | -------- | -------- | -| Promise<[AbilityResult](js-apis-featureAbility.md#abilityresult)> | Promise used to return the result.| +| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -373,7 +373,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -381,8 +381,8 @@ Starts an ability. This API uses an asynchronous callback to return the result w | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -418,7 +418,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void; -Starts an ability with start options specified. This API uses an asynchronous callback to return the result when the account of the ability is destroyed. +Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the account of the ability is destroyed. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -430,17 +430,17 @@ Starts an ability with start options specified. This API uses an asynchronous ca | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -479,7 +479,7 @@ Starts an ability with start options specified. This API uses an asynchronous ca startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; -Starts an ability with start options specified. This API uses a promise to return the result when the account of the ability is destroyed. +Starts an ability with the start options specified. This API uses a promise to return the result when the account of the ability is destroyed. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -491,9 +491,9 @@ Starts an ability with start options specified. This API uses a promise to retur | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | No| Parameters used for starting the ability.| **Return value** @@ -505,8 +505,8 @@ Starts an ability with start options specified. This API uses a promise to retur | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -553,15 +553,15 @@ Starts a new Service Extension ability. This API uses an asynchronous callback t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -604,14 +604,14 @@ Starts a new Service Extension ability. This API uses a promise to return the re | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -656,7 +656,7 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -664,8 +664,8 @@ Starts a new Service Extension ability with the account ID specified. This API u | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -711,15 +711,15 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -762,15 +762,15 @@ Stops a Service Extension ability in the same application. This API uses an asyn | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -813,14 +813,14 @@ Stops a Service Extension ability in the same application. This API uses a promi | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -865,7 +865,7 @@ Stops a Service Extension ability in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -873,8 +873,8 @@ Stops a Service Extension ability in the same application with the account ID sp | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -920,15 +920,15 @@ Stops a Service Extension ability in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -976,8 +976,8 @@ Terminates this ability. This API uses an asynchronous callback to return the re | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1013,8 +1013,8 @@ Terminates this ability. This API uses a promise to return the result. | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1042,15 +1042,15 @@ Terminates this ability. This API uses an asynchronous callback to return the ab | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| parameter | [AbilityResult](js-apis-featureAbility.md#abilityresult) | Yes| Information returned to the caller.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1097,7 +1097,7 @@ Terminates this ability. This API uses a promise to return the ability result in | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| parameter | [AbilityResult](js-apis-featureAbility.md#abilityresult) | Yes| Information returned to the caller.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| **Return value** @@ -1109,8 +1109,8 @@ Terminates this ability. This API uses a promise to return the ability result in | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1153,12 +1153,14 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to **System capability**: SystemCapability.Ability.AbilityRuntime.Core +**System API**: This is a system API and cannot be called by third-party applications. + **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | Yes| Parameters for the connection.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Parameters for the connection.| **Return value** @@ -1170,8 +1172,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1214,9 +1216,9 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | Yes| Parameters for the connection.| +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Parameters for the connection.| **Return value** @@ -1228,8 +1230,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1280,13 +1282,13 @@ Disconnects a connection. This API uses a promise to return the result. | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** ```ts - // connection is the return value of connectAbility. + // connection is the return value of connectServiceExtensionAbility. var connection = 1; try { @@ -1326,8 +1328,8 @@ Disconnects a connection. This API uses an asynchronous callback to return the r | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1367,7 +1369,7 @@ Starts an ability in the foreground or background and obtains the caller object | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| +| want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| **Return value** @@ -1458,7 +1460,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -1466,8 +1468,8 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1514,17 +1516,17 @@ Starts an ability with the account ID and start options specified. This API uses | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1574,16 +1576,16 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-application-startOptions.md) | No| Parameters used for starting the ability.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). **Example** @@ -1629,7 +1631,7 @@ Requests permissions from the user by displaying a dialog box. This API uses an | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | permissions | Array<string> | Yes| Permissions to request.| -| callback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback used to return the result.| +| callback | AsyncCallback<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Yes| Callback used to return the result.| **Example** @@ -1660,7 +1662,7 @@ Requests permissions from the user by displaying a dialog box. This API uses a p | Type| Description| | -------- | -------- | -| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result.| +| Promise<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Promise used to return the result.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-DataUriUtils.md b/en/application-dev/reference/apis/js-apis-ability-dataUriUtils.md similarity index 98% rename from en/application-dev/reference/apis/js-apis-DataUriUtils.md rename to en/application-dev/reference/apis/js-apis-ability-dataUriUtils.md index 18cfa0cdc0c54ea8e8aa85fc43fcf61b3d63fc7a..962caaeec04d095e0d11260afeb1fb16e73169d7 100644 --- a/en/application-dev/reference/apis/js-apis-DataUriUtils.md +++ b/en/application-dev/reference/apis/js-apis-ability-dataUriUtils.md @@ -1,4 +1,4 @@ -# DataUriUtils +# @ohos.ability.dataUriUtils The **DataUriUtils** module provides APIs to handle utility classes for objects using the **DataAbilityHelper** schema. You can use the APIs to attach an ID to the end of a given URI and obtain, delete, or update the ID attached to the end of a given URI. @@ -8,7 +8,7 @@ The **DataUriUtils** module provides APIs to handle utility classes for objects ## Modules to Import -```js +```ts import dataUriUtils from '@ohos.ability.dataUriUtils'; ``` @@ -34,7 +34,7 @@ Obtains the ID attached to the end of a given URI. **Example** -```js +```ts dataUriUtils.getId("com.example.dataUriUtils/1221") ``` @@ -63,7 +63,7 @@ Attaches an ID to the end of a given URI. **Example** -```js +```ts var idint = 1122; dataUriUtils.attachId( "com.example.dataUriUtils", @@ -95,12 +95,10 @@ Deletes the ID from the end of a given URI. **Example** -```js +```ts dataUriUtils.deleteId("com.example.dataUriUtils/1221") ``` - - ## dataUriUtils.updateId updateId(uri: string, id: number): string @@ -124,7 +122,7 @@ Updates the ID in a given URI. **Example** -```js +```ts var idint = 1122; dataUriUtils.updateId( "com.example.dataUriUtils", diff --git a/en/application-dev/reference/apis/js-apis-ability-errorCode.md b/en/application-dev/reference/apis/js-apis-ability-errorCode.md index 6a131521d3c447cfb2df65b53a592c5be89678be..c6e16f3f0cbe2bd0dd18dd5ea7fd72c8a0f44fb7 100644 --- a/en/application-dev/reference/apis/js-apis-ability-errorCode.md +++ b/en/application-dev/reference/apis/js-apis-ability-errorCode.md @@ -1,14 +1,14 @@ -# ErrorCode +# @ohos.ability.errorCode -The **ErrorCode** module defines the error codes that can be used when the ability is started. +The **ErrorCode** module defines the error codes that can be used when the ability is started. + + **NOTE** -> **NOTE** -> > The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import -``` +```ts import errorCode from '@ohos.ability.errorCode' ``` diff --git a/en/application-dev/reference/apis/js-apis-featureAbility.md b/en/application-dev/reference/apis/js-apis-ability-featureAbility.md similarity index 79% rename from en/application-dev/reference/apis/js-apis-featureAbility.md rename to en/application-dev/reference/apis/js-apis-ability-featureAbility.md index 66999a98279dc43aa0fee542883a6ed70ad5ee8d..2f1b927b6191b6b87b649f1b4a85067deb705541 100644 --- a/en/application-dev/reference/apis/js-apis-featureAbility.md +++ b/en/application-dev/reference/apis/js-apis-ability-featureAbility.md @@ -1,4 +1,4 @@ -# FeatureAbility +# @ohos.ability.featureAbility The **FeatureAbility** module provides a UI for interacting with users. You can use APIs of this module to start a new ability, obtain the **dataAbilityHelper**, set a Page ability, obtain the window corresponding to this ability, and connect to a Service ability. @@ -13,7 +13,7 @@ APIs of the **FeatureAbility** module can be called only by Page abilities. ## Modules to Import -``` +```ts import featureAbility from '@ohos.ability.featureAbility'; ``` @@ -29,12 +29,12 @@ Starts an ability. This API uses an asynchronous callback to return the result. | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | -------------- | -| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.startAbility( @@ -72,11 +72,11 @@ Starts an ability. This API uses a promise to return the result. | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | -------------- | -| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.startAbility( @@ -121,7 +121,7 @@ Obtains a **dataAbilityHelper** object. **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; var dataAbilityHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -140,12 +140,12 @@ Starts an ability. This API uses an asynchronous callback to return the executio | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | -------------- | -| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| -| callback | AsyncCallback\<[AbilityResult](#abilityresult)> | Yes | Callback used to return the result. | +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| +| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes | Callback used to return the result. | **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.startAbilityForResult( @@ -181,17 +181,17 @@ Starts an ability. This API uses a promise to return the execution result when t | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | ------------- | -| parameter | [StartAbilityParameter](#startabilityparameter) | Yes | Ability to start.| +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| **Return value** | Type | Description | | ---------------------------------------- | ------- | -| Promise\<[AbilityResult](#abilityresult)> | Promised returned with the execution result.| +| Promise\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promised returned with the execution result.| **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.startAbilityForResult( @@ -237,12 +237,12 @@ Destroys this Page ability, with the result code and data sent to the caller. Th | Name | Type | Mandatory | Description | | --------- | ------------------------------- | ---- | -------------- | -| parameter | [AbilityResult](#abilityresult) | Yes | Ability to destroy.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes | Ability to start.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.terminateSelfWithResult( @@ -289,7 +289,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th | Name | Type | Mandatory | Description | | --------- | ------------------------------- | ---- | ------------- | -| parameter | [AbilityResult](#abilityresult) | Yes | Ability to destroy.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes | Ability to start.| **Return value** @@ -299,7 +299,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; import wantConstant from '@ohos.ability.wantConstant'; featureAbility.terminateSelfWithResult( @@ -349,7 +349,7 @@ Checks whether the main window of this ability has the focus. This API uses an a **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.hasWindowFocus((err, data) => { console.info("hasWindowFocus err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); @@ -372,7 +372,7 @@ Checks whether the main window of this ability has the focus. This API uses a pr **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.hasWindowFocus().then((data) => { console.info("hasWindowFocus data: " + JSON.stringify(data)); @@ -391,11 +391,11 @@ Obtains the **Want** object sent from this ability. This API uses an asynchronou | Name | Type | Mandatory | Description | | -------- | ----------------------------- | ---- | --------- | -| callback | AsyncCallback\<[Want](js-apis-application-Want.md)> | Yes | Callback used to return the result.| +| callback | AsyncCallback\<[Want](js-apis-application-want.md)> | Yes | Callback used to return the result.| **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.getWant((err, data) => { console.info("getWant err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); @@ -414,11 +414,11 @@ Obtains the **Want** object sent from this ability. This API uses a promise to r | Type | Description | | ----------------------- | ---------------- | -| Promise\<[Want](js-apis-application-Want.md)> | Promise used to return the result.| +| Promise\<[Want](js-apis-application-want.md)> | Promise used to return the result.| **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.getWant().then((data) => { console.info("getWant data: " + JSON.stringify(data)); @@ -441,7 +441,7 @@ Obtains the application context. **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext() context.getBundleName((err, data) => { @@ -465,7 +465,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.terminateSelf( (err) => { @@ -490,7 +490,7 @@ Destroys this Page ability, with the result code and data sent to the caller. Th **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility'; featureAbility.terminateSelf().then((data) => { console.info("==========================>terminateSelf=======================>"); @@ -509,20 +509,8 @@ Connects this ability to a specific Service ability. This API uses an asynchrono | Name | Type | Mandatory | Description | | ------- | -------------- | ---- | --------------------- | -| request | [Want](js-apis-application-Want.md) | Yes | Service ability to connect.| -| options | [ConnectOptions](#connectoptions) | Yes | Callback used to return the result. | - -## ConnectOptions - -Describes the connection options. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Readable|Writable| Type | Mandatory | Description | -| ------------ | -- | -- | -------- | ---- | ------------------------- | -| onConnect7+ | Yes|No | function | Yes | Callback invoked when the connection is successful. | -| onDisconnect7+ | Yes|No | function | Yes | Callback invoked when the connection fails. | -| onFailed7+ | Yes|No | function | Yes | Callback invoked when **connectAbility** fails to be called.| +| request | [Want](js-apis-application-want.md) | Yes | Service ability to connect.| +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes | Callback used to return the result. | **Return value** @@ -532,7 +520,7 @@ Describes the connection options. **Example** -```javascript +```ts import rpc from '@ohos.rpc'; import featureAbility from '@ohos.ability.featureAbility'; function onConnectCallback(element, remote){ @@ -575,7 +563,7 @@ Disconnects this ability from a specific Service ability. This API uses an async **Example** -```javascript +```ts import rpc from '@ohos.rpc'; import featureAbility from '@ohos.ability.featureAbility'; function onConnectCallback(element, remote){ @@ -627,7 +615,7 @@ Disconnects this ability from a specific Service ability. This API uses a promis **Example** -```javascript +```ts import rpc from '@ohos.rpc'; import featureAbility from '@ohos.ability.featureAbility'; function onConnectCallback(element, remote){ @@ -675,7 +663,7 @@ Obtains the window corresponding to this ability. This API uses an asynchronous **Example** -```javascript +```ts featureAbility.getWindow((err, data) => { console.info("getWindow err: " + JSON.stringify(err) + "data: " + typeof(data)); }); @@ -697,143 +685,12 @@ Obtains the window corresponding to this ability. This API uses a promise to ret **Example** -```javascript +```ts featureAbility.getWindow().then((data) => { console.info("getWindow data: " + typeof(data)); }); ``` -## ConnectOptions.onConnect7+ - -onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void; - -Callback invoked when the connection is successful. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ----------------- | ---- | -------- | -| elementName | ElementName | Yes | Element name. | -| remote | rpc.IRemoteObject | Yes | RPC remote object.| - -**Example** - -```javascript -import rpc from '@ohos.rpc'; -import featureAbility from '@ohos.ability.featureAbility'; -function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); -} -function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) -} -function onFailedCallback(code){ - console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) -} -var connectId = featureAbility.connectAbility( - { - deviceId: "", - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, -); -``` - -## ConnectOptions.onDisconnect7+ - -onDisconnect(elementName: ElementName): void; - -Callback invoked when the connection fails. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| ----------- | ----------- | ---- | ---- | -| elementName | ElementName | Yes | Element name.| - -**Example** - -```javascript -import rpc from '@ohos.rpc'; -import featureAbility from '@ohos.ability.featureAbility'; -function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); -} -function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) -} -function onFailedCallback(code){ - console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) -} -var connectId = featureAbility.connectAbility( - { - deviceId: "", - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, -); -``` - -## ConnectOptions.onFailed7+ - -onFailed(code: number): void; - -Callback invoked when **connectAbility** fails to be called. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name | Type | Mandatory | Description | -| ---- | ------ | ---- | --------- | -| code | number | Yes | Number type.| - -**Example** - -```javascript -import rpc from '@ohos.rpc'; -import featureAbility from '@ohos.ability.featureAbility'; -function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); -} -function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) -} -function onFailedCallback(code){ - console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) -} -var connectId = featureAbility.connectAbility( - { - deviceId: "", - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, -); -``` - - - - - ## AbilityWindowConfiguration The value is obtained through the **featureAbility.AbilityWindowConfiguration** API. @@ -902,26 +759,6 @@ Enumerates operation types of the Data ability. | TYPE_DELETE7+ | 3 | Deletion operation.| | TYPE_ASSERT7+ | 4 | Assert operation.| - - -## AbilityResult - -**System capability**: SystemCapability.Ability.AbilityBase - -| Name | Type | Readable| Writable | Mandatory | Description | -| --------------- |-------- | ------ | ------------- | ---- | ------------------------------------- | -| resultCode7+| number| Yes | No | Yes | Result code returned after the ability is destroyed. The feature for defining error-specific result codes is coming soon.| -| want7+ | [Want](js-apis-application-Want.md)| Yes | No| No | Data returned after the ability is destroyed. You can define the data to be returned. This parameter can be **null**. | - -## StartAbilityParameter - -**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel - -| Name | Type | Readable| Writable | Mandatory | Description | -| ------------------- | -------- | -------------------- | ---- | -------------------------------------- | -| want | [Want](js-apis-application-Want.md)| Yes | No | Yes | Information about the ability to start. | -| abilityStartSetting | {[key: string]: any} | Yes |No | No | Special attribute of the ability to start. This attribute can be passed in the method call.| - ## flags **System capability**: SystemCapability.Ability.AbilityBase diff --git a/en/application-dev/reference/apis/js-apis-particleAbility.md b/en/application-dev/reference/apis/js-apis-ability-particleAbility.md similarity index 75% rename from en/application-dev/reference/apis/js-apis-particleAbility.md rename to en/application-dev/reference/apis/js-apis-ability-particleAbility.md index 75b6378962fb1f3c25bcf7e12a0a2df20a151628..46355b926228755520d3d215d4275af03ecd88bc 100644 --- a/en/application-dev/reference/apis/js-apis-particleAbility.md +++ b/en/application-dev/reference/apis/js-apis-ability-particleAbility.md @@ -1,4 +1,4 @@ -# particleAbility +# @ohos.ability.particleAbility The **particleAbility** module provides APIs for Service abilities. You can use the APIs to start and terminate a Particle ability, obtain a **dataAbilityHelper** object, connect the current ability to a specific Service ability, and disconnect the current ability from a specific Service ability. @@ -13,7 +13,7 @@ The ParticleAbility module is used to perform operations on abilities of the Dat ## Modules to Import -```js +```ts import particleAbility from '@ohos.ability.particleAbility' ``` @@ -27,19 +27,19 @@ Starts a Particle ability. This API uses an asynchronous callback to return the **Parameters** - | Name | Type | Mandatory| Description | | --------- | ----------------------------------------------- | ---- | ----------------- | -| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes | Ability to start.| +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility' import wantConstant from '@ohos.ability.wantConstant' + particleAbility.startAbility( - { + { want: { action: "action.system.home", @@ -49,17 +49,15 @@ particleAbility.startAbility( deviceId: "", bundleName: "com.example.Data", abilityName: "com.example.Data.MainAbility", - uri:"" + uri: "" }, }, (error, result) => { - console.log('particleAbility startAbility errCode:' + error + 'result:' + result) + console.log('particleAbility startAbility errCode:' + error + 'result:' + result) }, ) ``` - - ## particleAbility.startAbility startAbility(parameter: StartAbilityParameter): Promise\; @@ -70,10 +68,9 @@ Starts a Particle ability. This API uses a promise to return the result. **Parameters** - | Name | Type | Mandatory| Description | | --------- | ----------------------------------------------- | ---- | ----------------- | -| parameter | [StartAbilityParameter](js-apis-featureAbility.md#startabilityparameter) | Yes | Ability to start.| +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | Yes | Ability to start.| **Return value** @@ -83,11 +80,12 @@ Starts a Particle ability. This API uses a promise to return the result. **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility' import wantConstant from '@ohos.ability.wantConstant' + particleAbility.startAbility( - { + { want: { action: "action.system.home", @@ -97,7 +95,7 @@ particleAbility.startAbility( deviceId: "", bundleName: "com.example.Data", abilityName: "com.example. Data.MainAbility", - uri:"" + uri: "" }, }, ).then((data) => { @@ -105,8 +103,6 @@ particleAbility.startAbility( }); ``` - - ## particleAbility.terminateSelf terminateSelf(callback: AsyncCallback\): void @@ -123,17 +119,16 @@ Terminates this Particle ability. This API uses an asynchronous callback to retu **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility' + particleAbility.terminateSelf( (error, result) => { - console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result) + console.log('particleAbility terminateSelf errCode:' + error + 'result:' + result) } ) ``` - - ## particleAbility.terminateSelf terminateSelf(): Promise\ @@ -150,8 +145,9 @@ Terminates this Particle ability. This API uses a promise to return the result. **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility' + particleAbility.terminateSelf().then((data) => { console.info("particleAbility terminateSelf"); }); @@ -181,8 +177,9 @@ Obtains a **dataAbilityHelper** object. **Example** -```js -import particleAbility from '@ohos.ability.particleAbility' +```ts +import particleAbility from '@ohos.ability.particleAbility' + var uri = ""; particleAbility.acquireDataAbilityHelper(uri) ``` @@ -208,7 +205,7 @@ Requests a continuous task from the system. This API uses an asynchronous callba **Example** -```js +```ts import notification from '@ohos.notification'; import particleAbility from '@ohos.ability.particleAbility'; import wantAgent from '@ohos.wantAgent'; @@ -277,7 +274,7 @@ Requests a continuous task from the system. This API uses a promise to return th **Example** -```js +```ts import notification from '@ohos.notification'; import particleAbility from '@ohos.ability.particleAbility'; import wantAgent from '@ohos.wantAgent'; @@ -333,7 +330,7 @@ Requests to cancel a continuous task from the system. This API uses an asynchron **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility'; function callback(err, data) { @@ -364,7 +361,7 @@ Requests a continuous task from the system. This API uses a promise to return th **Example** -```js +```ts import particleAbility from '@ohos.ability.particleAbility'; particleAbility.cancelBackgroundRunning().then(() => { @@ -375,7 +372,6 @@ particleAbility.cancelBackgroundRunning().then(() => { ``` - ## particleAbility.connectAbility connectAbility(request: Want, options:ConnectOptions): number @@ -388,7 +384,7 @@ Connects this ability to a specific Service ability. This API uses a callback to | Name | Type | Mandatory| Description | | ------- | -------------- | ---- | ---------------------------- | -| request | [Want](js-apis-application-Want.md) | Yes | Service ability to connect.| +| request | [Want](js-apis-application-want.md) | Yes | Service ability to connect.| | options | ConnectOptions | Yes | Callback used to return the result. | @@ -396,46 +392,48 @@ ConnectOptions **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name | Readable/Writable| Type | Mandatory | Description | -| ------------ | ---- | -------- | ---- | ------------------------- | -| onConnect | Read only | function | Yes | Callback invoked when the connection is successful. | -| onDisconnect | Read only | function | Yes | Callback invoked when the connection fails. | -| onFailed | Read only | function | Yes | Callback invoked when **connectAbility** fails to be called.| +| Name | Type | Mandatory | Description | +| ------------ | -------- | ---- | ------------------------- | +| onConnect | function | Yes | Callback invoked when the connection is successful. | +| onDisconnect | function | Yes | Callback invoked when the connection fails. | +| onFailed | function | Yes | Callback invoked when **connectAbility** fails to be called.| **Example** -```js - import rpc from '@ohos.rpc' - function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); - } - function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) - } - function onFailedCallback(code){ - console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) - } - var connId = particleAbility.connectAbility( - { - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, - ); - - particleAbility.disconnectAbility(connId).then((data)=>{ - console.log( " data: " + data); - }).catch((error)=>{ - console.log('particleAbilityTest result errCode : ' + error.code ) - }); - +```ts +import rpc from '@ohos.rpc' -``` +function onConnectCallback(element, remote) { + console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); +} + +function onDisconnectCallback(element) { + console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) +} + +function onFailedCallback(code) { + console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) +} + +var connId = particleAbility.connectAbility( + { + bundleName: "com.ix.ServiceAbility", + abilityName: "ServiceAbilityA", + }, + { + onConnect: onConnectCallback, + onDisconnect: onDisconnectCallback, + onFailed: onFailedCallback, + }, +); +particleAbility.disconnectAbility(connId).then((data) => { + console.log(" data: " + data); +}).catch((error) => { + console.log('particleAbilityTest result errCode : ' + error.code) +}); + +``` ## particleAbility.disconnectAbility @@ -453,34 +451,37 @@ Disconnects this ability from the Service ability. This API uses a callback to r **Example** -```js +```ts import rpc from '@ohos.rpc' - function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); - } - function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) - } - function onFailedCallback(code){ - console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) - } - var connId = particleAbility.connectAbility( - { - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, - ); - var result = particleAbility.disconnectAbility(connId).then((data)=>{ - console.log( " data: " + data); - }).catch((error)=>{ - console.log('particleAbilityTest result errCode : ' + error.code ) - }); +function onConnectCallback(element, remote) { + console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); +} + +function onDisconnectCallback(element) { + console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) +} + +function onFailedCallback(code) { + console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) +} + +var connId = particleAbility.connectAbility( + { + bundleName: "com.ix.ServiceAbility", + abilityName: "ServiceAbilityA", + }, + { + onConnect: onConnectCallback, + onDisconnect: onDisconnectCallback, + onFailed: onFailedCallback, + }, +); +var result = particleAbility.disconnectAbility(connId).then((data) => { + console.log(" data: " + data); +}).catch((error) => { + console.log('particleAbilityTest result errCode : ' + error.code) +}); ``` @@ -500,34 +501,38 @@ Disconnects this ability from the Service ability. This API uses a promise to re **Example** -```js +```ts import rpc from '@ohos.rpc' -function onConnectCallback(element, remote){ - console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); - } - function onDisconnectCallback(element){ - console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) - } - function onFailedCallback(code){ - console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) - } - var connId = particleAbility.connectAbility( - { - bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, - ); - - particleAbility.disconnectAbility(connId).then((data)=>{ - console.log( " data: " + data); - }).catch((error)=>{ - console.log('particleAbilityTest result errCode : ' + error.code ) - }); + +function onConnectCallback(element, remote) { + console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); +} + +function onDisconnectCallback(element) { + console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) +} + +function onFailedCallback(code) { + console.log('particleAbilityTest ConnectAbility onFailed errCode : ' + code) +} + +var connId = particleAbility.connectAbility( + { + bundleName: "com.ix.ServiceAbility", + abilityName: "ServiceAbilityA", + }, + { + onConnect: onConnectCallback, + onDisconnect: onDisconnectCallback, + onFailed: onFailedCallback, + }, +); + +particleAbility.disconnectAbility(connId).then((data) => { + console.log(" data: " + data); +}).catch((error) => { + console.log('particleAbilityTest result errCode : ' + error.code) +}); ``` diff --git a/en/application-dev/reference/apis/js-apis-ability-wantConstant.md b/en/application-dev/reference/apis/js-apis-ability-wantConstant.md index 4b1a66f071f464d6662d8429606c48aa025e8ef6..30fb8b3b970b22513f2dd520d43a11b76f66e47d 100644 --- a/en/application-dev/reference/apis/js-apis-ability-wantConstant.md +++ b/en/application-dev/reference/apis/js-apis-ability-wantConstant.md @@ -1,14 +1,14 @@ -# wantConstant +# @ohos.ability.wantConstant The **wantConstant** module provides the actions, entities, and flags used in **Want** objects. > **NOTE** > -> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported since API version 6 and deprecated since API version 9. You are advised to use [@ohos.app.ability.wantConstant](js-apis-app-ability-wantConstant.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import -```js +```ts import wantConstant from '@ohos.ability.wantConstant'; ``` @@ -46,6 +46,7 @@ Enumerates the action constants of the **Want** object. | ACTION_FILE_SELECT7+ | ohos.action.fileSelect | Action of selecting a file. | | PARAMS_STREAM7+ | ability.params.stream | URI of the data stream associated with the target when the data is sent. | | ACTION_APP_ACCOUNT_OAUTH 8+ | ohos.account.appAccount.action.oauth | Action of providing the OAuth service. | +| ACTION_APP_ACCOUNT_AUTH 9+ | account.appAccount.action.auth | Action of providing the authentication service. | | ACTION_MARKET_DOWNLOAD 9+ | ohos.want.action.marketDownload | Action of downloading an application from the application market.
**System API**: This is a system API and cannot be called by third-party applications. | | ACTION_MARKET_CROWDTEST 9+ | ohos.want.action.marketCrowdTest | Action of crowdtesting an application from the application market.
**System API**: This is a system API and cannot be called by third-party applications. | | DLP_PARAMS_SANDBOX9+ |ohos.dlp.params.sandbox | Action of obtaining the sandbox flag.
**System API**: This is a system API and cannot be called by third-party applications. | diff --git a/en/application-dev/reference/apis/js-apis-app-ability-ability.md b/en/application-dev/reference/apis/js-apis-app-ability-ability.md new file mode 100644 index 0000000000000000000000000000000000000000..59e1e229f2e8396ae11584dee80a439ea74fdf6b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-ability.md @@ -0,0 +1,62 @@ +# @ohos.app.ability.Ability + +The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import Ability from '@ohos.app.ability.Ability'; +``` + +## Ability.onConfigurationUpdate + +onConfigurationUpdate(newConfig: Configuration): void; + +Called when the configuration of the environment where the ability is running is updated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | newConfig | [Configuration](js-apis-app-ability-configuration.md) | Yes| New configuration.| + +**Example** + + ```ts + class myAbility extends Ability { + onConfigurationUpdate(config) { + console.log('onConfigurationUpdate, config:' + JSON.stringify(config)); + } + } + ``` + +## Ability.onMemoryLevel + +onMemoryLevel(level: AbilityConstant.MemoryLevel): void; + +Called when the system has decided to adjust the memory level. For example, this API can be used when there is not enough memory to run as many background processes as possible. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | level | [AbilityConstant.MemoryLevel](js-apis-app-ability-abilityConstant.md#abilityconstantmemorylevel) | Yes| Memory level that indicates the memory usage status. When the specified memory level is reached, a callback will be invoked and the system will start adjustment.| + +**Example** + + ```ts + class myAbility extends Ability { + onMemoryLevel(level) { + console.log('onMemoryLevel, level:' + JSON.stringify(level)); + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md new file mode 100644 index 0000000000000000000000000000000000000000..5d6c93e6e2b45b33ca9cb7ec9976435c17fd2a56 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md @@ -0,0 +1,117 @@ +# @ohos.app.ability.AbilityConstant + +The **AbilityConstant** module provides ability launch parameters. + +The parameters include the initial launch reasons, reasons for the last exit, and ability continuation results. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import AbilityConstant from '@ohos.app.ability.AbilityConstant'; +``` + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| launchReason | LaunchReason| Yes| Yes| Ability launch reason.| +| lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.| + +## AbilityConstant.LaunchReason + +Enumerates the ability launch reasons. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| UNKNOWN | 0 | Unknown reason.| +| START_ABILITY | 1 | Ability startup.| +| CALL | 2 | Call.| +| CONTINUATION | 3 | Ability continuation.| +| APP_RECOVERY | 4 | Application recovery.| + + +## AbilityConstant.LastExitReason + +Enumerates reasons for the last exit. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| UNKNOWN | 0 | Unknown reason.| +| ABILITY_NOT_RESPONDING | 1 | The ability does not respond.| +| NORMAL | 2 | Normal status.| + + +## AbilityConstant.OnContinueResult + +Enumerates ability continuation results. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| AGREE | 0 | Continuation agreed.| +| REJECT | 1 | Continuation denied.| +| MISMATCH | 2 | Mismatch.| + +## AbilityConstant.WindowMode + +Enumerates the window modes in which an ability can be displayed at startup. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value| Description | +| --- | --- | --- | +| WINDOW_MODE_UNDEFINED | 0 | Undefined window mode. | +| WINDOW_MODE_FULLSCREEN | 1 | The ability is displayed in full screen. | +| WINDOW_MODE_SPLIT_PRIMARY | 100 | The ability is displayed in the primary window in split-screen mode. | +| WINDOW_MODE_SPLIT_SECONDARY | 101 | The ability is displayed in the secondary window in split-screen mode. | +| WINDOW_MODE_FLOATING | 102 | The ability is displayed in a floating window.| + +## AbilityConstant.MemoryLevel + +Enumerates the memory levels. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value| Description | +| --- | --- | --- | +| MEMORY_LEVEL_MODERATE | 0 | Moderate memory usage. | +| MEMORY_LEVEL_LOW | 1 | Low memory usage. | +| MEMORY_LEVEL_CRITICAL | 2 | High memory usage. | + +## AbilityConstant.OnSaveResult + +Enumerates the result types for the operation of saving application data. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| ALL_AGREE | 0 | Agreed to save the status.| +| CONTINUATION_REJECT | 1 | Rejected to save the status in continuation.| +| CONTINUATION_MISMATCH | 2 | Continuation mismatch.| +| RECOVERY_AGREE | 3 | Agreed to restore the saved status.| +| RECOVERY_REJECT | 4 | Rejected to restore the saved state.| +| ALL_REJECT | 5 | Rejected to save the status.| + +## AbilityConstant.StateType + +Enumerates the scenarios for saving application data. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| CONTINUATION | 0 | Saving the status in continuation.| +| APP_RECOVERY | 1 | Saving the status in application recovery.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md new file mode 100644 index 0000000000000000000000000000000000000000..78fb6181c03380c6d69eb31318d1d459dec307fe --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityDelegatorRegistry.md @@ -0,0 +1,71 @@ +# @ohos.app.ability.abilityDelegatorRegistry + +The **AbilityDelegatorRegistry** module provides APIs for storing the global registers of the registered **AbilityDelegator** and **AbilityDelegatorArgs** objects. You can use the APIs to obtain the **AbilityDelegator** and **AbilityDelegatorArgs** objects of an application. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry' +``` + +## AbilityLifecycleState + +Enumerates the ability lifecycle states. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ------------- | ---- | --------------------------- | +| UNINITIALIZED | 0 | The ability is in an invalid state. | +| CREATE | 1 | The ability is created.| +| FOREGROUND | 2 | The ability is running in the foreground. | +| BACKGROUND | 3 | The ability is running in the background. | +| DESTROY | 4 | The ability is destroyed.| + +## AbilityDelegatorRegistry.getAbilityDelegator + +getAbilityDelegator(): AbilityDelegator + +Obtains the **AbilityDelegator** object of the application. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) | [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) object, which can be used to schedule functions related to the test framework.| + +**Example** + +```ts +var abilityDelegator; +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +``` + +## AbilityDelegatorRegistry.getArguments + +getArguments(): AbilityDelegatorArgs + +Obtains the **AbilityDelegatorArgs** object of the application. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md) | [AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md) object, which can be used to obtain test parameters.| + +**Example** + +```ts +var args = AbilityDelegatorRegistry.getArguments(); +console.info("getArguments bundleName:" + args.bundleName); +console.info("getArguments testCaseNames:" + args.testCaseNames); +console.info("getArguments testRunnerClassName:" + args.testRunnerClassName); +``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md new file mode 100644 index 0000000000000000000000000000000000000000..f3e6e08396d0b819efd6acda39218af497e83ef9 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityLifecycleCallback.md @@ -0,0 +1,211 @@ +# @ohos.app.ability.abilityLifecycleCallback + +The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + + +## Modules to Import + +```ts +import AbilityLifecycleCallback from "@ohos.app.ability.AbilityLifecycleCallback"; +``` + + +## AbilityLifecycleCallback.onAbilityCreate + +onAbilityCreate(ability: UIAbility): void; + +Called when an ability is created. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + + +## AbilityLifecycleCallback.onWindowStageCreate + +onWindowStageCreate(ability: UIAbility, windowStage: window.WindowStage): void; + +Called when the window stage of an ability is created. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onWindowStageActive + +onWindowStageActive(ability: UIAbility, windowStage: window.WindowStage): void; + +Called when the window stage of an ability gains focus. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onWindowStageInactive + +onWindowStageInactive(ability: UIAbility, windowStage: window.WindowStage): void; + +Called when the window stage of an ability loses focus. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onWindowStageDestroy + +onWindowStageDestroy(ability: UIAbility, windowStage: window.WindowStage): void; + +Called when the window stage of an ability is destroyed. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + + +## AbilityLifecycleCallback.onAbilityDestroy + +onAbilityDestroy(ability: UIAbility): void; + +Called when an ability is destroyed. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + + +## AbilityLifecycleCallback.onAbilityForeground + +onAbilityForeground(ability: UIAbility): void; + +Called when an ability is switched from the background to the foreground. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + + +## AbilityLifecycleCallback.onAbilityBackground + +onAbilityBackground(ability: UIAbility): void; + +Called when an ability is switched from the foreground to the background. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + + +## AbilityLifecycleCallback.onAbilityContinue + +onAbilityContinue(ability: UIAbility): void; + +Called when an ability is continued on another device. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | ability | [UIAbility](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| + +**Example** + + + ```ts + import UIAbility from "@ohos.app.ability.UIAbility"; + + export default class MyAbility extends UIAbility { + onCreate() { + console.log("MyAbility onCreate") + let AbilityLifecycleCallback = { + onAbilityCreate(ability){ + console.log("AbilityLifecycleCallback onAbilityCreate ability:" + JSON.stringify(ability)); + }, + onWindowStageCreate(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageCreate ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageCreate windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageActive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageActive ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageActive windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageInactive(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageInactive ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageInactive windowStage:" + JSON.stringify(windowStage)); + }, + onWindowStageDestroy(ability, windowStage){ + console.log("AbilityLifecycleCallback onWindowStageDestroy ability:" + JSON.stringify(ability)); + console.log("AbilityLifecycleCallback onWindowStageDestroy windowStage:" + JSON.stringify(windowStage)); + }, + 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. Obtain applicationContext through the context attribute. + let applicationContext = this.context.getApplicationContext(); + // 2. Use applicationContext to register a listener for the ability lifecycle in the application. + let lifecycleid = applicationContext.on("abilityLifecycle", AbilityLifecycleCallback); + console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); + }, + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + applicationContext.off("abilityLifecycle", lifecycleid, (error, data) => { + console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); + }); + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityManager.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityManager.md new file mode 100644 index 0000000000000000000000000000000000000000..0a191c0038f3a5811018346ffe779dc558b3ad20 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityManager.md @@ -0,0 +1,308 @@ +# @ohos.app.ability.abilityManager + +The **AbilityManager** module provides APIs for obtaining, adding, and modifying ability running information and state information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are system APIs and cannot be called by third-party applications. + +## Modules to Import + +```ts +import AbilityManager from '@ohos.app.ability.abilityManager' +``` + +## AbilityState + +Enumerates the ability states. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name| Value| Description| +| -------- | -------- | -------- | +| INITIAL | 0 | The ability is in the initial state.| +| FOREGROUND | 9 | The ability is in the foreground state. | +| BACKGROUND | 10 | The ability is in the background state. | +| FOREGROUNDING | 11 | The ability is in the foregrounding state. | +| BACKGROUNDING | 12 | The ability is in the backgrounding state. | + +## updateConfiguration + +updateConfiguration(config: Configuration, callback: AsyncCallback\): void + +Updates the configuration. This API uses an asynchronous callback to return the result. + +**Permission required**: ohos.permission.UPDATE_CONFIGURATION + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration.| +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +var config = { + language: 'chinese' +} + +try { + abilitymanager.updateConfiguration(config, () => { + console.log('------------ updateConfiguration -----------'); + }) +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## updateConfiguration + +updateConfiguration(config: Configuration): Promise\ + +Updates the configuration. This API uses a promise to return the result. + +**Permission required**: ohos.permission.UPDATE_CONFIGURATION + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +var config = { + language: 'chinese' +} + +try { + abilitymanager.updateConfiguration(config).then(() => { + console.log('updateConfiguration success'); + }).catch((err) => { + console.log('updateConfiguration fail'); + }) +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getAbilityRunningInfos + +getAbilityRunningInfos(callback: AsyncCallback\>): void + +Obtains the ability running information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback\> | Yes | Callback used to return the result. | + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +try { + abilitymanager.getAbilityRunningInfos((err,data) => { + console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); + }); +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getAbilityRunningInfos + +getAbilityRunningInfos(): Promise\> + +Obtains the ability running information. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\> | Promise used to return the result.| + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +try { + abilitymanager.getAbilityRunningInfos().then((data) => { + console.log("getAbilityRunningInfos data: " + JSON.stringify(data)) + }).catch((err) => { + console.log("getAbilityRunningInfos err: " + err) + }); +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getExtensionRunningInfos + +getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\>): void + +Obtains the extension running information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| upperLimit | number | Yes| Maximum number of messages that can be obtained.| +| callback | AsyncCallback\> | Yes | Callback used to return the result. | + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +var upperLimit = 0; + +try { + abilitymanager.getExtensionRunningInfos(upperLimit, (err,data) => { + console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); + }); +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getExtensionRunningInfos + +getExtensionRunningInfos(upperLimit: number): Promise\> + +Obtains the extension running information. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| upperLimit | number | Yes| Maximum number of messages that can be obtained.| + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\> | Promise used to return the result.| + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +var upperLimit = 0; + +try { + abilitymanager.getExtensionRunningInfos(upperLimit).then((data) => { + console.log("getAbilityRunningInfos data: " + JSON.stringify(data)); + }).catch((err) => { + console.log("getAbilityRunningInfos err: " + err); + }) +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getTopAbility9+ + +getTopAbility(callback: AsyncCallback\): void; + +Obtains the top ability, which is the ability that has the window focus. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| --------- | ---------------------------------------- | ---- | -------------- | +| callback | AsyncCallback\ | Yes | Callback used to return the result. | + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +try { + abilitymanager.getTopAbility((err,data) => { + console.log("getTopAbility err: " + err + " data: " + JSON.stringify(data)); + }); +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` + +## getTopAbility + +getTopAbility(): Promise\; + +Obtains the top ability, which is the ability that has the window focus. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type | Description | +| ---------------------------------------- | ------- | +| Promise\| Promise used to return the result.| + +**Example** + +```ts +import abilitymanager from '@ohos.app.ability.abilityManager'; + +try { + abilitymanager.getTopAbility().then((data) => { + console.log("getTopAbility data: " + JSON.stringify(data)); + }).catch((err) => { + console.log("getTopAbility err: " + err); + }) +} catch (paramError) { + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-abilityStage.md b/en/application-dev/reference/apis/js-apis-app-ability-abilityStage.md new file mode 100644 index 0000000000000000000000000000000000000000..b1226842409c7d03c82d25d33319042a716b9d86 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-abilityStage.md @@ -0,0 +1,127 @@ +# @ohos.app.ability.AbilityStage + +**AbilityStage** is a runtime class for HAP files. + +**AbilityStage** notifies you of when you can perform HAP initialization such as resource pre-loading and thread creation during the HAP loading. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import AbilityStage from '@ohos.app.ability.AbilityStage'; +``` + +## AbilityStage.onCreate + +onCreate(): void + +Called when the application is created. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Example** + + ```ts + class MyAbilityStage extends AbilityStage { + onCreate() { + console.log("MyAbilityStage.onCreate is called") + } + } + ``` + + +## AbilityStage.onAcceptWant + +onAcceptWant(want: Want): string; + +Called when a specified ability is started. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | string | Returns an ability ID. If this ability has been started, no new instance is created and the ability is placed at the top of the stack. Otherwise, a new instance is created and started.| + +**Example** + + ```ts + class MyAbilityStage extends AbilityStage { + onAcceptWant(want) { + console.log("MyAbilityStage.onAcceptWant called"); + return "com.example.test"; + } + } + ``` + + +## AbilityStage.onConfigurationUpdate + +onConfigurationUpdate(newConfig: Configuration): void; + +Called when the global configuration is updated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | newConfig | [Configuration](js-apis-app-ability-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.| + +**Example** + + ```ts + class MyAbilityStage extends AbilityStage { + onConfigurationUpdate(config) { + console.log('onConfigurationUpdate, language:' + config.language); + } + } + ``` + +## AbilityStage.onMemoryLevel + +onMemoryLevel(level: AbilityConstant.MemoryLevel): void; + +Called when the system has decided to adjust the memory level. For example, this API can be used when there is not enough memory to run as many background processes as possible. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | level | [AbilityConstant.MemoryLevel](js-apis-app-ability-abilityConstant.md#abilityconstantmemorylevel) | Yes| Memory level that indicates the memory usage status. When the specified memory level is reached, a callback will be invoked and the system will start adjustment.| + +**Example** + + ```ts + class MyAbilityStage extends AbilityStage { + onMemoryLevel(level) { + console.log('onMemoryLevel, level:' + JSON.stringify(level)); + } + } + ``` + +## AbilityStage.context + +context: AbilityStageContext; + +Describes the configuration information about the context. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Description | +| ----------- | --------------------------- | ------------------------------------------------------------ | +| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | Called when initialization is performed during ability startup.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-appManager.md b/en/application-dev/reference/apis/js-apis-app-ability-appManager.md new file mode 100644 index 0000000000000000000000000000000000000000..b6fae35d6d03575442b1223c63cbcd4150773bb9 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-appManager.md @@ -0,0 +1,753 @@ +# @ohos.app.ability.appManager + +The **appManager** module implements application management. You can use the APIs of this module to query whether the application is undergoing a stability test, whether the application is running on a RAM constrained device, the memory size of the application, and information about the running process. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import appManager from '@ohos.app.ability.appManager'; +``` + +## appManager.isRunningInStabilityTest9+ + +static isRunningInStabilityTest(callback: AsyncCallback<boolean>): void + +Checks whether this application is undergoing a stability test. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + import app from '@ohos.application.appManager'; + app.isRunningInStabilityTest((err, flag) => { + console.log('startAbility result:' + JSON.stringify(err)); + }) + ``` + + +## appManager.isRunningInStabilityTest9+ + +static isRunningInStabilityTest(): Promise<boolean> + +Checks whether this application is undergoing a stability test. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + import app from '@ohos.application.appManager'; + app.isRunningInStabilityTest().then((flag) => { + console.log('success:' + JSON.stringify(flag)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + + +## appManager.isRamConstrainedDevice + +isRamConstrainedDevice(): Promise\; + +Checks whether this application is running on a RAM constrained device. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + app.isRamConstrainedDevice().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.isRamConstrainedDevice + +isRamConstrainedDevice(callback: AsyncCallback\): void; + +Checks whether this application is running on a RAM constrained device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + app.isRamConstrainedDevice((err, data) => { + console.log('startAbility result failed:' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.getAppMemorySize + +getAppMemorySize(): Promise\; + +Obtains the memory size of this application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<number> | Size of the application memory.| + +**Example** + + ```ts + app.getAppMemorySize().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getAppMemorySize + +getAppMemorySize(callback: AsyncCallback\): void; + +Obtains the memory size of this application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<number> | Yes| Size of the application memory.| + +**Example** + + ```ts + app.getAppMemorySize((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(): Promise\>; + +Obtains information about the running processes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Promise used to return the process information.| + +**Example** + + ```ts + app.getProcessRunningInformation().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(callback: AsyncCallback\>): void; + +Obtains information about the running processes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Callback used to return the process information.| + +**Example** + + ```ts + app.getProcessRunningInformation((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.on + +on(type: "applicationState", observer: ApplicationStateObserver): number; + +Registers an observer to listen for the state changes of all applications. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | Yes| Numeric code of the observer.| + +**Example** + + ```js + var applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('------------ onForegroundApplicationChanged -----------', appStateData); + }, + onAbilityStateChanged(abilityStateData) { + console.log('------------ onAbilityStateChanged -----------', abilityStateData); + }, + onProcessCreated(processData) { + console.log('------------ onProcessCreated -----------', processData); + }, + onProcessDied(processData) { + console.log('------------ onProcessDied -----------', processData); + }, + onProcessStateChanged(processData) { + console.log('------------ onProcessStateChanged -----------', processData); + } + } + try { + const observerCode = app.on(applicationStateObserver); + console.log('-------- observerCode: ---------', observerCode); + } catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); + } + + ``` + +## appManager.on + +on(type: "applicationState", observer: ApplicationStateObserver, bundleNameList: Array\): number; + +Registers an observer to listen for the state changes of a specified application. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | Yes| Numeric code of the observer.| +| bundleNameList | Array | Yes| **bundleName** array of the application. A maximum of 128 bundle names can be passed.| + +**Example** + + ```js + var applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('------------ onForegroundApplicationChanged -----------', appStateData); + }, + onAbilityStateChanged(abilityStateData) { + console.log('------------ onAbilityStateChanged -----------', abilityStateData); + }, + onProcessCreated(processData) { + console.log('------------ onProcessCreated -----------', processData); + }, + onProcessDied(processData) { + console.log('------------ onProcessDied -----------', processData); + }, + onProcessStateChanged(processData) { + console.log('------------ onProcessStateChanged -----------', processData); + } + } + var bundleNameList = ['bundleName1', 'bundleName2']; + try { + const observerCode = app.on("applicationState", applicationStateObserver, bundleNameList); + console.log('-------- observerCode: ---------', observerCode); + } catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); + } + + ``` +## appManager.off + +off(type: "applicationState", observerId: number, callback: AsyncCallback\): void; + +Deregisters the application state observer. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observerId | number | Yes| Numeric code of the observer.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```js + var observerId = 100; + + function unregisterApplicationStateObserverCallback(err) { + if (err) { + console.log('------------ unregisterApplicationStateObserverCallback ------------', err); + } + } + try { + app.off(observerId, unregisterApplicationStateObserverCallback); + } catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); + } + ``` + +## appManager.off + +off(type: "applicationState", observerId: number): Promise\; + +Deregisters the application state observer. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observerId | number | Yes| Numeric code of the observer.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```js + var observerId = 100; + + try { + app.off(observerId) + .then((data) => { + console.log('----------- unregisterApplicationStateObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- unregisterApplicationStateObserver fail ----------', err); + }) + } catch (paramError) { + console.log('error: ' + paramError.code + ', ' + paramError.message); + } + ``` + +## appManager.getForegroundApplications + +getForegroundApplications(callback: AsyncCallback\>): void; + +Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Callback used to return the application state data.| + +**Example** + + ```js + function getForegroundApplicationsCallback(err, data) { + if (err) { + console.log('--------- getForegroundApplicationsCallback fail ---------', err.code + ': ' + err.message); + } else { + console.log('--------- getForegroundApplicationsCallback success ---------', data) + } + } + app.getForegroundApplications(getForegroundApplicationsCallback); + ``` + +unregisterApplicationStateObserver(observerId: number): Promise\; + +Deregisters the application state observer. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observerId | number | Yes| Numeric code of the observer.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts + var observerId = 100; + app.unregisterApplicationStateObserver(observerId) + .then((data) => { + console.log('----------- unregisterApplicationStateObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- unregisterApplicationStateObserver fail ----------', err); + }) + ``` + +## appManager.getForegroundApplications9+ + +getForegroundApplications(callback: AsyncCallback\>): void; + +Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Callback used to return the application state data.| + +**Example** + + ```ts + function getForegroundApplicationsCallback(err, data) { + if (err) { + console.log('--------- getForegroundApplicationsCallback fail ---------', err); + } else { + console.log('--------- getForegroundApplicationsCallback success ---------', data) + } + } + app.getForegroundApplications(getForegroundApplicationsCallback); + ``` + +## appManager.getForegroundApplications9+ + +getForegroundApplications(): Promise\>; + +Obtains applications that are running in the foreground. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Promise used to return the application state data.| + +**Example** + + ```ts + app.getForegroundApplications() + .then((data) => { + console.log('--------- getForegroundApplications success -------', data); + }) + .catch((err) => { + console.log('--------- getForegroundApplications fail -------', err); + }) + ``` + +## appManager.killProcessWithAccount9+ + +killProcessWithAccount(bundleName: string, accountId: number): Promise\ + +Kills a process by bundle name and account ID. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Bundle name of an application.| + | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Example** + +```ts +var bundleName = 'bundleName'; +var accountId = 0; +app.killProcessWithAccount(bundleName, accountId) + .then((data) => { + console.log('------------ killProcessWithAccount success ------------', data); + }) + .catch((err) => { + console.log('------------ killProcessWithAccount fail ------------', err); + }) +``` + + +## appManager.killProcessWithAccount9+ + +killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\): void + +Kills a process by bundle name and account ID. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Bundle name of an application.| + | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + | callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + +```ts +var bundleName = 'bundleName'; +var accountId = 0; +function killProcessWithAccountCallback(err, data) { + if (err) { + console.log('------------- killProcessWithAccountCallback fail, err: --------------', err); + } else { + console.log('------------- killProcessWithAccountCallback success, data: --------------', data); + } +} +app.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback); +``` + +## appManager.killProcessesByBundleName9+ + +killProcessesByBundleName(bundleName: string, callback: AsyncCallback\); + +Kills a process by bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + function killProcessesByBundleNameCallback(err, data) { + if (err) { + console.log('------------- killProcessesByBundleNameCallback fail, err: --------------', err); + } else { + console.log('------------- killProcessesByBundleNameCallback success, data: --------------', data); + } + } + app.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback); + ``` + +## appManager.killProcessesByBundleName9+ + +killProcessesByBundleName(bundleName: string): Promise\; + +Kills a process by bundle name. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts +var bundleName = 'bundleName'; +app.killProcessesByBundleName(bundleName) + .then((data) => { + console.log('------------ killProcessesByBundleName success ------------', data); + }) + .catch((err) => { + console.log('------------ killProcessesByBundleName fail ------------', err); + }) + ``` + +## appManager.clearUpApplicationData9+ + +clearUpApplicationData(bundleName: string, callback: AsyncCallback\); + +Clears application data by bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + function clearUpApplicationDataCallback(err, data) { + if (err) { + console.log('------------- clearUpApplicationDataCallback fail, err: --------------', err); + } else { + console.log('------------- clearUpApplicationDataCallback success, data: --------------', data); + } + } + app.clearUpApplicationData(bundleName, clearUpApplicationDataCallback); + ``` + +## appManager.clearUpApplicationData9+ + +clearUpApplicationData(bundleName: string): Promise\; + +Clears application data by bundle name. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + app.clearUpApplicationData(bundleName) + .then((data) => { + console.log('------------ clearUpApplicationData success ------------', data); + }) + .catch((err) => { + console.log('------------ clearUpApplicationData fail ------------', err); + }) + ``` + +## ApplicationState9+ + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Value | Description | +| -------------------- | --- | --------------------------------- | +| STATE_CREATE | 1 | State indicating that the application is being created. | +| STATE_FOREGROUND | 2 | State indicating that the application is running in the foreground. | +| STATE_ACTIVE | 3 | State indicating that the application is active. | +| STATE_BACKGROUND | 4 | State indicating that the application is running in the background. | +| STATE_DESTROY | 5 | State indicating that the application is destroyed. | + +## ProcessState9+ + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Value | Description | +| -------------------- | --- | --------------------------------- | +| STATE_CREATE | 1 | State indicating that the process is being created. | +| STATE_FOREGROUND | 2 | State indicating that the process is running in the foreground. | +| STATE_ACTIVE | 3 | State indicating that the process is active. | +| STATE_BACKGROUND | 4 | State indicating that the process is running in the background. | +| STATE_DESTROY | 5 | State indicating that the process is destroyed. | diff --git a/en/application-dev/reference/apis/js-apis-app-ability-appRecovery.md b/en/application-dev/reference/apis/js-apis-app-ability-appRecovery.md new file mode 100644 index 0000000000000000000000000000000000000000..80c507b83ab0012aafbdc9745810730a54997293 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-appRecovery.md @@ -0,0 +1,121 @@ +# @ohos.app.ability.appRecovery + +The **appRecovery** module provides APIs for recovering faulty applications. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. In the current version, only applications with a single ability in a single process can be recovered. + +## Modules to Import +```ts +import appRecovery from '@ohos.app.ability.appRecovery' +``` + + +## appRecovery.RestartFlag + +Enumerates the application restart options used in [enableAppRecovery](#apprecoveryenableapprecovery). + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| ALWAYS_RESTART | 0 | The application is restarted in all cases.| +| CPP_CRASH_NO_RESTART | 0x0001 | The application is not restarted in the case of CPP_CRASH.| +| JS_CRASH_NO_RESTART | 0x0002 | The application is not restarted in the case of JS_CRASH.| +| APP_FREEZE_NO_RESTART | 0x0004 | The application is not restarted in the case of APP_FREEZE.| +| NO_RESTART | 0xFFFF | The application is not restarted in any case.| + +## appRecovery.SaveOccasionFlag + +Enumerates the scenarios for saving the application state, which is used in [enableAppRecovery](#apprecoveryenableapprecovery). + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| SAVE_WHEN_ERROR | 0x0001 | Saving the application state when an application fault occurs.| +| SAVE_WHEN_BACKGROUND | 0x0002 | Saving the application state when the application is switched to the background.| + +## appRecovery.SaveModeFlag + +Enumerates the application state saving modes used in [enableAppRecovery](#apprecoveryenableapprecovery). + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| SAVE_WITH_FILE | 0x0001 | The application state is saved and written to the local file cache.| +| SAVE_WITH_SHARED_MEMORY | 0x0002 | The application state is saved in the memory. When the application exits due to a fault, it is written to the local file cache.| + +## appRecovery.enableAppRecovery + +enableAppRecovery(restart?: RestartFlag, saveOccasion?: SaveOccasionFlag, saveMode?: SaveModeFlag) : void; + +Enables application recovery. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| restart | [RestartFlag](#apprecoveryrestartflag) | No| Whether the application is restarted upon a fault. By default, the application is not restarted.| +| saveOccasion | [SaveOccasionFlag](#apprecoverysaveoccasionflag) | No| Scenario for saving the application state. By default, the state is saved when a fault occurs.| +| saveMode | [SaveModeFlag](#apprecoverysavemodeflag) | No| Application state saving mode. By default, the application state is written to the local file cache.| + +**Example** + +```ts +export default class MyAbilityStage extends AbilityStage { + onCreate() { + appRecovery.enableAppRecovery(RestartFlag::ALWAYS_RESTART, SaveOccasionFlag::SAVE_WHEN_ERROR, SaveModeFlag::SAVE_WITH_FILE); + } +} +``` + +## appRecovery.restartApp + +restartApp(): void; + +Restarts the application. This API can be used together with APIs of [errorManager](js-apis-app-ability-errorManager.md). + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + + +**Example** + +```ts +var observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ', errorMsg) + appRecovery.restartApp(); + } +} + +``` + +## appRecovery.saveAppState + +saveAppState(): boolean; + +Saves the application state. This API can be used together with APIs of [errorManager](js-apis-app-ability-errorManager.md). + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean | Whether the saving is successful.| + +**Example** + +```ts +var observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ', errorMsg) + appRecovery.saveAppState(); + } +} +``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-common.md b/en/application-dev/reference/apis/js-apis-app-ability-common.md new file mode 100644 index 0000000000000000000000000000000000000000..23184c6036f12bd3c914d7b500fece72afafc538 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-common.md @@ -0,0 +1,62 @@ +# @ohos.app.ability.common + +The **Common** module provides all level-2 module APIs for developers to export. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import common from '@ohos.app.ability.common' +``` + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| UIAbilityContext | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | No | Level-2 module **UIAbilityContext**. | +| AbilityStageContext | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | No | Level-2 module **AbilityStageContext**.| +| ApplicationContext | [ApplicationContext](js-apis-inner-application-applicationContext.md) | No | Level-2 module **ApplicationContext**.| +| BaseContext | [BaseContext](js-apis-inner-application-baseContext.md) | No | Level-2 module **BaseContext**.| +| Context | [Context](js-apis-inner-application-context.md) | No | Level-2 module **Context**.| +| ExtensionContext | [ExtensionContext](js-apis-inner-application-extensionContext.md) | No | Level-2 module **ExtensionContext**.| +| FormExtensionContext | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | No | Level-2 module **FormExtensionContext**.| +| AreaMode | [AreaMode](#areamode) | No | Enumerated values of **AreaMode**.| +| EventHub | [EventHub](js-apis-inner-application-eventHub.md) | No | Level-2 module **EventHub**.| +| PermissionRequestResult | [PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md) | No | Level-2 module **PermissionRequestResult**.| +| PacMap | [PacMap](js-apis-inner-ability-dataAbilityHelper.md#PacMap) | No | Level-2 module **PacMap**.| +| AbilityResult | [AbilityResult](js-apis-inner-ability-abilityResult.md) | No | Level-2 module **AbilityResult**.| +| ConnectOptions | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No | Level-2 module **ConnectOptions**.| + +**Example** +```ts +import common from '@ohos.app.ability.common' + +let uiAbilityContext: common.UIAbilityContext; +let abilityStageContext: common.AbilityStageContext; +let applicationContext: common.ApplicationContext; +let baseContext: common.BaseContext; +let context: common.Context; +let extensionContext: common.ExtensionContext; +let formExtensionContext: common.FormExtensionContext; +let areaMode: common.AreaMode; +let eventHub: common.EventHub; +let permissionRequestResult: common.PermissionRequestResult; +let pacMap: common.PacMap; +let abilityResult: common.AbilityResult; +let connectOptions: common.ConnectOptions; +``` + +## AreaMode + +Defines the area where the file to be access is located. Each area has its own content. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| --------------- | ---- | --------------- | +| EL1 | 0 | Device-level encryption area. | +| EL2 | 1 | User credential encryption area. The default value is **EL2**.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-configuration.md b/en/application-dev/reference/apis/js-apis-app-ability-configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..90075377af701150b8de77600ed3ae3808b50d41 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-configuration.md @@ -0,0 +1,47 @@ +# @ohos.app.ability.Configuration + +The **Configuration** module defines environment change information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import Configuration from '@ohos.app.ability.Configuration' +``` + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| language | string | Yes| Yes| Language of the application.| +| colorMode | [ColorMode](js-apis-app-ability-configurationConstant.md#configurationconstantcolormode) | Yes| Yes| Color mode, which can be **COLOR_MODE_LIGHT** or **COLOR_MODE_DARK**. The default value is **COLOR_MODE_LIGHT**.| +| direction | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.| +| screenDensity | ScreenDensity | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).| +| displayId | number | Yes| No| ID of the display where the application is located.| +| hasPointerDevice | boolean | Yes| No| Whether a pointer device, such as a keyboard, mouse, or touchpad, is connected.| + +For details about the fields, see the **ohos.app.ability.Configuration.d.ts** file. + +**Example** + + ```ts + let envCallback = { + onConfigurationUpdated(config) { + console.info(`envCallback onConfigurationUpdated success: ${JSON.stringify(config)}`) + let language = config.language; + let colorMode = config.colorMode; + let direction = config.direction; + let screenDensity = config.screenDensity; + let displayId = config.displayId; + let hasPointerDevice = config.hasPointerDevice; + } + }; + try { + var callbackId = applicationContext.on("environment", envCallback); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-configurationconstant.md b/en/application-dev/reference/apis/js-apis-app-ability-configurationConstant.md similarity index 82% rename from en/application-dev/reference/apis/js-apis-configurationconstant.md rename to en/application-dev/reference/apis/js-apis-app-ability-configurationConstant.md index 70d527483a15d7f676402ad406964740a5686a6b..24b6b4745b1ba606cdb40c741fa2fcf10376cc06 100644 --- a/en/application-dev/reference/apis/js-apis-configurationconstant.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-configurationConstant.md @@ -1,28 +1,21 @@ -# ConfigurationConstant +# @ohos.app.ability.ConfigurationConstant The **ConfigurationConstant** module provides the enumerated values of the environment configuration information. > **NOTE** > -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import - -```js -import ConfigurationConstant from '@ohos.application.ConfigurationConstant'; +```ts +import ConfigurationConstant from '@ohos.app.ability.ConfigurationConstant'; ``` ## ConfigurationConstant.ColorMode You can obtain the value of this constant by calling the **ConfigurationConstant.ColorMode** API. -**Example** - -``` -ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT -``` - **System capability**: SystemCapability.Ability.AbilityBase | Name| Value| Description| @@ -36,12 +29,6 @@ ConfigurationConstant.ColorMode.COLOR_MODE_LIGHT You can obtain the value of this constant by calling the **ConfigurationConstant.Direction** API. -**Example** - -``` -ConfigurationConstant.Direction.DIRECTION_VERTICAL -``` - **System capability**: SystemCapability.Ability.AbilityBase | Name| Value| Description| @@ -55,12 +42,6 @@ ConfigurationConstant.Direction.DIRECTION_VERTICAL You can obtain the value of this constant by calling the **ConfigurationConstant.ScreenDensity** API. -**Example** - -``` -ConfigurationConstant.ScreenDensity.SCREEN_DENSITY_NOT_SET -``` - **System capability**: SystemCapability.Ability.AbilityBase | Name| Value| Description| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-contextConstant.md b/en/application-dev/reference/apis/js-apis-app-ability-contextConstant.md new file mode 100644 index 0000000000000000000000000000000000000000..dc1b5a1430c8c063de23cc87126ff891d5363b80 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-contextConstant.md @@ -0,0 +1,25 @@ +# @ohos.app.ability.contextConstant + +The **ContextConstant** module defines data encryption levels. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import contextConstant from '@ohos.app.ability.contextConstant'; +``` + +## ContextConstant.AreaMode + +You can obtain the value of this constant by calling the **ContextConstant.AreaMode** API. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Value| Description| +| -------- | -------- | -------- | +| EL1 | 0 | Device-level encryption area.| +| EL2 | 1 | User credential encryption area.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-environmentCallback.md b/en/application-dev/reference/apis/js-apis-app-ability-environmentCallback.md new file mode 100644 index 0000000000000000000000000000000000000000..1208aeb8dabdbc09b77a9395e0ad313b1bf7e8cd --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-environmentCallback.md @@ -0,0 +1,62 @@ +# @ohos.app.ability.EnvironmentCallback + +The **EnvironmentCallback** module provides the **onConfigurationUpdated** API for the application context to listen for system environment changes. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + + +## Modules to Import + +```ts +import EnvironmentCallback from "@ohos.app.ability.EnvironmentCallback"; +``` + + +## EnvironmentCallback.onConfigurationUpdated + +onConfigurationUpdated(config: Configuration): void; + +Called when the system environment changes. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | config | [Configuration](js-apis-app-ability-configuration.md) | Yes| **Configuration** object after the change.| + +**Example** + + + ```ts +import Ability from "@ohos.application.Ability"; + +var callbackId; + +export default class MyAbility extends Ability { + onCreate() { + console.log("MyAbility onCreate") + globalThis.applicationContext = this.context.getApplicationContext(); + let EnvironmentCallback = { + onConfigurationUpdated(config){ + console.log("onConfigurationUpdated config:" + JSON.stringify(config)); + }, + } + // 1. Obtain an applicationContext object. + let applicationContext = globalThis.applicationContext; + // 2. Register a listener for the environment changes through the applicationContext object. + callbackId = applicationContext.registerEnvironmentCallback(EnvironmentCallback); + console.log("registerEnvironmentCallback number: " + JSON.stringify(callbackId)); + } + onDestroy() { + let applicationContext = globalThis.applicationContext; + applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => { + console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error)); + }); + } +} + ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-errorManager.md b/en/application-dev/reference/apis/js-apis-app-ability-errorManager.md new file mode 100644 index 0000000000000000000000000000000000000000..3fb88a2b8ad93d3dbb5adf627f105d117ca86fda --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-errorManager.md @@ -0,0 +1,114 @@ +# @ohos.app.ability.errorManager + +The **ErrorManager** module provides APIs for registering and deregistering error observers. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import +``` +import errorManager from '@ohos.app.ability.errorManager' +``` + +## ErrorManager.on + +on(type: "error", observer: ErrorObserver): number; + +Registers an error observer. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observer | [ErrorObserver](./js-apis-inner-application-errorObserver.md) | Yes| Numeric code of the observer.| + +**Example** + +```js +var observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ', errorMsg) + } +} +try { + errorManager.on("error", observer); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## ErrorManager.off + +off(type: "error", observerId: number, callback: AsyncCallback\): void; + +Deregisters an error observer. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observerId | number | Yes| Numeric code of the observer.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + +```js +var observerId = 100; + +function unregisterErrorObserverCallback(err) { + if (err) { + console.log('------------ unregisterErrorObserverCallback ------------', err); + } +} +try { + errorManager.off("error", observerId, unregisterErrorObserverCallback); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## ErrorManager.off + +off(type: "error", observerId: number): Promise\; + +Deregisters an error observer. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| type | string | Yes| Type of the API to call.| +| observerId | number | Yes| Numeric code of the observer.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +var observerId = 100; +try { + errorManager.off("error", observerId) + .then((data) => { + console.log('----------- unregisterErrorObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- unregisterErrorObserver fail ----------', err); + }) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} + +``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-extensionAbility.md b/en/application-dev/reference/apis/js-apis-app-ability-extensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..b53881f7fdb5df90cf0a1783c04554ce93240b04 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-extensionAbility.md @@ -0,0 +1,30 @@ +# @ohos.app.ability.ExtensionAbility + +The **ExtensionAbility** module manages the Extension ability lifecycle and context, such as creating and destroying an Extension ability, and dumping client information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import ExtensionAbility from '@ohos.app.ability.ExtensionAbility'; +``` + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Example** + + ```ts + class MyExtensionAbility extends ExtensionAbility { + onConfigurationUpdated(config) { + console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); + } + + onMemoryLevel(level) { + console.log('onMemoryLevel, level:' + JSON.stringify(level)); + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-missionManager.md b/en/application-dev/reference/apis/js-apis-app-ability-missionManager.md new file mode 100644 index 0000000000000000000000000000000000000000..73fba6a39646820720498fc20a9d7da89cf65bf3 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-missionManager.md @@ -0,0 +1,940 @@ +# @ohos.app.ability.missionManager + +The **missionManager** module provides APIs to lock, unlock, and clear missions, and switch a mission to the foreground. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import missionManager from '@ohos.app.ability.missionManager' +``` + +## Required Permissions + +ohos.permission.MANAGE_MISSIONS + +## missionManager.on + +on(type:"mission", listener: MissionListener): number; + +Registers a listener to observe the mission status. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | listener | MissionListener | Yes| Listener to register.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | number | Returns the unique index of the mission status listener, which is created by the system and allocated when the listener is registered.| + +**Example** + +```ts + var listener = { + onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, + onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, + onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, + onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, + onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} + }; + console.log("registerMissionListener") + try { + var listenerid = missionManager.on("mission", listener); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } +``` + + +## missionManager.off + +off(type: "mission", listenerId: number, callback: AsyncCallback<void>): void; + +Deregisters a mission status listener. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + +```ts + var listener = { + onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, + onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, + onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, + onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, + onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} + }; + console.log("registerMissionListener") + try { + var listenerid = missionManager.registerMissionListener(listener); + + missionManager.unregisterMissionListener(listenerid, (error) => { + console.log("unregisterMissionListener"); + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } +``` + + +## missionManager.off + +off(type: "mission", listenerId: number): Promise<void>; + +Deregisters a mission status listener. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + +```ts + var listener = { + onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, + onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, + onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, + onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, + onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} + }; + console.log("registerMissionListener") + try { + var listenerid = missionManager.registerMissionListener(listener); + + missionManager.unregisterMissionListener(listenerid).catch(function (err) { + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } +``` + + +## missionManager.getMissionInfo + +getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback<MissionInfo>): void; + +Obtains the information about a given mission. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<[MissionInfo](./js-apis-inner-application-missionInfo.md))> | Yes| Callback used to return the mission information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions=missionManager.getMissionInfos("",10).catch(function(err){console.log(err);}); + missionManager.getMissionInfo("", allMissions[0].missionId, (error, mission) => { + console.log("getMissionInfo is called, error.code = " + error.code) + console.log("mission.missionId = " + mission.missionId); + console.log("mission.runningState = " + mission.runningState); + console.log("mission.lockedState = " + mission.lockedState); + console.log("mission.timestamp = " + mission.timestamp); + console.log("mission.label = " + mission.label); + console.log("mission.iconPath = " + mission.iconPath); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getMissionInfo + +getMissionInfo(deviceId: string, missionId: number): Promise<MissionInfo>; + +Obtains the information about a given mission. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<[MissionInfo](./js-apis-inner-application-missionInfo.md)> | Promise used to return the mission information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var mission = missionManager.getMissionInfo("", 10).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getMissionInfos + +getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback<Array<MissionInfo>>): void; + +Obtains information about all missions. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | numMax | number | Yes| Maximum number of missions whose information can be obtained.| + | callback | AsyncCallback<Array<[MissionInfo](./js-apis-inner-application-missionInfo.md)>> | Yes| Callback used to return the array of mission information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getMissionInfos + +getMissionInfos(deviceId: string, numMax: number): Promise<Array<MissionInfo>>; + +Obtains information about all missions. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | numMax | number | Yes| Maximum number of missions whose information can be obtained.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<Array<[MissionInfo](./js-apis-inner-application-missionInfo.md)>> | Promise used to return the array of mission information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getMissionSnapShot + +getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback<MissionSnapshot>): void; + +Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.getMissionSnapShot("", id, (error, snapshot) => { + console.log("getMissionSnapShot is called, error.code = " + error.code); + console.log("bundleName = " + snapshot.ability.bundleName); + }) + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getMissionSnapShot + +getMissionSnapShot(deviceId: string, missionId: number): Promise<MissionSnapshot>; + +Obtains the snapshot of a given mission. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Promise used to return the snapshot information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + var snapshot = missionManager.getMissionSnapShot("", id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + +## missionManager.getLowResolutionMissionSnapShot + +getLowResolutionMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback\): void; + +Obtains the low-resolution snapshot of a given mission. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.getLowResolutionMissionSnapShot("", id, (error, snapshot) => { + console.log("getLowResolutionMissionSnapShot is called, error.code = " + error.code); + console.log("bundleName = " + snapshot.ability.bundleName); + }) + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.getLowResolutionMissionSnapShot + +getLowResolutionMissionSnapShot(deviceId: string, missionId: number): Promise\; + +Obtains the low-resolution snapshot of a given mission. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Promise used to return the snapshot information obtained.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + var snapshot = missionManager.getLowResolutionMissionSnapShot("", id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.lockMission + +lockMission(missionId: number, callback: AsyncCallback<void>): void; + +Locks a given mission. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.lockMission(id).then(() => { + console.log("lockMission is called "); + }); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.lockMission + +lockMission(missionId: number): Promise<void>; + +Locks a given mission. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + missionManager.lockMission(id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.unlockMission + +unlockMission(missionId: number, callback: AsyncCallback<void>): void; + +Unlocks a given mission. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| missionId | number | Yes| Mission ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.unlockMission(id).then(() => { + console.log("unlockMission is called "); + }); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.unlockMission + +unlockMission(missionId: number): Promise<void>; + +Unlocks a given mission. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + missionManager.lockMission(id).catch(function (err){ + console.log(err); + }); + missionManager.unlockMission(id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.clearMission + +clearMission(missionId: number, callback: AsyncCallback<void>): void; + +Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.clearMission(id).then(() => { + console.log("clearMission is called "); + }); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.clearMission + +clearMission(missionId: number): Promise<void>; + +Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + missionManager.clearMission(id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.clearAllMissions + +clearAllMissions(callback: AsyncCallback<void>): void; + +Clears all unlocked missions. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + missionManager.clearAllMissions().then(() => { + console.log("clearAllMissions is called "); + }); + ``` + + +## missionManager.clearAllMissions + +clearAllMissions(): Promise<void>; + +Clears all unlocked missions. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + missionManager.clearAllMissions().catch(function (err){ + console.log(err); + }); + ``` + + +## missionManager.moveMissionToFront + +moveMissionToFront(missionId: number, callback: AsyncCallback<void>): void; + +Switches a given mission to the foreground. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.moveMissionToFront(id).then(() => { + console.log("moveMissionToFront is called "); + }); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.moveMissionToFront + +moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCallback<void>): void; + +Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + | options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| + | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + missionManager.getMissionInfos("", 10, (error, missions) => { + console.log("getMissionInfos is called, error.code = " + error.code); + console.log("size = " + missions.length); + console.log("missions = " + JSON.stringify(missions)); + var id = missions[0].missionId; + + missionManager.moveMissionToFront(id,{windowMode : 101}).then(() => { + console.log("moveMissionToFront is called "); + }); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` + + +## missionManager.moveMissionToFront + +moveMissionToFront(missionId: number, options?: StartOptions): Promise<void>; + +Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.MANAGE_MISSIONS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | missionId | number | Yes| Mission ID.| + | options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import missionManager from '@ohos.app.ability.missionManager' + + try { + var allMissions; + missionManager.getMissionInfos("",10).then(function(res){ + allMissions=res; + }).catch(function(err){console.log(err);}); + console.log("size = " + allMissions.length); + console.log("missions = " + JSON.stringify(allMissions)); + var id = allMissions[0].missionId; + + missionManager.moveMissionToFront(id).catch(function (err){ + console.log(err); + }); + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-application-quickFixManager.md b/en/application-dev/reference/apis/js-apis-app-ability-quickFixManager.md similarity index 50% rename from en/application-dev/reference/apis/js-apis-application-quickFixManager.md rename to en/application-dev/reference/apis/js-apis-app-ability-quickFixManager.md index 5abe8c19658d484fb335efc0d3fe8e2aa49bdc48..c703726492eb8bc4ddd1211f97d95a3490a8938a 100644 --- a/en/application-dev/reference/apis/js-apis-application-quickFixManager.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-quickFixManager.md @@ -1,4 +1,4 @@ -# quickFixManager +# @ohos.app.ability.quickFixManager The **quickFixManager** module provides APIs for quick fix. With quick fix, you can fix bugs in your application by applying patches, which is more efficient than by updating the entire application. @@ -8,8 +8,8 @@ The **quickFixManager** module provides APIs for quick fix. With quick fix, you ## Modules to Import -``` -import quickFixManager from '@ohos.application.quickFixManager'; +```ts +import quickFixManager from '@ohos.app.ability.quickFixManager'; ``` ## HapModuleQuickFixInfo @@ -20,11 +20,11 @@ Defines the quick fix information at the HAP file level. **System API**: This is a system API and cannot be called by third-party applications. -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| moduleName | Read only | string | Yes | Name of the HAP file. | -| originHapHash | Read only | string | Yes | Hash value of the HAP file. | -| quickFixFilePath | Read only | string | Yes | Installation path of the quick fix file. | +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| moduleName | string | Yes | Name of the HAP file. | +| originHapHash | string | Yes | Hash value of the HAP file. | +| quickFixFilePath | string | Yes | Installation path of the quick fix file. | ## ApplicationQuickFixInfo @@ -34,14 +34,14 @@ Defines the quick fix information at the application level. **System API**: This is a system API and cannot be called by third-party applications. -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| bundleName | Read only | string | Yes | Bundle name of the application. | -| bundleVersionCode | Read only | number | Yes | Internal version number of the application. | -| bundleVersionName | Read only | string | Yes | Version number of the application that is shown to users. | -| quickFixVersionCode | Read only | number | Yes | Version code of the quick fix patch package. | -| quickFixVersionName | Read only | string | Yes | Text description of the version number of the quick fix patch package. | -| hapModuleQuickFixInfo | Read only | Array\<[HapModuleQuickFixInfo](#hapmodulequickfixinfo)> | Yes | Quick fix information at the HAP file level. | +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| bundleName | string | Yes | Bundle name of the application. | +| bundleVersionCode | number | Yes | Internal version number of the application. | +| bundleVersionName | string | Yes | Version number of the application that is shown to users. | +| quickFixVersionCode | number | Yes | Version code of the quick fix patch package. | +| quickFixVersionName | string | Yes | Text description of the version number of the quick fix patch package. | +| hapModuleQuickFixInfo | Array\<[HapModuleQuickFixInfo](#hapmodulequickfixinfo)> | Yes | Quick fix information at the HAP file level. | ## quickFixManager.applyQuickFix @@ -59,22 +59,26 @@ Applies a quick fix patch. This API uses an asynchronous callback to return the | Parameter| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | hapModuleQuickFixFiles | Array\ | No| Quick fix files, each of which must contain a valid file path.| - | callback | AsyncCallback\ | No| Callback used to return the result.| + | hapModuleQuickFixFiles | Array\ | Yes| Quick fix files, each of which must contain a valid file path.| + | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** -```js - import quickFixManager from '@ohos.application.quickFixManager' +```ts + import quickFixManager from '@ohos.app.ability.quickFixManager' - let hapModuleQuickFixFiles = ["/data/storage/el2/base/entry.hqf"] - quickFixManager.applyQuickFix(hapModuleQuickFixFiles, (error) => { + try { + let hapModuleQuickFixFiles = ["/data/storage/el2/base/entry.hqf"] + quickFixManager.applyQuickFix(hapModuleQuickFixFiles, (error) => { if (error) { console.info( `applyQuickFix failed with error + ${error}`) } else { console.info( 'applyQuickFix success') } - }) + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } ``` ## quickFixManager.applyQuickFix @@ -93,7 +97,7 @@ Applies a quick fix patch. This API uses a promise to return the result. | Parameter| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | hapModuleQuickFixFiles | Array\ | No| Quick fix files, each of which must contain a valid file path.| + | hapModuleQuickFixFiles | Array\ | Yes| Quick fix files, each of which must contain a valid file path.| **Return value** @@ -103,15 +107,19 @@ Applies a quick fix patch. This API uses a promise to return the result. **Example** -```js - import quickFixManager from '@ohos.application.quickFixManager' +```ts + import quickFixManager from '@ohos.app.ability.quickFixManager' let hapModuleQuickFixFiles = ["/data/storage/el2/base/entry.hqf"] - quickFixManager.applyQuickFix(hapModuleQuickFixFiles).then(() => { - console.info('applyQuickFix success') - }).catch((error) => { - console.info(`applyQuickFix err: + ${error}`) - }) + try { + quickFixManager.applyQuickFix(hapModuleQuickFixFiles).then(() => { + console.info('applyQuickFix success') + }).catch((error) => { + console.info(`applyQuickFix err: + ${error}`) + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } ``` ## quickFixManager.getApplicationQuickFixInfo @@ -130,22 +138,26 @@ Obtains the quick fix information of the application. This API uses an asynchron | Parameter| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | bundleName | string | No|Bundle name of the application. | - | callback | AsyncCallback\<[ApplicationQuickFixInfo](#applicationquickfixinfo)> | No| Callback used to return the quick fix information.| + | bundleName | string | Yes|Bundle name of the application. | + | callback | AsyncCallback\<[ApplicationQuickFixInfo](#applicationquickfixinfo)> | Yes| Callback used to return the quick fix information.| **Example** -```js - import quickFixManager from '@ohos.application.quickFixManager' - - let bundleName = "bundleName" - quickFixManager.getApplicationQuickFixInfo(bundleName, (error, data) => { - if (error) { - console.info(`getApplicationQuickFixInfo error: + ${error}`) - } else { - console.info(`getApplicationQuickFixInfo success: + ${data}`) - } - }) +```ts + import quickFixManager from '@ohos.app.ability.quickFixManager' + + try { + let bundleName = "bundleName" + quickFixManager.getApplicationQuickFixInfo(bundleName, (error, data) => { + if (error) { + console.info(`getApplicationQuickFixInfo error: + ${error}`) + } else { + console.info(`getApplicationQuickFixInfo success: + ${data}`) + } + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } ``` ## quickFixManager.getApplicationQuickFixInfo @@ -164,7 +176,7 @@ Obtains the quick fix information of the application. This API uses a promise to | Parameter| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | bundleName | string | No| Bundle name of the application. | + | bundleName | string | Yes| Bundle name of the application. | **Return value** @@ -174,13 +186,17 @@ Obtains the quick fix information of the application. This API uses a promise to **Example** - ```js - import quickFixManager from '@ohos.application.quickFixManager' - - let bundleName = "bundleName" - quickFixManager.getApplicationQuickFixInfo(bundleName).then((data) => { - console.info(`getApplicationQuickFixInfo success: + ${data}`) - }).catch((error) => { - console.info(`getApplicationQuickFixInfo err: + ${error}`) - }) + ```ts + import quickFixManager from '@ohos.app.ability.quickFixManager' + + try { + let bundleName = "bundleName" + quickFixManager.getApplicationQuickFixInfo(bundleName).then((data) => { + console.info(`getApplicationQuickFixInfo success: + ${data}`) + }).catch((error) => { + console.info(`getApplicationQuickFixInfo err: + ${error}`) + }) + } catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); + } ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-serviceExtensionAbility.md b/en/application-dev/reference/apis/js-apis-app-ability-serviceExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..6c3e0e6e2a0e116120aa405758506d46175c3468 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-serviceExtensionAbility.md @@ -0,0 +1,252 @@ +# @ohos.app.ability.ServiceExtensionAbility + +The **ServiceExtensionAbility** module provides APIs for Service Extension abilities. + +> **NOTE** +> +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.ServiceExtensionAbility](js-apis-app-ability-serviceExtensionAbility.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import ServiceExtension from '@ohos.app.ability.ServiceExtensionAbility'; +``` + +## Required Permissions + +None. + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.| + + +## ServiceExtensionAbility.onCreate + +onCreate(want: Want): void; + +Called when a Service Extension ability is created to initialize the service logic. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onCreate(want) { + console.log('onCreate, want:' + want.abilityName); + } + } + ``` + + +## ServiceExtensionAbility.onDestroy + +onDestroy(): void; + +Called when this Service Extension ability is destroyed to clear resources. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onDestroy() { + console.log('onDestroy'); + } + } + ``` + + +## ServiceExtensionAbility.onRequest + +onRequest(want: Want, startId: number): void; + +Called after **onCreate** is invoked when a Service Extension ability is started by calling **startAbility**. The value of **startId** is incremented for each ability that is started. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| + | startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onRequest(want, startId) { + console.log('onRequest, want:' + want.abilityName); + } + } + ``` + + +## ServiceExtensionAbility.onConnect + +onConnect(want: Want): rpc.RemoteObject; + +Called after **onCreate** is invoked when a Service Extension ability is started by calling **connectAbility**. A **RemoteObject** object is returned for communication with the client. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | rpc.RemoteObject | A **RemoteObject** object used for communication with the client.| + +**Example** + + ```ts + import rpc from '@ohos.rpc' + class StubTest extends rpc.RemoteObject{ + constructor(des) { + super(des); + } + onConnect(code, data, reply, option) { + } + } + class ServiceExt extends ServiceExtension { + onConnect(want) { + console.log('onConnect , want:' + want.abilityName); + return new StubTest("test"); + } + } + ``` + + +## ServiceExtensionAbility.onDisconnect + +onDisconnect(want: Want): void; + +Called when this Service Extension ability is disconnected. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onDisconnect(want) { + console.log('onDisconnect, want:' + want.abilityName); + } + } + ``` + +## ServiceExtensionAbility.onReconnect + +onReconnect(want: Want): void; + +Called when this Service Extension ability is reconnected. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onReconnect(want) { + console.log('onReconnect, want:' + want.abilityName); + } + } + ``` + +## ServiceExtensionAbility.onConfigurationUpdate + +onConfigurationUpdate(newConfig: Configuration): void; + +Called when the configuration of this Service Extension ability is updated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | newConfig | [Configuration](js-apis-app-ability-configuration.md) | Yes| New configuration.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onConfigurationUpdate(config) { + console.log('onConfigurationUpdate, config:' + JSON.stringify(config)); + } + } + ``` + +## ServiceExtensionAbility.onDump + +onDump(params: Array\): Array\; + +Dumps the client information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | params | Array\ | Yes| Parameters in the form of a command.| + +**Example** + + ```ts + class ServiceExt extends ServiceExtension { + onDump(params) { + console.log('dump, params:' + JSON.stringify(params)); + return ["params"] + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-app-ability-startOptions.md b/en/application-dev/reference/apis/js-apis-app-ability-startOptions.md new file mode 100644 index 0000000000000000000000000000000000000000..fc5215fe400919172a7c2f2dd7c5a567e44acae3 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-startOptions.md @@ -0,0 +1,24 @@ +# @ohos.app.ability.StartOptions + +The **StartOptions** module implements ability startup options. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import StartOptions from '@ohos.app.ability.StartOptions'; +``` + +## Attributes + + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| [windowMode](js-apis-application-abilityConstant.md#abilityconstantwindowmode) | number | No| Window mode.| +| displayId | number | No| Display ID.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md b/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..cce8b81738f29586417ae5f9814da2448f053e17 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md @@ -0,0 +1,742 @@ +# @ohos.app.ability.UIAbility + +The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information. + +This module provides the following common ability-related functions: + +- [Caller](#caller): implements sending of sequenceable data to the target ability when an ability (caller ability) invokes the target ability (callee ability). +- [Callee](#callee): implements callbacks for registration and deregistration of caller notifications. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import Ability from '@ohos.app.ability.UIAbility'; +``` + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | Yes| No| Context of an ability.| +| launchWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters for starting the ability.| +| lastRequestWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters used when the ability was started last time.| +| callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.| + +## Ability.onCreate + +onCreate(want: Want, param: AbilityConstant.LaunchParam): void; + +Called to initialize the service logic when an ability is created. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this ability, including the ability name and bundle name.| + | param | AbilityConstant.LaunchParam | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.| + +**Example** + + ```ts + class myAbility extends Ability { + onCreate(want, param) { + console.log('onCreate, want:' + want.abilityName); + } + } + ``` + + +## Ability.onWindowStageCreate + +onWindowStageCreate(windowStage: window.WindowStage): void + +Called when a **WindowStage** is created for this ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | windowStage | window.WindowStage | Yes| **WindowStage** information.| + +**Example** + + ```ts + class myAbility extends Ability { + onWindowStageCreate(windowStage) { + console.log('onWindowStageCreate'); + } + } + ``` + + +## Ability.onWindowStageDestroy + +onWindowStageDestroy(): void + +Called when the **WindowStage** is destroyed for this ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Example** + + ```ts + class myAbility extends Ability { + onWindowStageDestroy() { + console.log('onWindowStageDestroy'); + } + } + ``` + + +## Ability.onWindowStageRestore + +onWindowStageRestore(windowStage: window.WindowStage): void + +Called when the **WindowStage** is restored during the migration of this ability, which is a multi-instance ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | windowStage | window.WindowStage | Yes| **WindowStage** information.| + +**Example** + + ```ts + class myAbility extends Ability { + onWindowStageRestore(windowStage) { + console.log('onWindowStageRestore'); + } + } + ``` + + +## Ability.onDestroy + +onDestroy(): void; + +Called when this ability is destroyed to clear resources. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Example** + + ```ts + class myAbility extends Ability { + onDestroy() { + console.log('onDestroy'); + } + } + ``` + + +## Ability.onForeground + +onForeground(): void; + +Called when this ability is switched from the background to the foreground. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Example** + + ```ts + class myAbility extends Ability { + onForeground() { + console.log('onForeground'); + } + } + ``` + + +## Ability.onBackground + +onBackground(): void; + +Called when this ability is switched from the foreground to the background. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Example** + + ```ts + class myAbility extends Ability { + onBackground() { + console.log('onBackground'); + } + } + ``` + + +## Ability.onContinue + +onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult; + +Called to save data during the ability migration preparation process. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | wantParam | {[key: string]: any} | Yes| **want** parameter.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | AbilityConstant.OnContinueResult | Continuation result.| + +**Example** + + ```ts + import AbilityConstant from "@ohos.application.AbilityConstant" + class myAbility extends Ability { + onContinue(wantParams) { + console.log('onContinue'); + wantParams["myData"] = "my1234567"; + return AbilityConstant.OnContinueResult.AGREE; + } + } + ``` + + +## Ability.onNewWant + +onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; + +Called when the ability startup mode is set to singleton. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-application-want.md) | Yes| Want parameters, such as the ability name and bundle name.| + | launchParams | AbilityConstant.LaunchParam | Yes| Reason for the ability startup and the last abnormal exit.| + +**Example** + + ```ts + class myAbility extends Ability { + onNewWant(want) { + console.log('onNewWant, want:' + want.abilityName); + } + } + ``` + +## Ability.onDump + +onDump(params: Array\): Array\; + +Dumps client information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | params | Array\ | Yes| Parameters in the form of a command.| + +**Example** + + ```ts + class myAbility extends Ability { + onDump(params) { + console.log('dump, params:' + JSON.stringify(params)); + return ["params"] + } + } + ``` + + +## Ability.onSaveState + +onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: any}): AbilityConstant.OnSaveResult; + +Called when the framework automatically saves the ability state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | reason | [AbilityConstant.StateType](js-apis-application-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the ability state.| + | wantParam | {[key: string]: any} | Yes| **want** parameter.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | AbilityConstant.OnSaveResult | Whether the ability state is saved.| + +**Example** + + ```ts +import AbilityConstant from '@ohos.application.AbilityConstant' + +class myAbility extends Ability { + onSaveState(reason, wantParam) { + console.log('onSaveState'); + wantParam["myData"] = "my1234567"; + return AbilityConstant.OnSaveResult.RECOVERY_AGREE; + } +} + ``` + + + +## Caller + +Implements sending of sequenceable data to the target ability when an ability (caller ability) invokes the target ability (callee ability). + +## Caller.call + +call(method: string, data: rpc.Sequenceable): Promise<void>; + +Sends sequenceable data to the target ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.| + | data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return a response.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + class MyMessageAble{ // Custom sequenceable data structure + name:"" + str:"" + num: 1 + constructor(name, str) { + this.name = name; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + console.log('MyMessageAble marshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + console.log('MyMessageAble unmarshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + }; + var method = 'call_Function'; // Notification message string negotiated by the two abilities + var caller; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + let msg = new MyMessageAble("msg", "world"); // See the definition of Sequenceable. + caller.call(method, msg) + .then(() => { + console.log('Caller call() called'); + }) + .catch((callErr) => { + console.log('Caller.call catch error, error.code: ' + JSON.stringify(callErr.code) + + ' error.message: ' + JSON.stringify(callErr.message)); + }); + }).catch((err) => { + console.log('Caller GetCaller error, error.code: ' + JSON.stringify(err.code) + + ' error.message: ' + JSON.stringify(err.message)); + }); + } + } + ``` + + +## Caller.callWithResult + +callWithResult(method: string, data: rpc.Sequenceable): Promise<rpc.MessageParcel>; + +Sends sequenceable data to the target ability and obtains the sequenceable data returned by the target ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.| + | data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<rpc.MessageParcel> | Promise used to return the sequenceable data from the target ability.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + class MyMessageAble{ + name:"" + str:"" + num: 1 + constructor(name, str) { + this.name = name; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + console.log('MyMessageAble marshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + console.log('MyMessageAble unmarshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + }; + var method = 'call_Function'; + var caller; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + let msg = new MyMessageAble(1, "world"); + caller.callWithResult(method, msg) + .then((data) => { + console.log('Caller callWithResult() called'); + let retmsg = new MyMessageAble(0, ""); + data.readSequenceable(retmsg); + }) + .catch((callErr) => { + console.log('Caller.callWithResult catch error, error.code: ' + JSON.stringify(callErr.code) + + ' error.message: ' + JSON.stringify(callErr.message)); + }); + }).catch((err) => { + console.log('Caller GetCaller error, error.code: ' + JSON.stringify(err.code) + + ' error.message: ' + JSON.stringify(err.message)); + }); + } + } + ``` + + +## Caller.release + +release(): void; + +Releases the caller interface of the target ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | Invalid input parameter. | +| 16200001 | Caller released. The caller has been released. | +| 16200002 | Callee invalid. The callee does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + var caller; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + try { + caller.release(); + } catch (releaseErr) { + console.log('Caller.release catch error, error.code: ' + JSON.stringify(releaseErr.code) + + ' error.message: ' + JSON.stringify(releaseErr.message)); + } + }).catch((err) => { + console.log('Caller GetCaller error, error.code: ' + JSON.stringify(err.code) + + ' error.message: ' + JSON.stringify(err.message)); + }); + } + } + ``` + +## Caller.onRelease + + onRelease(callback: OnReleaseCallBack): void; + +Registers a callback that is invoked when the stub on the target ability is disconnected. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | OnReleaseCallBack | Yes| Callback used for the **onRelease** API.| + +**Example** + + ```ts + import Ability from '@ohos.application.Ability'; + var caller; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + try { + caller.onRelease((str) => { + console.log(' Caller OnRelease CallBack is called ' + str); + }); + } catch (error) { + console.log('Caller.on catch error, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + } + }).catch((err) => { + console.log('Caller GetCaller error, error.code: ' + JSON.stringify(err.code) + + ' error.message: ' + JSON.stringify(err.message)); + }); + } + } + ``` + +## Caller.on + + on(type: "release", callback: OnReleaseCallback): void; + +Registers a callback that is invoked when the stub on the target ability is disconnected. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is fixed at **release**.| + | callback | OnReleaseCallback | Yes| Callback used for the **onRelease** API.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + var caller; + export default class MainAbility extends Ability { + onWindowStageCreate(windowStage) { + this.context.startAbilityByCall({ + bundleName: "com.example.myservice", + abilityName: "MainAbility", + deviceId: "" + }).then((obj) => { + caller = obj; + try { + caller.on("release", (str) => { + console.log(' Caller OnRelease CallBack is called ' + str); + }); + } catch (error) { + console.log('Caller.on catch error, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + } + }).catch((err) => { + console.log('Caller GetCaller error, error.code: ' + JSON.stringify(err.code) + + ' error.message: ' + JSON.stringify(err.message)); + }); + } + } + ``` + + +## Callee + +Implements callbacks for caller notification registration and deregistration. + +## Callee.on + +on(method: string, callback: CalleeCallback): void; + +Registers a caller notification callback, which is invoked when the target ability registers a function. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two abilities.| + | callback | CalleeCallback | Yes| JS notification synchronization callback of the **rpc.MessageParcel** type. The callback must return at least one empty **rpc.Sequenceable** object. Otherwise, the function execution fails.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + class MyMessageAble{ + name:"" + str:"" + num: 1 + constructor(name, str) { + this.name = name; + this.str = str; + } + marshalling(messageParcel) { + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + console.log('MyMessageAble marshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + unmarshalling(messageParcel) { + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + console.log('MyMessageAble unmarshalling num[' + this.num + '] str[' + this.str + ']'); + return true; + } + }; + var method = 'call_Function'; + function funcCallBack(pdata) { + console.log('Callee funcCallBack is called ' + pdata); + let msg = new MyMessageAble("test", ""); + pdata.readSequenceable(msg); + return new MyMessageAble("test1", "Callee test"); + } + export default class MainAbility extends Ability { + onCreate(want, launchParam) { + console.log('Callee onCreate is called'); + try { + this.callee.on(method, funcCallBack); + } catch (error) { + console.log('Callee.on catch error, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + } + } + } + ``` + +## Callee.off + +off(method: string): void; + +Deregisters a caller notification callback, which is invoked when the target ability registers a function. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Registered notification message string.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 401 | If the input parameter is not valid parameter. | +For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md). + + +**Example** + + ```ts + import Ability from '@ohos.app.ability.UIAbility'; + var method = 'call_Function'; + export default class MainAbility extends Ability { + onCreate(want, launchParam) { + console.log('Callee onCreate is called'); + try { + this.callee.off(method); + } catch (error) { + console.log('Callee.off catch error, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + } + } + } + ``` + +## OnReleaseCallback + +(msg: string): void; + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +| Name| Readable| Writable| Type| Description| +| -------- | -------- | -------- | -------- | -------- | +| (msg: string) | Yes| No| function | Prototype of the listener function registered by the caller.| + +## CalleeCallback + +(indata: rpc.MessageParcel): rpc.Sequenceable; + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +| Name| Readable| Writable| Type| Description| +| -------- | -------- | -------- | -------- | -------- | +| (indata: rpc.MessageParcel) | Yes| No| rpc.Sequenceable | Prototype of the listener function registered by the callee.| diff --git a/en/application-dev/reference/apis/js-apis-app-ability-want.md b/en/application-dev/reference/apis/js-apis-app-ability-want.md new file mode 100644 index 0000000000000000000000000000000000000000..c7bd4f6e9693c9bcc7ac71286e204f4d0b5005a8 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-want.md @@ -0,0 +1,134 @@ +# @ohos.app.ability.Want + +Want is a carrier for information transfer between objects (application components). Want can be used as a parameter of **startAbility** to specify a startup target and information that needs to be carried during startup, for example, **bundleName** and **abilityName**, which respectively indicate the bundle name of the target ability and the ability name in the bundle. When ability A needs to start ability B and transfer some data to ability B, it can use Want a carrier to transfer the data. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import Want from '@ohos.app.ability.Want'; +``` + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| deviceId | string | No | ID of the device running the ability. | +| bundleName | string | No | Bundle name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| +| abilityName | string | No | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.| +| uri | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| +| type | string | No | MIME type, that is, the type of the file to open, for example, **text/xml** and **image/***. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. | +| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantConstant.Flags).| +| action | string | No | Action to take, such as viewing and sharing application details. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. | +| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information. | +| entities | Array\ | No | Additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit Want and is used to filter ability types. | +| moduleName | string | No | Module to which the ability belongs.| + +**Example** + +- Basic usage + + ```ts + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry" // moduleName is optional. + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + +- Data is transferred through user-defined fields. The following data types are supported: + + * String + ```ts + let want = { + bundleName: "com.example.demo", + abilityName: "com.example.demo.MainAbility", + parameters: { + keyForString: "str", + }, + } + ``` + * Number + ```ts + let want = { + bundleName: "com.example.demo", + abilityName: "com.example.demo.MainAbility", + parameters: { + keyForInt: 100, + keyForDouble: 99.99, + }, + } + ``` + * Boolean + ```ts + let want = { + bundleName: "com.example.demo", + abilityName: "com.example.demo.MainAbility", + parameters: { + keyForBool: true, + }, + } + ``` + * Object + ```ts + let want = { + bundleName: "com.example.demo", + abilityName: "com.example.demo.MainAbility", + parameters: { + keyForObject: { + keyForObjectString: "str", + keyForObjectInt: -200, + keyForObjectDouble: 35.5, + keyForObjectBool: false, + }, + }, + } + ``` + * Array + ```ts + let want = { + bundleName: "com.example.demo", + abilityName: "com.example.demo.MainAbility", + parameters: { + keyForArrayString: ["str1", "str2", "str3"], + keyForArrayInt: [100, 200, 300, 400], + keyForArrayDouble: [0.1, 0.2], + keyForArrayObject: [{obj1: "aaa"}, {obj2: 100}], + }, + } + ``` + * File descriptor (FD) + ```ts + import fileio from '@ohos.fileio'; + var fd; + try { + fd = fileio.openSync("/data/storage/el2/base/haps/pic.png"); + } catch(e) { + console.log("openSync fail:" + JSON.stringify(e)); + } + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry", // moduleName is optional. + "parameters": { + "keyFd":{"type":"FD", "value":fd} + } + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + + diff --git a/en/application-dev/reference/apis/js-apis-app-ability-wantAgent.md b/en/application-dev/reference/apis/js-apis-app-ability-wantAgent.md new file mode 100644 index 0000000000000000000000000000000000000000..ca2fe41baceb69cf60481b3c88cc4c2ceb13a198 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-wantAgent.md @@ -0,0 +1,1158 @@ +# @ohos.app.ability.wantAgent + +The **app.ability.WantAgent** module provides APIs for triggering, canceling, and comparing **WantAgent** objects. You can use the APIs to create a **WantAgent** object, and obtain the user ID, bundle name, and want information of the object. You are advised to use this module, since it will replace the [@ohos.wantAgent](js-apis-wantAgent.md) module in the near future. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; +``` + +## WantAgent.getWantAgent + +getWantAgent(info: WantAgentInfo, callback: AsyncCallback\): void + +Obtains a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | -------------------------- | ---- | ----------------------- | +| info | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain. | +| callback | AsyncCallback\ | Yes | Callback used to return the **WantAgent** object.| + + + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getWantAgent + +getWantAgent(info: WantAgentInfo): Promise\ + +Obtains a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type | Mandatory| Description | +| ---- | ------------- | ---- | ------------- | +| info | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the **WantAgent** object.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getBundleName + +getBundleName(agent: WantAgent, callback: AsyncCallback\): void + +Obtains the bundle name of a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | --------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + // getBundleName callback + function getBundleNameCallback(err, data) { + console.info("==========================>getBundleNameCallback=======================>"); + } + WantAgent.getBundleName(wantAgent, getBundleNameCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getBundleName + +getBundleName(agent: WantAgent): Promise\ + +Obtains the bundle name of a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the bundle name.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + + // WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.getBundleName(wantAgent).then((data) => { + console.info("==========================>getBundleNameCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getUid + +getUid(agent: WantAgent, callback: AsyncCallback\): void + +Obtains the user ID of a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ----------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the user ID.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + // getUid callback + function getUidCallback(err, data) { + console.info("==========================>getUidCallback=======================>"); + } + WantAgent.getUid(wantAgent, getUidCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getUid + +getUid(agent: WantAgent): Promise\ + +Obtains the user ID of a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the user ID.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + + // WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.getUid(wantAgent).then((data) => { + console.info("==========================>getUidCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getWant + +getWant(agent: WantAgent, callback: AsyncCallback\): void + +Obtains the want in a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the want.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + //getWant»Øµ÷ + function getWantCallback(err, data) { + console.info("==========================>getWantCallback=======================>"); + } + WantAgent.getWant(wantAgent, getWantCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.getWant + +getWant(agent: WantAgent): Promise\ + +Obtains the want in a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the want.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + + // WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.getWant(wantAgent).then((data) => { + console.info("==========================>getWantCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.cancel + +cancel(agent: WantAgent, callback: AsyncCallback\): void + +Cancels a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | --------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + // cancel callback + function cancelCallback(err, data) { + console.info("==========================>cancelCallback=======================>"); + } + WantAgent.cancel(wantAgent, cancelCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.cancel + +cancel(agent: WantAgent): Promise\ + +Cancels a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| + +**Return value** + +| Type | Description | +| --------------- | ------------------------------- | +| Promise\ | Promise used to return the result.| + +**Example** + +```ts +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.cancel(wantAgent).then((data) => { + console.info("==========================>cancelCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.trigger + +trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: AsyncCallback\): void + +Triggers a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ----------- | ----------------------------- | ---- | ------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| triggerInfo | TriggerInfo | Yes | **TriggerInfo** object. | +| callback | AsyncCallback\ | No | Callback used to return the result.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + // Trigger the callback. + function triggerCallback(data) { + console.info("==========================>triggerCallback=======================>"); + } + + + var triggerInfo = { + code:0 + } + WantAgent.trigger(wantAgent, triggerInfo, triggerCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.equal + +equal(agent: WantAgent, otherAgent: WantAgent, callback: AsyncCallback\): void + +Checks whether two **WantAgent** objects are equal. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------ | ---- | --------------------------------------- | +| agent | WantAgent | Yes | The first **WantAgent** object. | +| otherAgent | WantAgent | Yes | The second **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + +// WantAgent object +var wantAgent1; +var wantAgent2; + +// getWantAgent callback +function getWantAgentCallback(err, data) { + console.info("==========================>getWantAgentCallback=======================>"); + if (err.code == 0) { + wantAgent1 = data; + wantAgent2 = data; + } else { + console.info('----getWantAgent failed!----'); + } +} +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo, getWantAgentCallback) + + // equal callback + function equalCallback(err, data) { + console.info("==========================>equalCallback=======================>"); + } + WantAgent.equal(wantAgent1, wantAgent2, equalCallback) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + + + +## WantAgent.equal + +equal(agent: WantAgent, otherAgent: WantAgent): Promise\ + +Checks whether two **WantAgent** objects are equal. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | The first **WantAgent** object.| +| otherAgent | WantAgent | Yes | The second **WantAgent** object.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the result.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + + // WantAgent object +var wantAgent1; +var wantAgent2; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent1 = data; + wantAgent2 = data; + }); + + WantAgent.equal(wantAgent1, wantAgent2).then((data) => { + console.info("==========================>equalCallback=======================>"); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## WantAgent.getOperationType + +getOperationType(agent: WantAgent, callback: AsyncCallback\): void; + +Obtains the operation type of a **WantAgent** object. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------ | ---- | --------------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the operation type.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + +// WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.getOperationType(wantAgent, (OperationType) => { + console.log('----------- getOperationType ----------, OperationType: ' + OperationType); + }) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## WantAgent.getOperationType + +getOperationType(agent: WantAgent): Promise\; + +Obtains the operation type of a **WantAgent** object. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory| Description | +| ---------- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| + +**Return value** + +| Type | Description | +| ----------------------------------------------------------- | ------------------------------------------------------------ | +| Promise\ | Promise used to return the operation type.| + +**Example** + +```js +import WantAgent from '@ohos.app.ability.wantAgent'; + + // WantAgent object +var wantAgent; + +// WantAgentInfo object +var wantAgentInfo = { + wants: [ + { + deviceId: "deviceId", + bundleName: "com.neu.setResultOnAbilityResultTest1", + abilityName: "com.example.test.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true,true,false}", + parameters: + { + mykey0: 2222, + mykey1: [1, 2, 3], + mykey2: "[1, 2, 3]", + mykey3: "ssssssssssssssssssssssssss", + mykey4: [false, true, false], + mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"], + mykey6: true, + } + } + ], + operationType: WantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags:[WantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG] +} + +try { + WantAgent.getWantAgent(wantAgentInfo).then((data) => { + console.info("==========================>getWantAgentCallback=======================>"); + wantAgent = data; + }); + + WantAgent.getOperationType(wantAgent).then((OperationType) => { + console.log('getOperationType success, OperationType: ' + OperationType); + }).catch((err) => { + console.log('getOperationType fail, err: ' + err); + }) +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## WantAgentFlags + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ------------------- | -------------- | ------------------------------------------------------------ | +| ONE_TIME_FLAG | 0 | The **WantAgent** object can be used only once. | +| NO_BUILD_FLAG | 1 | The **WantAgent** object does not exist and hence it is not created. In this case, **null** is returned. | +| CANCEL_PRESENT_FLAG | 2 | The existing **WantAgent** object should be canceled before a new object is generated.| +| UPDATE_PRESENT_FLAG | 3 | Extra information of the existing **WantAgent** object is replaced with that of the new object.| +| CONSTANT_FLAG | 4 | The **WantAgent** object is immutable. | +| REPLACE_ELEMENT | 5 | The **element** attribute of the current **Want** can be replaced by the **element** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_ACTION | 6 | The **action** attribute of the current **Want** can be replaced by the **action** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_URI | 7 | The **uri** attribute of the current **Want** can be replaced by the **uri** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_ENTITIES | 8 | The **entities** attribute of the current **Want** can be replaced by the **entities** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_BUNDLE | 9 | The **bundleName** attribute of the current **Want** can be replaced by the **bundleName** attribute of **Want** in **WantAgent.trigger()**.| + + + +## OperationType + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------- | ------------- | ------------------------- | +| UNKNOWN_TYPE | 0 | Unknown operation type. | +| START_ABILITY | 1 | Starts an ability with a UI.| +| START_ABILITIES | 2 | Starts multiple abilities with a UI.| +| START_SERVICE | 3 | Starts an ability without a UI.| +| SEND_COMMON_EVENT | 4 | Sends a common event. | + + + +## CompleteData + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------ | ---- | ---------------------- | +| info | WantAgent | Yes | A triggered **WantAgent** object. | +| want | Want | Yes | An existing triggered **want**. | +| finalCode | number | Yes | Request code that triggers the **WantAgent** object.| +| finalData | string | No | Final data collected by the common event. | +| extraInfo | {[key: string]: any} | No | Extra information. | diff --git a/en/application-dev/reference/apis/js-apis-app-ability-wantConstant.md b/en/application-dev/reference/apis/js-apis-app-ability-wantConstant.md new file mode 100644 index 0000000000000000000000000000000000000000..ece4baa69e5d3b2883e971655e2367e23acf7812 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-ability-wantConstant.md @@ -0,0 +1,95 @@ +# @ohos.app.ability.wantConstant + +The **wantConstant** module provides the actions, entities, and flags used in **Want** objects. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```js +import wantConstant from '@ohos.app.ability.wantConstant'; +``` + +## wantConstant.Action + +Enumerates the action constants of the **Want** object. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Value | Description | +| ------------ | ------------------ | ---------------------- | +| ACTION_HOME | ohos.want.action.home | Action of returning to the home page. | +| ACTION_DIAL | ohos.want.action.dial | Action of launching the numeric keypad. | +| ACTION_SEARCH | ohos.want.action.search | Action of launching the search function. | +| ACTION_WIRELESS_SETTINGS | ohos.settings.wireless | Action of launching the UI that provides wireless network settings, for example, Wi-Fi options. | +| ACTION_MANAGE_APPLICATIONS_SETTINGS | ohos.settings.manage.applications | Action of launching the UI for managing installed applications. | +| ACTION_APPLICATION_DETAILS_SETTINGS | ohos.settings.application.details | Action of launching the UI that displays the details of an application. | +| ACTION_SET_ALARM | ohos.want.action.setAlarm | Action of launching the UI for setting the alarm clock. | +| ACTION_SHOW_ALARMS | ohos.want.action.showAlarms | Action of launching the UI that displays all alarms. | +| ACTION_SNOOZE_ALARM | ohos.want.action.snoozeAlarm | Action of launching the UI for snoozing an alarm. | +| ACTION_DISMISS_ALARM | ohos.want.action.dismissAlarm | Action of launching the UI for deleting an alarm. | +| ACTION_DISMISS_TIMER | ohos.want.action.dismissTimer | Action of launching the UI for dismissing a timer. | +| ACTION_SEND_SMS | ohos.want.action.sendSms | Action of launching the UI for sending an SMS message. | +| ACTION_CHOOSE | ohos.want.action.choose | Action of launching the UI for opening a contact or picture. | +| ACTION_IMAGE_CAPTURE | ohos.want.action.imageCapture | Action of launching the UI for photographing. | +| ACTION_VIDEO_CAPTURE | ohos.want.action.videoCapture | Action of launching the UI for shooting a video. | +| ACTION_SELECT | ohos.want.action.select | Action of launching the UI for application selection. | +| ACTION_SEND_DATA | ohos.want.action.sendData | Action of launching the UI for sending a single data record. | +| ACTION_SEND_MULTIPLE_DATA | ohos.want.action.sendMultipleData | Action of launching the UI for sending multiple data records. | +| ACTION_SCAN_MEDIA_FILE | ohos.want.action.scanMediaFile | Action of requesting a media scanner to scan a file and add the file to the media library. | +| ACTION_VIEW_DATA | ohos.want.action.viewData | Action of viewing data. | +| ACTION_EDIT_DATA | ohos.want.action.editData | Action of editing data. | +| INTENT_PARAMS_INTENT | ability.want.params.INTENT | Action of displaying selection options with an action selector. | +| INTENT_PARAMS_TITLE | ability.want.params.TITLE | Title of the character sequence dialog box used with the action selector. | +| ACTION_FILE_SELECT | ohos.action.fileSelect | Action of selecting a file. | +| PARAMS_STREAM | ability.params.stream | URI of the data stream associated with the target when the data is sent. | | +| ACTION_APP_ACCOUNT_AUTH | account.appAccount.action.auth | Action of providing the authentication service. | +| ACTION_MARKET_DOWNLOAD | ohos.want.action.marketDownload | Action of downloading an application from the application market.
**System API**: This is a system API and cannot be called by third-party applications. | +| ACTION_MARKET_CROWDTEST | ohos.want.action.marketCrowdTest | Action of crowdtesting an application from the application market.
**System API**: This is a system API and cannot be called by third-party applications. | +| DLP_PARAMS_SANDBOX |ohos.dlp.params.sandbox | Action of obtaining the sandbox flag.
**System API**: This is a system API and cannot be called by third-party applications. | +| DLP_PARAMS_BUNDLE_NAME |ohos.dlp.params.bundleName |Action of obtaining the DLP bundle name.
**System API**: This is a system API and cannot be called by third-party applications. | +| DLP_PARAMS_MODULE_NAME |ohos.dlp.params.moduleName |Action of obtaining the DLP module name.
**System API**: This is a system API and cannot be called by third-party applications. | +| DLP_PARAMS_ABILITY_NAME |ohos.dlp.params.abilityName |Action of obtaining the DLP ability name.
**System API**: This is a system API and cannot be called by third-party applications. | +| DLP_PARAMS_INDEX |ohos.dlp.params.index |Action of obtaining the DLP index.
**System API**: This is a system API and cannot be called by third-party applications. | + +## wantConstant.Entity + +Enumerates the entity constants of the **Want** object. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Value | Description | +| ------------ | ------------------ | ---------------------- | +| ENTITY_DEFAULT | entity.system.default | Default entity. The default entity is used if no entity is specified. | +| ENTITY_HOME | entity.system.home | Home screen entity. | +| ENTITY_VOICE | entity.system.voice | Voice interaction entity. | +| ENTITY_BROWSABLE | entity.system.browsable | Browser type entity. | +| ENTITY_VIDEO | entity.system.video | Video type entity. | + + +## wantConstant.Flags + +Describes flags. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Value | Description | +| ------------------------------------ | ---------- | ------------------------------------------------------------ | +| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. | +| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write data to the URI. | +| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability. | +| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be continued on a remote device. | +| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. | +| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates that an ability is enabled. | +| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent.
**System API**: This is a system API and cannot be called by third-party applications. | +| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching.
**System API**: This is a system API and cannot be called by third-party applications.| +| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler. | +| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started. | +| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible.
**System API**: This is a system API and cannot be called by third-party applications. | +| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed. | +| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed. | +| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object in the **startAbility** API passed to [ohos.app.Context](js-apis-ability-context.md) and must be used together with **flag_ABILITY_NEW_MISSION**.| +| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Indicates the operation of creating a mission on the history mission stack. | +| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Starts the mission on the top of the existing mission stack; creates an ability instance if no mission exists.| diff --git a/en/application-dev/reference/apis/js-apis-app-form-formBindingData.md b/en/application-dev/reference/apis/js-apis-app-form-formBindingData.md new file mode 100644 index 0000000000000000000000000000000000000000..bf3f9cbb803b4bed60bba43d88813e6acf38fcb2 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-form-formBindingData.md @@ -0,0 +1,67 @@ +# @ohos.app.form.formBindingData + +The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import formBindingData from '@ohos.app.form.formBindingData'; +``` + +## FormBindingData + +Describes a **FormBindingData** object. + +**System capability**: SystemCapability.Ability.Form + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | Object | Yes| Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format.| + + +## createFormBindingData + +createFormBindingData(obj?: Object | string): FormBindingData + +Creates a **FormBindingData** object. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------- | ---- | ------------------------------------------------------------ | +| obj | Object\|string | No | Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by "formImages", and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {"formImages": {"key1": fd1, "key2": fd2}}.| + + +**Return value** + +| Type | Description | +| ----------------------------------- | --------------------------------------- | +| [FormBindingData](#formbindingdata) | **FormBindingData** object created based on the passed data.| + + +**Example** + +```ts +import featureAbility from '@ohos.ability.featureAbility'; +import fileio from '@ohos.fileio'; +let context=featureAbility.getContext(); +context.getOrCreateLocalDir((err,data)=>{ + let path=data+"/xxx.jpg"; + let fd = fileio.openSync(path); + let obj = { + "temperature": "21°", + "formImages": {"image": fd} + }; + try { + formBindingData.createFormBindingData(obj); + } catch (error) { + console.log(`catch err->${JSON.stringify(err)}`); + } +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-app-form-formExtensionAbility.md b/en/application-dev/reference/apis/js-apis-app-form-formExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..c2bedd6d4dc1b50b6575120b88c0ab88423e7846 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-form-formExtensionAbility.md @@ -0,0 +1,283 @@ +# @ohos.app.form.FormExtensionAbility + +The **FormExtensionAbility** module provides APIs related to Form Extension abilities. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; +``` + +## Attributes + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable| Writable| Description | +| ------- | ------------------------------------------------------- | ---- | ---- | --------------------------------------------------- | +| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the **FormExtensionAbility**. This context is inherited from **ExtensionContext**.| + +## onAddForm + +onAddForm(want: Want): formBindingData.FormBindingData + +Called to notify the widget provider that a **Form** instance (widget) has been created. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-want.md) | Yes | Information related to the Extension ability, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------- | +| [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| + +**Example** + +```ts +import FormExtensionAbility from '@ohos.app.form.FormExtensionAbility'; +export default class MyFormExtensionAbility extends FormExtensionAbility { + onAddForm(want) { + console.log('FormExtensionAbility onAddForm, want:' + want.abilityName); + let dataObj1 = { + temperature:"11c", + "time":"11:00" + }; + let obj1 = formBindingData.createFormBindingData(dataObj1); + return obj1; + } +} +``` + +## onCastToNormalForm + +onCastToNormalForm(formId: string): void + +Called to notify the widget provider that a temporary widget has been converted to a normal one. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------ | +| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| + +**Example** + +```ts +export default class MyFormExtensionAbility extends FormExtensionAbility { + onCastToNormalForm(formId) { + console.log('FormExtensionAbility onCastToNormalForm, formId:' + formId); + } +} +``` + +## onUpdateForm + +onUpdateForm(formId: string): void + +Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) class to update the widget data. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| formId | string | Yes | ID of the widget that requests to be updated.| + +**Example** + +```ts +import formBindingData from '@ohos.app.form.formBindingData' +export default class MyFormExtensionAbility extends FormExtensionAbility { + onUpdateForm(formId) { + console.log('FormExtensionAbility onUpdateForm, formId:' + formId); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2).then((data)=>{ + console.log('FormExtensionAbility context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + } +} +``` + +## onChangeFormVisibility + +onChangeFormVisibility(newStatus: { [key: string]: number }): void + +Called to notify the widget provider of the change of visibility. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------------------------- | ---- | ---------------------------- | +| newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| + +**Example** + +```ts +import formBindingData from '@ohos.app.form.formBindingData' +export default class MyFormExtensionAbility extends FormExtensionAbility { + onChangeFormVisibility(newStatus) { + console.log('FormExtensionAbility onChangeFormVisibility, newStatus:' + newStatus); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + + for (let key in newStatus) { + console.log('FormExtensionAbility onChangeFormVisibility, key:' + key + ", value=" + newStatus[key]); + this.context.updateForm(key, obj2).then((data)=>{ + console.log('FormExtensionAbility context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + } + } +} +``` + +## onFormEvent + +onFormEvent(formId: string, message: string): void + +Called to instruct the widget provider to receive and process the widget event. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ---------------------- | +| formId | string | Yes | ID of the widget that requests the event.| +| message | string | Yes | Event message. | + +**Example** + +```ts +export default class MyFormExtension extends FormExtensionAbility { + onFormEvent(formId, message) { + console.log('FormExtensionAbility onFormEvent, formId:' + formId + ", message:" + message); + } +} +``` + +## onRemoveForm + +onRemoveForm(formId: string): void + +Called to notify the widget provider that a **Form** instance (widget) has been destroyed. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| formId | string | Yes | ID of the widget to be destroyed.| + +**Example** + +```ts +export default class MyFormExtensionAbility extends FormExtensionAbility { + onRemoveForm(formId) { + console.log('FormExtensionAbility onRemoveForm, formId:' + formId); + } +} +``` + +## onConfigurationUpdate + +onConfigurationUpdate(newConfig: Configuration): void; + +Called when the configuration of the environment where the ability is running is updated. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| newConfig | [Configuration](js-apis-configuration.md) | Yes| New configuration.| + +**Example** + +```ts +class MyFormExtensionAbility extends FormExtensionAbility { + onConfigurationUpdate(config) { + console.log('onConfigurationUpdate, config:' + JSON.stringify(config)); + } +} +``` + +## onAcquireFormState + +onAcquireFormState?(want: Want): formInfo.FormState; + +Called when the widget provider receives the status query result of a widget. By default, the initial state is returned. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| + +**Example** + +```ts +import formInfo from '@ohos.app.form.formInfo'; +class MyFormExtensionAbility extends FormExtensionAbility { + onAcquireFormState(want) { + console.log('FormExtensionAbility onAcquireFormState, want:' + want); + return formInfo.FormState.UNKNOWN; + } +} +``` + +## onShareForm + +onShareForm?(formId: string): { [key: string]: any } + +Called by the widget provider to receive shared widget data. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------- | +| {[key: string]: any} | Data to be shared by the widget, in the form of key-value pairs.| + +**Example** + +```ts +class MyFormExtensionAbility extends FormExtensionAbility { + onShareForm(formId) { + console.log('FormExtensionAbility onShareForm, formId:' + formId); + let wantParams = { + "temperature":"20", + "time":"2022-8-8 09:59", + }; + return wantParams; + } +} +``` diff --git a/en/application-dev/reference/apis/js-apis-app-form-formHost.md b/en/application-dev/reference/apis/js-apis-app-form-formHost.md new file mode 100644 index 0000000000000000000000000000000000000000..84ff89f88c678312bf5e398d6553f2dff38a1ec1 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-form-formHost.md @@ -0,0 +1,1476 @@ +# @ohos.app.form.formHost + +The **FormHost** module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets installed by the same user, and obtain widget information and status. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs provided by this module are system APIs. + +## Modules to Import + +```ts +import formHost from '@ohos.app.form.formHost'; +``` + +## deleteForm + +deleteForm(formId: string, callback: AsyncCallback<void>): void + +Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.deleteForm(formId, (error, data) => { + if (error) { + console.log('formHost deleteForm, error:' + JSON.stringify(error)); + } else { + console.log('formHost deleteForm success'); + } + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} + +``` + +## deleteForm + +deleteForm(formId: string): Promise<void> + +Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Parameters** + +```ts +try { + var formId = "12400633174999288"; + formHost.deleteForm(formId).then(() => { + console.log('formHost deleteForm success'); + }).catch((error) => { + console.log('formHost deleteForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## releaseForm + +releaseForm(formId: string, callback: AsyncCallback<void>): void + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.releaseForm(formId, (error, data) => { + if (error) { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | ----------- | +| formId | string | Yes | Widget ID. | +| isReleaseCache | boolean | Yes | Whether to release the cache.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.releaseForm(formId, true, (error, data) => { + if (error) { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | ----------- | +| formId | string | Yes | Widget ID. | +| isReleaseCache | boolean | No | Whether to release the cache.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.releaseForm(formId, true).then(() => { + console.log('formHost releaseForm success'); + }).catch((error) => { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## requestForm + +requestForm(formId: string, callback: AsyncCallback<void>): void + +Requests a widget update. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.requestForm(formId, (error, data) => { + if (error) { + console.log('formHost requestForm, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## requestForm + +requestForm(formId: string): Promise<void> + +Requests a widget update. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.requestForm(formId).then(() => { + console.log('formHost requestForm success'); + }).catch((error) => { + console.log('formHost requestForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} + +``` + +## castToNormalForm + +castToNormalForm(formId: string, callback: AsyncCallback<void>): void + +Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.castToNormalForm(formId, (error, data) => { + if (error) { + console.log('formHost castTempForm, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## castToNormalForm + +castToNormalForm(formId: string): Promise<void> + +Converts a temporary widget to a normal one. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.castToNormalForm(formId).then(() => { + console.log('formHost castTempForm success'); + }).catch((error) => { + console.log('formHost castTempForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyVisibleForms + +notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.notifyVisibleForms(formId, (error, data) => { + if (error) { + console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyVisibleForms + +notifyVisibleForms(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.notifyVisibleForms(formId).then(() => { + console.log('formHost notifyVisibleForms success'); + }).catch((error) => { + console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyInvisibleForms + +notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.notifyInvisibleForms(formId, (error, data) => { + if (error) { + console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyInvisibleForms + +notifyInvisibleForms(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.notifyInvisibleForms(formId).then(() => { + console.log('formHost notifyInvisibleForms success'); + }).catch((error) => { + console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## enableFormsUpdate + +enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.enableFormsUpdate(formId, (error, data) => { + if (error) { + console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## enableFormsUpdate + +enableFormsUpdate(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.enableFormsUpdate(formId).then(() => { + console.log('formHost enableFormsUpdate success'); + }).catch((error) => { + console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## disableFormsUpdate + +disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget not updatable, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.disableFormsUpdate(formId, (error, data) => { + if (error) { + console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## disableFormsUpdate + +disableFormsUpdate(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + var formId = ["12400633174999288"]; + formHost.disableFormsUpdate(formId).then(() => { + console.log('formHost disableFormsUpdate success'); + }).catch((error) => { + console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## isSystemReady + +isSystemReady(callback: AsyncCallback<void>): void + +Checks whether the system is ready. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.isSystemReady((error, data) => { + if (error) { + console.log('formHost isSystemReady, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## isSystemReady + +isSystemReady(): Promise<void> + +Checks whether the system is ready. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +try { + var formId = "12400633174999288"; + formHost.isSystemReady().then(() => { + console.log('formHost isSystemReady success'); + }).catch((error) => { + console.log('formHost isSystemReady, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getAllFormsInfo + +getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Example** + +```ts +try { + formHost.getAllFormsInfo((error, data) => { + if (error) { + console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getAllFormsInfo, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getAllFormsInfo + +getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> + +Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| + +**Example** + +```ts +try { + formHost.getAllFormsInfo().then((data) => { + console.log('formHost getAllFormsInfo data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getFormsInfo + +getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + formHost.getFormsInfo("com.example.ohos.formjsdemo", (error, data) => { + if (error) { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| moduleName | string | Yes| Module name.| +| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry", (error, data) => { + if (error) { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> + +Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| moduleName | string | No| Module name.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +try { + formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry").then((data) => { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## deleteInvalidForms + +deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void + +Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of valid widget IDs.| +| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **err** is undefined and **data** is the number of widgets deleted; otherwise, **err** is an error object.| + +**Example** + +```ts +try { + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.deleteInvalidForms(formIds, (error, data) => { + if (error) { + console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); + } else { + console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## deleteInvalidForms + +deleteInvalidForms(formIds: Array<string>): Promise<number> + +Deletes invalid widgets from the list. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of valid widget IDs.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<number> | Promise used to return the number of widgets deleted.| + +**Example** + +```ts +try { + var formIds = new Array("12400633174999288", "12400633174999289"); + formHost.deleteInvalidForms(formIds).then((data) => { + console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## acquireFormState + +acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void + +Obtains the widget state. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| +| callback | AsyncCallback<[FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **err** is undefined and **data** is the widget state obtained; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var want = { + "deviceId": "", + "bundleName": "ohos.samples.FormApplication", + "abilityName": "FormAbility", + "parameters": { + "ohos.extra.param.key.module_name": "entry", + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.form_dimension": 2 + } +}; +try { + formHost.acquireFormState(want, (error, data) => { + if (error) { + console.log('formHost acquireFormState, error:' + JSON.stringify(error)); + } else { + console.log('formHost acquireFormState, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## acquireFormState + +acquireFormState(want: Want): Promise<formInfo.FormStateInfo> + +Obtains the widget state. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<[FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var want = { + "deviceId": "", + "bundleName": "ohos.samples.FormApplication", + "abilityName": "FormAbility", + "parameters": { + "ohos.extra.param.key.module_name": "entry", + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.form_dimension": 2 + } +}; +try { + formHost.acquireFormState(want).then((data) => { + console.log('formHost acquireFormState, data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost acquireFormState, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## on("formUninstall") + +on(type: "formUninstall", callback: Callback<string>): void + +Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| type | string | Yes | Event type. The value **formUninstall** indicates a widget uninstallation event.| +| callback | Callback<string> | Yes| Callback used to return the widget ID.| + +**Example** + +```ts +let callback = function(formId) { + console.log('formHost on formUninstall, formId:' + formId); +} +formHost.on("formUninstall", callback); +``` + +## off("formUninstall") + +off(type: "formUninstall", callback?: Callback<string>): void + +Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| type | string | Yes | Event type. The value **formUninstall** indicates a widget uninstallation event.| +| callback | Callback<string> | No| Callback used to return the widget ID. If it is left unspecified, it indicates the callback for all the events that have been subscribed.| + +**Example** + +```ts +let callback = function(formId) { + console.log('formHost on formUninstall, formId:' + formId); +} +formHost.off("formUninstall", callback); +``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void + +Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isVisible | boolean | Yes | Whether to make the widgets visible.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +try { + formHost.notifyFormsVisible(formIds, true, (error, data) => { + if (error) { + console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> + +Instructs the widgets to make themselves visible. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isVisible | boolean | Yes | Whether to make the widgets visible.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +try { + formHost.notifyFormsVisible(formIds, true).then(() => { + console.log('formHost notifyFormsVisible success'); + }).catch((error) => { + console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void + +Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +try { + formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { + if (error) { + console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> + +Instructs the widgets to enable or disable updates. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +try { + formHost.notifyFormsEnableUpdate(formIds, true).then(() => { + console.log('formHost notifyFormsEnableUpdate success'); + }).catch((error) => { + console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` +## shareForm + +shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void + +Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **err** is undefined; otherwise, **err** is an error object.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + + +**Example** + +```ts +var formId = "12400633174999288"; +var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; +try { + formHost.shareForm(formId, deviceId, (error, data) => { + if (error) { + console.log('formHost shareForm, error:' + JSON.stringify(error)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## shareForm + +shareForm(formId: string, deviceId: string): Promise<void> + +Shares a specified widget with a remote device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.DISTRIBUTED_DATASYNC + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Parameters** + +```ts +var formId = "12400633174999288"; +var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; +try { + formHost.shareForm(formId, deviceId).then(() => { + console.log('formHost shareForm success'); + }).catch((error) => { + console.log('formHost shareForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## notifyFormsPrivacyProtected + +notifyFormsPrivacyProtected(formIds: Array\, isProtected: boolean, callback: AsyncCallback\): void + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +try { + formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { + console.log('formHost shareForm success'); + }).catch((error) => { + console.log('formHost shareForm, error:' + JSON.stringify(error)); + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-app-form-formInfo.md b/en/application-dev/reference/apis/js-apis-app-form-formInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..5f1ff73b163ffd2c1c5b0feeb1c26a4f3f60cb78 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-form-formInfo.md @@ -0,0 +1,141 @@ +# @ohos.app.form.formInfo + +The **FormInfo** module provides widget information and state. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import formInfo from '@ohos.app.form.formInfo'; +``` + +## FormInfo + +Describes widget information. + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable | Writable | Description | +| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | +| bundleName | string | Yes | No | Name of the bundle to which the widget belongs. | +| moduleName | string | Yes | No | Name of the module to which the widget belongs. | +| abilityName | string | Yes | No | Name of the ability to which the widget belongs. | +| name | string | Yes | No | Widget name. | +| description | string | Yes | No | Description of the widget. | +| type | [FormType](#formtype) | Yes | No | Type of the widget. Currently, only JS widgets are supported.| +| jsComponentName | string | Yes | No | Name of the component used in the JS widget. | +| colorMode | [ColorMode](#colormode) | Yes | No | Color mode of the widget. | +| isDefault | boolean | Yes | No | Whether the widget is the default one. | +| updateEnabled | boolean | Yes | No | Whether the widget is updatable. | +| formVisibleNotify | string | Yes | No | Whether to send a notification when the widget is visible. | +| relatedBundleName | string | Yes | No | Name of the associated bundle to which the widget belongs. | +| scheduledUpdateTime | string | Yes | No | Time when the widget was updated. | +| formConfigAbility | string | Yes | No | Configuration ability of the widget, that is, the ability corresponding to the option in the selection box displayed when the widget is long pressed. | +| updateDuration | string | Yes | No | Update period of the widget.| +| defaultDimension | number | Yes | No | Default dimension of the widget. | +| supportDimensions | Array<number> | Yes | No | Dimensions supported by the widget. For details, see [FormDimension](#formdimension). | +| customizeData | {[key: string]: [value: string]} | Yes | No | Custom data of the widget. | + +## FormType + +Enumerates the widget types. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| JS | 1 | JS widget. | +| eTS | 2 | eTS widget.| + +## ColorMode + +Enumerates the color modes supported by the widget. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| MODE_AUTO | -1 | Auto mode. | +| MODE_DARK | 0 | Dark mode. | +| MODE_LIGHT | 1 | Light mode. | + +## FormStateInfo + +Describes the widget state information. + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable | Writable | Description | +| ----------- | -------- | -------- | -------------------- | ------------------------------------------------------------ | +| formState | [FormState](#formstate) | Yes | No | Widget state. | +| want | Want | Yes | No | Want text. | + +## FormState + +Enumerates the widget states. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| UNKNOWN | -1 | Unknown state. | +| DEFAULT | 0 | Default state. | +| READY | 1 | Ready state. | + +## FormParam + +Enumerates the widget parameters. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| IDENTITY_KEY | "ohos.extra.param.key.form_identity" | Widget ID. | +| DIMENSION_KEY | "ohos.extra.param.key.form_dimension" | Widget dimension. | +| NAME_KEY | "ohos.extra.param.key.form_name" | Widget name. | +| MODULE_NAME_KEY | "ohos.extra.param.key.module_name" | Name of the module to which the widget belongs. | +| WIDTH_KEY | "ohos.extra.param.key.form_width" | Widget width. | +| HEIGHT_KEY | "ohos.extra.param.key.form_height" | Widget height. | +| TEMPORARY_KEY | "ohos.extra.param.key.form_temporary" | Temporary widget. | +| ABILITY_NAME_KEY | "ohos.extra.param.key.ability_name" | Ability name. | +| DEVICE_ID_KEY | "ohos.extra.param.key.device_id" | Device ID.
**System API**: This is a system API. | +| BUNDLE_NAME_KEY | "ohos.extra.param.key.bundle_name" | Key that specifies the target bundle name.| + +## FormDimension + +Enumerates the widget dimensions. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| Dimension_1_2 | 1 | 1 x 2. | +| Dimension_2_2 | 2 | 2 x 2. | +| Dimension_2_4 | 3 | 2 x 4. | +| Dimension_4_4 | 4 | 4 x 4. | +| Dimension_2_1 | 5 | 2 x 1. | + + +## FormInfoFilter + +Defines the widget information filter. Only the widget information that meets the filter is returned. + +**System capability**: SystemCapability.Ability.Form + +| Name | Description | +| ----------- | ------------ | +| moduleName | Only the information about the widget whose **moduleName** is the same as the provided value is returned.| + +## VisibilityType + +Enumerates the visibility types of the widget. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| FORM_VISIBLE | 1 | The widget is visible.| +| FORM_INVISIBLE | 2 | The widget is invisible.| diff --git a/en/application-dev/reference/apis/js-apis-app-form-formProvider.md b/en/application-dev/reference/apis/js-apis-app-form-formProvider.md new file mode 100644 index 0000000000000000000000000000000000000000..2cd47084ef64cd6ff22f5338706688b2fd5b51e8 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-app-form-formProvider.md @@ -0,0 +1,562 @@ +# @ohos.app.form.formProvider + +The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release. + +> **NOTE** +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import formProvider from '@ohos.app.form.formProvider'; +``` + +## setFormNextRefreshTime + +setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void + +Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| formId | string | Yes | Widget ID. | +| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formId = "12400633174999288"; +try { + formProvider.setFormNextRefreshTime(formId, 5, (error, data) => { + if (error) { + console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); + } else { + console.log(`formProvider setFormNextRefreshTime success`); + } + }); +} catch (error) { + console.log("error" + JSON.stringify(error)) +} +``` + +## setFormNextRefreshTime + +setFormNextRefreshTime(formId: string, minute: number): Promise<void> + +Sets the next refresh time for a widget. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| formId | string | Yes | Widget ID. | +| minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | + +**Return value** + +| Type | Description | +| ------------- | ---------------------------------- | +| Promise\ | Promise that returns no value. | + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var formId = "12400633174999288"; +try { + formProvider.setFormNextRefreshTime(formId, 5).then(() => { + console.log('formProvider setFormNextRefreshTime success'); + }).catch((error) => { + console.log('formProvider setFormNextRefreshTime, error:' + JSON.stringify(error)); + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void + +Updates a widget. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| formId | string | Yes | ID of the widget to update.| +| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData'; +var formId = "12400633174999288"; +try { + let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + formProvider.updateForm(formId, obj, (error, data) => { + if (error) { + console.log('formProvider updateForm, error:' + JSON.stringify(error)); + } else { + console.log(`formProvider updateForm success`); + } + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## updateForm + +updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> + +Updates a widget. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| formId | string | Yes | ID of the widget to update.| +| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | + +**Return value** + +| Type | Description | +| -------------- | ----------------------------------- | +| Promise\ | Promise that returns no value.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData'; +var formId = "12400633174999288"; +let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); +try { + formProvider.updateForm(formId, obj).then(() => { + console.log('formProvider updateForm success'); + }).catch((error) => { + console.log('formProvider updateForm, error:' + JSON.stringify(error)); + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getFormsInfo + +getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + + +**Example** + +```ts +try { + formProvider.getFormsInfo((error, data) => { + if (error) { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); + } + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` +## getFormsInfo + +getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | Yes| Filter criterion.| +| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +import formInfo from '@ohos.application.formInfo'; +const filter : formInfo.FormInfoFilter = { + // get info of forms belong to module entry. + moduleName : "entry" +}; +try { + formProvider.getFormsInfo(filter, (error, data) => { + if (error) { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); + } + }); +} catch(error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## getFormsInfo + +getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> + +Obtains the application's widget information on the device. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| filter | [formInfo.FormInfoFilter](js-apis-app-form-formInfo.md#forminfofilter) | No| Filter criterion.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Promise used to return the information obtained.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +import formInfo from '@ohos.application.formInfo'; +const filter : formInfo.FormInfoFilter = { + // get info of forms belong to module entry. + moduleName : "entry" +}; +try { + formProvider.getFormsInfo(filter).then((data) => { + console.log('formProvider getFormsInfo, data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## requestPublishForm + +requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void + +Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. + +**System capability**: SystemCapability.Ability.Form + +**System API**: This is a system API. + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ---------------------------------------------------------------------- | ---- | ---------------- | +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.| +| callback | AsyncCallback<string> | Yes| Callback used to return the widget ID.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData'; +var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } +}; +try { + let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + formProvider.requestPublishForm(want, obj, (error, data) => { + if (error) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## requestPublishForm + +requestPublishForm(want: Want, callback: AsyncCallback<string>): void + +Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. + +**System capability**: SystemCapability.Ability.Form + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| callback | AsyncCallback<string> | Yes | Callback used to return the widget ID.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } +}; +try { + formProvider.requestPublishForm(want, (error, data) => { + if (error) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} + +``` + +## requestPublishForm + +requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string> + +Requests to publish a widget to the widget host. This API uses a promise to return the result. This API is usually called by the home screen. + +**System capability**: SystemCapability.Ability.Form + +**System API**: This is a system API. + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | No | Data used for creating the widget. | + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<string> | Promise used to return the widget ID.| + +**Error codes** + +| Error Code ID| Error Message| +| -------- | -------- | +| 401 | If the input parameter is not valid parameter. | +For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md). + +**Example** + +```ts +var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } +}; +try { + formProvider.requestPublishForm(want).then((data) => { + console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); + }).catch((error) => { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## isRequestPublishFormSupported + +isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void + +Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the widget can be published to the widget host.| + +**Example** + +```ts +try { + formProvider.isRequestPublishFormSupported((error, isSupported) => { + if (error) { + console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); + } else { + if (isSupported) { + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + try { + formProvider.requestPublishForm(want, (error, data) => { + if (error) { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + } else { + console.log('formProvider requestPublishForm, form ID is: ' + JSON.stringify(data)); + } + }); + } catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); + } + + } + } +}); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` + +## isRequestPublishFormSupported + +isRequestPublishFormSupported(): Promise<boolean> + +Checks whether a widget can be published to the widget host. This API uses a promise to return the result. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<boolean> | Promise used to return whether the widget can be published to the widget host.| + +**Example** + +```ts +try { + formProvider.isRequestPublishFormSupported().then((isSupported) => { + if (isSupported) { + var want = { + abilityName: "FormAbility", + parameters: { + "ohos.extra.param.key.form_dimension": 2, + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.module_name": "entry" + } + }; + try { + formProvider.requestPublishForm(want).then((data) => { + console.log('formProvider requestPublishForm success, form ID is :' + JSON.stringify(data)); + }).catch((error) => { + console.log('formProvider requestPublishForm, error: ' + JSON.stringify(error)); + }); + } catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); + } + + } + }).catch((error) => { + console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); + }); +} catch (error) { + console.log(`catch err->${JSON.stringify(error)}`); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-application-EnvironmentCallback.md b/en/application-dev/reference/apis/js-apis-application-EnvironmentCallback.md index f0d75fc57deed25160bbb080ef1565a45a94679d..e1d2033c652d413ddac9933e32c3c53c1372f443 100644 --- a/en/application-dev/reference/apis/js-apis-application-EnvironmentCallback.md +++ b/en/application-dev/reference/apis/js-apis-application-EnvironmentCallback.md @@ -1,16 +1,16 @@ -# EnvironmentCallback +# @ohos.application.EnvironmentCallback The **EnvironmentCallback** module provides the **onConfigurationUpdated** API for the application context to listen for system environment changes. > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.EnvironmentCallback](js-apis-app-ability-environmentCallback.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. ## Modules to Import -```js +```ts import EnvironmentCallback from "@ohos.application.EnvironmentCallback"; ``` @@ -25,21 +25,20 @@ Called when the system environment changes. **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | config | [Configuration](js-apis-configuration.md) | Yes| **Configuration** object after the change.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| config | [Configuration](js-apis-application-configuration.md) | Yes| **Configuration** object after the change.| -**Example** - +**Example** - ```js -import AbilityStage from "@ohos.application.AbilityStage"; + ```ts +import Ability from "@ohos.application.Ability"; var callbackId; -export default class MyAbilityStage extends AbilityStage { +export default class MyAbility extends Ability { onCreate() { - console.log("MyAbilityStage onCreate") + console.log("MyAbility onCreate") globalThis.applicationContext = this.context.getApplicationContext(); let EnvironmentCallback = { onConfigurationUpdated(config){ diff --git a/en/application-dev/reference/apis/js-apis-application-StartOptions.md b/en/application-dev/reference/apis/js-apis-application-StartOptions.md index 39f44f65437b6b91ce457228fa12153d10aed3e6..40ad2a516377faf476cfe688914afe3cd3eccb6c 100644 --- a/en/application-dev/reference/apis/js-apis-application-StartOptions.md +++ b/en/application-dev/reference/apis/js-apis-application-StartOptions.md @@ -1,15 +1,15 @@ -# StartOptions +# @ohos.application.StartOptions The **StartOptions** module implements ability startup options. > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.StartOptions](js-apis-app-ability-startOptions.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. ## Modules to Import -``` +```ts import StartOptions from '@ohos.application.StartOptions'; ``` @@ -17,7 +17,7 @@ import StartOptions from '@ohos.application.StartOptions'; **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name| Readable| Writable| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -------- | -------- | -| [windowMode](js-apis-application-abilityConstant.md#abilityconstantwindowmode) | Yes| No| number | No| Window mode.| -| displayId | Yes| No| number | No| Display ID.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| [windowMode](js-apis-application-abilityConstant.md#abilityconstantwindowmode) | number | No| Window mode.| +| displayId | number | No| Display ID.| diff --git a/en/application-dev/reference/apis/js-apis-application-Want.md b/en/application-dev/reference/apis/js-apis-application-Want.md index 9275473cd14727d8a3e8f16327d2020a1adefb4d..620885945b572e8129e4f8c61b156ef658a6805d 100644 --- a/en/application-dev/reference/apis/js-apis-application-Want.md +++ b/en/application-dev/reference/apis/js-apis-application-Want.md @@ -1,14 +1,14 @@ -# Want +# @ohos.application.Want -The **Want** module provides the basic communication component of the system. +Want is a carrier for information transfer between objects (application components). Want can be used as a parameter of **startAbility** to specify a startup target and information that needs to be carried during startup, for example, **bundleName** and **abilityName**, which respectively indicate the bundle name of the target ability and the ability name in the bundle. When ability A needs to start ability B and transfer some data to ability B, it can use Want a carrier to transfer the data. > **NOTE** -> +> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import -``` +```ts import Want from '@ohos.application.Want'; ``` @@ -16,24 +16,24 @@ import Want from '@ohos.application.Want'; **System capability**: SystemCapability.Ability.AbilityBase -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| deviceId | Read only | string | No | ID of the device running the ability. | -| bundleName | Read only | string | No | Bundle name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| -| abilityName | Read only | string | No | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.| -| uri | Read only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| -| type | Read only | string | No | MIME type, that is, the type of the file to open, for example, **text/xml** and **image/***. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. | -| flags | Read only | number | No | How the **Want** object will be handled. For details, see [flags](js-apis-featureAbility.md#flags).| -| action | Read only | string | No | Action to take, such as viewing and sharing application details. In implicit **Want**, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. | -| parameters | Read only | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information. | -| entities | Read only | Array\ | No | Additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit **Want** and is used to filter ability types. | -| moduleName9+ | Read only | string | No | Module to which the ability belongs.| +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| deviceId | string | No | ID of the device running the ability. | +| bundleName | string | No | Bundle name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| +| abilityName | string | No | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.| +| uri | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| +| type | string | No | MIME type, that is, the type of the file to open, for example, **text/xml** and **image/***. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. | +| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantConstant.Flags).| +| action | string | No | Action to take, such as viewing and sharing application details. In implicit **Want**, you can define this attribute and use it together with **uri** or **parameters** to specify the operation to be performed on the data. | +| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information. | +| entities | Array\ | No | Additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit **Want** and is used to filter ability types. | +| moduleName9+ | string | No | Module to which the ability belongs.| **Example** - Basic usage - ``` js + ```ts var want = { "deviceId": "", // An empty deviceId indicates the local device. "bundleName": "com.extreme.test", diff --git a/en/application-dev/reference/apis/js-apis-application-WindowExtensionAbility.md b/en/application-dev/reference/apis/js-apis-application-WindowExtensionAbility.md index 1fa16906d34877c7e7dce4638b472b0c539b8921..bf71a0422f2bb6f8c7ce18f2e956ca21105e0915 100644 --- a/en/application-dev/reference/apis/js-apis-application-WindowExtensionAbility.md +++ b/en/application-dev/reference/apis/js-apis-application-WindowExtensionAbility.md @@ -1,4 +1,5 @@ -# Window Extension Ability +# @ohos.application.WindowExtensionAbility + **WindowExtensionAbility** inherits from **ExtensionAbility**. The content in a **WindowExtensionAbility** object can be displayed as an ability component in other application windows. > **NOTE** @@ -21,7 +22,7 @@ import WindowExtensionAbility from '@ohos.application.WindowExtensionAbility'; | Name | Type| Readable| Writable| Description | | --------- | -------- | ---- | ---- | ------------------------- | -| context | [ExtensionContext](js-apis-extension-context.md) | Yes | No | Context of an Extension ability. | +| context | [ExtensionContext](js-apis-inner-application-extensionContext.md) | Yes | No | Context of an Extension ability. | ## WindowExtensionAbility.onConnect @@ -35,7 +36,7 @@ Called when this Window Extension ability is connected to an ability for the fir | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information related to this Window Extension ability, including the ability name and bundle name.| +| want | [Want](js-apis-application-want.md) | Yes| Information related to this Window Extension ability, including the ability name and bundle name.| **Example** @@ -61,7 +62,7 @@ Called when this Window Extension ability is disconnected from all connected abi | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information related to this Window Extension ability, including the ability name and bundle name.| +| want | [Want](js-apis-application-want.md) | Yes| Information related to this Window Extension ability, including the ability name and bundle name.| **Example** diff --git a/en/application-dev/reference/apis/js-apis-application-ability.md b/en/application-dev/reference/apis/js-apis-application-ability.md index 7ba7d62c053ea5eb7f03e6264f959c5770e196ee..8c1c83988c352d24ac4bc7d64b61d53f3378156a 100644 --- a/en/application-dev/reference/apis/js-apis-application-ability.md +++ b/en/application-dev/reference/apis/js-apis-application-ability.md @@ -1,4 +1,4 @@ -# Ability +# @ohos.application.Ability The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information. @@ -14,7 +14,7 @@ This module provides the following common ability-related functions: ## Modules to Import -``` +```ts import Ability from '@ohos.application.Ability'; ``` @@ -24,9 +24,9 @@ import Ability from '@ohos.application.Ability'; | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| context | [AbilityContext](js-apis-ability-context.md) | Yes| No| Context of an ability.| -| launchWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters for starting the ability.| -| lastRequestWant | [Want](js-apis-application-Want.md) | Yes| No| Parameters used when the ability was started last time.| +| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | Yes| No| Context of an ability.| +| launchWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters for starting the ability.| +| lastRequestWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters used when the ability was started last time.| | callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.| ## Ability.onCreate @@ -41,7 +41,7 @@ Called to initialize the service logic when an ability is created. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information related to this ability, including the ability name and bundle name.| + | want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this ability, including the ability name and bundle name.| | param | AbilityConstant.LaunchParam | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.| **Example** @@ -227,7 +227,7 @@ Called when the ability startup mode is set to singleton. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Want parameters, such as the ability name and bundle name.| + | want | [Want](js-apis-application-want.md) | Yes| Want parameters, such as the ability name and bundle name.| | launchParams | AbilityConstant.LaunchParam | Yes| Reason for the ability startup and the last abnormal exit.| **Example** @@ -240,27 +240,26 @@ Called when the ability startup mode is set to singleton. } ``` - ## Ability.onConfigurationUpdated onConfigurationUpdated(config: Configuration): void; -Called when the configuration of the environment where the ability is running is updated. +Called when the global configuration is updated. -**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore +**System capability**: SystemCapability.Ability.AbilityRuntime.Core **Parameters** | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| + | config | [Configuration](js-apis-application-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.| **Example** ```ts class myAbility extends Ability { onConfigurationUpdated(config) { - console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); + console.log('onConfigurationUpdated, language:' + config.language); } } ``` @@ -314,12 +313,11 @@ Called when the system has decided to adjust the memory level. For example, this } ``` - ## Ability.onSaveState onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: any}): AbilityConstant.OnSaveResult; -Called when the framework saves the ability state in the case of an application fault if automatic saving is enabled. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). +Called when the framework automatically saves the ability state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -338,7 +336,7 @@ Called when the framework saves the ability state in the case of an application **Example** - ```js + ```ts import AbilityConstant from '@ohos.application.AbilityConstant' class myAbility extends Ability { @@ -390,7 +388,7 @@ Sends sequenceable data to the target ability. **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; class MyMessageAble{ // Custom sequenceable data structure name:"" str:"" @@ -474,7 +472,7 @@ Sends sequenceable data to the target ability and obtains the sequenceable data **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; class MyMessageAble{ name:"" str:"" @@ -546,7 +544,7 @@ Releases the caller interface of the target ability. **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; var caller; export default class MainAbility extends Ability { onWindowStageCreate(windowStage) { @@ -570,10 +568,9 @@ Releases the caller interface of the target ability. } ``` +## Caller.onRelease -## Caller.on - - on(type: "release", callback: OnReleaseCallback): void; + onRelease(callback: OnReleaseCallBack): void; Registers a callback that is invoked when the stub on the target ability is disconnected. @@ -583,21 +580,12 @@ Registers a callback that is invoked when the stub on the target ability is disc | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | type | string | Yes| Event type. The value is fixed at **release**.| | callback | OnReleaseCallBack | Yes| Callback used for the **onRelease** API.| -**Error codes** - -| ID| Error Message| -| ------- | -------------------------------- | -| 401 | Invalid input parameter. | -| 16200001 | Caller released. The caller has been released. | -| 16000050 | Internal Error. | - **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; var caller; export default class MainAbility extends Ability { onWindowStageCreate(windowStage) { @@ -608,7 +596,7 @@ Registers a callback that is invoked when the stub on the target ability is disc }).then((obj) => { caller = obj; try { - caller.on("release", (str) => { + caller.onRelease((str) => { console.log(' Caller OnRelease CallBack is called ' + str); }); } catch (error) { @@ -654,7 +642,7 @@ Registers a caller notification callback, which is invoked when the target abili **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; class MyMessageAble{ name:"" str:"" @@ -679,9 +667,9 @@ Registers a caller notification callback, which is invoked when the target abili var method = 'call_Function'; function funcCallBack(pdata) { console.log('Callee funcCallBack is called ' + pdata); - let msg = new MyMessageAble(0, ""); + let msg = new MyMessageAble("test", ""); pdata.readSequenceable(msg); - return new MyMessageAble(10, "Callee test"); + return new MyMessageAble("test1", "Callee test"); } export default class MainAbility extends Ability { onCreate(want, launchParam) { @@ -722,7 +710,7 @@ Deregisters a caller notification callback, which is invoked when the target abi **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import Ability from '@ohos.application.Ability'; var method = 'call_Function'; export default class MainAbility extends Ability { onCreate(want, launchParam) { @@ -736,8 +724,8 @@ Deregisters a caller notification callback, which is invoked when the target abi } } ``` - -## OnReleaseCallback + +## OnReleaseCallBack (msg: string): void; @@ -747,7 +735,7 @@ Deregisters a caller notification callback, which is invoked when the target abi | -------- | -------- | -------- | -------- | -------- | | (msg: string) | function | Yes| No| Prototype of the listener function registered by the caller.| -## CalleeCallback +## CalleeCallBack (indata: rpc.MessageParcel): rpc.Sequenceable; @@ -756,5 +744,3 @@ Deregisters a caller notification callback, which is invoked when the target abi | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | | (indata: rpc.MessageParcel) | rpc.Sequenceable | Yes| No| Prototype of the listener function registered by the callee.| - - \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-application-abilityConstant.md b/en/application-dev/reference/apis/js-apis-application-abilityConstant.md index 50e65757431e7df6b9bc784c6169da902a04bf5d..c97e344590f1bdd6b0d0242c1b61003053908e37 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityConstant.md +++ b/en/application-dev/reference/apis/js-apis-application-abilityConstant.md @@ -1,4 +1,4 @@ -# AbilityConstant +# @ohos.application.AbilityConstant The **AbilityConstant** module provides ability launch parameters. @@ -6,12 +6,12 @@ The parameters include the initial launch reasons, reasons for the last exit, an > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.AbilityConstant](js-apis-app-ability-abilityConstant.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. ## Modules to Import -```js +```ts import AbilityConstant from '@ohos.application.AbilityConstant'; ``` @@ -19,10 +19,10 @@ import AbilityConstant from '@ohos.application.AbilityConstant'; **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name| Type| Readable| Writable| Description| +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| launchReason | LaunchReason| Yes| Yes| Ability launch reason.| -| lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.| +| launchReason | LaunchReason| Yes| Yes| Ability launch reason.| +| lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.| ## AbilityConstant.LaunchReason @@ -36,6 +36,7 @@ Enumerates ability launch reasons. | START_ABILITY | 1 | Ability startup.| | CALL | 2 | Call.| | CONTINUATION | 3 | Ability continuation.| +| APP_RECOVERY | 4 | Application recovery.| ## AbilityConstant.LastExitReason @@ -88,3 +89,29 @@ Enumerates the memory levels. | MEMORY_LEVEL_MODERATE | 0 | Moderate memory usage. | | MEMORY_LEVEL_LOW | 1 | Low memory usage. | | MEMORY_LEVEL_CRITICAL | 2 | High memory usage. | + +## AbilityConstant.OnSaveResult + +Enumerates the result types for the operation of saving application data. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| ALL_AGREE | 0 | Agreed to save the status.| +| CONTINUATION_REJECT | 1 | Rejected to save the status in continuation.| +| CONTINUATION_MISMATCH | 2 | Continuation mismatch.| +| RECOVERY_AGREE | 3 | Agreed to restore the saved status.| +| RECOVERY_REJECT | 4 | Rejected to restore the saved state.| +| ALL_REJECT | 5 | Rejected to save the status.| + +## AbilityConstant.StateType + +Enumerates the scenarios for saving application data. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Value | Description | +| ----------------------------- | ---- | ------------------------------------------------------------ | +| CONTINUATION | 0 | Saving the status in continuation.| +| APP_RECOVERY | 1 | Saving the status in application recovery.| diff --git a/en/application-dev/reference/apis/js-apis-abilityDelegatorRegistry.md b/en/application-dev/reference/apis/js-apis-application-abilityDelegatorRegistry.md similarity index 81% rename from en/application-dev/reference/apis/js-apis-abilityDelegatorRegistry.md rename to en/application-dev/reference/apis/js-apis-application-abilityDelegatorRegistry.md index d30dce2a75e700019c9f44ce1c918a9574f3cea7..c58eae8878a6df52715e9b4ec06738aeef34bf01 100644 --- a/en/application-dev/reference/apis/js-apis-abilityDelegatorRegistry.md +++ b/en/application-dev/reference/apis/js-apis-application-abilityDelegatorRegistry.md @@ -1,4 +1,4 @@ -# AbilityDelegatorRegistry +# @ohos.application.abilityDelegatorRegistry The **AbilityDelegatorRegistry** module provides APIs for storing the global registers of the registered **AbilityDelegator** and **AbilityDelegatorArgs** objects. You can use the APIs to obtain the **AbilityDelegator** and **AbilityDelegatorArgs** objects of an application. @@ -8,7 +8,7 @@ The **AbilityDelegatorRegistry** module provides APIs for storing the global reg ## Modules to Import -```js +```ts import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' ``` @@ -38,18 +38,16 @@ Obtains the **AbilityDelegator** object of the application. | Type | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | -| [AbilityDelegator](js-apis-application-abilityDelegator.md#AbilityDelegator) | [AbilityDelegator](js-apis-application-abilityDelegator.md#AbilityDelegator) object, which can be used to schedule functions related to the test framework.| +| [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) | [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) object, which can be used to schedule functions related to the test framework.| **Example** -```js +```ts var abilityDelegator; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); ``` - - ## AbilityDelegatorRegistry.getArguments getArguments(): AbilityDelegatorArgs @@ -62,11 +60,11 @@ Obtains the **AbilityDelegatorArgs** object of the application. | Type | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | -| [AbilityDelegatorArgs](js-apis-application-abilityDelegatorArgs.md#AbilityDelegatorArgs) | [AbilityDelegatorArgs](js-apis-application-abilityDelegatorArgs.md#AbilityDelegatorArgs) object, which can be used to obtain test parameters.| +| [AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md#AbilityDelegatorArgs) | [AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md#AbilityDelegatorArgs) object, which can be used to obtain test parameters.| **Example** -```js +```ts var args = AbilityDelegatorRegistry.getArguments(); console.info("getArguments bundleName:" + args.bundleName); console.info("getArguments testCaseNames:" + args.testCaseNames); diff --git a/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md b/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md index 54264312fcc88ad0177473a7e4d256f566e6c2d2..cd4a4db73667651bae07a865d0a088321cda0ce6 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md +++ b/en/application-dev/reference/apis/js-apis-application-abilityLifecycleCallback.md @@ -1,16 +1,16 @@ -# AbilityLifecycleCallback +# @ohos.application.AbilityLifecycleCallback The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context. > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.AbilityLifecycleCallback](js-apis-app-ability-abilityLifecycleCallback.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. ## Modules to Import -```js +```ts import AbilityLifecycleCallback from "@ohos.application.AbilityLifecycleCallback"; ``` @@ -43,7 +43,7 @@ Called when the window stage of an ability is created. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| - | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| ## AbilityLifecycleCallback.onWindowStageActive @@ -59,7 +59,7 @@ Called when the window stage of an ability gains focus. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| - | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| ## AbilityLifecycleCallback.onWindowStageInactive @@ -75,7 +75,7 @@ Called when the window stage of an ability loses focus. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| - | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| ## AbilityLifecycleCallback.onWindowStageDestroy @@ -91,7 +91,7 @@ Called when the window stage of an ability is destroyed. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | ability | [Ability](js-apis-application-ability.md#Ability) | Yes| **Ability** object.| - | windowStage | [WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** object.| ## AbilityLifecycleCallback.onAbilityDestroy @@ -156,16 +156,18 @@ Called when an ability is continued on another device. **Example** - ```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)); - }, +```ts +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)); + }, onWindowStageCreate(ability, windowStage){ console.log("AbilityLifecycleCallback onWindowStageCreate ability:" + JSON.stringify(ability)); console.log("AbilityLifecycleCallback onWindowStageCreate windowStage:" + JSON.stringify(windowStage)); @@ -182,24 +184,30 @@ Called when an ability is continued on another device. console.log("AbilityLifecycleCallback onWindowStageDestroy ability:" + JSON.stringify(ability)); console.log("AbilityLifecycleCallback onWindowStageDestroy windowStage:" + JSON.stringify(windowStage)); }, - 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. Obtain applicationContext through the context attribute. - let applicationContext = this.context.getApplicationContext(); - // 2. Use applicationContext to register a listener for the ability lifecycle in the application. - let lifecycleid = applicationContext.registerAbilityLifecycleCallback(AbilityLifecycleCallback); - console.log("registerAbilityLifecycleCallback number: " + JSON.stringify(lifecycleid)); - } - } - ``` + 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. Obtain applicationContext through the context attribute. + let applicationContext = this.context.getApplicationContext(); + // 2. Use applicationContext to register a listener for the ability lifecycle in the application. + 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)); + }); + } +} +``` diff --git a/en/application-dev/reference/apis/js-apis-application-abilityManager.md b/en/application-dev/reference/apis/js-apis-application-abilityManager.md index e1bf96bae511de4e1fb83d92df6ee05bdddbf990..cf7f8da5870889e80853b396a433932afc895679 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityManager.md +++ b/en/application-dev/reference/apis/js-apis-application-abilityManager.md @@ -1,4 +1,4 @@ -# AbilityManager +# @ohos.application.abilityManager The **AbilityManager** module provides APIs for obtaining, adding, and modifying ability running information and state information. @@ -9,7 +9,7 @@ The **AbilityManager** module provides APIs for obtaining, adding, and modifying ## Modules to Import -```js +```ts import AbilityManager from '@ohos.application.abilityManager' ``` @@ -43,12 +43,12 @@ Updates the configuration. This API uses an asynchronous callback to return the | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | -------------- | -| config | Configuration | Yes | New configuration.| +| config | [Configuration](js-apis-application-configuration.md) | Yes | New configuration.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; var config = { @@ -74,7 +74,7 @@ Updates the configuration. This API uses a promise to return the result. | Name | Type | Mandatory | Description | | --------- | ---------------------------------------- | ---- | -------------- | -| config | Configuration | Yes | New configuration.| +| config | [Configuration](js-apis-application-configuration.md) | Yes | New configuration.| **Return value** @@ -84,7 +84,7 @@ Updates the configuration. This API uses a promise to return the result. **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; var config = { @@ -116,7 +116,7 @@ Obtains the ability running information. This API uses an asynchronous callback **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; abilitymanager.getAbilityRunningInfos((err,data) => { @@ -142,7 +142,7 @@ Obtains the ability running information. This API uses a promise to return the r **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; abilitymanager.getAbilityRunningInfos().then((data) => { @@ -171,7 +171,7 @@ Obtains the extension running information. This API uses an asynchronous callbac **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; var upperLimit = 0; @@ -205,7 +205,7 @@ Obtains the extension running information. This API uses a promise to return the **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; var upperLimit = 0; @@ -233,7 +233,7 @@ Obtains the top ability, which is the ability that has the window focus. This AP **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; abilitymanager.getTopAbility((err,data) => { @@ -257,7 +257,7 @@ Obtains the top ability, which is the ability that has the window focus. This AP **Example** -```js +```ts import abilitymanager from '@ohos.application.abilityManager'; abilitymanager.getTopAbility().then((data) => { diff --git a/en/application-dev/reference/apis/js-apis-application-abilityMonitor.md b/en/application-dev/reference/apis/js-apis-application-abilityMonitor.md deleted file mode 100644 index 33feda3afdd757e91ed7b7f682dca1ef597a7847..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-application-abilityMonitor.md +++ /dev/null @@ -1,47 +0,0 @@ -# AbilityMonitor - -The **AbilityMonitor** module provides monitors for abilities that meet specified conditions. The latest matched abilities are stored in an **AbilityMonitor** object. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Usage - -The ability monitor is set by calling **addAbilityMonitor** in **abilityDelegator**. - -```js -import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' -var abilityDelegator; - -function onAbilityCreateCallback(data) { - console.info("onAbilityCreateCallback"); -} - -var monitor = { - abilityName: "abilityname", - onAbilityCreate: onAbilityCreateCallback -} - -abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); -abilityDelegator.addAbilityMonitor(monitor, (err : any) => { - console.info("addAbilityMonitor callback"); -}); -``` - -## AbilityMonitor - -Describes an ability monitor. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Type | Readable| Writable| Description | -| ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ | -| abilityName | string | Yes | Yes | Name of the ability bound to the ability monitor. | -| onAbilityCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is created.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onAbilityForeground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the foreground.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onAbilityBackground?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability starts to run in the background.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onAbilityDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the ability is destroyed.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onWindowStageCreate?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is created.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onWindowStageRestore?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is restored.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | -| onWindowStageDestroy?:(data: [Ability](js-apis-application-ability.md#Ability)) | function | Yes | Yes | Called when the window stage is destroyed.
If this attribute is not set, the corresponding lifecycle callback cannot be received. | diff --git a/en/application-dev/reference/apis/js-apis-application-abilitystage.md b/en/application-dev/reference/apis/js-apis-application-abilitystage.md index d1c8592f97d4c8b8799d5773b391bb1798663219..45227a89b2a6ed8d01997b8c699f8fc8c320b955 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilitystage.md +++ b/en/application-dev/reference/apis/js-apis-application-abilitystage.md @@ -1,4 +1,4 @@ -# AbilityStage +# @ohos.application.AbilityStage **AbilityStage** is a runtime class for HAP files. @@ -6,12 +6,12 @@ The **AbilityStage** module notifies you of when you can perform HAP initializat > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported and deprecated since API version 9. You are advised to use [@ohos.app.ability.AbilityStage](js-apis-app-ability-abilityStage.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. ## Modules to Import -```js +```ts import AbilityStage from '@ohos.application.AbilityStage'; ``` @@ -25,7 +25,7 @@ Called when the application is created. **Example** - ```js + ```ts class MyAbilityStage extends AbilityStage { onCreate() { console.log("MyAbilityStage.onCreate is called") @@ -46,7 +46,7 @@ Called when a specified ability is started. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| + | want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.| **Return value** @@ -56,7 +56,7 @@ Called when a specified ability is started. **Example** - ```js + ```ts class MyAbilityStage extends AbilityStage { onAcceptWant(want) { console.log("MyAbilityStage.onAcceptWant called"); @@ -78,11 +78,11 @@ Called when the global configuration is updated. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | config | [Configuration](js-apis-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.| + | config | [Configuration](js-apis-application-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.| **Example** - ```js + ```ts class MyAbilityStage extends AbilityStage { onConfigurationUpdated(config) { console.log('onConfigurationUpdated, language:' + config.language); @@ -106,7 +106,7 @@ Called when the system has decided to adjust the memory level. For example, this **Example** - ```js + ```ts class MyAbilityStage extends AbilityStage { onMemoryLevel(level) { console.log('onMemoryLevel, level:' + JSON.stringify(level)); @@ -124,4 +124,4 @@ Describes the configuration information about the context. | Name | Type | Description | | ----------- | --------------------------- | ------------------------------------------------------------ | -| context | [AbilityStageContext](js-apis-abilitystagecontext.md) | Called when initialization is performed during ability startup.| +| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | Called when initialization is performed during ability startup.| diff --git a/en/application-dev/reference/apis/js-apis-application-appManager.md b/en/application-dev/reference/apis/js-apis-application-appManager.md new file mode 100644 index 0000000000000000000000000000000000000000..a3f97be529cfef048393d37907a257fddf10b0bf --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-appManager.md @@ -0,0 +1,715 @@ +# @ohos.application.appManager + +The **appManager** module implements application management. You can use the APIs of this module to query whether the application is undergoing a stability test, whether the application is running on a RAM constrained device, the memory size of the application, and information about the running process. + +> **NOTE** +> +> The APIs of this module are supported since API version 7 and deprecated since API version 9. You are advised to use [@ohos.app.ability.appManager](js-apis-app-ability-appManager.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import app from '@ohos.application.appManager'; +``` + +## appManager.isRunningInStabilityTest8+ + +static isRunningInStabilityTest(callback: AsyncCallback<boolean>): void + +Checks whether this application is undergoing a stability test. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + import app from '@ohos.application.appManager'; + app.isRunningInStabilityTest((err, flag) => { + console.log('startAbility result:' + JSON.stringify(err)); + }) + ``` + + +## appManager.isRunningInStabilityTest8+ + +static isRunningInStabilityTest(): Promise<boolean> + +Checks whether this application is undergoing a stability test. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + import app from '@ohos.application.appManager'; + app.isRunningInStabilityTest().then((flag) => { + console.log('success:' + JSON.stringify(flag)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + + +## appManager.isRamConstrainedDevice + +isRamConstrainedDevice(): Promise\; + +Checks whether this application is running on a RAM constrained device. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<boolean> | Promise used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + app.isRamConstrainedDevice().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.isRamConstrainedDevice + +isRamConstrainedDevice(callback: AsyncCallback\): void; + +Checks whether this application is running on a RAM constrained device. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<boolean> | Yes| Callback used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| + +**Example** + + ```ts + app.isRamConstrainedDevice((err, data) => { + console.log('startAbility result failed:' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.getAppMemorySize + +getAppMemorySize(): Promise\; + +Obtains the memory size of this application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<number> | Size of the application memory.| + +**Example** + + ```ts + app.getAppMemorySize().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getAppMemorySize + +getAppMemorySize(callback: AsyncCallback\): void; + +Obtains the memory size of this application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | AsyncCallback<number> | Yes| Size of the application memory.| + +**Example** + + ```ts + app.getAppMemorySize((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` +## appManager.getProcessRunningInfos(deprecated) + +getProcessRunningInfos(): Promise\>; + +Obtains information about the running processes. This API uses a promise to return the result. + +> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9) instead. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Promise used to return the process information.| + +**Example** + + ```ts + app.getProcessRunningInfos().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getProcessRunningInfos(deprecated) + +getProcessRunningInfos(callback: AsyncCallback\>): void; + +Obtains information about the running processes. This API uses an asynchronous callback to return the result. + +> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9-1) instead. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Obtains information about the running processes. This API uses a promise to return the result.| + +**Example** + + ```ts + app.getProcessRunningInfos((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(): Promise\>; + +Obtains information about the running processes. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Obtains information about the running processes. This API uses a promise to return the result.| + +**Example** + + ```ts + app.getProcessRunningInformation().then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` + +## appManager.getProcessRunningInformation9+ + +getProcessRunningInformation(callback: AsyncCallback\>): void; + +Obtains information about the running processes. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Obtains information about the running processes. This API uses a promise to return the result.| + +**Example** + + ```ts + app.getProcessRunningInformation((err, data) => { + console.log('startAbility result failed :' + JSON.stringify(err)); + console.log('startAbility result success:' + JSON.stringify(data)); + }) + ``` + +## appManager.registerApplicationStateObserver8+ + +registerApplicationStateObserver(observer: ApplicationStateObserver): number; + +Registers an observer to listen for the state changes of all applications. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observer | [ApplicationStateObserver](js-apis-inner-application-applicationStateObserver.md) | Yes| Numeric code of the observer.| + +**Example** + + ```ts + var applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('------------ onForegroundApplicationChanged -----------', appStateData); + }, + onAbilityStateChanged(abilityStateData) { + console.log('------------ onAbilityStateChanged -----------', abilityStateData); + }, + onProcessCreated(processData) { + console.log('------------ onProcessCreated -----------', processData); + }, + onProcessDied(processData) { + console.log('------------ onProcessDied -----------', processData); + }, + onProcessStateChanged(processData) { + console.log('------------ onProcessStateChanged -----------', processData); + } + } + const observerCode = app.registerApplicationStateObserver(applicationStateObserver); + console.log('-------- observerCode: ---------', observerCode); + ``` + +## appManager.registerApplicationStateObserver9+ + +registerApplicationStateObserver(observer: ApplicationStateObserver, bundleNameList: Array\): number; + +Registers an observer to listen for the state changes of a specified application. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observer | [ApplicationStateObserver](js-apis-inner-application-applicationStateObserver.md) | Yes| Numeric code of the observer.| +| bundleNameList | Array | Yes| **bundleName** array of the application. A maximum of 128 bundle names can be passed.| + +**Example** + + ```ts + var applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('------------ onForegroundApplicationChanged -----------', appStateData); + }, + onAbilityStateChanged(abilityStateData) { + console.log('------------ onAbilityStateChanged -----------', abilityStateData); + }, + onProcessCreated(processData) { + console.log('------------ onProcessCreated -----------', processData); + }, + onProcessDied(processData) { + console.log('------------ onProcessDied -----------', processData); + }, + onProcessStateChanged(processData) { + console.log('------------ onProcessStateChanged -----------', processData); + } + } + var bundleNameList = ['bundleName1', 'bundleName2']; + const observerCode = app.registerApplicationStateObserver(applicationStateObserver, bundleNameList); + console.log('-------- observerCode: ---------', observerCode); + ``` +## appManager.unregisterApplicationStateObserver8+ + +unregisterApplicationStateObserver(observerId: number, callback: AsyncCallback\): void; + +Deregisters the application state observer. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observerId | number | Yes| Numeric code of the observer.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + var observerId = 100; + + function unregisterApplicationStateObserverCallback(err) { + if (err) { + console.log('------------ unregisterApplicationStateObserverCallback ------------', err); + } + } + app.unregisterApplicationStateObserver(observerId, unregisterApplicationStateObserverCallback); + ``` + +## appManager.unregisterApplicationStateObserver8+ + +unregisterApplicationStateObserver(observerId: number): Promise\; + +Deregisters the application state observer. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| observerId | number | Yes| Numeric code of the observer.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts + var observerId = 100; + + app.unregisterApplicationStateObserver(observerId) + .then((data) => { + console.log('----------- unregisterApplicationStateObserver success ----------', data); + }) + .catch((err) => { + console.log('----------- unregisterApplicationStateObserver fail ----------', err); + }) + ``` + +## appManager.getForegroundApplications8+ + +getForegroundApplications(callback: AsyncCallback\>): void; + +Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback\> | Yes| Callback used to return the application state data.| + +**Example** + + ```ts + function getForegroundApplicationsCallback(err, data) { + if (err) { + console.log('--------- getForegroundApplicationsCallback fail ---------', err); + } else { + console.log('--------- getForegroundApplicationsCallback success ---------', data) + } + } + app.getForegroundApplications(getForegroundApplicationsCallback); + ``` + +## appManager.getForegroundApplications8+ + +getForegroundApplications(): Promise\>; + +Obtains applications that are running in the foreground. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_RUNNING_INFO + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\> | Promise used to return the application state data.| + +**Example** + + ```ts + app.getForegroundApplications() + .then((data) => { + console.log('--------- getForegroundApplications success -------', data); + }) + .catch((err) => { + console.log('--------- getForegroundApplications fail -------', err); + }) + ``` + +## appManager.killProcessWithAccount8+ + +killProcessWithAccount(bundleName: string, accountId: number): Promise\ + +Kills a process by bundle name and account ID. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Bundle name of an application.| + | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Example** + +```ts +var bundleName = 'bundleName'; +var accountId = 0; +app.killProcessWithAccount(bundleName, accountId) + .then((data) => { + console.log('------------ killProcessWithAccount success ------------', data); + }) + .catch((err) => { + console.log('------------ killProcessWithAccount fail ------------', err); + }) +``` + + +## appManager.killProcessWithAccount8+ + +killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\): void + +Kills a process by bundle name and account ID. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | bundleName | string | Yes| Bundle name of an application.| + | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + | callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + +```ts +var bundleName = 'bundleName'; +var accountId = 0; +function killProcessWithAccountCallback(err, data) { + if (err) { + console.log('------------- killProcessWithAccountCallback fail, err: --------------', err); + } else { + console.log('------------- killProcessWithAccountCallback success, data: --------------', data); + } +} +app.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback); +``` + +## appManager.killProcessesByBundleName8+ + +killProcessesByBundleName(bundleName: string, callback: AsyncCallback\); + +Kills a process by bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + function killProcessesByBundleNameCallback(err, data) { + if (err) { + console.log('------------- killProcessesByBundleNameCallback fail, err: --------------', err); + } else { + console.log('------------- killProcessesByBundleNameCallback success, data: --------------', data); + } + } + app.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback); + ``` + +## appManager.killProcessesByBundleName8+ + +killProcessesByBundleName(bundleName: string): Promise\; + +Kills a process by bundle name. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + app.killProcessesByBundleName(bundleName) + .then((data) => { + console.log('------------ killProcessesByBundleName success ------------', data); + }) + .catch((err) => { + console.log('------------ killProcessesByBundleName fail ------------', err); + }) + ``` + +## appManager.clearUpApplicationData8+ + +clearUpApplicationData(bundleName: string, callback: AsyncCallback\); + +Clears application data by bundle name. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + function clearUpApplicationDataCallback(err, data) { + if (err) { + console.log('------------- clearUpApplicationDataCallback fail, err: --------------', err); + } else { + console.log('------------- clearUpApplicationDataCallback success, data: --------------', data); + } + } + app.clearUpApplicationData(bundleName, clearUpApplicationDataCallback); + ``` + +## appManager.clearUpApplicationData8+ + +clearUpApplicationData(bundleName: string): Promise\; + +Clears application data by bundle name. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| bundleName | string | Yes| Bundle name of an application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Example** + + ```ts + var bundleName = 'bundleName'; + app.clearUpApplicationData(bundleName) + .then((data) => { + console.log('------------ clearUpApplicationData success ------------', data); + }) + .catch((err) => { + console.log('------------ clearUpApplicationData fail ------------', err); + }) + ``` + +## ApplicationState9+ + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Value | Description | +| -------------------- | --- | --------------------------------- | +| STATE_CREATE | 1 | State indicating that the application is being created. | +| STATE_FOREGROUND | 2 | State indicating that the application is running in the foreground. | +| STATE_ACTIVE | 3 | State indicating that the application is active. | +| STATE_BACKGROUND | 4 | State indicating that the application is running in the background. | +| STATE_DESTROY | 5 | State indicating that the application is destroyed. | + +## ProcessState9+ + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Value | Description | +| -------------------- | --- | --------------------------------- | +| STATE_CREATE | 1 | State indicating that the process is being created. | +| STATE_FOREGROUND | 2 | State indicating that the process is running in the foreground. | +| STATE_ACTIVE | 3 | State indicating that the process is active. | +| STATE_BACKGROUND | 4 | State indicating that the process is running in the background. | +| STATE_DESTROY | 5 | State indicating that the process is destroyed. | diff --git a/en/application-dev/reference/apis/js-apis-application-configuration.md b/en/application-dev/reference/apis/js-apis-application-configuration.md new file mode 100644 index 0000000000000000000000000000000000000000..9c374059dc89f8ebdc719597df0afb7c12247d66 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-configuration.md @@ -0,0 +1,69 @@ +# @ohos.application.Configuration + +The **Configuration** module defines environment change information. + +> **NOTE** +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [@ohos.app.ability.Configuration](js-apis-app-ability-configuration.md) instead. + +## Modules to Import + +```ts +import Configuration from '@ohos.application.Configuration' +``` + +**System capability**: SystemCapability.Ability.AbilityBase + + | Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| language8+ | string | Yes| Yes| Language of the application.| +| colorMode8+ | [ColorMode](js-apis-application-configurationConstant.md#configurationconstantcolormode) | Yes| Yes| Color mode, which can be **COLOR_MODE_LIGHT** or **COLOR_MODE_DARK**. The default value is **COLOR_MODE_LIGHT**.| +| direction9+ | [Direction](js-apis-application-configurationConstant.md#configurationconstantdirection9) | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.| +| screenDensity9+ | [ScreenDensity](js-apis-application-configurationConstant.md#configurationconstantscreendensity9) | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).| +| displayId9+ | number | Yes| No| ID of the display where the application is located.| +| hasPointerDevice9+ | boolean | Yes| No| Whether a pointer device, such as a keyboard, mouse, or touchpad, is connected.| + +For details about the fields, see the **ohos.application.Configuration.d.ts** file. + +**Example** + + ```ts +import hilog from '@ohos.hilog'; +import Ability from '@ohos.application.Ability' +import Window from '@ohos.window' + +export default class MainAbility extends Ability { + onCreate(want, launchParam) { + } + + onDestroy() { + } + + onWindowStageCreate(windowStage: Window.WindowStage) { + let envCallback = { + onConfigurationUpdated(config) { + console.info(`envCallback onConfigurationUpdated success: ${JSON.stringify(config)}`) + let language = config.language; + let colorMode = config.colorMode; + let direction = config.direction; + let screenDensity = config.screenDensity; + let displayId = config.displayId; + let hasPointerDevice = config.hasPointerDevice; + } + }; + + let applicationContext = this.context.getApplicationContext(); + applicationContext.registerEnvironmentCallback(envCallback); + + windowStage.loadContent('pages/index', (err, data) => { + if (err.code) { + hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.ERROR); + hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); + return; + } + hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO); + hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? ''); + }); + } +} + ``` diff --git a/en/application-dev/reference/apis/js-apis-application-configurationConstant.md b/en/application-dev/reference/apis/js-apis-application-configurationConstant.md new file mode 100644 index 0000000000000000000000000000000000000000..863848066791fd23c5811bcc2af027552d8e5991 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-configurationConstant.md @@ -0,0 +1,55 @@ +# @ohos.application.ConfigurationConstant + +The **ConfigurationConstant** module provides the enumerated values of the environment configuration information. + +> **NOTE** +> +> The APIs of this module are supported since API version 8 and deprecated since API version 9. You are advised to use [@ohos.app.ability.ConfigurationConstant](js-apis-app-ability-configurationConstant.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import ConfigurationConstant from '@ohos.application.ConfigurationConstant'; +``` + +## ConfigurationConstant.ColorMode + +You can obtain the value of this constant by calling the **ConfigurationConstant.ColorMode** API. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name| Value| Description| +| -------- | -------- | -------- | +| COLOR_MODE_NOT_SET | -1 | Unspecified color mode.| +| COLOR_MODE_DARK | 0 | Dark mode.| +| COLOR_MODE_LIGHT | 1 | Light mode.| + + +## ConfigurationConstant.Direction9+ + +You can obtain the value of this constant by calling the **ConfigurationConstant.Direction** API. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name| Value| Description| +| -------- | -------- | -------- | +| DIRECTION_NOT_SET | -1 | Unspecified direction.| +| DIRECTION_VERTICAL | 0 | Vertical direction.| +| DIRECTION_HORIZONTAL | 1 | Horizontal direction.| + + +## ConfigurationConstant.ScreenDensity9+ + +You can obtain the value of this constant by calling the **ConfigurationConstant.ScreenDensity** API. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name| Value| Description| +| -------- | -------- | -------- | +| SCREEN_DENSITY_NOT_SET | 0 | Unspecified screen resolution.| +| SCREEN_DENSITY_SDPI | 120 | The screen resolution is sdpi.| +| SCREEN_DENSITY_MDPI | 160 | The screen resolution is mdpi.| +| SCREEN_DENSITY_LDPI | 240 | The screen resolution is ldpi.| +| SCREEN_DENSITY_XLDPI | 320 | The screen resolution is xldpi.| +| SCREEN_DENSITY_XXLDPI | 480 | The screen resolution is xxldpi.| +| SCREEN_DENSITY_XXXLDPI | 640 | The screen resolution is xxxldpi.| diff --git a/en/application-dev/reference/apis/js-apis-application-context.md b/en/application-dev/reference/apis/js-apis-application-context.md index 16d5fd0c3d79d097bc8f78ef24cae8f91869b8e3..88a5c84c617f675c93ea2f43de62625294025ca6 100644 --- a/en/application-dev/reference/apis/js-apis-application-context.md +++ b/en/application-dev/reference/apis/js-apis-application-context.md @@ -1,183 +1,41 @@ -# Context +# @ohos.application.context -The **Context** module provides the context for running code. You can use the APIs to query and set the application information and resource manager. +The **Context** module provides all level-2 module APIs for developers to export. > **NOTE** > -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. -## Usage +## Modules to Import -You must extend **AbilityContext** to implement this module. - - ```js -import AbilityContext from '@ohos.application.Ability' - class MainAbility extends AbilityContext { - onWindowStageCreate(windowStage) { - let test = "com.example.test"; - let context = this.context.createBundleContext(test); - } - } +```ts +import context from '@ohos.application.context' ``` -## Attributes - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| resourceManager | resmgr.ResourceManager; | Yes| No| **ResourceManager** object.| -| applicationInfo | ApplicationInfo | Yes| No| Information about the application.| -| cacheDir | string | Yes| No| Cache directory of the application on the internal storage.| -| tempDir | string | Yes| No| Temporary file directory of the application.| -| filesDir | string | Yes| No| File directory of the application on the internal storage.| -| databaseDir | string | Yes| No| Storage directory of local data.| -| bundleCodeDir | string | Yes| No| Application installation path.| -| distributedFilesDir | string | Yes| No| Storage directory of distributed application data files.| -| eventHub | [EventHub](js-apis-eventhub.md) | Yes| No| Event hub information.| -| area | [AreaMode](#areamode) | Yes| Yes| Area in which the file to be access is located.| -| preferencesDir | string | Yes| Yes| Preferences directory of the application.| - -## Context.createBundleContext - -createBundleContext(bundleName: string): Context; - -Creates a context for a given application. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core +**System capability**: SystemCapability.Ability.AbilityBase -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Application bundle name.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Context | Context created.| +| Name | Readable/Writable| Type | Mandatory| Description | +| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | +| AbilityContext | Read Only | [AbilityContext](js-apis-ability-context.md) | No | Level-2 module **AbilityContext**. | +| AbilityStageContext | Read Only | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | No | Level-2 module **AbilityStageContext**.| +| ApplicationContext | Read Only | [ApplicationContext](js-apis-inner-application-applicationContext.md) | No | Level-2 module **ApplicationContext**.| +| BaseContext | Read Only | [BaseContext](js-apis-inner-application-baseContext.md) | No | Level-2 module **BaseContext**.| +| Context | Read Only | [Context](js-apis-inner-application-context.md) | No | Level-2 module **Context**.| +| ExtensionContext | Read Only | [ExtensionContext](js-apis-inner-application-extensionContext.md) | No | Level-2 module **ExtensionContext**.| +| FormExtensionContext | Read Only | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | No | Level-2 module **FormExtensionContext**.| +| EventHub | Read Only | [EventHub](js-apis-inner-application-eventHub.md) | No | Level-2 module **EventHub**.| +| PermissionRequestResult | Read Only | [PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md) | No | Level-2 module **PermissionRequestResult**.| **Example** - - ```js - import AbilityContext from '@ohos.application.Ability' - class MainAbility extends AbilityContext { - onWindowStageCreate(windowStage) { - let test = "com.example.test"; - let context = this.context.createBundleContext(test); - } -} - - ``` - - -## Context.createModuleContext - -createModuleContext(moduleName: string): Context; - -Creates a context for a given HAP. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | moduleName | string | Yes| HAP name in the application.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Context | Context created.| - -**Example** - - ```js - import AbilityContext from '@ohos.application.Ability' - class MainAbility extends AbilityContext { - onWindowStageCreate(windowStage) { - let moduleName = "module"; - let context = this.context.createModuleContext(moduleName); - } -} - - ``` - - -## Context.createModuleContext - -createModuleContext(bundleName: string, moduleName: string): Context; - -Creates a context for a given HAP in an application. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Application bundle name.| - | moduleName | string | Yes| HAP name in the application.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Context | Context created.| - -**Example** - - ```js - import AbilityContext from '@ohos.application.Ability' - class MainAbility extends AbilityContext { - onWindowStageCreate(windowStage) { - let bundleName = "com.example.bundle"; - let moduleName = "module"; - let context = this.context.createModuleContext(bundleName, moduleName); - } -} - - ``` - - -## Context.getApplicationContext - -getApplicationContext(): ApplicationContext; - -Obtains the context of this application. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - -| Type| Description| -| -------- | -------- | -| ApplicationContext | Current application context.| - -**Example** - - ```js - // This part is mandatory. - let applicationContext = this.context.getApplicationContext(); - ``` - - -## AreaMode - -Defines the area where the file to be access is located. Each area has its own content. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Value | Description | -| --------------- | ---- | --------------- | -| EL1 | 0 | Device-level encryption area. | -| EL2 | 1 | User credential encryption area. The default value is **EL2**.| +```ts +let abilityContext: context.AbilityContext; +let abilityStageContext: context.AbilityStageContext; +let applicationContext: context.ApplicationContext; +let baseContext: context.BaseContext; +let context: context.Context; +let extensionContext: context.ExtensionContext; +let formExtensionContext: context.FormExtensionContext; +let eventHub: context.EventHub; +let permissionRequestResult: context.PermissionRequestResult; +``` diff --git a/en/application-dev/reference/apis/js-apis-errorManager.md b/en/application-dev/reference/apis/js-apis-application-errorManager.md similarity index 72% rename from en/application-dev/reference/apis/js-apis-errorManager.md rename to en/application-dev/reference/apis/js-apis-application-errorManager.md index 4a39fdd6b0031be7e3fcbdfc7a570609ba217a1b..5326b582120b6dcbf23a88bedb1ff4dcbe6192ae 100644 --- a/en/application-dev/reference/apis/js-apis-errorManager.md +++ b/en/application-dev/reference/apis/js-apis-application-errorManager.md @@ -1,4 +1,4 @@ -# ErrorManager +# @ohos.application.errorManager The **ErrorManager** module provides APIs for registering and deregistering error observers. @@ -7,7 +7,7 @@ The **ErrorManager** module provides APIs for registering and deregistering erro > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import -``` +```ts import errorManager from '@ohos.application.errorManager' ``` @@ -23,11 +23,11 @@ Registers an error observer. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| observer | [ErrorObserver](#errorobserver) | No| Numeric code of the observer.| +| observer | [ErrorObserver](js-apis-inner-application-errorObserver.md) | Yes| Numeric code of the observer.| **Example** -```js +```ts var observer = { onUnhandledException(errorMsg) { console.log('onUnhandledException, errorMsg: ', errorMsg) @@ -48,12 +48,12 @@ Deregisters an error observer. This API uses an asynchronous callback to return | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| observerId | number | No| Numeric code of the observer.| -| callback | AsyncCallback\ | No| Callback used to return the result.| +| observerId | number | Yes| Numeric code of the observer.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** -```js +```ts var observerId = 100; function unregisterErrorObserverCallback(err) { @@ -77,7 +77,7 @@ Deregisters an error observer. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| observerId | number | No| Numeric code of the observer.| +| observerId | number | Yes| Numeric code of the observer.| **Return value** @@ -87,7 +87,7 @@ Deregisters an error observer. This API uses a promise to return the result. **Example** -```js +```ts var observerId = 100; errorManager.unregisterErrorObserver(observerId) .then((data) => { @@ -98,28 +98,3 @@ errorManager.unregisterErrorObserver(observerId) }) ``` - -## ErrorObserver - -onUnhandledException(errMsg: string): void; - -Called when an unhandled exception occurs in the JS runtime. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| errMsg | string | No| Message and error stack trace about the exception.| - -**Example** - -```js -var observer = { - onUnhandledException(errorMsg) { - console.log('onUnhandledException, errorMsg: ', errorMsg) - } -} -errorManager.registerErrorObserver(observer) -``` diff --git a/en/application-dev/reference/apis/js-apis-application-extensionAbility.md b/en/application-dev/reference/apis/js-apis-application-extensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..055980e455acb5fd56ece9d4a1a582c7868b1646 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-extensionAbility.md @@ -0,0 +1,62 @@ +# @ohos.application.ExtensionAbility + +The **ExtensionAbility** module manages the Extension ability lifecycle and context, such as creating and destroying an Extension ability, and dumping client information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import ExtensionAbility from '@ohos.application.ExtensionAbility'; +``` + +## ExtensionAbility.onConfigurationUpdated + +onConfigurationUpdated(newConfig: Configuration): void; + +Called when the configuration of the environment where the ability is running is updated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | newConfig | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.| + +**Example** + + ```ts + class MyExtensionAbility extends ExtensionAbility { + onConfigurationUpdated(config) { + console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); + } + } + ``` + +## ExtensionAbility.onMemoryLevel + +onMemoryLevel(level: AbilityConstant.MemoryLevel): void; + +Called when the system has decided to adjust the memory level. For example, this API can be used when there is not enough memory to run as many background processes as possible. + +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore + +**Parameters** + + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | level | [AbilityConstant.MemoryLevel](js-apis-application-abilityConstant.md#abilityconstantmemorylevel) | Yes| Memory level that indicates the memory usage status. When the specified memory level is reached, a callback will be invoked and the system will start adjustment.| + +**Example** + + ```ts + class MyExtensionAbility extends ExtensionAbility { + onMemoryLevel(level) { + console.log('onMemoryLevel, level:' + JSON.stringify(level)); + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-application-formBindingData.md b/en/application-dev/reference/apis/js-apis-application-formBindingData.md new file mode 100644 index 0000000000000000000000000000000000000000..f0cdf74799a4373cfe61446191166a1e2ca0a014 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-formBindingData.md @@ -0,0 +1,63 @@ +# @ohos.application.formBindingData + +The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [FormBindingData](js-apis-app-form-formBindingData.md) instead. +## Modules to Import + +```ts +import formBindingData from '@ohos.application.formBindingData'; +``` + +## FormBindingData + +Describes a **FormBindingData** object. + +**System capability**: SystemCapability.Ability.Form + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| data | Object | Yes| Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format.| + + +## createFormBindingData + +createFormBindingData(obj?: Object | string): FormBindingData + +Creates a **FormBindingData** object. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------- | ---- | ------------------------------------------------------------ | +| obj | Object\|string | No | Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by "formImages", and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {"formImages": {"key1": fd1, "key2": fd2}}.| + + +**Return value** + +| Type | Description | +| ----------------------------------- | --------------------------------------- | +| [FormBindingData](#formbindingdata) | **FormBindingData** object created based on the passed data.| + + +**Example** + +```ts +import featureAbility from '@ohos.ability.featureAbility'; +import fileio from '@ohos.fileio'; +let context=featureAbility.getContext(); +context.getOrCreateLocalDir((err,data)=>{ + let path=data+"/xxx.jpg"; + let fd = fileio.openSync(path); + let obj = { + "temperature": "21°", + "formImages": {"image": fd} + }; + let formBindingDataObj = formBindingData.createFormBindingData(obj); +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-formerror.md b/en/application-dev/reference/apis/js-apis-application-formError.md similarity index 83% rename from en/application-dev/reference/apis/js-apis-formerror.md rename to en/application-dev/reference/apis/js-apis-application-formError.md index 9425026504a875b92fe5d2312b7de6d4c1e61d84..b3f2185d0c187edb998c768602b7c678833587b9 100644 --- a/en/application-dev/reference/apis/js-apis-formerror.md +++ b/en/application-dev/reference/apis/js-apis-application-formError.md @@ -1,14 +1,15 @@ -# FormError +# @ohos.application.formError The **FormError** module provides error codes for widgets. > **NOTE** -> +> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [Form Error Codes](../errorcodes/errorcode-form.md) instead. ## Modules to Import -``` +```ts import formError from '@ohos.application.formError'; ``` @@ -16,9 +17,9 @@ import formError from '@ohos.application.formError'; None. -## enum FormError +## FormError -Enumerates the available error codes. +Enumerates the widget types. **System capability** @@ -27,12 +28,12 @@ SystemCapability.Ability.Form | Name | Value | Description | | ----------- | ---- | ------------ | | ERR_COMMON | 1 | Default error code. | -| ERR_PERMISSION_DENY | 2 | No permission to perform the operation. | +| ERR_PERMISSION_DENY | 2 | You are not authorized to perform the operation. | | ERR_GET_INFO_FAILED | 4 | Failed to obtain the widget information. | | ERR_GET_BUNDLE_FAILED | 5 | Failed to obtain the bundle information. | | ERR_GET_LAYOUT_FAILED | 6 | Failed to obtain the layout information. | -| ERR_ADD_INVALID_PARAM | 7 | Invalid parameter. | -| ERR_CFG_NOT_MATCH_ID | 8 | The widget ID does not match any widget. | +| ERR_ADD_INVALID_PARAM | 7 | Invalid parameters are detected. | +| ERR_CFG_NOT_MATCH_ID | 8 | The widget ID does not match any widget. | | ERR_NOT_EXIST_ID | 9 | The widget ID does not exist. | | ERR_BIND_PROVIDER_FAILED | 10 | Failed to bind to the widget provider. | | ERR_MAX_SYSTEM_FORMS | 11 | The number of system widgets exceeds the upper limit. | @@ -48,4 +49,4 @@ SystemCapability.Ability.Form | ERR_SYSTEM_RESPONSES_FAILED | 30 | The system service failed to respond. | | ERR_FORM_DUPLICATE_ADDED | 31 | The widget has been added. | | ERR_IN_RECOVERY | 36 | Failed to overwrite the widget data. | -| ERR_DISTRIBUTED_SCHEDULE_FAILED9+ | 37 | The distributed scheduler failed.
This is a system API. | +| ERR_DISTRIBUTED_SCHEDULE_FAILED9+ | 37 | The distributed scheduler failed.
**System API**: This is a system API. | diff --git a/en/application-dev/reference/apis/js-apis-application-formExtension.md b/en/application-dev/reference/apis/js-apis-application-formExtension.md new file mode 100644 index 0000000000000000000000000000000000000000..a01e08710907030edfc7f0b1d04927282f5bc387 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-formExtension.md @@ -0,0 +1,284 @@ +# @ohos.application.FormExtension + +The **FormExtension** module provides APIs related to Form Extension abilities. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [FormExtensionAbility](js-apis-app-form-formExtensionAbility.md) instead. +> The APIs of this module can be used only in the stage model. + +## Modules to Import + +```ts +import FormExtension from '@ohos.application.FormExtension'; +``` + +## Attributes + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable| Writable| Description | +| ------- | ------------------------------------------------------- | ---- | ---- | --------------------------------------------------- | +| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the **FormExtension**. This context is inherited from **ExtensionContext**.| + +## onCreate + +onCreate(want: Want): formBindingData.FormBindingData + +Called to notify the widget provider that a **Form** instance (widget) has been created. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | +| want | [Want](js-apis-application-want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------- | +| [formBindingData.FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData' +export default class MyFormExtension extends FormExtension { + onCreate(want) { + console.log('FormExtension onCreate, want:' + want.abilityName); + let dataObj1 = { + temperature:"11c", + "time":"11:00" + }; + let obj1 = formBindingData.createFormBindingData(dataObj1); + return obj1; + } +} +``` + +## FormExtension.onCastToNormal + +onCastToNormal(formId: string): void + +Called to notify the widget provider that a temporary widget has been converted to a normal one. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------ | +| formId | string | Yes | ID of the widget that requests to be converted to a normal one.| + +**Example** + +```ts +export default class MyFormExtension extends FormExtension { + onCastToNormal(formId) { + console.log('FormExtension onCastToNormal, formId:' + formId); + } +} +``` + +## FormExtension.onUpdate + +onUpdate(formId: string): void + +Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) class to update the widget data. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| formId | string | Yes | ID of the widget that requests to be updated.| + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData' +export default class MyFormExtension extends FormExtension { + onUpdate(formId) { + console.log('FormExtension onUpdate, formId:' + formId); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + this.context.updateForm(formId, obj2).then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + } +} +``` + +## FormExtension.onVisibilityChange + +onVisibilityChange(newStatus: { [key: string]: number }): void + +Called to notify the widget provider of the change of visibility. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| --------- | ------------------------- | ---- | ---------------------------- | +| newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| + +**Example** + +```ts +import formBindingData from '@ohos.application.formBindingData' +export default class MyFormExtension extends FormExtension { + onVisibilityChange(newStatus) { + console.log('FormExtension onVisibilityChange, newStatus:' + newStatus); + let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); + + for (let key in newStatus) { + console.log('FormExtension onVisibilityChange, key:' + key + ", value=" + newStatus[key]); + this.context.updateForm(key, obj2).then((data)=>{ + console.log('FormExtension context updateForm, data:' + data); + }).catch((error) => { + console.error('Operation updateForm failed. Cause: ' + error);}); + } + } +} +``` + +## FormExtension.onEvent + +onEvent(formId: string, message: string): void + +Called to instruct the widget provider to receive and process the widget event. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | ------ | ---- | ---------------------- | +| formId | string | Yes | ID of the widget that requests the event.| +| message | string | Yes | Event message. | + +**Example** + +```ts +export default class MyFormExtension extends FormExtension { + onEvent(formId, message) { + console.log('FormExtension onEvent, formId:' + formId + ", message:" + message); + } +} +``` + +## FormExtension.onDestroy + +onDestroy(formId: string): void + +Called to notify the widget provider that a **Form** instance (widget) has been destroyed. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------ | +| formId | string | Yes | ID of the widget to be destroyed.| + +**Example** + +```ts +export default class MyFormExtension extends FormExtension { + onDestroy(formId) { + console.log('FormExtension onDestroy, formId:' + formId); + } +} +``` + +## FormExtension.onConfigurationUpdated + +onConfigurationUpdated(config: Configuration): void; + +Called when the configuration of the environment where the ability is running is updated. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| config | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.| + +**Example** + +```ts +class MyFormExtension extends FormExtension { + onConfigurationUpdated(config) { + console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); + } +} +``` + +## FormExtension.onAcquireFormState + +onAcquireFormState?(want: Want): formInfo.FormState; + +Called when the widget provider receives the status query result of a widget. By default, the initial state is returned. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| + +**Example** + +```ts +import formInfo from '@ohos.application.formInfo' +class MyFormExtension extends FormExtension { + onAcquireFormState(want) { + console.log('FormExtension onAcquireFormState, want:' + want); + return formInfo.FormState.UNKNOWN; + } +} +``` + +## FormExtension.onShare + +onShare?(formId: string): {[key: string]: any}; + +Called by the widget provider to receive shared widget data. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type | Description | +| ------------------------------------------------------------ | ----------------------------------------------------------- | +| {[key: string]: any} | Data to be shared by the widget, in the form of key-value pairs.| + +**Example** + +```ts +class MyFormExtension extends FormExtension { + onShare(formId) { + console.log('FormExtension onShare, formId:' + formId); + let wantParams = { + "temperature":"20", + "time":"2022-8-8 09:59", + }; + return wantParams; + } +} +``` diff --git a/en/application-dev/reference/apis/js-apis-application-formHost.md b/en/application-dev/reference/apis/js-apis-application-formHost.md new file mode 100644 index 0000000000000000000000000000000000000000..8b44dbf345b717b3cf1433392fd82907b6caab5f --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-formHost.md @@ -0,0 +1,1135 @@ +# @ohos.application.formHost + +The **FormHost** module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets installed by the same user, and obtain widget information and status. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [FormHost](js-apis-app-form-formHost.md) instead. +> The APIs provided by this module are system APIs. + +## Modules to Import + +```ts +import formHost from '@ohos.application.formHost'; +``` + +## deleteForm + +deleteForm(formId: string, callback: AsyncCallback<void>): void + +Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.deleteForm(formId, (error, data) => { + if (error.code) { + console.log('formHost deleteForm, error:' + JSON.stringify(error)); + } +}); +``` + +## deleteForm + +deleteForm(formId: string): Promise<void> + +Deletes a widget. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Parameters** + +```ts +var formId = "12400633174999288"; +formHost.deleteForm(formId).then(() => { + console.log('formHost deleteForm success'); +}).catch((error) => { + console.log('formHost deleteForm, error:' + JSON.stringify(error)); +}); +``` + +## releaseForm + +releaseForm(formId: string, callback: AsyncCallback<void>): void + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.releaseForm(formId, (error, data) => { + if (error.code) { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); + } +}); +``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | ----------- | +| formId | string | Yes | Widget ID. | +| isReleaseCache | boolean | Yes | Whether to release the cache.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.releaseForm(formId, true, (error, data) => { + if (error.code) { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); + } +}); +``` + +## releaseForm + +releaseForm(formId: string, isReleaseCache?: boolean): Promise<void> + +Releases a widget. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------------- | ------ | ---- | ----------- | +| formId | string | Yes | Widget ID. | +| isReleaseCache | boolean | No | Whether to release the cache.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.releaseForm(formId, true).then(() => { + console.log('formHost releaseForm success'); +}).catch((error) => { + console.log('formHost releaseForm, error:' + JSON.stringify(error)); +}); +``` + +## requestForm + +requestForm(formId: string, callback: AsyncCallback<void>): void + +Requests a widget update. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.requestForm(formId, (error, data) => { + if (error.code) { + console.log('formHost requestForm, error:' + JSON.stringify(error)); + } +}); +``` + +## requestForm + +requestForm(formId: string): Promise<void> + +Requests a widget update. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.requestForm(formId).then(() => { + console.log('formHost requestForm success'); +}).catch((error) => { + console.log('formHost requestForm, error:' + JSON.stringify(error)); +}); +``` + +## castTempForm + +castTempForm(formId: string, callback: AsyncCallback<void>): void + +Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.castTempForm(formId, (error, data) => { + if (error.code) { + console.log('formHost castTempForm, error:' + JSON.stringify(error)); + } +}); +``` + +## castTempForm + +castTempForm(formId: string): Promise<void> + +Converts a temporary widget to a normal one. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.castTempForm(formId).then(() => { + console.log('formHost castTempForm success'); +}).catch((error) => { + console.log('formHost castTempForm, error:' + JSON.stringify(error)); +}); +``` + +## notifyVisibleForms + +notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.notifyVisibleForms(formId, (error, data) => { + if (error.code) { + console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); + } +}); +``` + +## notifyVisibleForms + +notifyVisibleForms(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget visible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.notifyVisibleForms(formId).then(() => { + console.log('formHost notifyVisibleForms success'); +}).catch((error) => { + console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); +}); +``` + +## notifyInvisibleForms + +notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.notifyInvisibleForms(formId, (error, data) => { + if (error.code) { + console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); + } +}); +``` + +## notifyInvisibleForms + +notifyInvisibleForms(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget invisible. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.notifyInvisibleForms(formId).then(() => { + console.log('formHost notifyInvisibleForms success'); +}).catch((error) => { + console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); +}); +``` + +## enableFormsUpdate + +enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.enableFormsUpdate(formId, (error, data) => { + if (error.code) { + console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); + } +}); +``` + +## enableFormsUpdate + +enableFormsUpdate(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget updatable. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.enableFormsUpdate(formId).then(() => { + console.log('formHost enableFormsUpdate success'); +}).catch((error) => { + console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); +}); +``` + +## disableFormsUpdate + +disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void + +Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs. | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget not updatable, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.disableFormsUpdate(formId, (error, data) => { + if (error.code) { + console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); + } +}); +``` + +## disableFormsUpdate + +disableFormsUpdate(formIds: Array<string>): Promise<void> + +Instructs the widget framework to make a widget not updatable. After this API is called, the widget cannot receive updates from the widget provider. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = ["12400633174999288"]; +formHost.disableFormsUpdate(formId).then(() => { + console.log('formHost disableFormsUpdate success'); +}).catch((error) => { + console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); +}); +``` + +## isSystemReady + +isSystemReady(callback: AsyncCallback<void>): void + +Checks whether the system is ready. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.isSystemReady((error, data) => { + if (error.code) { + console.log('formHost isSystemReady, error:' + JSON.stringify(error)); + } +}); +``` + +## isSystemReady + +isSystemReady(): Promise<void> + +Checks whether the system is ready. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formId = "12400633174999288"; +formHost.isSystemReady().then(() => { + console.log('formHost isSystemReady success'); +}).catch((error) => { + console.log('formHost isSystemReady, error:' + JSON.stringify(error)); +}); +``` + +## getAllFormsInfo + +getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Example** + +```ts +formHost.getAllFormsInfo((error, data) => { + if (error.code) { + console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getAllFormsInfo, data:' + JSON.stringify(data)); + } +}); +``` + +## getAllFormsInfo + +getAllFormsInfo(): Promise<Array<formInfo.FormInfo>> + +Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](js-apis-application-formInfo.md)>> | Promise used to return the information obtained.| + +**Example** + + ```ts + formHost.getAllFormsInfo().then((data) => { + console.log('formHost getAllFormsInfo data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); + }); + ``` + +## getFormsInfo + +getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Example** + +```ts +formHost.getFormsInfo("com.example.ohos.formjsdemo", (error, data) => { + if (error.code) { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + } +}); +``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void + +Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| moduleName | string | Yes| Module name.| +| callback | AsyncCallback<Array<[FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **err** is undefined and **data** is the information obtained; otherwise, **err** is an error object.| + +**Example** + +```ts +formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry", (error, data) => { + if (error.code) { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + } else { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + } +}); +``` + +## getFormsInfo + +getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>> + +Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| bundleName | string | Yes| Bundle name of the application.| +| moduleName | string | No| Module name.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<Array<[FormInfo](js-apis-application-formInfo.md)>> | Promise used to return the information obtained.| + +**Example** + + ```ts + formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry").then((data) => { + console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); + }).catch((error) => { + console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); + }); + ``` + +## deleteInvalidForms + +deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void + +Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of valid widget IDs.| +| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **err** is undefined and **data** is the number of widgets deleted; otherwise, **err** is an error object.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.deleteInvalidForms(formIds, (error, data) => { + if (error.code) { + console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); + } else { + console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); + } +}); +``` + +## deleteInvalidForms + +deleteInvalidForms(formIds: Array<string>): Promise<number> + +Deletes invalid widgets from the list. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of valid widget IDs.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<number> | Promise used to return the number of widgets deleted.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.deleteInvalidForms(formIds).then((data) => { + console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); +}).catch((error) => { + console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); +}); +``` + +## acquireFormState + +acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void + +Obtains the widget state. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| +| callback | AsyncCallback<[FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **err** is undefined and **data** is the widget state obtained; otherwise, **err** is an error object.| + +**Example** + +```ts +var want = { + "deviceId": "", + "bundleName": "ohos.samples.FormApplication", + "abilityName": "FormAbility", + "parameters": { + "ohos.extra.param.key.module_name": "entry", + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.form_dimension": 2 + } +}; +formHost.acquireFormState(want, (error, data) => { + if (error.code) { + console.log('formHost acquireFormState, error:' + JSON.stringify(error)); + } else { + console.log('formHost acquireFormState, data:' + JSON.stringify(data)); + } +}); +``` + +## acquireFormState + +acquireFormState(want: Want): Promise<formInfo.FormStateInfo> + +Obtains the widget state. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.| + +**Return value** + +| Type | Description | +| :------------ | :---------------------------------- | +| Promise<[FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Promise used to return the widget state obtained.| + +**Example** + +```ts +var want = { + "deviceId": "", + "bundleName": "ohos.samples.FormApplication", + "abilityName": "FormAbility", + "parameters": { + "ohos.extra.param.key.module_name": "entry", + "ohos.extra.param.key.form_name": "widget", + "ohos.extra.param.key.form_dimension": 2 + } +}; +formHost.acquireFormState(want).then((data) => { + console.log('formHost acquireFormState, data:' + JSON.stringify(data)); +}).catch((error) => { + console.log('formHost acquireFormState, error:' + JSON.stringify(error)); +}); +``` + +## on("formUninstall") + +on(type: "formUninstall", callback: Callback<string>): void + +Subscribes to widget uninstall events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| type | string | Yes | Event type. The value **formUninstall** indicates a widget uninstallation event.| +| callback | Callback<string> | Yes| Callback used to return the widget ID.| + +**Example** + +```ts +let callback = function(formId) { + console.log('formHost on formUninstall, formId:' + formId); +} +formHost.on("formUninstall", callback); +``` + +## off("formUninstall") + +off(type: "formUninstall", callback?: Callback<string>): void + +Unsubscribes from widget uninstall events. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| type | string | Yes | Event type. The value **formUninstall** indicates a widget uninstallation event.| +| callback | Callback<string> | No| Callback used to return the widget ID. If it is left unspecified, it indicates the callback for all the events that have been subscribed.| + +**Example** + +```ts +let callback = function(formId) { + console.log('formHost on formUninstall, formId:' + formId); +} +formHost.off("formUninstall", callback); +``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void + +Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isVisible | boolean | Yes | Whether to make the widgets visible.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.notifyFormsVisible(formIds, true, (error, data) => { + if (error.code) { + console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); + } +}); +``` + +## notifyFormsVisible + +notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void> + +Instructs the widgets to make themselves visible. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isVisible | boolean | Yes | Whether to make the widgets visible.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.notifyFormsVisible(formIds, true).then(() => { + console.log('formHost notifyFormsVisible success'); +}).catch((error) => { + console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); +}); +``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void + +Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formIds | Array<string> | Yes | List of widget IDs.| +| isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { + if (error.code) { + console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); + } +}); +``` + +## notifyFormsEnableUpdate + +notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void> + +Instructs the widgets to enable or disable updates. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + + | Name| Type | Mandatory| Description | + | ------ | ------ | ---- | ------- | + | formIds | Array<string> | Yes | List of widget IDs.| + | isEnableUpdate | boolean | Yes | Whether to make the widgets updatable.| + +**Return value** + + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise that returns no value.| + +**Example** + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.notifyFormsEnableUpdate(formIds, true).then(() => { + console.log('formHost notifyFormsEnableUpdate success'); +}).catch((error) => { + console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); +}); +``` +## shareForm9+ + +shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void + +Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **err** is undefined; otherwise, **err** is an error object.| + +**Example** + +```ts +var formId = "12400633174999288"; +var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; +formHost.shareForm(formId, deviceId, (error, data) => { + if (error.code) { + console.log('formHost shareForm, error:' + JSON.stringify(error)); + } +}); +``` + +## shareForm9+ + +shareForm(formId: string, deviceId: string): Promise<void> + +Shares a specified widget with a remote device. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise that returns no value.| + +**Parameters** + +```ts +var formId = "12400633174999288"; +var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; +formHost.shareForm(formId, deviceId).then(() => { + console.log('formHost shareForm success'); +}).catch((error) => { + console.log('formHost shareForm, error:' + JSON.stringify(error)); +}); +``` + +## notifyFormsPrivacyProtected9+ + +notifyFormsPrivacyProtected(formIds: Array\, isProtected: boolean, callback: AsyncCallback\): void + +**Required permissions**: ohos.permission.REQUIRE_FORM + +**System capability**: SystemCapability.Ability.Form + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------- | +| formId | string | Yes | Widget ID.| +| deviceId | string | Yes | Remote device ID.| + +```ts +var formIds = new Array("12400633174999288", "12400633174999289"); +formHost.notifyFormsPrivacyProtected(formIds, true).then(() => { + console.log('formHost shareForm success'); +}).catch((error) => { + console.log('formHost shareForm, error:' + JSON.stringify(error)); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-application-formInfo.md b/en/application-dev/reference/apis/js-apis-application-formInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..de5bd8f6b24e7bd1f6e3fe66b4f4122c9a570d16 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-application-formInfo.md @@ -0,0 +1,152 @@ +# @ohos.application.formInfo + +The **FormInfo** module provides widget information and state. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [FormInfo](js-apis-app-form-formInfo.md) instead. + +## Modules to Import + +```ts +import formInfo from '@ohos.application.formInfo'; +``` + +## FormInfo + +Describes widget information. + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable | Writable | Description | +| ----------- | -------- |-------- | -------------------- | ------------------------------------------------------------ | +| bundleName | string | Yes | No | Name of the bundle to which the widget belongs. | +| moduleName | string | Yes | No | Name of the module to which the widget belongs. | +| abilityName | string | Yes | No | Name of the ability to which the widget belongs. | +| name | string | Yes | No | Widget name. | +| description | string | Yes | No | Description of the widget. | +| type | [FormType](#formtype) | Yes | No | Type of the widget. Currently, only JS widgets are supported.| +| jsComponentName | string | Yes | No | Name of the component used in the JS widget. | +| colorMode | [ColorMode](#colormode) | Yes | No | Color mode of the widget. | +| isDefault | boolean | Yes | No | Whether the widget is the default one. | +| updateEnabled | boolean | Yes | No | Whether the widget is updatable. | +| formVisibleNotify | string | Yes | No | Whether to send a notification when the widget is visible. | +| relatedBundleName | string | Yes | No | Name of the associated bundle to which the widget belongs. | +| scheduledUpdateTime | string | Yes | No | Time when the widget was updated. | +| formConfigAbility | string | Yes | No | Configuration ability of the widget. | +| updateDuration | string | Yes | No | Update period of the widget.| +| defaultDimension | number | Yes | No | Default dimension of the widget. | +| supportDimensions | Array<number> | Yes | No | Dimensions supported by the widget. | +| customizeData | {[key: string]: [value: string]} | Yes | No | Custom data of the widget. | + +## FormType + +Enumerates the widget types. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| JS | 1 | JS widget. | +| eTS9+ | 2 | eTS widget.| + +## ColorMode + +Enumerates the color modes supported by the widget. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| MODE_AUTO | -1 | Auto mode. | +| MODE_DARK | 0 | Dark mode. | +| MODE_LIGHT | 1 | Light mode. | + +## FormStateInfo + +Describes the widget state information. + +**System capability**: SystemCapability.Ability.Form + +| Name | Type | Readable | Writable | Description | +| ----------- | -------- |-------- | -------------------- | ------------------------------------------------------------ | +| formState | [FormState](#formstate) | Yes | No | Widget state. | +| want | Want | Yes | No | Want text. | + +## FormState + +Enumerates the widget states. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| UNKNOWN | -1 | Unknown state. | +| DEFAULT | 0 | Default state. | +| READY | 1 | Ready state. | + +## FormParam + +Enumerates the widget parameters. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| IDENTITY_KEY9+ | "ohos.extra.param.key.form_identity" | Widget ID.
**System API**: This is a system API. | +| DIMENSION_KEY | "ohos.extra.param.key.form_dimension" | Widget dimension. | +| NAME_KEY | "ohos.extra.param.key.form_name" | Widget name. | +| MODULE_NAME_KEY | "ohos.extra.param.key.module_name" | Name of the module to which the widget belongs. | +| WIDTH_KEY | "ohos.extra.param.key.form_width" | Widget width. | +| HEIGHT_KEY | "ohos.extra.param.key.form_height" | Widget height. | +| TEMPORARY_KEY | "ohos.extra.param.key.form_temporary" | Temporary widget. | +| ABILITY_NAME_KEY9+ | "ohos.extra.param.key.ability_name" | Ability name. | +| DEVICE_ID_KEY9+ | "ohos.extra.param.key.device_id" | Device ID.
**System API**: This is a system API. | +| BUNDLE_NAME_KEY9+ | "ohos.extra.param.key.bundle_name" | Key that specifies the target bundle name.| + +## FormDimension9+ + +Enumerates the widget dimensions. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| Dimension_1_2 9+ | 1 | 1 x 2. | +| Dimension_2_2 9+ | 2 | 2 x 2. | +| Dimension_2_4 9+ | 3 | 2 x 4. | +| Dimension_4_4 9+ | 4 | 4 x 4. | +| Dimension_2_1 9+ | 5 | 2 x 1. | + +## VisibilityType + +Enumerates the visibility types of the widget. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| FORM_VISIBLE9+ | 1 | The card is visible. | +| FORM_INVISIBLE9+ | 2 | The card is invisible.| + +## FormInfoFilter9+ + +Defines the widget information filter. Only the widget information that meets the filter is returned. + +**System capability**: SystemCapability.Ability.Form + +| Name | Description | +| ----------- | ------------ | +| moduleName9+ | Only the information about the widget whose **moduleName** is the same as the provided value is returned.| + +## VisibilityType9+ + +Enumerates the visibility types of the widget. + +**System capability**: SystemCapability.Ability.Form + +| Name | Value | Description | +| ----------- | ---- | ------------ | +| FORM_VISIBLE9+ | 1 | The widget is visible.| +| FORM_INVISIBLE9+ | 2 | The widget is invisible.| diff --git a/en/application-dev/reference/apis/js-apis-formprovider.md b/en/application-dev/reference/apis/js-apis-application-formProvider.md similarity index 74% rename from en/application-dev/reference/apis/js-apis-formprovider.md rename to en/application-dev/reference/apis/js-apis-application-formProvider.md index 8ce539886e5460ffe712b486addf6e3813c44a90..05318bda39a220c15a328368fd5bf54c29f0ad05 100644 --- a/en/application-dev/reference/apis/js-apis-formprovider.md +++ b/en/application-dev/reference/apis/js-apis-application-formProvider.md @@ -1,42 +1,36 @@ -# FormProvider +# @ohos.application.formProvider The **FormProvider** module provides APIs related to the widget provider. You can use the APIs to update a widget, set the next refresh time for a widget, obtain widget information, and request a widget release. > **NOTE** -> > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> This module is deprecated since API version 9. You are advised to use [FormProvider](js-apis-app-form-formProvider.md) instead. ## Modules to Import -``` +```ts import formProvider from '@ohos.application.formProvider'; ``` -## Required Permissions - -None. - ## setFormNextRefreshTime -setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void; +setFormNextRefreshTime(formId: string, minute: number, callback: AsyncCallback<void>): void Sets the next refresh time for a widget. This API uses an asynchronous callback to return the result. -**System capability** - -SystemCapability.Ability.Form +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------- | - | formId | string | Yes | ID of a widget. | + | formId | string | Yes | Widget ID. | | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** - ```js + ```ts var formId = "12400633174999288"; formProvider.setFormNextRefreshTime(formId, 5, (error, data) => { if (error.code) { @@ -47,30 +41,28 @@ SystemCapability.Ability.Form ## setFormNextRefreshTime -setFormNextRefreshTime(formId: string, minute: number): Promise<void>; +setFormNextRefreshTime(formId: string, minute: number): Promise<void> Sets the next refresh time for a widget. This API uses a promise to return the result. -**System capability** - -SystemCapability.Ability.Form +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------------------------------------- | - | formId | string | Yes | ID of a widget. | + | formId | string | Yes | Widget ID. | | minute | number | Yes | Refresh interval, in minutes. The value must be greater than or equal to 5. | **Return value** | Type | Description | | ------------- | ---------------------------------- | - | Promise\ |Promise used to return the result. | + | Promise\ | Promise that returns no value. | **Example** - ```js + ```ts var formId = "12400633174999288"; formProvider.setFormNextRefreshTime(formId, 5).then(() => { console.log('formProvider setFormNextRefreshTime success'); @@ -81,25 +73,23 @@ SystemCapability.Ability.Form ## updateForm -updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void; +updateForm(formId: string, formBindingData: formBindingData.FormBindingData,callback: AsyncCallback<void>): void Updates a widget. This API uses an asynchronous callback to return the result. -**System capability** - -SystemCapability.Ability.Form +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------ | ---------------------------------------------------------------------- | ---- | ---------------- | | formId | string | Yes | ID of the widget to update.| - | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | + | formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | Yes | Data to be used for the update. | | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** - ```js + ```ts import formBindingData from '@ohos.application.formBindingData'; var formId = "12400633174999288"; let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); @@ -112,30 +102,28 @@ SystemCapability.Ability.Form ## updateForm -updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void>; +updateForm(formId: string, formBindingData: formBindingData.FormBindingData): Promise<void> Updates a widget. This API uses a promise to return the result. -**System capability** - -SystemCapability.Ability.Form +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------ | ---------------------------------------------------------------------- | ---- | ---------------- | | formId | string | Yes | ID of the widget to update.| - | formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data to be used for the update. | + | formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdat) | Yes | Data to be used for the update. | **Return value** | Type | Description | | -------------- | ----------------------------------- | -| Promise\ | Promise used to return the result.| +| Promise\ | Promise that returns no value.| **Example** - ```js + ```ts import formBindingData from '@ohos.application.formBindingData'; var formId = "12400633174999288"; let obj = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); @@ -148,7 +136,7 @@ SystemCapability.Ability.Form ## getFormsInfo9+ -getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void; +getFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void Obtains the application's widget information on the device. This API uses an asynchronous callback to return the result. @@ -158,11 +146,11 @@ Obtains the application's widget information on the device. This API uses an asy | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | -| callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| +| callback | AsyncCallback<Array<[FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.| **Example** -```js +```ts formProvider.getFormsInfo((error, data) => { if (error.code) { console.log('formProvider getFormsInfo, error:' + JSON.stringify(error)); @@ -173,7 +161,7 @@ formProvider.getFormsInfo((error, data) => { ``` ## getFormsInfo9+ -getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void; +getFormsInfo(filter: formInfo.FormInfoFilter, callback: AsyncCallback<Array<formInfo.FormInfo>>): void Obtains the application's widget information that meets a filter criterion on the device. This API uses an asynchronous callback to return the result. @@ -183,14 +171,15 @@ Obtains the application's widget information that meets a filter criterion on th | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | -| filter | [formInfo.FormInfoFilter](./js-apis-formInfo.md#forminfofilter) | Yes| Filter criterion.| -| callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| +| filter | [formInfo.FormInfoFilter](./js-apis-application-formInfo.md#forminfofilter) | Yes| Filter criterion.| +| callback | AsyncCallback<Array<[FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.| **Example** -```js +```ts import formInfo from '@ohos.application.formInfo'; const filter : formInfo.FormInfoFilter = { + // get info of forms belong to module entry. moduleName : "entry" }; formProvider.getFormsInfo(filter, (error, data) => { @@ -204,7 +193,7 @@ formProvider.getFormsInfo(filter, (error, data) => { ## getFormsInfo9+ -getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>>; +getFormsInfo(filter?: formInfo.FormInfoFilter): Promise<Array<formInfo.FormInfo>> Obtains the application's widget information on the device. This API uses a promise to return the result. @@ -214,19 +203,20 @@ Obtains the application's widget information on the device. This API uses a prom | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | -| filter | [formInfo.FormInfoFilter](./js-apis-formInfo.md) | No| Filter criterion.| +| filter | [formInfo.FormInfoFilter](./js-apis-application-formInfo.md) | No| Filter criterion.| **Return value** | Type | Description | | :------------ | :---------------------------------- | -| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| +| Promise<Array<[FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Promise used to return the information obtained.| **Example** -```js +```ts import formInfo from '@ohos.application.formInfo'; const filter : formInfo.FormInfoFilter = { + // get info of forms belong to module entry. moduleName : "entry" }; formProvider.getFormsInfo(filter).then((data) => { @@ -238,25 +228,25 @@ formProvider.getFormsInfo(filter).then((data) => { ## requestPublishForm9+ -requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void; +requestPublishForm(want: Want, formBindingData: formBindingData.FormBindingData, callback: AsyncCallback\): void -Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. +Requests to publish a widget carrying data to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. **System capability**: SystemCapability.Ability.Form -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** | Name| Type | Mandatory| Description | | ------ | ---------------------------------------------------------------------- | ---- | ---------------- | -| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | -| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | Yes | Data used for creating the widget.| +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.| | callback | AsyncCallback<string> | Yes| Callback used to return the widget ID.| **Example** - ```js + ```ts import formBindingData from '@ohos.application.formBindingData'; var want = { abilityName: "FormAbility", @@ -278,24 +268,24 @@ Requests to publish a widget carrying data to the widget host. This API uses an ## requestPublishForm9+ -requestPublishForm(want: Want, callback: AsyncCallback<string>): void; +requestPublishForm(want: Want, callback: AsyncCallback<string>): void -Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. +Requests to publish a widget to the widget host. This API uses an asynchronous callback to return the result. This API is usually called by the home screen. **System capability**: SystemCapability.Ability.Form -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** | Name | Type | Mandatory| Description | | -------- | ----------------------------------- | ---- | ------------------------------------------------------------ | -| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | -| callback | AsyncCallback<string> | Yes | Callback used to return the widget ID. | +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| callback | AsyncCallback<string> | Yes | Callback used to return the widget ID.| **Example** - ```js + ```ts var want = { abilityName: "FormAbility", parameters: { @@ -315,20 +305,20 @@ Requests to publish a widget to the widget host. This API uses an asynchronous c ## requestPublishForm9+ -requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string>; +requestPublishForm(want: Want, formBindingData?: formBindingData.FormBindingData): Promise<string> -Requests to publish a widget to the widget host. This API uses a promise to return the result. +Requests to publish a widget to the widget host. This API uses a promise to return the result. This API is usually called by the home screen. **System capability**: SystemCapability.Ability.Form -**System API**: This is a system API and cannot be called by third-party applications. +**System API**: This is a system API. **Parameters** | Name | Type | Mandatory| Description | | --------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| want | [Want](js-apis-application-Want.md) | Yes | Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | -| formBindingData | [FormBindingData](js-apis-formbindingdata.md#formbindingdata) | No | Data used for creating the widget. | +| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:
Information about the target widget.
**abilityName**: ability of the target widget.
**parameters**:
"ohos.extra.param.key.form_dimension"
"ohos.extra.param.key.form_name"
"ohos.extra.param.key.module_name" | +| formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | No | Data used for creating the widget. | **Return value** @@ -338,7 +328,7 @@ Requests to publish a widget to the widget host. This API uses a promise to retu **Example** - ```js + ```ts var want = { abilityName: "FormAbility", parameters: { @@ -356,23 +346,23 @@ Requests to publish a widget to the widget host. This API uses a promise to retu ## isRequestPublishFormSupported9+ -isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void; +isRequestPublishFormSupported(callback: AsyncCallback<boolean>): void Checks whether a widget can be published to the widget host. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Ability.Form +**System API**: This is a system API. -**System API**: This is a system API and cannot be called by third-party applications. +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------ | ------ | ---- | ------- | -| callback | AsyncCallback<boolean> | Yes| Callback used to return the result.| +| callback | AsyncCallback<boolean> | Yes| Callback used to return whether the widget can be published to the widget host.| **Example** -```js +```ts formProvider.isRequestPublishFormSupported((error, isSupported) => { if (error.code) { console.log('formProvider isRequestPublishFormSupported, error:' + JSON.stringify(error)); @@ -400,23 +390,23 @@ formProvider.isRequestPublishFormSupported((error, isSupported) => { ## isRequestPublishFormSupported9+ -isRequestPublishFormSupported(): Promise<boolean>; +isRequestPublishFormSupported(): Promise<boolean> Checks whether a widget can be published to the widget host. This API uses a promise to return the result. -**System capability**: SystemCapability.Ability.Form +**System API**: This is a system API. -**System API**: This is a system API and cannot be called by third-party applications. +**System capability**: SystemCapability.Ability.Form **Return value** | Type | Description | | :------------ | :---------------------------------- | -| Promise<boolean> | Promise used to return the result.| +| Promise<boolean> | Promise used to return whether the widget can be published to the widget host.| **Example** -```js +```ts formProvider.isRequestPublishFormSupported().then((isSupported) => { if (isSupported) { var want = { diff --git a/en/application-dev/reference/apis/js-apis-missionManager.md b/en/application-dev/reference/apis/js-apis-application-missionManager.md similarity index 84% rename from en/application-dev/reference/apis/js-apis-missionManager.md rename to en/application-dev/reference/apis/js-apis-application-missionManager.md index 189042b1f1df1727423c65c0a226b11ae473db2a..c30dda422ded7148e35ebab1cc26804290bc1ea6 100644 --- a/en/application-dev/reference/apis/js-apis-missionManager.md +++ b/en/application-dev/reference/apis/js-apis-application-missionManager.md @@ -1,4 +1,4 @@ -# missionManager +# @ohos.application.missionManager The **missionManager** module provides APIs to lock, unlock, and clear missions, and switch a mission to the foreground. @@ -8,7 +8,7 @@ The **missionManager** module provides APIs to lock, unlock, and clear missions, ## Modules to Import -``` +```ts import missionManager from '@ohos.application.missionManager' ``` @@ -22,7 +22,7 @@ registerMissionListener(listener: MissionListener): number; Registers a listener to observe the mission status. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -32,7 +32,7 @@ Registers a listener to observe the mission status. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | listener | MissionListener | Yes| Listener to register.| + | listener | [MissionListener](js-apis-inner-application-missionListener.md) | Yes| Listener to register.| **Return value** @@ -42,17 +42,18 @@ Registers a listener to observe the mission status. **Example** -```js - var listener = { - onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, - onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, - onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, - onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, - onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, - onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} - }; - console.log("registerMissionListener") - var listenerid = missionManager.registerMissionListener(listener); +```ts +var listener = { + onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, + onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, + onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, + onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, + onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")}, + onMissionLabelUpdated: function (mission) {console.log("--------onMissionLabelUpdated-------")} +}; +console.log("registerMissionListener") +var listenerid = missionManager.registerMissionListener(listener); ``` @@ -62,7 +63,7 @@ unregisterMissionListener(listenerId: number, callback: AsyncCallback<void> Deregisters a mission status listener. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -77,14 +78,15 @@ Deregisters a mission status listener. This API uses an asynchronous callback to **Example** -```js +```ts var listener = { onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, - onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")}, + onMissionLabelUpdated: function (mission) {console.log("--------onMissionLabelUpdated-------")} }; console.log("registerMissionListener") var listenerid = missionManager.registerMissionListener(listener); @@ -101,7 +103,7 @@ unregisterMissionListener(listenerId: number): Promise<void>; Deregisters a mission status listener. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -121,14 +123,15 @@ Deregisters a mission status listener. This API uses a promise to return the res **Example** -```js +```ts var listener = { onMissionCreated: function (mission) {console.log("--------onMissionCreated-------")}, onMissionDestroyed: function (mission) {console.log("--------onMissionDestroyed-------")}, onMissionSnapshotChanged: function (mission) {console.log("--------onMissionSnapshotChanged-------")}, onMissionMovedToFront: function (mission) {console.log("--------onMissionMovedToFront-------")}, onMissionIconUpdated: function (mission, icon) {console.log("--------onMissionIconUpdated-------")}, - onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")} + onMissionClosed: function (mission) {console.log("--------onMissionClosed-------")}, + onMissionLabelUpdated: function (mission) {console.log("--------onMissionLabelUpdated-------")} }; console.log("registerMissionListener") var listenerid = missionManager.registerMissionListener(listener); @@ -145,7 +148,7 @@ getMissionInfo(deviceId: string, missionId: number, callback: AsyncCallback<M Obtains the information about a given mission. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -157,11 +160,11 @@ Obtains the information about a given mission. This API uses an asynchronous cal | -------- | -------- | -------- | -------- | | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| | missionId | number | Yes| Mission ID.| - | callback | AsyncCallback<[MissionInfo](#missioninfo)> | Yes| Callback used to return the mission information obtained.| + | callback | AsyncCallback<[MissionInfo](js-apis-inner-application-missionInfo.md)> | Yes| Callback used to return the mission information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions=missionManager.getMissionInfos("",10).catch(function(err){console.log(err);}); @@ -183,7 +186,7 @@ getMissionInfo(deviceId: string, missionId: number): Promise<MissionInfo>; Obtains the information about a given mission. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -200,11 +203,11 @@ Obtains the information about a given mission. This API uses a promise to return | Type| Description| | -------- | -------- | - | Promise<[MissionInfo](#missioninfo)> | Promise used to return the mission information obtained.| + | Promise<[MissionInfo](js-apis-inner-application-missionInfo.md)> | Promise used to return the mission information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var mission = missionManager.getMissionInfo("", 10).catch(function (err){ @@ -219,7 +222,7 @@ getMissionInfos(deviceId: string, numMax: number, callback: AsyncCallback<Arr Obtains information about all missions. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -231,11 +234,11 @@ Obtains information about all missions. This API uses an asynchronous callback t | -------- | -------- | -------- | -------- | | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| | numMax | number | Yes| Maximum number of missions whose information can be obtained.| - | callback | AsyncCallback<Array<[MissionInfo](#missioninfo)>> | Yes| Callback used to return the array of mission information obtained.| + | callback | AsyncCallback<Array<[MissionInfo](js-apis-inner-application-missionInfo.md)>> | Yes| Callback used to return the array of mission information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -252,7 +255,7 @@ getMissionInfos(deviceId: string, numMax: number): Promise<Array<MissionIn Obtains information about all missions. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -269,11 +272,11 @@ Obtains information about all missions. This API uses a promise to return the re | Type| Description| | -------- | -------- | - | Promise<Array<[MissionInfo](#missioninfo)>> | Promise used to return the array of mission information obtained.| + | Promise<Array<[MissionInfo](js-apis-inner-application-missionInfo.md)>> | Promise used to return the array of mission information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions = missionManager.getMissionInfos("", 10).catch(function (err){ @@ -288,7 +291,7 @@ getMissionSnapShot(deviceId: string, missionId: number, callback: AsyncCallback& Obtains the snapshot of a given mission. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -300,11 +303,11 @@ Obtains the snapshot of a given mission. This API uses an asynchronous callback | -------- | -------- | -------- | -------- | | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| | missionId | number | Yes| Mission ID.| - | callback | AsyncCallback<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| + | callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -327,7 +330,7 @@ getMissionSnapShot(deviceId: string, missionId: number): Promise<MissionSnaps Obtains the snapshot of a given mission. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -344,11 +347,11 @@ Obtains the snapshot of a given mission. This API uses a promise to return the r | Type| Description| | -------- | -------- | - | Promise<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Promise used to return the snapshot information obtained.| + | Promise<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Promise used to return the snapshot information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions; @@ -370,7 +373,7 @@ getLowResolutionMissionSnapShot(deviceId: string, missionId: number, callback: A Obtains the low-resolution snapshot of a given mission. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -382,11 +385,11 @@ Obtains the low-resolution snapshot of a given mission. This API uses an asynchr | -------- | -------- | -------- | -------- | | deviceId | string | Yes| Device ID. It is a null string by default for the local device.| | missionId | number | Yes| Mission ID.| - | callback | AsyncCallback<[MissionSnapshot](js-apis-application-MissionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| + | callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -409,7 +412,7 @@ getLowResolutionMissionSnapShot(deviceId: string, missionId: number): Promise\ { @@ -490,7 +493,7 @@ lockMission(missionId: number): Promise<void>; Locks a given mission. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -510,7 +513,7 @@ Locks a given mission. This API uses a promise to return the result. **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions; missionManager.getMissionInfos("",10).then(function(res){ @@ -532,7 +535,7 @@ unlockMission(missionId: number, callback: AsyncCallback<void>): void; Unlocks a given mission. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -547,7 +550,7 @@ Unlocks a given mission. This API uses an asynchronous callback to return the re **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -569,7 +572,7 @@ unlockMission(missionId: number): Promise<void>; Unlocks a given mission. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -589,7 +592,7 @@ Unlocks a given mission. This API uses a promise to return the result. **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions; @@ -615,7 +618,7 @@ clearMission(missionId: number, callback: AsyncCallback<void>): void; Clears a given mission, regardless of whether it is locked. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -630,7 +633,7 @@ Clears a given mission, regardless of whether it is locked. This API uses an asy **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -652,7 +655,7 @@ clearMission(missionId: number): Promise<void>; Clears a given mission, regardless of whether it is locked. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -672,7 +675,7 @@ Clears a given mission, regardless of whether it is locked. This API uses a prom **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions; @@ -695,7 +698,7 @@ clearAllMissions(callback: AsyncCallback<void>): void; Clears all unlocked missions. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -703,7 +706,7 @@ Clears all unlocked missions. This API uses an asynchronous callback to return t **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.clearAllMissions().then(() => { @@ -718,7 +721,7 @@ clearAllMissions(): Promise<void>; Clears all unlocked missions. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -732,7 +735,7 @@ Clears all unlocked missions. This API uses a promise to return the result. **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.clearAllMissions().catch(function (err){ console.log(err); @@ -746,7 +749,7 @@ moveMissionToFront(missionId: number, callback: AsyncCallback<void>): void Switches a given mission to the foreground. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -761,7 +764,7 @@ Switches a given mission to the foreground. This API uses an asynchronous callba **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -783,7 +786,7 @@ moveMissionToFront(missionId: number, options: StartOptions, callback: AsyncCall Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses an asynchronous callback to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -794,12 +797,12 @@ Switches a given mission to the foreground, with the startup parameters for the | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | missionId | number | Yes| Mission ID.| - | options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| + | options | [StartOptions](js-apis-application-startOptions.md) | Yes| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' missionManager.getMissionInfos("", 10, (error, missions) => { @@ -821,7 +824,7 @@ moveMissionToFront(missionId: number, options?: StartOptions): Promise<void&g Switches a given mission to the foreground, with the startup parameters for the switching specified. This API uses a promise to return the result. -**Required permission**: ohos.permission.MANAGE_MISSIONS +**Required permissions**: ohos.permission.MANAGE_MISSIONS **System capability**: SystemCapability.Ability.AbilityRuntime.Mission @@ -832,7 +835,7 @@ Switches a given mission to the foreground, with the startup parameters for the | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | missionId | number | Yes| Mission ID.| - | options | [StartOptions](js-apis-application-StartOptions.md) | No| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| + | options | [StartOptions](js-apis-application-startOptions.md) | No| Startup parameters, which are used to specify the window mode and device ID for switching the mission to the foreground.| **Return value** @@ -842,7 +845,7 @@ Switches a given mission to the foreground, with the startup parameters for the **Example** - ```js + ```ts import missionManager from '@ohos.application.missionManager' var allMissions; @@ -857,22 +860,3 @@ Switches a given mission to the foreground, with the startup parameters for the console.log(err); }); ``` - -## MissionInfo - -Describes the mission information. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Mission - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| missionId | number | Yes| Yes| Mission ID.| -| runningState | number | Yes| Yes| Running state of the mission.| -| lockedState | boolean | Yes| Yes| Locked state of the mission.| -| timestamp | string | Yes| Yes| Latest time when the mission was created or updated.| -| want | [Want](js-apis-application-Want.md) | Yes| Yes| **Want** information of the mission.| -| label | string | Yes| Yes| Label of the mission.| -| iconPath | string | Yes| Yes| Path of the mission icon.| -| continuable | boolean | Yes| Yes| Whether the mission can be continued on another device.| diff --git a/en/application-dev/reference/apis/js-apis-service-extension-ability.md b/en/application-dev/reference/apis/js-apis-application-serviceExtensionAbility.md similarity index 81% rename from en/application-dev/reference/apis/js-apis-service-extension-ability.md rename to en/application-dev/reference/apis/js-apis-application-serviceExtensionAbility.md index 388b4308555f8dc061bfa62da40fd4dc5d97cfee..ba59d9a6ea78434939ee99a6e25b3c2945874532 100644 --- a/en/application-dev/reference/apis/js-apis-service-extension-ability.md +++ b/en/application-dev/reference/apis/js-apis-application-serviceExtensionAbility.md @@ -1,4 +1,4 @@ -# ServiceExtensionAbility +# @ohos.application.ServiceExtensionAbility The **ServiceExtensionAbility** module provides APIs for Service Extension abilities. @@ -9,8 +9,8 @@ The **ServiceExtensionAbility** module provides APIs for Service Extension abili ## Modules to Import -``` -import ServiceExtension from '@ohos.application.ServiceExtensionAbility'; +```ts +import ServiceExtensionAbility from '@ohos.application.ServiceExtensionAbility'; ``` ## Required Permissions @@ -25,7 +25,7 @@ None. | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.| +| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.| ## ServiceExtensionAbility.onCreate @@ -42,11 +42,11 @@ Called when a Service Extension ability is created to initialize the service log | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | want | [Want](js-apis-application-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onCreate(want) { console.log('onCreate, want:' + want.abilityName); @@ -67,7 +67,7 @@ Called when this Service Extension ability is destroyed to clear resources. **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onDestroy() { console.log('onDestroy'); @@ -90,12 +90,12 @@ Called after **onCreate** is invoked when a Service Extension ability is started | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | want | [Want](js-apis-application-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| | startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.| **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onRequest(want, startId) { console.log('onRequest, want:' + want.abilityName); @@ -118,7 +118,7 @@ Called after **onCreate** is invoked when a Service Extension ability is started | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | want | [Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| **Return value** @@ -128,7 +128,7 @@ Called after **onCreate** is invoked when a Service Extension ability is started **Example** - ```js + ```ts import rpc from '@ohos.rpc' class StubTest extends rpc.RemoteObject{ constructor(des) { @@ -160,11 +160,11 @@ Called when this Service Extension ability is disconnected. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onDisconnect(want) { console.log('onDisconnect, want:' + want.abilityName); @@ -186,11 +186,11 @@ Called when this Service Extension ability is reconnected. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want |[Want](js-apis-application-Want.md)| Yes| Information related to this Service Extension ability, including the ability name and bundle name.| + | want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.| **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onReconnect(want) { console.log('onReconnect, want:' + want.abilityName); @@ -202,7 +202,7 @@ Called when this Service Extension ability is reconnected. onConfigurationUpdated(config: Configuration): void; - Called when the configuration of this Service Extension ability is updated. +Called when the configuration of this Service Extension ability is updated. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -212,11 +212,11 @@ onConfigurationUpdated(config: Configuration): void; | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| + | config | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.| **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { onConfigurationUpdated(config) { console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); @@ -242,7 +242,7 @@ Dumps the client information. **Example** - ```js + ```ts class ServiceExt extends ServiceExtension { dump(params) { console.log('dump, params:' + JSON.stringify(params)); diff --git a/en/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md b/en/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md index 57a313f1f600607c143aaec48205a482221ba355..b9086a6ce6cbd42c53730baa1531255c0d383ba9 100644 --- a/en/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md +++ b/en/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md @@ -1,4 +1,4 @@ -# StaticSubscriberExtensionAbility +# @ohos.application.StaticSubscriberExtensionAbility The **StaticSubscriberExtensionAbility** module provides Extension abilities for static subscribers. @@ -8,7 +8,7 @@ The **StaticSubscriberExtensionAbility** module provides Extension abilities for > The APIs of this module can be used only in the stage model. ## Modules to Import -``` +```ts import StaticSubscriberExtensionAbility from '@ohos.application.StaticSubscriberExtensionAbility' ``` @@ -24,13 +24,12 @@ Callback of the common event of a static subscriber. **Parameters** - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | event | [CommonEventData](js-apis-commonEvent.md#commoneventdata) | Yes| Common event of a static subscriber.| +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| event | [CommonEventData](js-apis-commonEvent.md#commoneventdata) | Yes| Common event of a static subscriber.| -**Example** - - ```js +**Example** + ```ts var StaticSubscriberExtensionAbility = requireNapi("application.StaticSubscriberExtensionAbility") { onReceiveEvent(event){ diff --git a/en/application-dev/reference/apis/js-apis-testRunner.md b/en/application-dev/reference/apis/js-apis-application-testRunner.md similarity index 95% rename from en/application-dev/reference/apis/js-apis-testRunner.md rename to en/application-dev/reference/apis/js-apis-application-testRunner.md index 403ec97e87bce272b6b4ee45568eb6a23590ab31..688774a0d4b840e19e398624be41ac85c07c8f37 100644 --- a/en/application-dev/reference/apis/js-apis-testRunner.md +++ b/en/application-dev/reference/apis/js-apis-application-testRunner.md @@ -1,4 +1,4 @@ -# TestRunner +# @ohos.application.testRunner The **TestRunner** module provides a test framework. You can use the APIs of this module to prepare the unit test environment and run test cases. @@ -10,7 +10,7 @@ To implement your own unit test framework, extend this class and override its AP ## Modules to Import -```js +```ts import TestRunner from '@ohos.application.testRunner' ``` @@ -24,7 +24,7 @@ Prepares the unit test environment to run test cases. **Example** -```js +```ts export default class UserTestRunner implements TestRunner { onPrepare() { console.log("Trigger onPrepare") @@ -45,7 +45,7 @@ Runs test cases. **Example** -```js +```ts export default class UserTestRunner implements TestRunner { onPrepare() {} onRun() { diff --git a/en/application-dev/reference/apis/js-apis-appmanager.md b/en/application-dev/reference/apis/js-apis-appmanager.md deleted file mode 100644 index 3d93bdf33a527668c4c1c98ac4cfd8611ea9010a..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-appmanager.md +++ /dev/null @@ -1,1000 +0,0 @@ -# appManager - -The **appManager** module implements application management. You can use the APIs of this module to query whether the application is undergoing a stability test, whether the application is running on a RAM constrained device, the memory size of the application, and information about the running process. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -```js -import app from '@ohos.application.appManager'; -``` - -## appManager.isRunningInStabilityTest8+ - -static isRunningInStabilityTest(callback: AsyncCallback<boolean>): void - -Checks whether this application is undergoing a stability test. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | No| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| - -**Example** - - ```js - import app from '@ohos.application.appManager'; - app.isRunningInStabilityTest((err, flag) => { - console.log('startAbility result:' + JSON.stringify(err)); - }) - ``` - - -## appManager.isRunningInStabilityTest8+ - -static isRunningInStabilityTest(): Promise<boolean> - -Checks whether this application is undergoing a stability test. This API uses a promise to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.| - -**Example** - - ```js - import app from '@ohos.application.appManager'; - app.isRunningInStabilityTest().then((flag) => { - console.log('success:' + JSON.stringify(flag)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` - - -## appManager.isRamConstrainedDevice - -isRamConstrainedDevice(): Promise\; - -Checks whether this application is running on a RAM constrained device. This API uses a promise to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<boolean> | Promise used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| - -**Example** - - ```js - app.isRamConstrainedDevice().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` - -## appManager.isRamConstrainedDevice - -isRamConstrainedDevice(callback: AsyncCallback\): void; - -Checks whether this application is running on a RAM constrained device. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<boolean> | No| Callback used to return whether the application is running on a RAM constrained device. If the application is running on a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.| - -**Example** - - ```js - app.isRamConstrainedDevice((err, data) => { - console.log('startAbility result failed:' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` - -## appManager.getAppMemorySize - -getAppMemorySize(): Promise\; - -Obtains the memory size of this application. This API uses a promise to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<number> | Size of the application memory.| - -**Example** - - ```js - app.getAppMemorySize().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` - -## appManager.getAppMemorySize - -getAppMemorySize(callback: AsyncCallback\): void; - -Obtains the memory size of this application. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<number> | No| Size of the application memory.| - -**Example** - - ```js - app.getAppMemorySize((err, data) => { - console.log('startAbility result failed :' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` -## appManager.getProcessRunningInfos(deprecated) - -getProcessRunningInfos(): Promise\>; - -Obtains information about the running processes. This API uses a promise to return the result. - -> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9) instead. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\> | Promise used to return the process information.| - -**Example** - - ```js - app.getProcessRunningInfos().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` - -## appManager.getProcessRunningInfos(deprecated) - -getProcessRunningInfos(callback: AsyncCallback\>): void; - -Obtains information about the running processes. This API uses an asynchronous callback to return the result. - -> This API is deprecated since API version 9. You are advised to use [appManager.getProcessRunningInformation9+](#appmanagergetprocessrunninginformation9-1) instead. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | No| Callback used to return the process information.| - -**Example** - - ```js - app.getProcessRunningInfos((err, data) => { - console.log('startAbility result failed :' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` - -## appManager.getProcessRunningInformation9+ - -getProcessRunningInformation(): Promise\>; - -Obtains information about the running processes. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\> | Promise used to return the process information.| - -**Example** - - ```js - app.getProcessRunningInformation().then((data) => { - console.log('success:' + JSON.stringify(data)); - }).catch((error) => { - console.log('failed:' + JSON.stringify(error)); - }); - ``` - -## appManager.getProcessRunningInformation9+ - -getProcessRunningInformation(callback: AsyncCallback\>): void; - -Obtains information about the running processes. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | No| Callback used to return the process information.| - -**Example** - - ```js - app.getProcessRunningInformation((err, data) => { - console.log('startAbility result failed :' + JSON.stringify(err)); - console.log('startAbility result success:' + JSON.stringify(data)); - }) - ``` - -## appManager.registerApplicationStateObserver8+ - -registerApplicationStateObserver(observer: ApplicationStateObserver): number; - -Registers an observer to listen for the state changes of all applications. - -**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| observer | [ApplicationStateObserver](#applicationstateobserver) | No| Numeric code of the observer.| - -**Example** - - ```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); - - ``` - -## appManager.registerApplicationStateObserver9+ - -registerApplicationStateObserver(observer: ApplicationStateObserver, bundleNameList: Array\): number; - -Registers an observer to listen for the state changes of a specified application. - -**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| observer | [ApplicationStateObserver](#applicationstateobserver) | No| Numeric code of the observer.| -| bundleNameList | Array | No| **bundleName** array of the application. A maximum of 128 bundle names can be passed.| - -**Example** - - ```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - var bundleNameList = ['bundleName1', 'bundleName2']; - const observerCode = app.registerApplicationStateObserver(applicationStateObserver, bundleNameList); - console.log('-------- observerCode: ---------', observerCode); - - ``` -## appManager.unregisterApplicationStateObserver8+ - -unregisterApplicationStateObserver(observerId: number, callback: AsyncCallback\): void; - -Deregisters the application state observer. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| observerId | number | No| Numeric code of the observer.| -| callback | AsyncCallback\ | No| Callback used to return the result.| - -**Example** - - ```js - var observerId = 100; - - function unregisterApplicationStateObserverCallback(err) { - if (err) { - console.log('------------ unregisterApplicationStateObserverCallback ------------', err); - } - } - app.unregisterApplicationStateObserver(observerId, unregisterApplicationStateObserverCallback); - ``` - -## appManager.unregisterApplicationStateObserver8+ - -unregisterApplicationStateObserver(observerId: number): Promise\; - -Deregisters the application state observer. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.RUNNING_STATE_OBSERVER - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| observerId | number | No| Numeric code of the observer.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\ | Promise used to return the result.| - -**Example** - - ```js - var observerId = 100; - - app.unregisterApplicationStateObserver(observerId) - .then((data) => { - console.log('----------- unregisterApplicationStateObserver success ----------', data); - }) - .catch((err) => { - console.log('----------- unregisterApplicationStateObserver fail ----------', err); - }) - ``` - -## appManager.getForegroundApplications8+ - -getForegroundApplications(callback: AsyncCallback\>): void; - -Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | No| Callback used to return the application state data.| - -**Example** - - ```js - function getForegroundApplicationsCallback(err, data) { - if (err) { - console.log('--------- getForegroundApplicationsCallback fail ---------', err); - } else { - console.log('--------- getForegroundApplicationsCallback success ---------', data) - } - } - app.getForegroundApplications(getForegroundApplicationsCallback); - ``` - -## appManager.getForegroundApplications8+ - -getForegroundApplications(): Promise\>; - -Obtains applications that are running in the foreground. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_RUNNING_INFO - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\> | Promise used to return the application state data.| - -**Example** - - ```js - app.getForegroundApplications() - .then((data) => { - console.log('--------- getForegroundApplications success -------', data); - }) - .catch((err) => { - console.log('--------- getForegroundApplications fail -------', err); - }) - ``` - -## appManager.killProcessWithAccount8+ - -killProcessWithAccount(bundleName: string, accountId: number): Promise\ - -Kills a process by bundle name and account ID. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Bundle name of an application.| - | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| - -**Example** - -```js -var bundleName = 'bundleName'; -var accountId = 0; -app.killProcessWithAccount(bundleName, accountId) - .then((data) => { - console.log('------------ killProcessWithAccount success ------------', data); - }) - .catch((err) => { - console.log('------------ killProcessWithAccount fail ------------', err); - }) -``` - - -## appManager.killProcessWithAccount8+ - -killProcessWithAccount(bundleName: string, accountId: number, callback: AsyncCallback\): void - -Kills a process by bundle name and account ID. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS and ohos.permission.CLEAN_BACKGROUND_PROCESSES - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | bundleName | string | Yes| Bundle name of an application.| - | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| - | callback | AsyncCallback\ | Yes| Callback used to return the result.| - -**Example** - -```js -var bundleName = 'bundleName'; -var accountId = 0; -function killProcessWithAccountCallback(err, data) { - if (err) { - console.log('------------- killProcessWithAccountCallback fail, err: --------------', err); - } else { - console.log('------------- killProcessWithAccountCallback success, data: --------------', data); - } -} -app.killProcessWithAccount(bundleName, accountId, killProcessWithAccountCallback); -``` - -## appManager.killProcessesByBundleName8+ - -killProcessesByBundleName(bundleName: string, callback: AsyncCallback\); - -Kills a process by bundle name. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | No| Bundle name of an application.| -| callback | AsyncCallback\ | No| Callback used to return the result.| - -**Example** - - ```js - var bundleName = 'bundleName'; - function killProcessesByBundleNameCallback(err, data) { - if (err) { - console.log('------------- killProcessesByBundleNameCallback fail, err: --------------', err); - } else { - console.log('------------- killProcessesByBundleNameCallback success, data: --------------', data); - } - } - app.killProcessesByBundleName(bundleName, killProcessesByBundleNameCallback); - ``` - -## appManager.killProcessesByBundleName8+ - -killProcessesByBundleName(bundleName: string): Promise\; - -Kills a process by bundle name. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CLEAN_BACKGROUND_PROCESSES - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | No| Bundle name of an application.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\ | Promise used to return the result.| - -**Example** - - ```js -var bundleName = 'bundleName'; -app.killProcessesByBundleName(bundleName) - .then((data) => { - console.log('------------ killProcessesByBundleName success ------------', data); - }) - .catch((err) => { - console.log('------------ killProcessesByBundleName fail ------------', err); - }) - - ``` - -## appManager.clearUpApplicationData8+ - -clearUpApplicationData(bundleName: string, callback: AsyncCallback\); - -Clears application data by bundle name. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | No| Bundle name of an application.| -| callback | AsyncCallback\ | No| Callback used to return the result.| - -**Example** - - ```js - var bundleName = 'bundleName'; - function clearUpApplicationDataCallback(err, data) { - if (err) { - console.log('------------- clearUpApplicationDataCallback fail, err: --------------', err); - } else { - console.log('------------- clearUpApplicationDataCallback success, data: --------------', data); - } - } - app.clearUpApplicationData(bundleName, clearUpApplicationDataCallback); - - ``` - -## appManager.clearUpApplicationData8+ - -clearUpApplicationData(bundleName: string): Promise\; - -Clears application data by bundle name. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CLEAN_APPLICATION_DATA - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| bundleName | string | No| Bundle name of an application.| - -**Return value** - -| Type| Description| -| -------- | -------- | -| Promise\ | Promise used to return the result.| - -**Example** - - ```js - var bundleName = 'bundleName'; - app.clearUpApplicationData(bundleName) - .then((data) => { - console.log('------------ clearUpApplicationData success ------------', data); - }) - .catch((err) => { - console.log('------------ clearUpApplicationData fail ------------', err); - }) - - ``` - -## ApplicationStateObserver.onForegroundApplicationChanged8+ - -onForegroundApplicationChanged(appStateData: AppStateData): void; - -Called when the application state changes. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| appStateData | [AppStateData](#appstatedata) | No| Information about the application whose state is changed.| - -**Example** - -```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); - -``` - -## ApplicationStateObserver.onAbilityStateChanged8+ - -onAbilityStateChanged(abilityStateData: AbilityStateData): void; - -Called when the ability state changes. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| abilityStateData | [AbilityStateData](#abilitystatedata) | No| Information about the ability whose state is changed.| - -**Example** - -```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); -``` - -## ApplicationStateObserver.onProcessCreated8+ - -onProcessCreated(processData: ProcessData): void; - -Called when a process is created. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| processData | [ProcessData](#processdata) | No| Process information.| - -**Example** - -```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); -``` - -## ApplicationStateObserver.onProcessDied8+ - -onProcessDied(processData: ProcessData): void; - -Called when a process is terminated. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| processData | [ProcessData](#processdata) | No| Process information.| - -**Example** - -```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); -``` - -## ApplicationStateObserver.onProcessStateChanged9+ - - onProcessStateChanged(processData: ProcessData): void; - -Called when the process state changes. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -**Parameters** - -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| processData | [ProcessData](#processdata) | No| Process information.| - -**Example** - -```js - var applicationStateObserver = { - onForegroundApplicationChanged(appStateData) { - console.log('------------ onForegroundApplicationChanged -----------', appStateData); - }, - onAbilityStateChanged(abilityStateData) { - console.log('------------ onAbilityStateChanged -----------', abilityStateData); - }, - onProcessCreated(processData) { - console.log('------------ onProcessCreated -----------', processData); - }, - onProcessDied(processData) { - console.log('------------ onProcessDied -----------', processData); - }, - onProcessStateChanged(processData) { - console.log('------------ onProcessStateChanged -----------', processData); - } - } - const observerCode = app.registerApplicationStateObserver(applicationStateObserver); - console.log('-------- observerCode: ---------', observerCode); -``` - -## AppStateData - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| bundleName8+ | Read only | string | No | Bundle name of an application. | -| uid8+ | Read only | number | No | User ID.| -| state8+ | Read only | number | No | Application state.| - -## AbilityStateData - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Type | Readable| Writable| Description | -| ----------------------- | ---------| ---- | ---- | ------------------------- | -| pid8+ | number | Yes | No | Process ID. | -| bundleName8+ | string | Yes | No | Bundle name of an application. | -| abilityName8+ | string | Yes | No | Ability name. | -| uid8+ | number | Yes | No | User ID. | -| state8+ | number | Yes | No | Ability state. | -| moduleName9+ | string | Yes | No | Name of the HAP file to which the ability belongs. | -| abilityType8+ | string | Yes | No | Ability type. | - -## ProcessData - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Type | Readable| Writable| Description | -| ----------------------- | ---------| ---- | ---- | ------------------------- | -| pid8+ | number | Yes | No | Process ID. | -| bundleName8+ | string | Yes | No | Bundle name of an application. | -| uid8+ | number | Yes | No | User ID. | -| isContinuousTask9+ | boolean | Yes | No | Whether the process is a continuous task. | -| isKeepAlive9+ | boolean | Yes | No | Whether the process remains active. | - -## ProcessRunningInfo - -**System capability**: SystemCapability.Ability.AbilityRuntime.Mission - -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| pid8+ | Read only | number | No | Process ID. | -| uid8+ | Read only | number | No | User ID.| -| processName8+ | Read only | string | No | Process name.| -| bundleNames8+ | Read only | Array\ | No | **bundleName** array in the running processes.| - -## ApplicationStateObserver - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Type | Readable| Writable| Description | -| ----------------------- | ---------| ---- | ---- | ------------------------- | -| [onForegroundApplicationChanged8+](#applicationstateobserveronforegroundapplicationchanged8) | AsyncCallback\ | Yes | No | Callback invoked when the foreground or background state of an application changes. | -| [onAbilityStateChanged8+](#applicationstateobserveronabilitystatechanged8) | AsyncCallback\ | Yes | No | Callback invoked when the ability state changes. | -| [onProcessCreated8+](#applicationstateobserveronprocesscreated8) | AsyncCallback\ | Yes | No | Callback invoked when a process is created. | -| [onProcessDied8+](#applicationstateobserveronprocessdied8) | AsyncCallback\ | Yes | No | Callback invoked when a process is destroyed. | - -## ProcessRunningInformation - -Defines the process running information. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Readable/Writable| Type | Mandatory| Description | -| ----------- | -------- | -------------------- | ---- | ------------------------------------------------------------ | -| pid9+ | Read only | number | No | Process ID. | -| uid9+ | Read only | number | No | User ID.| -| processName9+ | Read only | string | No | Process name.| -| bundleNames9+ | Read only | Array\ | No | **bundleName** array in the running processes.| - -## ApplicationState9+ - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Value | Description | -| -------------------- | --- | --------------------------------- | -| STATE_CREATE | 1 | State indicating that the application is being created. | -| STATE_FOREGROUND | 2 | State indicating that the application is running in the foreground. | -| STATE_ACTIVE | 3 | State indicating that the application is active. | -| STATE_BACKGROUND | 4 | State indicating that the application is running in the background. | -| STATE_DESTROY | 5 | State indicating that the application is destroyed. | - -## ProcessState9+ - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -**System API**: This is a system API and cannot be called by third-party applications. - -| Name | Value | Description | -| -------------------- | --- | --------------------------------- | -| STATE_CREATE | 1 | State indicating that the process is being created. | -| STATE_FOREGROUND | 2 | State indicating that the process is running in the foreground. | -| STATE_ACTIVE | 3 | State indicating that the process is active. | -| STATE_BACKGROUND | 4 | State indicating that the process is running in the background. | -| STATE_DESTROY | 5 | State indicating that the process is destroyed. | diff --git a/en/application-dev/reference/apis/js-apis-configuration.md b/en/application-dev/reference/apis/js-apis-configuration.md deleted file mode 100644 index 25c57c7d5f0a6b7a1e8073fc9313bb92562b8576..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-configuration.md +++ /dev/null @@ -1,26 +0,0 @@ -# Configuration - -The **Configuration** module provides environment configuration information. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -```js -import Configuration from '@ohos.application.Configuration'; -``` - -## Attributes - -**System capability**: SystemCapability.Ability.AbilityBase - - | Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| language | string | Yes| Yes| Language of the application.| -| colorMode | [ColorMode](js-apis-configurationconstant.md) | Yes| Yes| Color mode, which can be **COLOR_MODE_LIGHT** or **COLOR_MODE_DARK**. The default value is **COLOR_MODE_LIGHT**.| -| direction9+ | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.| -| screenDensity9+ | ScreenDensity | Yes| No| Screen resolution, which can be **SCREEN_DENSITY_SDPI** (120), **SCREEN_DENSITY_MDPI** (160), **SCREEN_DENSITY_LDPI** (240), **SCREEN_DENSITY_XLDPI** (320), **SCREEN_DENSITY_XXLDPI** (480), or **SCREEN_DENSITY_XXXLDPI** (640).| -| displayId9+ | number | Yes| No| ID of the display where the application is located.| -| hasPointerDevice9+ | boolean | Yes| No| Whether a pointer device, such as a keyboard, mouse, or touchpad, is connected.| diff --git a/en/application-dev/reference/apis/js-apis-formInfo.md b/en/application-dev/reference/apis/js-apis-formInfo.md deleted file mode 100644 index 8acf0e5e3e1ccb81b2295b03c65ed8fd812efa8e..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-formInfo.md +++ /dev/null @@ -1,133 +0,0 @@ -# FormInfo - -The **FormInfo** module provides widget information and state. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -``` -import formInfo from '@ohos.application.formInfo'; -``` - -## Required Permissions - -None - -## FormInfo - -Describes widget information. - -**System capability**: SystemCapability.Ability.Form - -| Name | Readable/Writable| Type | Description | -| ----------- | -------- | -------------------- | ------------------------------------------------------------ | -| bundleName | Read only | string | Name of the bundle to which the widget belongs. | -| moduleName | Read only | string | Name of the module to which the widget belongs. | -| abilityName | Read only | string | Name of the ability to which the widget belongs. | -| name | Read only | string | Widget name. | -| description | Read only | string | Description of the widget. | -| type | Read only | [FormType](#formtype) | Widget type. Currently, only JS widgets are supported.| -| jsComponentName | Read only | string | Component name of the JS widget. | -| colorMode | Read only | [ColorMode](#colormode) | Color mode of the widget. | -| isDefault | Read only | boolean | Whether the widget is the default one. | -| updateEnabled | Read only | boolean | Whether the widget is updatable. | -| formVisibleNotify | Read only | string | Whether to send a notification when the widget is visible. | -| relatedBundleName | Read only | string | Name of the associated bundle to which the widget belongs. | -| scheduledUpdateTime | Read only | string | Time when the widget was updated. | -| formConfigAbility | Read only | string | Configuration ability of the widget. | -| updateDuration | Read only | string | Widget update period.| -| defaultDimension | Read only | number | Default dimension of the widget. | -| supportDimensions | Read only | Array<number> | Dimensions supported by the widget. | -| customizeData | Read only | {[key: string]: [value: string]} | Custom data of the widget. | - -## FormType - -Enumerates the widget types. - -**System capability**: SystemCapability.Ability.Form - -| Name | Value | Description | -| ----------- | ---- | ------------ | -| JS | 1 | JS widget. | - -## ColorMode - -Enumerates the color modes supported by the widget. - -**System capability**: SystemCapability.Ability.Form - -| Name | Value | Description | -| ----------- | ---- | ------------ | -| MODE_AUTO | -1 | Auto mode. | -| MODE_DARK | 0 | Dark mode. | -| MODE_LIGHT | 1 | Light mode. | - -## FormStateInfo - -Describes the widget state information. - -**System capability**: SystemCapability.Ability.Form - -| Name | Readable/Writable| Type | Description | -| ----------- | -------- | -------------------- | ------------------------------------------------------------ | -| formState | Read only | [FormState](#formstate) | Widget state. | -| want | Read only | Want | Want text. | - -## FormState - -Enumerates the widget states. - -**System capability**: SystemCapability.Ability.Form - -| Name | Value | Description | -| ----------- | ---- | ------------ | -| UNKNOWN | -1 | Unknown state. | -| DEFAULT | 0 | Default state. | -| READY | 1 | Ready state. | - -## FormParam - -Enumerates the widget parameters. - -**System capability**: SystemCapability.Ability.Form - -| Name | Value | Description | -| ----------- | ---- | ------------ | -| IDENTITY_KEY9+ | "ohos.extra.param.key.form_identity" | ID of a widget.
**System API**: This is a system API and cannot be called by third-party applications. | -| DIMENSION_KEY | "ohos.extra.param.key.form_dimension" | Widget dimension. | -| NAME_KEY | "ohos.extra.param.key.form_name" | Widget name. | -| MODULE_NAME_KEY | "ohos.extra.param.key.module_name" | Name of the module to which the widget belongs. | -| WIDTH_KEY | "ohos.extra.param.key.form_width" | Widget width. | -| HEIGHT_KEY | "ohos.extra.param.key.form_height" | Widget height. | -| TEMPORARY_KEY | "ohos.extra.param.key.form_temporary" | Temporary widget. | -| ABILITY_NAME_KEY9+ | "ohos.extra.param.key.ability_name" | Ability name. | -| DEVICE_ID_KEY9+ | "ohos.extra.param.key.device_id" | Device ID.
This is a system API. | -| BUNDLE_NAME_KEY9+ | "ohos.extra.param.key.bundle_name" | Key that specifies the target bundle name.| - -## FormDimension - -Enumerates the widget dimensions. - -**System capability**: SystemCapability.Ability.Form - -| Name | Value | Description | -| ----------- | ---- | ------------ | -| Dimension_1_29+ | 1 | 1 x 2. | -| Dimension_2_29+ | 2 | 2 x 2. | -| Dimension_2_49+ | 3 | 2 x 4. | -| Dimension_4_49+ | 4 | 4 x 4. | -| Dimension_2_19+ | 5 | 2 x 1. | - - -## FormInfoFilter - -Defines the widget information filter. Only the widget information that meets the filter is returned. - -**System capability**: SystemCapability.Ability.Form - -| Name | Yes | Description | -| ----------- | ---- | ------------ | -| moduleName9+ | No | Module name.| diff --git a/en/application-dev/reference/apis/js-apis-formbindingdata.md b/en/application-dev/reference/apis/js-apis-formbindingdata.md deleted file mode 100644 index 612b2dc84f23f465a844d73656954bc983c5a233..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-formbindingdata.md +++ /dev/null @@ -1,68 +0,0 @@ -# FormBindingData - -The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -``` -import formBindingData from '@ohos.application.formBindingData'; -``` - -## Required Permissions - -None - -## formBindingData.createFormBindingData - -createFormBindingData(obj?: Object | string): FormBindingData - -Creates a **FormBindingData** object. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | -------------- | ---- | ------------------------------------------------------------ | -| obj | Object or string| No | Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format. The image data is identified by "formImages", and the content is multiple key-value pairs, each of which consists of an image identifier and image file descriptor. The final format is {"formImages": {"key1": fd1, "key2": fd2}}.| - - -**Return value** - -| Type | Description | -| ----------------------------------- | --------------------------------------- | -| [FormBindingData](#formbindingdata) | **FormBindingData** object created based on the passed data.| - - -**Example** - - ```js - import featureAbility from '@ohos.ability.featureAbility'; - import fileio from '@ohos.fileio'; - let context=featureAbility.getContext(); - context.getOrCreateLocalDir((err,data)=>{ - let path=data+"/xxx.jpg"; - let fd = fileio.openSync(path); - let obj = { - "temperature": "21°", - "formImages": {"image": fd} - }; - let formBindingDataObj = formBindingData.createFormBindingData(obj); - }) - - - ``` - -## Attributes - -Describes a **FormBindingData** object. - -**System capability**: SystemCapability.Ability.Form - -| Name| Readable| Writable| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -------- | -------- | -| data | Yes| No| Object | Yes| Data to be displayed on the JS widget. The value can be an object containing multiple key-value pairs or a string in JSON format.| diff --git a/en/application-dev/reference/apis/js-apis-formextension.md b/en/application-dev/reference/apis/js-apis-formextension.md deleted file mode 100644 index 1540e538e1bcc8f53165a3fd277e60f76e73a7a1..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-formextension.md +++ /dev/null @@ -1,289 +0,0 @@ -# FormExtension - -The **FormExtension** module provides APIs related to Form Extension abilities. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> The APIs of this module can be used only in the stage model. - -## Modules to Import - -``` -import FormExtension from '@ohos.application.FormExtension'; -``` - -## Required Permissions - -None - -## Attributes - -**System capability**: SystemCapability.Ability.Form - -| Name | Type | Readable| Writable| Description | -| ------- | ------------------------------------------------------- | ---- | ---- | --------------------------------------------------- | -| context | [FormExtensionContext](js-apis-formextensioncontext.md) | Yes | No | Context of the **FormExtension**. This context is inherited from **ExtensionContext**.| - -## onCreate - -onCreate(want: Want): formBindingData.FormBindingData - -Called to notify the widget provider that a **Form** instance (widget) has been created. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | - | want | [Want](js-apis-application-Want.md) | Yes | Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.| - -**Return value** - - | Type | Description | - | ------------------------------------------------------------ | ----------------------------------------------------------- | - | [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.| - -**Example** - - ```js - import formBindingData from '@ohos.application.formBindingData' - export default class MyFormExtension extends FormExtension { - onCreate(want) { - console.log('FormExtension onCreate, want:' + want.abilityName); - let dataObj1 = { - temperature:"11c", - "time":"11:00" - }; - let obj1 = formBindingData.createFormBindingData(dataObj1); - return obj1; - } - } - ``` - -## FormExtension.onCastToNormal - -onCastToNormal(formId: string): void - -Called to notify the widget provider that a temporary widget has been converted to a normal one. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------------------------ | - | formId | string | Yes | ID of the widget that requests to be converted to a normal one.| - -**Example** - - ``` - export default class MyFormExtension extends FormExtension { - onCastToNormal(formId) { - console.log('FormExtension onCastToNormal, formId:' + formId); - } - } - ``` - -## FormExtension.onUpdate - -onUpdate(formId: string): void - -Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-formextensioncontext.md) class to update the widget data. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------------------ | - | formId | string | Yes | ID of the widget that requests to be updated.| - -**Example** - - ```js - import formBindingData from '@ohos.application.formBindingData' - export default class MyFormExtension extends FormExtension { - onUpdate(formId) { - console.log('FormExtension onUpdate, formId:' + formId); - let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); - this.context.updateForm(formId, obj2) - .then((data)=>{ - console.log('FormExtension context updateForm, data:' + data); - }).catch((error) => { - console.error('Operation updateForm failed. Cause: ' + error);}); - } - } - ``` - -## FormExtension.onVisibilityChange - -onVisibilityChange(newStatus: { [key: string]: number }): void - -Called to notify the widget provider of the change of visibility. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name | Type | Mandatory| Description | - | --------- | ------------------------- | ---- | ---------------------------- | - | newStatus | { [key: string]: number } | Yes | ID and visibility status of the widget to be changed.| - -**Example** - - ```js - import formBindingData from '@ohos.application.formBindingData' - export default class MyFormExtension extends FormExtension { - onVisibilityChange(newStatus) { - console.log('FormExtension onVisibilityChange, newStatus:' + newStatus); - let obj2 = formBindingData.createFormBindingData({temperature:"22c", time:"22:00"}); - - for (let key in newStatus) { - console.log('FormExtension onVisibilityChange, key:' + key + ", value=" + newStatus[key]); - this.context.updateForm(key, obj2) - .then((data)=>{ - console.log('FormExtension context updateForm, data:' + data); - }).catch((error) => { - console.error('Operation updateForm failed. Cause: ' + error);}); - } - } - } - ``` - -## FormExtension.onEvent - -onEvent(formId: string, message: string): void - -Called to instruct the widget provider to receive and process the widget event. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name | Type | Mandatory| Description | - | ------- | ------ | ---- | ---------------------- | - | formId | string | Yes | ID of the widget that requests the event.| - | message | string | Yes | Event message. | - -**Example** - - ```js - export default class MyFormExtension extends FormExtension { - onEvent(formId, message) { - console.log('FormExtension onEvent, formId:' + formId + ", message:" + message); - } - } - ``` - -## FormExtension.onDestroy - -onDestroy(formId: string): void - -Called to notify the widget provider that a **Form** instance (widget) has been destroyed. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------------------ | - | formId | string | Yes | ID of the widget to be destroyed.| - -**Example** - - ```js - export default class MyFormExtension extends FormExtension { - onDestroy(formId) { - console.log('FormExtension onDestroy, formId:' + formId); - } - } - ``` - -## FormExtension.onConfigurationUpdated - -onConfigurationUpdated(config: Configuration): void; - -Called when the configuration of the environment where the ability is running is updated. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | config | [Configuration](js-apis-configuration.md) | Yes| New configuration.| - -**Example** - - ```js - class MyFormExtension extends FormExtension { - onConfigurationUpdated(config) { - console.log('onConfigurationUpdated, config:' + JSON.stringify(config)); - } - } - ``` - -## FormExtension.onAcquireFormState - -onAcquireFormState?(want: Want): formInfo.FormState; - -Called when the widget provider receives the status query result of a widget. By default, the initial state is returned. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | No| Description of the widget state, including the bundle name, ability name, module name, widget name, and widget dimension.| - -**Example** - - ```js - import formInfo from '@ohos.application.formInfo' - class MyFormExtension extends FormExtension { - onAcquireFormState(want) { - console.log('FormExtension onAcquireFormState, want:' + want); - return formInfo.FormState.UNKNOWN; - } - } - ``` - -## FormExtension.onShare - -onShare?(formId: string): {[key: string]: any}; - -Called by the widget provider to receive shared widget data. - -This is a system API. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type| Mandatory| Description| - | -------- | -------- | -------- | -------- | - | formId | string | Yes | ID of a widget.| - -**Return value** - - | Type | Description | - | ------------------------------------------------------------ | ----------------------------------------------------------- | - | {[key: string]: any} | Data to be shared by the widget, in the form of key-value pairs.| - -**Example** - - ```js - class MyFormExtension extends FormExtension { - onShare(formId) { - console.log('FormExtension onShare, formId:' + formId); - let wantParams = { - "temperature":"20", - "time":"2022-8-8 09:59", - }; - return wantParams; - } - } - ``` diff --git a/en/application-dev/reference/apis/js-apis-formhost.md b/en/application-dev/reference/apis/js-apis-formhost.md deleted file mode 100644 index 7ed0ff46de845198aac96bbcf7ebdeaad4055ad1..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-formhost.md +++ /dev/null @@ -1,1124 +0,0 @@ -# FormHost - -The **FormHost** module provides APIs related to the widget host, which is an application that displays the widget content and controls the position where the widget is displayed. You can use the APIs to delete, release, and update widgets, send notifications to widgets, and obtain widget information and status. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. -> The APIs of this module are system APIs and cannot be called by third-party applications. - -## Modules to Import - -``` -import formHost from '@ohos.application.formHost'; -``` - -## Required Permissions - -ohos.permission.REQUIRE_FORM - -ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -## deleteForm - -deleteForm(formId: string, callback: AsyncCallback<void>): void; - -Deletes a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formId | string | Yes | Widget ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.deleteForm(formId, (error, data) => { - if (error.code) { - console.log('formHost deleteForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## deleteForm - -deleteForm(formId: string): Promise<void>; - -Deletes a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, and the Widget Manager will not retain the widget information. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formId | string | Yes | Widget ID.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Parameters** - - ```js - var formId = "12400633174999288"; - formHost.deleteForm(formId).then(() => { - console.log('formHost deleteForm success'); - }).catch((error) => { - console.log('formHost deleteForm, error:' + JSON.stringify(error)); - }); - ``` - -## releaseForm - -releaseForm(formId: string, callback: AsyncCallback<void>): void; - -Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager still retains the widget cache and storage information. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formId | string | Yes | Widget ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.releaseForm(formId, (error, data) => { - if (error.code) { - console.log('formHost releaseForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## releaseForm - -releaseForm(formId: string, isReleaseCache: boolean, callback: AsyncCallback<void>): void; - -Releases a widget. This API uses an asynchronous callback to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------------- | ------ | ---- | ----------- | -| formId | string | Yes | Widget ID. | -| isReleaseCache | boolean | Yes | Whether to release the cache.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.releaseForm(formId, true, (error, data) => { - if (error.code) { - console.log('formHost releaseForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## releaseForm - -releaseForm(formId: string, isReleaseCache?: boolean): Promise<void>; - -Releases a widget. This API uses a promise to return the result. After this API is called, the application can no longer use the widget, but the Widget Manager retains the storage information about the widget and retains or releases the cache information based on the setting. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name | Type | Mandatory| Description | - | -------------- | ------ | ---- | ----------- | - | formId | string | Yes | Widget ID. | - | isReleaseCache | boolean | No | Whether to release the cache.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.releaseForm(formId, true).then(() => { - console.log('formHost releaseForm success'); - }).catch((error) => { - console.log('formHost releaseForm, error:' + JSON.stringify(error)); - }); - ``` - -## requestForm - -requestForm(formId: string, callback: AsyncCallback<void>): void; - -Requests a widget update. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formId | string | Yes | Widget ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.requestForm(formId, (error, data) => { - if (error.code) { - console.log('formHost requestForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## requestForm - -requestForm(formId: string): Promise<void>; - -Requests a widget update. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formId | string | Yes | Widget ID.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.requestForm(formId).then(() => { - console.log('formHost requestForm success'); - }).catch((error) => { - console.log('formHost requestForm, error:' + JSON.stringify(error)); - }); - ``` - -## castTempForm - -castTempForm(formId: string, callback: AsyncCallback<void>): void; - -Converts a temporary widget to a normal one. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formId | string | Yes | Widget ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.castTempForm(formId, (error, data) => { - if (error.code) { - console.log('formHost castTempForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## castTempForm - -castTempForm(formId: string): Promise<void>; - -Converts a temporary widget to a normal one. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formId | string | Yes | Widget ID.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.castTempForm(formId).then(() => { - console.log('formHost castTempForm success'); - }).catch((error) => { - console.log('formHost castTempForm, error:' + JSON.stringify(error)); - }); - ``` - -## notifyVisibleForms - -notifyVisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void; - -Instructs the widget framework to make a widget visible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs. | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.notifyVisibleForms(formId, (error, data) => { - if (error.code) { - console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); - } - }); - ``` - -## notifyVisibleForms - -notifyVisibleForms(formIds: Array<string>): Promise<void>; - -Instructs the widget framework to make a widget visible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.notifyVisibleForms(formId).then(() => { - console.log('formHost notifyVisibleForms success'); - }).catch((error) => { - console.log('formHost notifyVisibleForms, error:' + JSON.stringify(error)); - }); - ``` - -## notifyInvisibleForms - -notifyInvisibleForms(formIds: Array<string>, callback: AsyncCallback<void>): void; - -Instructs the widget framework to make a widget invisible. This API uses an asynchronous callback to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs. | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.notifyInvisibleForms(formId, (error, data) => { - if (error.code) { - console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); - } - }); - ``` - -## notifyInvisibleForms - -notifyInvisibleForms(formIds: Array<string>): Promise<void>; - -Instructs the widget framework to make a widget invisible. This API uses a promise to return the result. After this API is called, **onVisibilityChange** is invoked to notify the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.notifyInvisibleForms(formId).then(() => { - console.log('formHost notifyInvisibleForms success'); - }).catch((error) => { - console.log('formHost notifyInvisibleForms, error:' + JSON.stringify(error)); - }); - ``` - -## enableFormsUpdate - -enableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void; - -Instructs the widget framework to make a widget updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs. | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.enableFormsUpdate(formId, (error, data) => { - if (error.code) { - console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); - } - }); - ``` - -## enableFormsUpdate - -enableFormsUpdate(formIds: Array<string>): Promise<void>; - -Instructs the widget framework to make a widget updatable. This API uses a promise to return the result. After this API is called, the widget is in the enabled state and can receive updates from the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.enableFormsUpdate(formId).then(() => { - console.log('formHost enableFormsUpdate success'); - }).catch((error) => { - console.log('formHost enableFormsUpdate, error:' + JSON.stringify(error)); - }); - ``` - -## disableFormsUpdate - -disableFormsUpdate(formIds: Array<string>, callback: AsyncCallback<void>): void; - -Instructs the widget framework to make a widget not updatable. This API uses an asynchronous callback to return the result. After this API is called, the widget cannot receive updates from the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs. | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.disableFormsUpdate(formId, (error, data) => { - if (error.code) { - console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); - } - }); - ``` - -## disableFormsUpdate - -disableFormsUpdate(formIds: Array<string>): Promise<void>; - -Instructs the widget framework to make a widget not updatable. This API uses a promise to return the result. After this API is called, the widget cannot receive updates from the widget provider. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = ["12400633174999288"]; - formHost.disableFormsUpdate(formId).then(() => { - console.log('formHost disableFormsUpdate success'); - }).catch((error) => { - console.log('formHost disableFormsUpdate, error:' + JSON.stringify(error)); - }); - ``` - -## isSystemReady - -isSystemReady(callback: AsyncCallback<void>): void; - -Checks whether the system is ready. This API uses an asynchronous callback to return the result. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.isSystemReady((error, data) => { - if (error.code) { - console.log('formHost isSystemReady, error:' + JSON.stringify(error)); - } - }); - ``` - -## isSystemReady - -isSystemReady(): Promise<void>; - -Checks whether the system is ready. This API uses a promise to return the result. - -**System capability**: SystemCapability.Ability.Form - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - formHost.isSystemReady().then(() => { - console.log('formHost isSystemReady success'); - }).catch((error) => { - console.log('formHost isSystemReady, error:' + JSON.stringify(error)); - }); - ``` - -## getAllFormsInfo - -getAllFormsInfo(callback: AsyncCallback<Array<formInfo.FormInfo>>): void; - -Obtains the widget information provided by all applications on the device. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| - -**Example** - - ```js - formHost.getAllFormsInfo((error, data) => { - if (error.code) { - console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); - } else { - console.log('formHost getAllFormsInfo, data:' + JSON.stringify(data)); - } - }); - ``` - -## getAllFormsInfo - -getAllFormsInfo(): Promise<Array<formInfo.FormInfo>>; - - -Obtains the widget information provided by all applications on the device. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Return value** - -| Type | Description | -| :------------ | :---------------------------------- | -| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| - -**Example** - - ```js - formHost.getAllFormsInfo().then((data) => { - console.log('formHost getAllFormsInfo data:' + JSON.stringify(data)); - }).catch((error) => { - console.log('formHost getAllFormsInfo, error:' + JSON.stringify(error)); - }); - ``` - -## getFormsInfo - -getFormsInfo(bundleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void; - - -Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | bundleName | string | Yes| Bundle name of the target application.| - | callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| - -**Example** - - ```js - formHost.getFormsInfo("com.example.ohos.formjsdemo", (error, data) => { - if (error.code) { - console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); - } else { - console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); - } - }); - ``` - -## getFormsInfo - -getFormsInfo(bundleName: string, moduleName: string, callback: AsyncCallback<Array<formInfo.FormInfo>>): void; - - -Obtains the widget information provided by a given application on the device. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | bundleName | string | Yes| Bundle name of the target application.| - | moduleName | string | Yes| Module name.| - | callback | AsyncCallback<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Yes| Callback used to return the widget information.| - -**Example** - - ```js - formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry", (error, data) => { - if (error.code) { - console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); - } else { - console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); - } - }); - ``` - -## getFormsInfo - -getFormsInfo(bundleName: string, moduleName?: string): Promise<Array<formInfo.FormInfo>>; - - -Obtains the widget information provided by a given application on the device. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | bundleName | string | Yes| Bundle name of the target application.| - | moduleName | string | No| Module name.| - -**Return value** - -| Type | Description | -| :------------ | :---------------------------------- | -| Promise<Array<[FormInfo](./js-apis-formInfo.md#forminfo-1)>> | Promise used to return the widget information.| - -**Example** - - ```js - formHost.getFormsInfo("com.example.ohos.formjsdemo", "entry").then((data) => { - console.log('formHost getFormsInfo, data:' + JSON.stringify(data)); - }).catch((error) => { - console.log('formHost getFormsInfo, error:' + JSON.stringify(error)); - }); - ``` - -## deleteInvalidForms - -deleteInvalidForms(formIds: Array<string>, callback: AsyncCallback<number>): void; - -Deletes invalid widgets from the list. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of valid widget IDs.| -| callback | AsyncCallback<number> | Yes| Callback used to return the number of widgets deleted.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.deleteInvalidForms(formIds, (error, data) => { - if (error.code) { - console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); - } else { - console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); - } - }); - ``` - -## deleteInvalidForms - -deleteInvalidForms(formIds: Array<string>): Promise<number>; - -Deletes invalid widgets from the list. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of valid widget IDs.| - -**Return value** - -| Type | Description | -| :------------ | :---------------------------------- | -| Promise<number> | Promise used to return the number of widgets deleted.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.deleteInvalidForms(formIds).then((data) => { - console.log('formHost deleteInvalidForms, data:' + JSON.stringify(data)); - }).catch((error) => { - console.log('formHost deleteInvalidForms, error:' + JSON.stringify(error)); - }); - ``` - -## acquireFormState - -acquireFormState(want: Want, callback: AsyncCallback<formInfo.FormStateInfo>): void; - -Obtains the widget state. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| want | [Want](js-apis-application-Want.md) | Yes | **Want** information carried to query the widget state.| -| callback | AsyncCallback<[FormStateInfo](js-apis-formInfo.md#formstateinfo)> | Yes| Callback used to return the widget state.| - -**Example** - - ```js - var want = { - "deviceId": "", - "bundleName": "ohos.samples.FormApplication", - "abilityName": "FormAbility", - "parameters": { - "ohos.extra.param.key.module_name": "entry", - "ohos.extra.param.key.form_name": "widget", - "ohos.extra.param.key.form_dimension": 2 - } - }; - formHost.acquireFormState(want, (error, data) => { - if (error.code) { - console.log('formHost acquireFormState, error:' + JSON.stringify(error)); - } else { - console.log('formHost acquireFormState, data:' + JSON.stringify(data)); - } - }); - ``` - -## acquireFormState - -acquireFormState(want: Want): Promise<formInfo.FormStateInfo>; - -Obtains the widget state. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM and ohos.permission.GET_BUNDLE_INFO_PRIVILEGED - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| want | [Want](js-apis-application-Want.md) | Yes | **Want** information carried to query the widget state.| - -**Return value** - -| Type | Description | -| :------------ | :---------------------------------- | -| Promise<[FormStateInfo](js-apis-formInfo.md#formstateinfo)> | Promise used to return the widget state.| - -**Example** - - ```js - var want = { - "deviceId": "", - "bundleName": "ohos.samples.FormApplication", - "abilityName": "FormAbility", - "parameters": { - "ohos.extra.param.key.module_name": "entry", - "ohos.extra.param.key.form_name": "widget", - "ohos.extra.param.key.form_dimension": 2 - } - }; - formHost.acquireFormState(want).then((data) => { - console.log('formHost acquireFormState, data:' + JSON.stringify(data)); - }).catch((error) => { - console.log('formHost acquireFormState, error:' + JSON.stringify(error)); - }); - ``` - -## on("formUninstall") - -on(type: "formUninstall", callback: Callback<string>): void; - -Subscribes to widget uninstall events. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| type | string | Yes | Type of event to subscribe to. The value **formUninstall** indicates a widget uninstallation event.| -| callback | Callback<string> | Yes| Callback used for event subscription.| - -**Example** - - ```js - let callback = function(formId) { - console.log('formHost on formUninstall, formId:' + formId); - } - formHost.on("formUninstall", callback); - ``` - -## off("formUninstall") - -off(type: "formUninstall", callback?: Callback<string>): void; - -Unsubscribes from widget uninstall events. - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| type | string | Yes | Type of event to subscribe to. The value **formUninstall** indicates a widget uninstallation event.| -| callback | Callback<string> | No| Callback used for event unsubscription. If it is left unspecified, it indicates the callback for all the events that have been subscribed.| - -**Example** - - ```js - let callback = function(formId) { - console.log('formHost on formUninstall, formId:' + formId); - } - formHost.off("formUninstall", callback); - ``` - -## notifyFormsVisible - -notifyFormsVisible(formIds: Array<string>, isVisible: boolean, callback: AsyncCallback<void>): void; - -Instructs the widgets to make themselves visible. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| -| isVisible | boolean | Yes | Whether to be visible.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.notifyFormsVisible(formIds, true, (error, data) => { - if (error.code) { - console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); - } - }); - ``` - -## notifyFormsVisible - -notifyFormsVisible(formIds: Array<string>, isVisible: boolean): Promise<void>; - -Instructs the widgets to make themselves visible. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formIds | Array<string> | Yes | List of widget IDs.| - | isVisible | boolean | Yes | Whether to be visible.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.notifyFormsVisible(formIds, true).then(() => { - console.log('formHost notifyFormsVisible success'); - }).catch((error) => { - console.log('formHost notifyFormsVisible, error:' + JSON.stringify(error)); - }); - ``` - -## notifyFormsEnableUpdate - -notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean, callback: AsyncCallback<void>): void; - -Instructs the widgets to enable or disable updates. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formIds | Array<string> | Yes | List of widget IDs.| -| isEnableUpdate | boolean | Yes | Whether to enable update.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.notifyFormsEnableUpdate(formIds, true, (error, data) => { - if (error.code) { - console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); - } - }); - ``` - -## notifyFormsEnableUpdate - -notifyFormsEnableUpdate(formIds: Array<string>, isEnableUpdate: boolean): Promise<void>; - -Instructs the widgets to enable or disable updates. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formIds | Array<string> | Yes | List of widget IDs.| - | isEnableUpdate | boolean | Yes | Whether to enable update.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Example** - - ```js - var formIds = new Array("12400633174999288", "12400633174999289"); - formHost.notifyFormsEnableUpdate(formIds, true).then(() => { - console.log('formHost notifyFormsEnableUpdate success'); - }).catch((error) => { - console.log('formHost notifyFormsEnableUpdate, error:' + JSON.stringify(error)); - }); - ``` -## shareForm9+ - -shareForm(formId: string, deviceId: string, callback: AsyncCallback<void>): void; - -Shares a specified widget with a remote device. This API uses an asynchronous callback to return the result. - -This is a system API. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - -| Name| Type | Mandatory| Description | -| ------ | ------ | ---- | ------- | -| formId | string | Yes | Widget ID.| -| deviceId | string | Yes | Remote device ID.| -| callback | AsyncCallback<void> | Yes| Callback used to return the result.| - -**Example** - - ```js - var formId = "12400633174999288"; - var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; - formHost.shareForm(formId, deviceId, (error, data) => { - if (error.code) { - console.log('formHost shareForm, error:' + JSON.stringify(error)); - } - }); - ``` - -## shareForm9+ - -shareForm(formId: string, deviceId: string): Promise<void>; - -Shares a specified widget with a remote device. This API uses a promise to return the result. - -This is a system API. - -**Required permissions**: ohos.permission.REQUIRE_FORM - -**System capability**: SystemCapability.Ability.Form - -**Parameters** - - | Name| Type | Mandatory| Description | - | ------ | ------ | ---- | ------- | - | formId | string | Yes | Widget ID.| - | deviceId | string | Yes | Remote device ID.| - -**Return value** - - | Type| Description| - | -------- | -------- | - | Promise<void> | Promise used to return the result.| - -**Parameters** - - ```js - var formId = "12400633174999288"; - var deviceId = "EFC11C0C53628D8CC2F8CB5052477E130D075917034613B9884C55CD22B3DEF2"; - formHost.shareForm(formId, deviceId).then(() => { - console.log('formHost shareForm success'); - }).catch((error) => { - console.log('formHost shareForm, error:' + JSON.stringify(error)); - }); - ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md b/en/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md new file mode 100644 index 0000000000000000000000000000000000000000..f776c56334112c2b739b5b6a85ef7153c4da1564 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md @@ -0,0 +1,26 @@ +# AbilityResult + +The **AbilityResult** module defines the result code and data returned when an ability is started or destroyed. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Readable | Writable | Type | Mandatory| Description | +| ----------- | -------- |-------- | -------------------- | ---- | ------------------------------------------------------------ | +| resultCode | Yes | No | number | No | Result code returned when the ability is started or destroyed. | +| want | Yes | No | [Want](./js-apis-app-ability-want.md) | No | Data returned when the ability is destroyed.| + +**Example** + ```ts + let want = { + bundleName: 'com.example.mydocapplication', + abilityName: 'MainAbility', + }; + this.context.startAbilityForResult(want, (error, data) => { + let resultCode = data.resultCode; + let want = data.want; + }); + ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md b/en/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md new file mode 100644 index 0000000000000000000000000000000000000000..685329b15fe26618c4b2a3be2242d4912415a66d --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md @@ -0,0 +1,45 @@ +# ConnectOptions + +The **ConnectOptions** module defines the options for connection. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Mandatory | Description | +| ------------ | -------- | ---- | ------------------------- | +| onConnect7+ | function | Yes | Callback invoked when the connection is successful. | +| onDisconnect7+ | function | Yes | Callback invoked when the connection fails. | +| onFailed7+ | function | Yes | Callback invoked when **connectAbility** fails to be called.| + +**Return value** + +| Type | Description | +| ------ | -------------------- | +| number | ID of the Service ability connected.| + +**Example** + +```ts +import rpc from '@ohos.rpc'; +import featureAbility from '@ohos.ability.featureAbility'; +function onConnectCallback(element, remote){ + console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); +} +function onDisconnectCallback(element){ + console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId) +} +function onFailedCallback(code){ + console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code) +} +var connectId = featureAbility.connectAbility( + { + deviceId: "", + bundleName: "com.ix.ServiceAbility", + abilityName: "ServiceAbilityA", + }, + { + onConnect: onConnectCallback, + onDisconnect: onDisconnectCallback, + onFailed: onFailedCallback, + }, +); +``` diff --git a/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md similarity index 91% rename from en/application-dev/reference/apis/js-apis-dataAbilityHelper.md rename to en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md index 1d10f56aeb69e13d2f329bfc18f56127667ef930..f06df85ac59ffe3074519efd2c9aef95a5093cd7 100644 --- a/en/application-dev/reference/apis/js-apis-dataAbilityHelper.md +++ b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityHelper.md @@ -8,8 +8,7 @@ ## Usage Import the following modules based on the actual situation before using the current module: -``` -import featureAbility from '@ohos.ability.featureAbility' +```ts import ohos_data_ability from '@ohos.data.dataAbility' import ohos_data_rdb from '@ohos.data.rdb' ``` @@ -32,7 +31,7 @@ Opens a file with a specified URI. This API uses an asynchronous callback to ret **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -69,7 +68,7 @@ Opens a file with a specified URI. This API uses a promise to return the result. **Example** -```javascript +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -100,7 +99,7 @@ Registers an observer to observe data specified by a given URI. This API uses an **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var helper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -133,7 +132,7 @@ Deregisters the observer used to observe data specified by a given URI. This API **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var helper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -169,7 +168,7 @@ Obtains the MIME type of the data specified by a given URI. This API uses an asy **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -203,7 +202,7 @@ Obtains the MIME type of the data specified by a given URI. This API uses a prom **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -233,7 +232,7 @@ Obtains the supported MIME types of a specified file. This API uses an asynchron **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -271,7 +270,7 @@ Obtains the supported MIME types of a specified file. This API uses a promise to **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -301,7 +300,7 @@ Converts the URI that refers to a Data ability into a normalized URI. This API u **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -335,7 +334,7 @@ Converts the URI that refers to a Data ability into a normalized URI. This API u **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -364,7 +363,7 @@ Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: str **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -400,7 +399,7 @@ Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: str **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -429,7 +428,7 @@ Notifies the registered observer of a change to the data specified by the URI. T **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var helper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -463,7 +462,7 @@ Notifies the registered observer of a change to the data specified by the URI. T **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -493,7 +492,7 @@ Inserts a single data record into the database. This API uses an asynchronous ca **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -535,7 +534,7 @@ Inserts a single data record into the database. This API uses a promise to retur **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -556,7 +555,7 @@ DAHelper.insert( ## DataAbilityHelper.batchInsert -batchInsert(uri: string, valuesBuckets: Array, callback: AsyncCallback\): void +batchInsert(uri: string, valuesBuckets: Array\, callback: AsyncCallback\): void Inserts multiple data records into the database. This API uses an asynchronous callback to return the result. @@ -567,12 +566,12 @@ Inserts multiple data records into the database. This API uses an asynchronous c | Name | Type | Mandatory| Description | | ------------ | ----------------------- | ---- | -------------------------------- | | uri | string | Yes | URI of the data to insert. | -| valuesBucket | Array | Yes | Data records to insert. | +| valuesBucket | Array\ | Yes | Data records to insert. | | callback | AsyncCallback\ | Yes | Callback used to return the number of inserted data records.| **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -611,7 +610,7 @@ Inserts multiple data records into the database. This API uses a promise to retu **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( "dataability:///com.example.DataAbility" @@ -640,12 +639,12 @@ Deletes one or more data records from the database. This API uses an asynchronou | Name | Type | Mandatory| Description | | ------------ | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the data to delete. | -| valuesBucket | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| +| predicates | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| | callback | AsyncCallback\ | Yes | Callback used to return the number of deleted data records. | **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -673,7 +672,7 @@ Deletes one or more data records from the database. This API uses a promise to r | Name | Type | Mandatory| Description | | ------------ | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the data to delete. | -| valuesBucket | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| +| predicates | dataAbility.DataAbilityPredicates | No | Filter criteria. You should define the processing logic when this parameter is **null**.| **Return value** @@ -683,7 +682,7 @@ Deletes one or more data records from the database. This API uses a promise to r **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -717,7 +716,7 @@ Updates data records in the database. This API uses an asynchronous callback to **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -753,7 +752,7 @@ Updates data records in the database. This API uses a promise to return the resu | ------------ | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the data to update. | | valuesBucket | rdb.ValuesBucket | Yes | New values. | -| predicates | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| +| predicates | dataAbility.DataAbilityPredicates | No | Filter criteria. You should define the processing logic when this parameter is **null**.| **Return value** @@ -763,7 +762,7 @@ Updates data records in the database. This API uses a promise to return the resu **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -798,13 +797,13 @@ Queries data in the database. This API uses an asynchronous callback to return t | Name | Type | Mandatory| Description | | ---------- | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the data to query. | -| columns | rdb.ValuesBucket | Yes | Columns to query. If this parameter is **null**, all columns will be queried. | +| columns | Array\ | Yes | Columns to query. If this parameter is **null**, all columns will be queried. | | predicates | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| | callback | AsyncCallback\ | Yes | Callback used to return the data queried. | **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -836,8 +835,8 @@ Queries data in the database. This API uses a promise to return the result. | Name | Type | Mandatory| Description | | ---------- | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the data to query. | -| columns | rdb.ValuesBucket | Yes | Columns to query. If this parameter is **null**, all columns will be queried. | -| predicates | dataAbility.DataAbilityPredicates | Yes | Filter criteria. You should define the processing logic when this parameter is **null**.| +| columns | Array\ | No | Columns to query. If this parameter is **null**, all columns will be queried. | +| predicates | dataAbility.DataAbilityPredicates | No | Filter criteria. You should define the processing logic when this parameter is **null**.| **Return value** @@ -847,7 +846,7 @@ Queries data in the database. This API uses a promise to return the result. **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility' import ohos_data_ability from '@ohos.data.dataAbility' var DAHelper = featureAbility.acquireDataAbilityHelper( @@ -889,7 +888,7 @@ Calls the extended API of the Data ability. This API uses a promise to return th **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility'; let dataAbilityHelper = featureAbility.acquireDataAbilityHelper("dataability:///com.example.jsapidemo.UserDataAbility"); @@ -920,7 +919,7 @@ Calls the extended API of the Data ability. This API uses an asynchronous callba **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility'; let dataAbilityHelper = featureAbility.acquireDataAbilityHelper("dataability:///com.example.jsapidemo.UserDataAbility"); @@ -946,12 +945,12 @@ Operates data in the database. This API uses an asynchronous callback to return | Name | Type | Mandatory| Description | | ---------- | --------------------------------- | ---- | ------------------------------------------------ | | uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".| -| operations | Array\<[DataAbilityOperation](#dataabilityoperation)> | Yes | A list of data operations on the database. | -| callback | AsyncCallback\> | Yes |Callback used to return the result of each operation in the **DataAbilityResult** array. | +| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | A list of data operations on the database. | +| callback | AsyncCallback\> | Yes |Callback used to return the result of each operation in the **DataAbilityResult** array. | **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility'; // Select the operations to be performed on the database according to the DataAbilityOperation array. @@ -979,17 +978,17 @@ Operates data in the database. This API uses a promise to return the result. | Name | Type | Mandatory| Description | | ---------- | -------------------------------| ---- | ------------------------------------------------ | | uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".| -| operations | Array\<[DataAbilityOperation](#dataabilityoperation)> | Yes | A list of data operations on the database. | +| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | A list of data operations on the database. | **Return value** | Type| Description| |------ | ------- | -|Promise\> | Promise used to return the result of each operation in the **DataAbilityResult** array.| +|Promise\> | Callback used to return the result of each operation in the **DataAbilityResult** array.| **Example** -```js +```ts import featureAbility from '@ohos.ability.featureAbility'; // Select the operations to be performed on the database according to the DataAbilityOperation array. @@ -1012,27 +1011,3 @@ dataAbilityHelper.executeBatch("dataability:///com.example.jsapidemo.UserDataAbi | Name| Type| Mandatory| Description| | ------ | ------ | ------ | ------ | | [key: string] | number \| string \| boolean \| Array\ \| null | Yes| Data stored in key-value pairs.| - -## DataAbilityOperation - -**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel - -| Name | Type | Readable | Writable | Mandatory| Description | -| -------- | -------- | -------- | -------- | --------| -------- | -| uri | string | Yes | No | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | -| type | featureAbility.DataAbilityOperationType | Yes | No | Yes | Operation type. | -| valuesBucket? | rdb.ValuesBucket | Yes | No | No | Data value to set. | -| valueBackReferences? | rdb.ValuesBucket | Yes | No | No | **ValuesBucket** object that contains a set of key-value pairs. | -| predicates? | dataAbility.DataAbilityPredicates | Yes | No | No | Predicates to set. If no predicate is set, all data records are displayed. | -| predicatesBackReferences? | Map\ | Yes | No | No | Back references of the predicates. | -| interrupted? | boolean | Yes | No | No | Whether batch operations can be interrupted. | -| expectedCount? | number | Yes | No | No | Expected number of rows to be updated or deleted. | - -## DataAbilityResult - -**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel - -| Name | Type | Readable | Writable | Mandatory | Description | -| -------- | -------- | -------- | -------- | -------- | -------- | -| uri? | string | Yes | No | No | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | -| count? | number | Yes | No | No | Number of rows affected by the operation. | diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md new file mode 100644 index 0000000000000000000000000000000000000000..30148ab3a64188abe2aef5a8c5cf2814f297da3e --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md @@ -0,0 +1,66 @@ +# DataAbilityOperation + +The **DataAbilityOperation** module defines the operation on Data abilities. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the FA model. + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name | Template | Mandatory| Description | +| -------- | -------- | --------| -------- | +| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | +| type | featureAbility.DataAbilityOperationType | Yes | Operation type. | +| valuesBucket? | rdb.ValuesBucket | No | Data value to set. | +| valueBackReferences? | rdb.ValuesBucket | No | **ValuesBucket** object that contains a set of key-value pairs. | +| predicates? | dataAbility.DataAbilityPredicates | No | Predicates to set. If no predicate is set, all data records are displayed. | +| predicatesBackReferences? | Map\ | No | Back references of the predicates. | +| interrupted? | boolean | No | Whether batch operations can be interrupted. | +| expectedCount? | number | No | Expected number of rows to be updated or deleted. | + +**Example** +```ts +import featureAbility from '@ohos.ability.featureAbility' + +let dataAbilityUri = ("dataability:///com.example.myapplication.TestDataAbility"); +let DAHelper; +try { + DAHelper = featureAbility.acquireDataAbilityHelper(dataAbilityUri); + if(DAHelper == null){ + console.error('DAHelper is null'); + return; + } +} catch (err) { + console.error('acquireDataAbilityHelper fail, error:' + JSON.stringify(err)); + return; +} + +let valueBucket = { + "name": "DataAbilityHelperTest", + "age": 24, + "salary": 2024.20, +}; +let dataAbilityOperation = { + uri: dataAbilityUri, + type: featureAbility.DataAbilityOperationType.TYPE_INSERT, + valuesBucket: valueBucket, + predicates: null, + expectedCount: 1, + PredicatesBackReferences: {}, + interrupted: true +} +let operations = [ + dataAbilityOperation +]; +try { + DAHelper.executeBatch(dataAbilityUri, operations, + (err, data) => { + console.log("executeBatch, data: " + JSON.stringify(data)); + } + ); +} catch (err) { + console.error('executeBatch fail: ' + JSON.stringify(err)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md new file mode 100644 index 0000000000000000000000000000000000000000..fe602f38efcbcbb8619a29e1d05c3a6f92bf2635 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md @@ -0,0 +1,73 @@ +# DataAbilityResult + +The **DataAbilityResult** module defines the operation result on Data abilities. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the FA model. + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name | Type | Mandatory | Description | +| -------- | -------- | -------- | -------- | +| uri? | string | No | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". | +| count? | number | No | Number of rows affected by the operation. | + +**Example** +```ts +import featureAbility from '@ohos.ability.featureAbility' + +let dataAbilityUri = ("dataability:///com.example.myapplication.TestDataAbility"); +let DAHelper; +try { + DAHelper = featureAbility.acquireDataAbilityHelper(dataAbilityUri); + if(DAHelper == null){ + console.error('DAHelper is null'); + return; + } +} catch (err) { + console.error('acquireDataAbilityHelper fail, error:' + JSON.stringify(err)); + return; +} + +let valueBucket = { + "name": "DataAbilityHelperTest", + "age": 24, + "salary": 2024.20, +}; +let operations = [ +{ + uri: dataAbilityUri, + type: featureAbility.DataAbilityOperationType.TYPE_INSERT, + valuesBucket: valueBucket, + predicates: null, + expectedCount: 1, + PredicatesBackReferences: {}, + interrupted: true, +}, +{ + uri: dataAbilityUri, + type: featureAbility.DataAbilityOperationType.TYPE_INSERT, + valuesBucket: valueBucket, + predicates: null, + expectedCount: 1, + PredicatesBackReferences: {}, + interrupted: true, +} +]; + +try { + let promise = DAHelper.executeBatch(dataAbilityUri, operations).then((data) => { + for (let i = 0; i < data.length; i++) { + let dataAbilityResult = data[i]; + console.log('dataAbilityResult.uri: ' + dataAbilityResult.uri); + console.log('dataAbilityResult.count: ' + dataAbilityResult.count); + } + }).catch(err => { + console.error('executeBatch error: ' + JSON.stringify(err)); + }); +} catch (err) { + console.error('executeBatch error: ' + JSON.stringify(err)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md b/en/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md new file mode 100644 index 0000000000000000000000000000000000000000..bbb025920d5a49ec02cc9fc84fed7c1bee8e6fca --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md @@ -0,0 +1,44 @@ +# StartAbilityParameter + +The **StartAbilityParameter** module defines the parameters for starting an ability. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the FA model. + +**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel + +| Name | Type | Mandatory | Description | +| ------------------- | -------- | ---- | -------------------------------------- | +| want | [Want](js-apis-application-want.md)| Yes | Information about the ability to start. | +| abilityStartSetting | {[key: string]: any} | No | Special attribute of the ability to start. This attribute can be passed in the method call.| + +**Example** +```ts +import featureAbility from '@ohos.ability.featureAbility' + +let Want = { + bundleName: "com.example.abilityStartSettingApp2", + abilityName: "com.example.abilityStartSettingApp.MainAbility", +} + +let abilityStartSetting ={ + [featureAbility.AbilityStartSetting.BOUNDS_KEY] : [100,200,300,400], + [featureAbility.AbilityStartSetting.WINDOW_MODE_KEY] : + featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED, + [featureAbility.AbilityStartSetting.DISPLAY_ID_KEY] : 1, +} + +let startAbilityParameter = { + want:Want, + abilityStartSetting:abilityStartSetting +} + +featureAbility.startAbility(startAbilityParameter, (err,data)=>{ + console.log('errCode : ' + JSON.stringify(err)); + console.log('data : ' + JSON.stringify(data)); +} catch(error) { + console.log("startAbility error: " + JSON.stringify(error)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-ability-want.md b/en/application-dev/reference/apis/js-apis-inner-ability-want.md new file mode 100644 index 0000000000000000000000000000000000000000..4eea38a4e28c3e344a8ecdc60118af0fe93ddf19 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-ability-want.md @@ -0,0 +1,65 @@ +# Want + +Want is a carrier for information transfer between objects (application components). Want can be used as a parameter of **startAbility** to specify a startup target and information that needs to be carried during startup, for example, **bundleName** and **abilityName**, which respectively indicate the bundle name of the target ability and the ability name in the bundle. When ability A needs to start ability B and transfer some data to ability B, it can use Want a carrier to transfer the data. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +**System capability**: SystemCapability.Ability.AbilityBase + +| Name | Type | Mandatory| Description | +| ----------- | -------------------- | ---- | ------------------------------------------------------------ | +| deviceId | string | No | ID of the device running the ability. | +| bundleName | string | No | Bundle name of the application. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability.| +| abilityName | string | No | Name of the ability. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can match a specific ability. The value of **abilityName** must be unique in an application.| +| uri | string | No | URI. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.| +| type | string | No | MIME type, that is, the type of the file to open, for example, **text/xml** and **image/***. For details about the MIME type definition, see https://www.iana.org/assignments/media-types/media-types.xhtml?utm_source=ld246.com. | +| flags | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](js-apis-ability-wantConstant.md#wantConstant.Flags).| +| action | string | No | Action to take, such as viewing and sharing application details. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data. | +| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:
**ohos.aafwk.callerPid**: PID of the caller.
**ohos.aafwk.param.callerToken**: token of the caller.
**ohos.aafwk.param.callerUid**: UID in [bundleInfo](js-apis-bundle-BundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information. | +| entities | Array\ | No | Additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit Want and is used to filter ability types. | +| moduleName9+ | string | No | Module to which the ability belongs.| + +**Example** + +- Basic usage + + ```ts + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry" // moduleName is optional. + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + +- Passing a file descriptor (FD) + + ```ts + import fileio from '@ohos.fileio'; + var fd; + try { + fd = fileio.openSync("/data/storage/el2/base/haps/pic.png"); + } catch(e) { + console.log("openSync fail:" + JSON.stringify(e)); + } + var want = { + "deviceId": "", // An empty deviceId indicates the local device. + "bundleName": "com.extreme.test", + "abilityName": "MainAbility", + "moduleName": "entry", // moduleName is optional. + "parameters": { + "keyFd":{"type":"FD", "value":fd} + } + }; + this.context.startAbility(want, (error) => { + // Start an ability explicitly. The bundleName, abilityName, and moduleName parameters work together to uniquely identify an ability. + console.log("error.code = " + error.code) + }) + ``` + diff --git a/en/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md b/en/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..a8eb10e600ef981de57a8acc227b1b6371efde26 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md @@ -0,0 +1,24 @@ +# AppVersionInfo + +The **AppVersionInfo** module defines the application version information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable | Writable | Description | +| ----------- | ------ | ---- | ---- | ------- | +| appName | string | Yes | No | Module name. | +| versionCode | number | Yes | No | Module description.| +| versionName | string | Yes | No | Module description ID.| + +**Example** +```ts +let appName; +let versionCode; +let versionName; +this.context.getAppVersionInfo((error, data) => { + console.info('getAppVersionInfo data is:' + JSON.stringify(data)); + appName = data.appName; + versionCode = data.versionCode; + versionName = data.versionName; +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-Context.md b/en/application-dev/reference/apis/js-apis-inner-app-context.md similarity index 78% rename from en/application-dev/reference/apis/js-apis-Context.md rename to en/application-dev/reference/apis/js-apis-inner-app-context.md index 116af9c40bdb3c13cc278a13bb7ae5b08330095f..84b46fd028782c8517e3c6aca5bad324c8eac179 100644 --- a/en/application-dev/reference/apis/js-apis-Context.md +++ b/en/application-dev/reference/apis/js-apis-inner-app-context.md @@ -4,17 +4,19 @@ The **Context** module provides context for abilities or applications. It allows > **NOTE** > -> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the FA model. ## Usage The **Context** object is created in a **featureAbility** and returned through its **getContext()** API. Therefore, you must import the **@ohos.ability.featureAbility** package before using the **Context** module. An example is as follows: -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getOrCreateLocalDir() +context.getOrCreateLocalDir().then((data) => { + console.info("getOrCreateLocalDir data: " + JSON.stringify(data)); +}); ``` ## Context.getOrCreateLocalDir7+ @@ -35,12 +37,12 @@ If this API is called for the first time, a root directory will be created. **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getOrCreateLocalDir((err, data)=>{ - console.info("data=" + data); -}) + console.info("getOrCreateLocalDir err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -63,16 +65,14 @@ If this API is called for the first time, a root directory will be created. **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getOrCreateLocalDir().then((data) => { - console.info("data=" + data); + console.info("getOrCreateLocalDir data: " + JSON.stringify(data)); }); ``` - - ## Context.verifyPermission7+ verifyPermission(permission: string, options: PermissionOptions, callback: AsyncCallback\): void @@ -86,17 +86,19 @@ Verifies whether a specific PID and UID have the given permission. This API uses | Name | Type | Mandatory | Description | | ---------- | --------------------------------------- | ---- | -------------------- | | permission | string | Yes | Name of the permission to verify. | -| options | [PermissionOptions](#permissionoptions) | Yes | Permission options. | +| options | [PermissionOptions](#permissionoptions7) | Yes | Permission options. | | callback | AsyncCallback\ | Yes | Callback used to return the permission verification result. The value **0** means that the PID and UID have the given permission, and the value **-1** means the opposite.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' -import bundle from '@ohos.bundle' +```ts +import featureAbility from '@ohos.ability.featureAbility'; +import bundle from '@ohos.bundle'; var context = featureAbility.getContext(); -bundle.getBundleInfo('com.context.test', 1, (err,datainfo) =>{ - context.verifyPermission("com.example.permission", {uid:datainfo.uid}); +bundle.getBundleInfo('com.context.test', 1, (err, datainfo) =>{ + context.verifyPermission("com.example.permission", {uid:datainfo.uid}, (err, data) =>{ + console.info("verifyPermission err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); + }); }); ``` @@ -119,10 +121,12 @@ Verifies whether the current PID and UID have the given permission. This API use **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.verifyPermission("com.example.permission") +context.verifyPermission("com.example.permission", (err, data) =>{ + console.info("verifyPermission err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` ## Context.verifyPermission7+ @@ -148,13 +152,12 @@ Verifies whether a specific PID and UID have the given permission. This API uses **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); var Permission = {pid:1}; context.verifyPermission('com.context.permission',Permission).then((data) => { - console.info("======================>verifyPermissionCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("verifyPermission data: " + JSON.stringify(data)); }); ``` @@ -178,8 +181,8 @@ Requests certain permissions from the system. This API uses an asynchronous call **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.requestPermissionsFromUser( ["com.example.permission1", @@ -187,11 +190,11 @@ context.requestPermissionsFromUser( "com.example.permission3", "com.example.permission4", "com.example.permission5"], - 1,(err, data)=>{ - console.info("====>requestdata====>" + JSON.stringify(data)); - console.info("====>requesterrcode====>" + JSON.stringify(err.code)); + 1, + (err, data) => { + console.info("requestPermissionsFromUser err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); } -) +); ``` @@ -218,8 +221,8 @@ Requests certain permissions from the system. This API uses a promise to return **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.requestPermissionsFromUser( ["com.example.permission1", @@ -228,8 +231,9 @@ context.requestPermissionsFromUser( "com.example.permission4", "com.example.permission5"], 1).then((data)=>{ - console.info("====>requestdata====>" + JSON.stringify(data)); - }); + console.info("requestPermissionsFromUser data: " + JSON.stringify(data)); + } +); ``` @@ -246,14 +250,16 @@ Obtains information about the current application. This API uses an asynchronous | Name | Type | Mandatory | Description | | -------- | ------------------------------- | ---- | ------------ | -| callback | AsyncCallback\ | Yes | Callback used to return the application information.| +| callback | AsyncCallback\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Yes | Callback used to return the application information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getApplicationInfo() +context.getApplicationInfo((err, data) => { + console.info("getApplicationInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -270,16 +276,15 @@ Obtains information about the current application. This API uses a promise to re | Type | Description | | ------------------------- | --------- | -| Promise\ | Promise used to return the application information.| +| Promise\<[ApplicationInfo](js-apis-bundle-ApplicationInfo.md)> | Promise used to return the application information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getApplicationInfo().then((data) => { - console.info("=====================>getApplicationInfoCallback===================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getApplicationInfo data: " + JSON.stringify(data)); }); ``` @@ -301,10 +306,12 @@ Obtains the bundle name of this ability. This API uses an asynchronous callback **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getBundleName() +context.getBundleName((err, data) => { + console.info("getBundleName err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -325,12 +332,11 @@ Obtains the bundle name of this ability. This API uses a promise to return the r **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getBundleName().then((data) => { - console.info("=======================>getBundleNameCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getBundleName data: " + JSON.stringify(data)); }); ``` @@ -350,10 +356,12 @@ Obtains the display orientation of this ability. This API uses an asynchronous c **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getDisplayOrientation() +context.getDisplayOrientation((err, data) => { + console.info("getDisplayOrientation err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` ## Context.getDisplayOrientation7+ @@ -372,12 +380,11 @@ Obtains the display orientation of this ability. This API uses a promise to retu **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getDisplayOrientation().then((data) => { - console.info("=======================>getDisplayOrientationCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getDisplayOrientation data: " + JSON.stringify(data)); }); ``` @@ -397,10 +404,12 @@ Obtains the external cache directory of the application. This API uses an asynch **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getExternalCacheDir() +context.getExternalCacheDir((err, data) => { + console.info("getExternalCacheDir err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` ## Context.getExternalCacheDir @@ -419,12 +428,11 @@ Obtains the external cache directory of the application. This API uses a promise **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getExternalCacheDir().then((data) => { - console.info("=======================>getExternalCacheDirCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getExternalCacheDir data: " + JSON.stringify(data)); }); ``` @@ -441,17 +449,17 @@ Sets the display orientation for this ability. This API uses an asynchronous cal | Name | Type | Mandatory | Description | | ----------- | ---------------------------------------- | ---- | ------------ | | orientation | [bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation) | Yes | Display orientation to set.| -| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Yes | Callback used to return the display orientation. | +| callback | AsyncCallback\ | Yes | Callback used to return the display orientation. | **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' -import bundle from '@ohos.bundle' +```ts +import featureAbility from '@ohos.ability.featureAbility'; +import bundle from '@ohos.bundle'; var context = featureAbility.getContext(); var orientation=bundle.DisplayOrientation.UNSPECIFIED context.setDisplayOrientation(orientation, (err) => { - console.log('---------- setDisplayOrientation fail, err: -----------', err); + console.info("setDisplayOrientation err: " + JSON.stringify(err)); }); ``` @@ -468,18 +476,17 @@ Sets the display orientation for this ability. This API uses a promise to return | Type | Description | | ---------------------------------------- | ---------------------------------------- | | orientation | [bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation) | -| Promise\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Promise used to return the display orientation. | +| Promise\ | Promise used to return the display orientation. | **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' -import bundle from '@ohos.bundle' +```ts +import featureAbility from '@ohos.ability.featureAbility'; +import bundle from '@ohos.bundle'; var context = featureAbility.getContext(); var orientation=bundle.DisplayOrientation.UNSPECIFIED context.setDisplayOrientation(orientation).then((data) => { - console.info("=======================>setDisplayOrientationCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("setDisplayOrientation data: " + JSON.stringify(data)); }); ``` @@ -500,12 +507,12 @@ Sets whether to show this feature at the top of the lock screen so that the feat **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); var show=true context.setShowOnLockScreen(show, (err) => { - console.log('---------- setShowOnLockScreen fail, err: -----------', err); + console.info("setShowOnLockScreen err: " + JSON.stringify(err)); }); ``` @@ -531,13 +538,12 @@ Sets whether to show this feature at the top of the lock screen so that the feat **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); var show=true context.setShowOnLockScreen(show).then((data) => { - console.info("=======================>setShowOnLockScreenCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("setShowOnLockScreen data: " + JSON.stringify(data)); }); ``` @@ -558,12 +564,12 @@ Sets whether to wake up the screen when this feature is restored. This API uses **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); var wakeUp=true context.setWakeUpScreen(wakeUp, (err) => { - console.log('---------- setWakeUpScreen fail, err: -----------', err); + console.info("setWakeUpScreen err: " + JSON.stringify(err)); }); ``` @@ -589,13 +595,12 @@ Sets whether to wake up the screen when this feature is restored. This API uses **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); var wakeUp=true context.setWakeUpScreen(wakeUp).then((data) => { - console.info("=======================>setWakeUpScreenCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("setWakeUpScreen data: " + JSON.stringify(data)); }); ``` @@ -614,14 +619,16 @@ Obtains information about the current process, including the PID and process nam | Name | Type | Mandatory | Description | | -------- | --------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the process information.| +| callback | AsyncCallback\<[ProcessInfo](js-apis-inner-app-processInfo.md)> | Yes | Callback used to return the process information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getProcessInfo() +context.getProcessInfo((err, data) => { + console.info("getProcessInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -638,16 +645,15 @@ Obtains information about the current process, including the PID and process nam | Type | Description | | --------------------- | ------- | -| Promise\ | Promise used to return the process information.| +| Promise\<[ProcessInfo](js-apis-inner-app-processInfo.md)> | Promise used to return the process information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getProcessInfo().then((data) => { - console.info("=======================>getProcessInfoCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getProcessInfo data: " + JSON.stringify(data)); }); ``` @@ -667,14 +673,16 @@ This API is available only to Page abilities. | Name | Type | Mandatory | Description | | -------- | --------------------------- | ---- | -------------------------------------- | -| callback | AsyncCallback\ | Yes | Callback used to return the **ohos.bundle.ElementName** object.| +| callback | AsyncCallback\<[ElementName](js-apis-bundle-ElementName.md)> | Yes | Callback used to return the **ohos.bundle.ElementName** object.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getElementName() +context.getElementName((err, data) => { + console.info("getElementName err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -693,16 +701,15 @@ This API is available only to Page abilities. | Type | Description | | --------------------- | ------------------------------------ | -| Promise\ | Promise used to return the **ohos.bundle.ElementName** object.| +| Promise\<[ElementName](js-apis-bundle-ElementName.md)> | Promise used to return the **ohos.bundle.ElementName** object.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getElementName().then((data) => { - console.info("=======================>getElementNameCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getElementName data: " + JSON.stringify(data)); }); ``` @@ -722,10 +729,12 @@ Obtains the name of the current process. This API uses an asynchronous callback **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getProcessName() +context.getProcessName((err, data) => { + console.info("getProcessName err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -746,12 +755,11 @@ Obtains the name of the current process. This API uses a promise to return the r **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getProcessName().then((data) => { - console.info("=======================>getProcessNameCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getProcessName data: " + JSON.stringify(data)); }); ``` @@ -773,10 +781,12 @@ Obtains the bundle name of the calling ability. This API uses an asynchronous ca **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.getCallingBundle() +context.getCallingBundle((err, data) => { + console.info("getCallingBundle err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); +}); ``` @@ -797,12 +807,11 @@ Obtains the bundle name of the calling ability. This API uses a promise to retur **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getCallingBundle().then((data) => { - console.info("======================>getCallingBundleCallback====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getCallingBundle data: " + JSON.stringify(data)); }); ``` @@ -822,15 +831,11 @@ Obtains the cache directory of the application in the internal storage. This API **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getCacheDir((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getCacheDir err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -850,12 +855,11 @@ Obtains the cache directory of the application in the internal storage. This API **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getCacheDir().then((data) => { - console.info("======================>getCacheDirPromsie====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getCacheDir data: " + JSON.stringify(data)); }); ``` @@ -875,15 +879,11 @@ Obtains the file directory of the application in the internal storage. This API **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getFilesDir((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getFilesDir err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -903,12 +903,11 @@ Obtains the file directory of the application in the internal storage. This API **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getFilesDir().then((data) => { - console.info("======================>getFilesDirPromsie====================>"); - console.info("====>data====>" + JSON.stringify(data)); + console.info("getFilesDir data: " + JSON.stringify(data)); }); ``` @@ -930,15 +929,11 @@ If the distributed file path does not exist, the system will create one and retu **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getOrCreateDistributedDir((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getOrCreateDistributedDir err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -960,11 +955,11 @@ If the distributed file path does not exist, the system will create one and retu **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getOrCreateDistributedDir().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("getOrCreateDistributedDir data: " + JSON.stringify(data)); }); ``` @@ -984,15 +979,11 @@ Obtains the application type. This API uses an asynchronous callback to return t **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAppType((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getAppType err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -1012,11 +1003,11 @@ Obtains the application type. This API uses a promise to return the result. **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAppType().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("getAppType data: " + JSON.stringify(data)); }); ``` @@ -1036,15 +1027,11 @@ Obtains the **ModuleInfo** object of the application. This API uses an asynchron **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getHapModuleInfo((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getHapModuleInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -1064,11 +1051,11 @@ Obtains the **ModuleInfo** object of the application. This API uses a promise to **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getHapModuleInfo().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("getHapModuleInfo data: " + JSON.stringify(data)); }); ``` @@ -1084,19 +1071,15 @@ Obtains the version information of the application. This API uses an asynchronou | Name | Type | Mandatory | Description | | -------- | ---------------------------------------- | ---- | ------------------------------ | -| callback | AsyncCallback\<[AppVersionInfo](#appversioninfo)> | Yes | Callback used to return the version information.| +| callback | AsyncCallback\<[AppVersionInfo](js-apis-inner-app-appVersionInfo.md)> | Yes | Callback used to return the version information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAppVersionInfo((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getAppVersionInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -1112,15 +1095,15 @@ Obtains the version information of the application. This API uses a promise to r | Type | Description | | ---------------------------------------- | --------- | -| Promise\<[AppVersionInfo](#appversioninfo)> | Promise used to return the version information.| +| Promise\<[AppVersionInfo](js-apis-inner-app-appVersionInfo.md)> | Promise used to return the version information.| **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAppVersionInfo().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("getAppVersionInfo data: " + JSON.stringify(data)); }); ``` @@ -1140,15 +1123,11 @@ Obtains information about this ability. This API uses an asynchronous callback t **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAbilityInfo((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("getAbilityInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -1168,11 +1147,11 @@ Obtains information about this ability. This API uses a promise to return the re **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.getAbilityInfo().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("getAbilityInfo data: " + JSON.stringify(data)); }); ``` @@ -1192,8 +1171,8 @@ Obtains the context of the application. **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext().getApplicationContext(); ``` @@ -1213,15 +1192,11 @@ Checks whether the configuration of this ability is being updated. This API uses **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.isUpdatingConfigurations((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); + console.info("isUpdatingConfigurations err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); }); ``` @@ -1241,11 +1216,11 @@ Checks whether the configuration of this ability is being updated. This API uses **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.isUpdatingConfigurations().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("isUpdatingConfigurations data: " + JSON.stringify(data)); }); ``` @@ -1265,15 +1240,11 @@ Notifies the system of the time required to draw this page function. This API us **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); -context.printDrawnCompleted((err, data) => { - if (err) { - console.error('Operation failed. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Operation successful. Data:' + JSON.stringify(data)); +context.printDrawnCompleted((err) => { + console.error('printDrawnCompleted err: ' + JSON.stringify(err)); }); ``` @@ -1293,11 +1264,11 @@ Notifies the system of the time required to draw this page function. This API us **Example** -```js -import featureAbility from '@ohos.ability.featureAbility' +```ts +import featureAbility from '@ohos.ability.featureAbility'; var context = featureAbility.getContext(); context.printDrawnCompleted().then((data) => { - console.info("====>data====>" + JSON.stringify(data)); + console.info("printDrawnCompleted data: " + JSON.stringify(data)); }); ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-app-processInfo.md b/en/application-dev/reference/apis/js-apis-inner-app-processInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..0da1d45efcd3ae56473a37ec28da8e056dbf3def --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-app-processInfo.md @@ -0,0 +1,22 @@ +# ProcessInfo + +The **ProcessInfo** module defines process information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| pid | number | Yes| No| Process ID.| +| processName | string | Yes| No| Process name.| + +**Example** +```ts +import featureAbility from '@ohos.ability.featureAbility'; + +var context = featureAbility.getContext(); +context.getProcessInfo((err, data) => { + console.info("getProcessInfo err: " + JSON.stringify(err) + "data: " + JSON.stringify(data)); + let pid = data.pid; + let processName = data.processName; +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-application-abilityDelegator.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md similarity index 84% rename from en/application-dev/reference/apis/js-apis-application-abilityDelegator.md rename to en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md index 1a6035f15c6d68dd374d21e1953163b57d1e7648..71163a1d857e897306e1c90ed3262943fe898e98 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityDelegator.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md @@ -9,7 +9,7 @@ The **AbilityDelegator** module provides APIs for managing **AbilityMonitor** in ## Usage The ability delegator can be obtained by calling **getAbilityDelegator** in **AbilityDelegatorRegistry**. -```js +```ts import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' var abilityDelegator; @@ -22,7 +22,7 @@ abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); ### addAbilityMonitor9+ -addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void +addAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void; Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. @@ -32,12 +32,12 @@ Adds an **AbilityMonitor** instance. This API uses an asynchronous callback to r | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -55,11 +55,9 @@ abilityDelegator.addAbilityMonitor(monitor, (err : any) => { }); ``` - - ### addAbilityMonitor9+ -addAbilityMonitor(monitor: AbilityMonitor): Promise\ +addAbilityMonitor(monitor: AbilityMonitor): Promise\; Adds an **AbilityMonitor** instance. This API uses a promise to return the result. @@ -69,7 +67,7 @@ Adds an **AbilityMonitor** instance. This API uses a promise to return the resul | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| **Return value** @@ -79,7 +77,7 @@ Adds an **AbilityMonitor** instance. This API uses a promise to return the resul **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -101,7 +99,7 @@ abilityDelegator.addAbilityMonitor(monitor).then(() => { ### removeAbilityMonitor9+ -removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void +removeAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void; Removes an **AbilityMonitor** instance. This API uses an asynchronous callback to return the result. @@ -111,12 +109,12 @@ Removes an **AbilityMonitor** instance. This API uses an asynchronous callback t | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -138,7 +136,7 @@ abilityDelegator.removeAbilityMonitor(monitor, (err : any) => { ### removeAbilityMonitor9+ -removeAbilityMonitor(monitor: AbilityMonitor): Promise\ +removeAbilityMonitor(monitor: AbilityMonitor): Promise\; Removes an **AbilityMonitor** instance. This API uses a promise to return the result. @@ -148,7 +146,7 @@ Removes an **AbilityMonitor** instance. This API uses a promise to return the re | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| **Return value** @@ -158,7 +156,7 @@ Removes an **AbilityMonitor** instance. This API uses a promise to return the re - Example -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -180,7 +178,7 @@ abilityDelegator.removeAbilityMonitor(monitor).then(() => { ### waitAbilityMonitor9+ -waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void +waitAbilityMonitor(monitor: AbilityMonitor, callback: AsyncCallback\): void; Waits for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. @@ -190,12 +188,12 @@ Waits for the **Ability** instance that matches the **AbilityMonitor** instance | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| -| callback | AsyncCallback\<[Ability](js-apis-application-ability.md#Ability)> | Yes | Callback used to return the result. | +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| +| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -213,11 +211,9 @@ abilityDelegator.waitAbilityMonitor(monitor, (err : any, data : any) => { }); ``` - - ### waitAbilityMonitor9+ -waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\): void +waitAbilityMonitor(monitor: AbilityMonitor, timeout: number, callback: AsyncCallback\): void; Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses an asynchronous callback to return the result. @@ -227,13 +223,13 @@ Waits a period of time for the **Ability** instance that matches the **AbilityMo | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| -| timeout | number | Yes | Maximum waiting time, in milliseconds. | -| callback | AsyncCallback\<[Ability](js-apis-application-ability.md#Ability)> | Yes | Callback used to return the result. | +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| +| timeout | number | No | Maximum waiting time, in milliseconds. | +| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; var timeout = 100; @@ -256,7 +252,7 @@ abilityDelegator.waitAbilityMonitor(monitor, timeout, (err : any, data : any) => ### waitAbilityMonitor9+ -waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\ +waitAbilityMonitor(monitor: AbilityMonitor, timeout?: number): Promise\; Waits a period of time for the **Ability** instance that matches the **AbilityMonitor** instance to reach the **OnCreate** lifecycle state and returns the **Ability** instance. This API uses a promise to return the result. @@ -266,18 +262,18 @@ Waits a period of time for the **Ability** instance that matches the **AbilityMo | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-application-abilityMonitor.md#AbilityMonitor) instance.| +| monitor | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) | Yes | [AbilityMonitor](js-apis-inner-application-abilityMonitor.md#AbilityMonitor) instance.| | timeout | number | No | Maximum waiting time, in milliseconds. | **Return value** | Type | Description | | ----------------------------------------------------------- | -------------------------- | -| Promise\<[Ability](js-apis-application-ability.md#Ability)> | Promise used to return the **Ability** instance.| +| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the **Ability** instance.| **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -299,7 +295,7 @@ abilityDelegator.waitAbilityMonitor(monitor).then((data : any) => { ### getAppContext9+ -getAppContext(): Context +getAppContext(): Context; Obtains the application context. @@ -309,11 +305,11 @@ Obtains the application context. | Type | Description | | ------------------------------------- | ------------------------------------------- | -| [Context](js-apis-Context.md#Context) | [Context](js-apis-Context.md#Context) of the application.| +| [Context](js-apis-inner-application-context.md) | Application [context](js-apis-inner-application-context.md).| **Example** -```js +```ts var abilityDelegator; abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); @@ -324,7 +320,7 @@ var context = abilityDelegator.getAppContext(); ### getAbilityState9+ -getAbilityState(ability: Ability): number +getAbilityState(ability: UIAbility): number; Obtains the lifecycle state of an ability. @@ -334,17 +330,17 @@ Obtains the lifecycle state of an ability. | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------- | ---- | --------------- | -| ability | [Ability](js-apis-application-ability.md#Ability) | Yes | Target ability.| +| ability | [UIAbility](js-apis-app-ability-uiAbility.md) | Yes | Target ability.| **Return value** | Type | Description | | ------ | ------------------------------------------------------------ | -| number | Lifecycle state of the ability. For details about the available enumerated values, see [AbilityLifecycleState](js-apis-abilityDelegatorRegistry.md#AbilityLifecycleState).| +| number | Lifecycle state of the ability. For details about the available enumerated values, see [AbilityLifecycleState](js-apis-application-abilityDelegatorRegistry.md#AbilityLifecycleState).| **Example** -```js +```ts var abilityDelegator; var ability; @@ -361,7 +357,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### getCurrentTopAbility9+ -getCurrentTopAbility(callback: AsyncCallback\): void +getCurrentTopAbility(callback: AsyncCallback\): void; Obtains the top ability of this application. This API uses an asynchronous callback to return the result. @@ -371,11 +367,11 @@ Obtains the top ability of this application. This API uses an asynchronous callb | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------ | -| callback | AsyncCallback\<[Ability](js-apis-application-ability.md#Ability)> | Yes | Callback used to return the result.| +| callback | AsyncCallback\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Yes | Callback used to return the result.| **Example** -```js +```ts var abilityDelegator; var ability; @@ -390,7 +386,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### getCurrentTopAbility9+ -getCurrentTopAbility(): Promise\ +getCurrentTopAbility(): Promise\; Obtains the top ability of this application. This API uses a promise to return the result. @@ -400,11 +396,11 @@ Obtains the top ability of this application. This API uses a promise to return t | Type | Description | | ----------------------------------------------------------- | -------------------------------------- | -| Promise\<[Ability](js-apis-application-ability.md#Ability)> | Promise used to return the top ability.| +| Promise\<[UIAbility](js-apis-app-ability-uiAbility.md)> | Promise used to return the top ability.| **Example** -```js +```ts var abilityDelegator; var ability; @@ -419,7 +415,7 @@ abilityDelegator.getCurrentTopAbility().then((data : any) => { ### startAbility9+ -startAbility(want: Want, callback: AsyncCallback\): void +startAbility(want: Want, callback: AsyncCallback\): void; Starts an ability. This API uses an asynchronous callback to return the result. @@ -429,12 +425,12 @@ Starts an ability. This API uses an asynchronous callback to return the result. | Name | Type | Mandatory| Description | | -------- | -------------------------------------- | ---- | ------------------ | -| want | [Want](js-apis-application-Want.md) | Yes | **Want** parameter for starting the ability. | +| want | [Want](js-apis-application-want.md) | Yes | **Want** parameter for starting the ability. | | callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** -```js +```ts var abilityDelegator; var want = { bundleName: "bundleName", @@ -451,7 +447,7 @@ abilityDelegator.startAbility(want, (err : any, data : any) => { ### startAbility9+ -startAbility(want: Want): Promise\ +startAbility(want: Want): Promise\; Starts an ability. This API uses a promise to return the result. @@ -461,7 +457,7 @@ Starts an ability. This API uses a promise to return the result. | Name| Type | Mandatory| Description | | ------ | -------------------------------------- | ---- | --------------- | -| want | [Want](js-apis-application-Want.md) | Yes | **Want** parameter for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes | **Want** parameter for starting the ability.| **Return value** @@ -471,7 +467,7 @@ Starts an ability. This API uses a promise to return the result. **Example** -```js +```ts var abilityDelegator; var want = { bundleName: "bundleName", @@ -488,7 +484,7 @@ abilityDelegator.startAbility(want).then((data: any) => { ### doAbilityForeground9+ -doAbilityForeground(ability: Ability, callback: AsyncCallback\): void +doAbilityForeground(ability: UIAbility, callback: AsyncCallback\): void; Schedules the lifecycle state of an ability to **Foreground**. This API uses an asynchronous callback to return the result. @@ -498,12 +494,12 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses an | Name | Type | Mandatory| Description | | -------- | ----------------------- | ---- | ------------------------------------------------------- | -| ability | Ability | Yes | Target ability. | -| callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +| ability | UIAbility | Yes | Target ability. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| **Example** -```js +```ts var abilityDelegator; var ability; @@ -521,7 +517,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### doAbilityForeground9+ -doAbilityForeground(ability: Ability): Promise\ +doAbilityForeground(ability: UIAbility): Promise\; Schedules the lifecycle state of an ability to **Foreground**. This API uses a promise to return the result. @@ -531,7 +527,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses a p | Name | Type | Mandatory| Description | | ------- | ------- | ---- | --------------- | -| ability | Ability | Yes | Target ability.| +| ability | UIAbility | Yes | Target ability.| **Return value** @@ -541,7 +537,7 @@ Schedules the lifecycle state of an ability to **Foreground**. This API uses a p **Example** -```js +```ts var abilityDelegator; var ability; @@ -559,7 +555,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### doAbilityBackground9+ -doAbilityBackground(ability: Ability, callback: AsyncCallback\): void +doAbilityBackground(ability: UIAbility, callback: AsyncCallback\): void; Schedules the lifecycle state of an ability to **Background**. This API uses an asynchronous callback to return the result. @@ -569,12 +565,12 @@ Schedules the lifecycle state of an ability to **Background**. This API uses an | Name | Type | Mandatory| Description | | -------- | ----------------------- | ---- | ------------------------------------------------------- | -| ability | Ability | Yes | Target ability. | -| callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| +| ability | UIAbility | Yes | Target ability. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.
\- **true**: The operation is successful.
\- **false**: The operation failed.| **Example** -```js +```ts var abilityDelegator; var ability; @@ -592,7 +588,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### doAbilityBackground9+ -doAbilityBackground(ability: Ability): Promise\ +doAbilityBackground(ability: UIAbility): Promise\; Schedules the lifecycle state of an ability to **Background**. This API uses a promise to return the result. @@ -602,7 +598,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses a p | Name | Type | Mandatory| Description | | ------- | ------- | ---- | --------------- | -| ability | Ability | Yes | Target ability.| +| ability | UIAbility | Yes | Target ability.| **Return value** @@ -612,7 +608,7 @@ Schedules the lifecycle state of an ability to **Background**. This API uses a p **Example** -```js +```ts var abilityDelegator; var ability; @@ -630,7 +626,7 @@ abilityDelegator.getCurrentTopAbility((err : any, data : any) => { ### printSync9+ -printSync(msg: string): void +printSync(msg: string): void; Prints log information to the unit test console. @@ -644,7 +640,7 @@ Prints log information to the unit test console. **Example** -```js +```ts var abilityDelegator; var msg = "msg"; @@ -656,7 +652,7 @@ abilityDelegator.printSync(msg); ### print -print(msg: string, callback: AsyncCallback\): void +print(msg: string, callback: AsyncCallback\): void; Prints log information to the unit test console. This API uses an asynchronous callback to return the result. @@ -671,7 +667,7 @@ Prints log information to the unit test console. This API uses an asynchronous c **Example** -```js +```ts var abilityDelegator; var msg = "msg"; @@ -685,7 +681,7 @@ abilityDelegator.print(msg, (err : any) => { ### print -print(msg: string): Promise\ +print(msg: string): Promise\; Prints log information to the unit test console. This API uses a promise to return the result. @@ -705,7 +701,7 @@ Prints log information to the unit test console. This API uses a promise to retu **Example** -```js +```ts var abilityDelegator; var msg = "msg"; @@ -719,7 +715,7 @@ abilityDelegator.print(msg).then(() => { ### executeShellCommand -executeShellCommand(cmd: string, callback: AsyncCallback\): void +executeShellCommand(cmd: string, callback: AsyncCallback\): void; Executes a shell command. This API uses an asynchronous callback to return the result. @@ -730,11 +726,11 @@ Executes a shell command. This API uses an asynchronous callback to return the r | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | ---- | ------------------ | | cmd | string | Yes | Shell command string. | -| callback | AsyncCallback\<[ShellCmdResult](js-apis-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result.| +| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result.| **Example** -```js +```ts var abilityDelegator; var cmd = "cmd"; @@ -748,7 +744,7 @@ abilityDelegator.executeShellCommand(cmd, (err : any, data : any) => { ### executeShellCommand -executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\): void +executeShellCommand(cmd: string, timeoutSecs: number, callback: AsyncCallback\): void; Executes a shell command with the timeout period specified. This API uses an asynchronous callback to return the result. @@ -759,12 +755,12 @@ Executes a shell command with the timeout period specified. This API uses an asy | Name | Type | Mandatory| Description | | ----------- | ------------------------------------------------------------ | ---- | ----------------------------- | | cmd | string | Yes | Shell command string. | -| timeoutSecs | number | Yes | Command timeout period, in seconds.| -| callback | AsyncCallback\<[ShellCmdResult](js-apis-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result. | +| timeoutSecs | number | No | Command timeout period, in seconds.| +| callback | AsyncCallback\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; var cmd = "cmd"; var timeout = 100; @@ -779,7 +775,7 @@ abilityDelegator.executeShellCommand(cmd, timeout, (err : any, data : any) => { ### executeShellCommand -executeShellCommand(cmd: string, timeoutSecs?: number): Promise\ +executeShellCommand(cmd: string, timeoutSecs?: number): Promise\; Executes a shell command with the timeout period specified. This API uses a promise to return the result. @@ -796,11 +792,11 @@ Executes a shell command with the timeout period specified. This API uses a prom | Type | Description | | ------------------------------------------------------------ | ------------------------------------------------------------ | -| Promise\<[ShellCmdResult](js-apis-application-shellCmdResult.md#ShellCmdResult)> | Promise used to return a [ShellCmdResult](js-apis-application-shellCmdResult.md#ShellCmdResult) object.| +| Promise\<[ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult)> | Promise used to return a [ShellCmdResult](js-apis-inner-application-shellCmdResult.md#ShellCmdResult) object.| **Example** -```js +```ts var abilityDelegator; var cmd = "cmd"; var timeout = 100; @@ -815,7 +811,7 @@ abilityDelegator.executeShellCommand(cmd, timeout).then((data : any) => { ### finishTest9+ -finishTest(msg: string, code: number, callback: AsyncCallback\): void +finishTest(msg: string, code: number, callback: AsyncCallback\): void; Finishes the test and prints log information to the unit test console. This API uses an asynchronous callback to return the result. @@ -831,7 +827,7 @@ Finishes the test and prints log information to the unit test console. This API **Example** -```js +```ts var abilityDelegator; var msg = "msg"; @@ -845,7 +841,7 @@ abilityDelegator.finishTest(msg, 0, (err : any) => { ### finishTest9+ -finishTest(msg: string, code: number): Promise\ +finishTest(msg: string, code: number): Promise\; Finishes the test and prints log information to the unit test console. This API uses a promise to return the result. @@ -866,7 +862,7 @@ Finishes the test and prints log information to the unit test console. This API **Example** -```js +```ts var abilityDelegator; var msg = "msg"; @@ -888,12 +884,12 @@ Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; var monitor = { @@ -921,7 +917,7 @@ Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| **Return value** @@ -931,7 +927,7 @@ Adds an **AbilityStageMonitor** instance to monitor the lifecycle state changes **Example** -```js +```ts var abilityDelegator; var monitor = { @@ -957,12 +953,12 @@ Removes an **AbilityStageMonitor** instance from the application memory. This AP | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. | **Example** -```js +```ts var abilityDelegator; var monitor = { @@ -990,7 +986,7 @@ Removes an **AbilityStageMonitor** object from the application memory. This API | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| **Return value** @@ -1000,7 +996,7 @@ Removes an **AbilityStageMonitor** object from the application memory. This API **Example** -```js +```ts var abilityDelegator; var monitor = { @@ -1026,12 +1022,12 @@ Waits for an **AbilityStage** instance that matches the conditions set in an **A | Name | Type | Mandatory| Description | | -------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -1061,7 +1057,7 @@ Waits for an **AbilityStage** instance that matches the conditions set in an **A | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | timeout | number | No | Maximum waiting time, in milliseconds.| **Return value** @@ -1072,7 +1068,7 @@ Waits for an **AbilityStage** instance that matches the conditions set in an **A **Example** -```js +```ts var abilityDelegator; function onAbilityCreateCallback(data) { @@ -1102,13 +1098,13 @@ Waits a period of time for an **AbilityStage** instance that matches the conditi | Name | Type | Mandatory| Description | | ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| monitor | [AbilityStageMonitor](#abilitystagemonitor) | Yes | [AbilityStageMonitor](#abilitystagemonitor) instance.| +| monitor | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) | Yes | [AbilityStageMonitor](js-apis-inner-application-abilityStageMonitor.md) instance.| | timeout | number | No | Maximum waiting time, in milliseconds.| | callback | AsyncCallback\ | Yes | Callback used to return the result. If the operation is successful, an **AbilityStage** instance is returned. Otherwise, no value is returned. | **Example** -```js +```ts var abilityDelegator; var timeout = 100; @@ -1126,14 +1122,3 @@ abilityDelegator.waitAbilityStageMonitor(monitor, timeout, (err : any, data : an console.info("waitAbilityStageMonitor callback"); }); ``` - -## AbilityStageMonitor - -Provides conditions for matching **AbilityStage** instances. The most recently matched **AbilityStage** instance is saved in an **AbilityStageMonitor** instance. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Type | Readable| Writable| Description | -| ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ | -| moduleName9+ | string | Yes | Yes | Module name of the **AbilityStage** instance.| -| srcEntrance9+ | string | Yes | Yes | Source path of the **AbilityStage** instance.| diff --git a/en/application-dev/reference/apis/js-apis-application-abilityDelegatorArgs.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegatorArgs.md similarity index 88% rename from en/application-dev/reference/apis/js-apis-application-abilityDelegatorArgs.md rename to en/application-dev/reference/apis/js-apis-inner-application-abilityDelegatorArgs.md index e1b3aa3bbe5e16262db584894055c090a224b625..97ecb0ed8bf03802ac2a8e1dcab4516d45acc36d 100644 --- a/en/application-dev/reference/apis/js-apis-application-abilityDelegatorArgs.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityDelegatorArgs.md @@ -10,12 +10,6 @@ The **AbilityDelegatorArgs** module provides a global register to store the regi The ability delegator arguments are obtained by calling **getArguments** in **AbilityDelegatorRegistry**. -```js -import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'; - -var args = AbilityDelegatorRegistry.getArguments(); -``` - ## AbilityDelegatorArgs Describes the ability delegator arguments. @@ -24,7 +18,15 @@ Describes the ability delegator arguments. | Name | Type | Readable| Writable| Description | | ------------------- | ---------------------- | ---- | ---- | ------------------------------------------------------------ | -| bundleName | string | Yes | Yes | Bundle name of the application to test. | -| parameters | {[key:string]: string} | Yes | Yes | Parameters of the unit test that is started currently. | -| testCaseNames | string | Yes | Yes | Test case names. | -| testRunnerClassName | string | Yes | Yes | Names of the test case executors. | +| bundleName | string | Yes | Yes | Bundle name of the application to test.| +| parameters | {[key:string]: string} | Yes | Yes | Parameters of the unit test that is started currently.| +| testCaseNames | string | Yes | Yes | Test case names.| +| testRunnerClassName | string | Yes | Yes | Names of the test case executors.| + +**Example** + +```ts +import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'; + +var args = AbilityDelegatorRegistry.getArguments(); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md new file mode 100644 index 0000000000000000000000000000000000000000..7aef3303481563008a79f7f8a43be66cbbbfa7fa --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityMonitor.md @@ -0,0 +1,49 @@ +# AbilityMonitor + +The **AbilityMonitor** module provides monitors for abilities that meet specified conditions. The latest matched abilities are stored in an **AbilityMonitor** object. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Usage + +The ability monitor can be set by calling **addAbilityMonitor** in **abilityDelegator**. + +## AbilityMonitor + +Describes an ability monitor. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable| Writable| Description | +| ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ | +| abilityName | string | Yes | Yes | Name of the ability bound to the ability monitor.| +| onAbilityCreate?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the ability is created.
If this attribute is not set, the corresponding lifecycle callback cannot be received.| +| onAbilityForeground?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the ability starts to run in the foreground.
If this attribute is not set, the corresponding lifecycle callback cannot be received.| +| onAbilityBackground?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the ability starts to run in the background.
If this attribute is not set, the corresponding lifecycle callback cannot be received.| +| onAbilityDestroy?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the ability is destroyed.
If this attribute is not set, the corresponding lifecycle callback cannot be received.
| +| onWindowStageCreate?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the window stage is created.
If this attribute is not set, the corresponding lifecycle callback cannot be received.
| +| onWindowStageRestore?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the window stage is restored.
If this attribute is not set, the corresponding lifecycle callback cannot be received.
| +| onWindowStageDestroy?:(data: [UIAbility](js-apis-app-ability-uiAbility.md)) | function | Yes | Yes | Called when the window stage is destroyed.
If this attribute is not set, the corresponding lifecycle callback cannot be received.
| + +**Example** + +```ts +import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' +var abilityDelegator; + +function onAbilityCreateCallback(data) { + console.info("onAbilityCreateCallback"); +} + +var monitor = { + abilityName: "abilityname", + onAbilityCreate: onAbilityCreateCallback +} + +abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.addAbilityMonitor(monitor, (err : any) => { + console.info("addAbilityMonitor callback"); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-abilityrunninginfo.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md similarity index 56% rename from en/application-dev/reference/apis/js-apis-abilityrunninginfo.md rename to en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md index 098f4ebba840a13d1f37d6e14256fcc9695f2a8d..4f553001c63881441b23a3ce42ba429497775b2d 100644 --- a/en/application-dev/reference/apis/js-apis-abilityrunninginfo.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityRunningInfo.md @@ -1,6 +1,6 @@ # AbilityRunningInfo -The **AbilityRunningInfo** module implements ability running information and ability states. +The **AbilityRunningInfo** module defines the running information and state of an ability. > **NOTE** > @@ -10,13 +10,6 @@ The **AbilityRunningInfo** module implements ability running information and abi The ability running information is obtained by using the **getAbilityRunningInfos** API in **abilityManager**. -```js -import abilitymanager from '@ohos.application.abilityManager'; -abilitymanager.getAbilityRunningInfos((err,data) => { - console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); -}); -``` - ## Attributes **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -30,4 +23,22 @@ abilitymanager.getAbilityRunningInfos((err,data) => { | uid | number | Yes| No| User ID. | | processName | string | Yes| No| Process name. | | startTime | number | Yes| No| Ability start time. | -| abilityState | [abilityManager.AbilityState](js-apis-application-abilityManager.md#abilitystate) | Yes| No| Ability state. | +| abilityState | [abilityManager.AbilityState](js-apis-app-ability-abilityManager.md#abilitystate) | Yes| No| Ability state. | + +**Example** + +```ts +import abilitymanager from '@ohos.application.abilityManager'; +abilitymanager.getAbilityRunningInfos((err,data) => { + console.log("getAbilityRunningInfos err: " + err + " data: " + JSON.stringify(data)); + for (let i = 0; i < data.length; i++) { + let abilityinfo = data[i]; + console.log("abilityinfo.ability: " + JSON.stringify(abilityinfo.ability)); + console.log("abilityinfo.pid: " + JSON.stringify(abilityinfo.pid)); + console.log("abilityinfo.uid: " + JSON.stringify(abilityinfo.uid)); + console.log("abilityinfo.processName: " + JSON.stringify(abilityinfo.processName)); + console.log("abilityinfo.startTime: " + JSON.stringify(abilityinfo.startTime)); + console.log("abilityinfo.abilityState: " + JSON.stringify(abilityinfo.abilityState)); + } +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-abilitystagecontext.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageContext.md similarity index 99% rename from en/application-dev/reference/apis/js-apis-abilitystagecontext.md rename to en/application-dev/reference/apis/js-apis-inner-application-abilityStageContext.md index 5475dc51466d01d8eadef472248cce237f1b6241..99a2453d84124b1eee3d7dc6a5aa7c2d8e5b8663 100644 --- a/en/application-dev/reference/apis/js-apis-abilitystagecontext.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageContext.md @@ -13,7 +13,7 @@ This module provides APIs for accessing a specific ability stage. You can use th The ability stage context is obtained through an **AbilityStage** instance. -```js +```ts import AbilityStage from '@ohos.application.AbilityStage'; class MyAbilityStage extends AbilityStage { onCreate() { diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md new file mode 100644 index 0000000000000000000000000000000000000000..76a4ae2e425ce91acb0f79d22889cba231809c26 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md @@ -0,0 +1,25 @@ +# AbilityStageMonitor + +The **AbilityStageMonitor** module provides conditions for matching **AbilityStage** instances. The most recently matched **AbilityStage** instance is saved in an **AbilityStageMonitor** instance. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable| Writable| Description | +| ------------------------------------------------------------ | -------- | ---- | ---- | ------------------------------------------------------------ | +| moduleName9+ | string | Yes | Yes | Module name of the **AbilityStage** instance.| +| srcEntrance9+ | string | Yes | Yes | Source path of the **AbilityStage** instance.| + +**Example** +```ts +import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry' + +let monitor = { + moduleName: "feature_as1", + srcEntrance: "./ets/Application/MyAbilityStage.ts", +}; + +let abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator(); +abilityDelegator.waitAbilityStageMonitor(monitor, (error, data) => { + console.info("stageMonitor waitAbilityStageMonitor, abilityStage = " + JSON.stringify(data)); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md b/en/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md new file mode 100644 index 0000000000000000000000000000000000000000..b86ba33545181076833461e4a63650290d15be9b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md @@ -0,0 +1,33 @@ +# AbilityStateData + +The **AbilityStateData** module defines the ability state information. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ---------| ---- | ---- | ------------------------- | +| pid8+ | number | Yes | No | Process ID. | +| bundleName8+ | string | Yes | No | Bundle name of an application. | +| abilityName8+ | string | Yes | No | Ability name. | +| uid8+ | number | Yes | No | User ID. | +| state8+ | number | Yes | No | Ability state. | +| moduleName9+ | string | Yes | No | Name of the HAP file to which the ability belongs. | +| abilityType8+ | string | Yes | No | Ability type. | + +**Example** +```ts +import appManager from "@ohos.application.appManager" + +appManager.getForegroundApplications((error, data) => { + for(let i=0; i8+ | string | No | Bundle name of the application. | +| uid8+ | number | No | User ID.| +| state8+ | number | No | Application state.| + +**Example** +```ts +import appManager from "@ohos.application.appManager" + +appManager.getForegroundApplications((error, data) => { + for(let i=0; i { - console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); - }); - } } - ``` - +``` ## ApplicationContext.unregisterAbilityLifecycleCallback @@ -102,14 +104,21 @@ Deregisters the listener that monitors the ability lifecycle of the application. **Example** - ```js - let applicationContext = this.context.getApplicationContext(); - let lifecycleId = 1; - console.log("stage applicationContext: " + JSON.stringify(applicationContext)); - applicationContext.unregisterAbilityLifecycleCallback(lifecycleId, (error, data) => { - console.log("unregisterAbilityLifecycleCallback success, err: " + JSON.stringify(error)); - }); - ``` +```ts +import Ability from "@ohos.application.Ability"; + +var lifecycleId; + +export default class MyAbility extends Ability { + onDestroy() { + 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)); + }); + } +} +``` ## ApplicationContext.registerEnvironmentCallback @@ -123,7 +132,7 @@ Registers a listener for system environment changes. This API uses an asynchrono | Name | Type | Mandatory| Description | | ------------------------ | -------- | ---- | ------------------------------ | -| callback | [EnvironmentCallback](js-apis-application-EnvironmentCallback.md) | Yes | Callback used to return the ID of the registered listener.| +| callback | [EnvironmentCallback](js-apis-app-ability-environmentCallback.md) | Yes | Callback used to return the ID of the registered listener.| **Return value** @@ -133,14 +142,14 @@ Registers a listener for system environment changes. This API uses an asynchrono **Example** - ```js -import AbilityStage from "@ohos.application.AbilityStage"; +```ts +import Ability from "@ohos.application.Ability"; var callbackId; -export default class MyAbilityStage extends AbilityStage { +export default class MyAbility extends Ability { onCreate() { - console.log("MyAbilityStage onCreate") + console.log("MyAbility onCreate") globalThis.applicationContext = this.context.getApplicationContext(); let EnvironmentCallback = { onConfigurationUpdated(config){ @@ -153,14 +162,8 @@ export default class MyAbilityStage extends AbilityStage { callbackId = applicationContext.registerEnvironmentCallback(EnvironmentCallback); console.log("registerEnvironmentCallback number: " + JSON.stringify(callbackId)); } - onDestroy() { - let applicationContext = globalThis.applicationContext; - applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => { - console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error)); - }); - } } - ``` +``` ## ApplicationContext.unregisterEnvironmentCallback @@ -179,10 +182,17 @@ Deregisters the listener for system environment changes. This API uses an asynch **Example** - ```js - let applicationContext = this.context.getApplicationContext(); - let callbackId = 1; - applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => { - console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error)); - }); - ``` +```ts +import Ability from "@ohos.application.Ability"; + +var callbackId; + +export default class MyAbility extends Ability { + onDestroy() { + let applicationContext = this.context.getApplicationContext(); + applicationContext.unregisterEnvironmentCallback(callbackId, (error, data) => { + console.log("unregisterEnvironmentCallback success, err: " + JSON.stringify(error)); + }); + } +} +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-applicationStateObserver.md b/en/application-dev/reference/apis/js-apis-inner-application-applicationStateObserver.md new file mode 100644 index 0000000000000000000000000000000000000000..15925c305ab652b9b4426c169b430af358e89331 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-applicationStateObserver.md @@ -0,0 +1,39 @@ +# ApplicationStateObserver + +The **ApplicationStateObserver** module defines the listener to observe the application state. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ---------| ---- | ---- | ------------------------- | +| onForegroundApplicationChanged8+ | AsyncCallback\ | Yes | No | Callback invoked when the foreground or background state of an application changes. | +| onAbilityStateChanged8+ | AsyncCallback\ | Yes | No | Callback invoked when the ability state changes. | +| onProcessCreated8+ | AsyncCallback\ | Yes | No | Callback invoked when a process is created. | +| onProcessDied8+ | AsyncCallback\ | Yes | No | Callback invoked when a process is destroyed. | +| onProcessStateChanged8+ | AsyncCallback\ | Yes | No | Callback invoked when the process state is changed. | + +**Example** +```ts +import appManager from "@ohos.application.appManager" + +let applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('onForegroundApplicationChanged appStateData: ' + JSON.stringify(appStateData)); + }, + onAbilityStateChanged(abilityStateData) { + console.log('onAbilityStateChanged onAbilityStateChanged: ' + JSON.stringify(abilityStateData)); + }, + onProcessCreated(processData) { + console.log('onProcessCreated onProcessCreated: ' + JSON.stringify(processData)); + }, + onProcessDied(processData) { + console.log('onProcessDied onProcessDied: ' + JSON.stringify(processData)); + }, + onProcessStateChanged(processData) { + console.log('onProcessStateChanged onProcessStateChanged: ' + JSON.stringify(processData)); + } +} +let observerCode = appManager.registerApplicationStateObserver(applicationStateObserver); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-baseContext.md b/en/application-dev/reference/apis/js-apis-inner-application-baseContext.md new file mode 100644 index 0000000000000000000000000000000000000000..24b284ed85986d96e58afba9c2bc4ff75804ebca --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-baseContext.md @@ -0,0 +1,23 @@ +# BaseContext + +The abstract class **BaseContext** specifies whether its child class **Context** is used for the stage model or FA model. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable | Writable | Description | +| -------- | ------ | ---- | ---- | ------- | +| stageMode | boolean | Yes | Yes | Whether the context is used for the stage model.| + +**Example** + + ```ts + class MyContext extends BaseContext { + constructor(stageMode) { + this.stageMode = stageMode; + } + } + ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-context.md b/en/application-dev/reference/apis/js-apis-inner-application-context.md new file mode 100644 index 0000000000000000000000000000000000000000..15e249798f9f731427b8b514b020abde8e924053 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-context.md @@ -0,0 +1,135 @@ +# Context + +The **Context** module provides context for abilities or applications. It allows access to application-specific resources, as well as permission requests and verification. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module can be used only in the stage model. + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable | Writable | Description | +| ----------- | ------ | ---- | ---- | ------- | +| resourceManager | resmgr.ResourceManager | Yes | No | Object for resource management. | +| applicationInfo | ApplicationInfo | Yes | No | Application information.| +| cacheDir | string | Yes | No | Cache directory.| +| tempDir | string | Yes | No | Temporary directory.| +| filesDir | string | Yes | No | File directory.| +| databaseDir | string | Yes | No | Database directory.| +| preferencesDir | string | Yes | No | Preferences directory.| +| bundleCodeDir | string | Yes | No | Bundle code directory.| +| distributedFilesDir | string | Yes | No | Distributed file directory.| +| eventHub | string | Yes | No | Event hub that implements event subscription, unsubscription, and triggering.| +| area | [AreaMode](#areamode) | Yes | No | Area in which the file to be access is located.| + + +## Context.createBundleContext + +createBundleContext(bundleName: string): Context; + +Creates the context based on the bundle name. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------- | +| bundleName | string | Yes | Bundle name of the application.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Context | Context created.| + +**Example** + +```ts +let bundleContext = this.context.createBundleContext("com.example.test"); +``` + +## Context.createModuleContext + +createModuleContext(moduleName: string): Context; + +Creates the context based on the module name. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------- | +| moduleName | string | Yes | Module name.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Context | Context created.| + +**Example** + +```ts +let moduleContext = this.context.createModuleContext("entry"); +``` + +createModuleContext(bundleName: string, moduleName: string): Context; + +Creates the context based on the bundle name and module name. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------- | ---- | ------------- | +| bundleName | string | Yes | Bundle name of the application.| +| moduleName | string | Yes | Module name.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Context | Context created.| + +**Example** + +```ts +let moduleContext = this.context.createModuleContext("com.example.test", "entry"); +``` + +## Context.getApplicationContext + +getApplicationContext(): ApplicationContext; + +Obtains the application context. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Context | Application context obtained.| + +**Example** + +```ts +let applicationContext = this.context.getApplicationContext(); +``` + +## AreaMode + +Enumerates the areas in which the file to be access can be located. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Value| Description| +| -------- | -------- | -------- | +| EL1 | 0 | Device-level encryption area.| +| EL2 | 1 | User credential encryption area.| diff --git a/en/application-dev/reference/apis/js-apis-inner-application-continueCallback.md b/en/application-dev/reference/apis/js-apis-inner-application-continueCallback.md new file mode 100644 index 0000000000000000000000000000000000000000..93d138db23255a3c312e55a423411cdb29f211e5 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-continueCallback.md @@ -0,0 +1,37 @@ +# ContinueCallback + +The **ContinueCallback** module defines the callback invoked when the mission continuation is complete. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| --------------------- | -------- | ---- | ---- | ------------------ | +| onContinueDone | function | Yes | No | Callback used to notify the user that the mission continuation is complete and return the continuation result. | + +**Example** + + ```ts + import distributedMissionManager from '@ohos.distributedMissionManager'; + + let continueDeviceInfo = { + srcDeviceId: "123", + dstDeviceId: "456", + missionId: 123, + wantParam: { + "key":"value" + } + }; + + let continueCallback = { + onContinueDone(result) { + console.log('onContinueDone, result: ' + JSON.stringify(result)); + } + } + + distributedMissionManager.continueMission(continueDeviceInfo, continueCallback, (error) => { + if (error.code != 0) { + console.error('continueMission failed, cause: ' + JSON.stringify(error)) + } + console.info('continueMission finished') + }) + ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md b/en/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..b42044ef893ebd23f97549ad378f21dcf8067c93 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md @@ -0,0 +1,40 @@ +# ContinueDeviceInfo + +The **ContinueDeviceInfo** module defines the parameters required for mission continuation. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| -------- | ------ | ---- | ---- | ------- | +| srcDeviceId | string | Yes | Yes | ID of the source device.| +| dstDeviceId | string | Yes | Yes | ID of the target device.| +| missionId | number | Yes | Yes | Mission ID.| +| wantParam | {[key: string]: any} | Yes | Yes | Extended parameters.| + +**Example** + + ```ts + import distributedMissionManager from '@ohos.distributedMissionManager'; + + let continueDeviceInfo = { + srcDeviceId: "123", + dstDeviceId: "456", + missionId: 123, + wantParam: { + "key":"value" + } + }; + + let continueCallback = { + onContinueDone(result) { + console.log('onContinueDone, result: ' + JSON.stringify(result)); + } + } + + distributedMissionManager.continueMission(continueDeviceInfo, continueCallback, (error) => { + if (error.code != 0) { + console.error('continueMission failed, cause: ' + JSON.stringify(error)) + } + console.info('continueMission finished') + }) + ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-errorObserver.md b/en/application-dev/reference/apis/js-apis-inner-application-errorObserver.md new file mode 100644 index 0000000000000000000000000000000000000000..056a2313dd1aeffdcd69812c491e9e03a77f5f41 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-errorObserver.md @@ -0,0 +1,30 @@ +# ErrorObserver + +The **ErrorObserver** module defines the listener to observe errors. + +## onUnhandledException + +onUnhandledException(errMsg: string): void; + +Called when an unhandled exception occurs in the JS runtime. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| errMsg | string | No| Message and error stack trace about the exception.| + +**Example** + +```ts +import errorManager from '@ohos.application.errorManager'; + +let observer = { + onUnhandledException(errorMsg) { + console.log('onUnhandledException, errorMsg: ' + JSON.stringify(errorMsg)); + } +} +errorManager.registerErrorObserver(observer) +``` diff --git a/en/application-dev/reference/apis/js-apis-eventhub.md b/en/application-dev/reference/apis/js-apis-inner-application-eventHub.md similarity index 97% rename from en/application-dev/reference/apis/js-apis-eventhub.md rename to en/application-dev/reference/apis/js-apis-inner-application-eventHub.md index 9ae7db735cbc61fa55a764cb285801297452c5d8..9c45684cd9faaf03a8de66ba73541ae75ded9cc3 100644 --- a/en/application-dev/reference/apis/js-apis-eventhub.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-eventHub.md @@ -11,7 +11,7 @@ The **EventHub** module provides APIs to subscribe to, unsubscribe from, and tri Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **Ability** instance. -```js +```ts import Ability from '@ohos.application.Ability'; export default class MainAbility extends Ability { func1(){ @@ -23,7 +23,6 @@ export default class MainAbility extends Ability { } ``` - ## EventHub.on on(event: string, callback: Function): void; @@ -39,9 +38,9 @@ Subscribes to an event. | event | string | Yes| Event name.| | callback | Function | Yes| Callback invoked when the event is triggered.| -**Example** - - ```js +**Example** + + ```ts import Ability from '@ohos.application.Ability'; export default class MainAbility extends Ability { @@ -77,9 +76,9 @@ Unsubscribes from an event. If **callback** is specified, this API unsubscribes | event | string | Yes| Event name.| | callback | Function | No| Callback for the event. If **callback** is unspecified, all callbacks of the event are unsubscribed.| -**Example** - - ```js +**Example** + + ```ts import Ability from '@ohos.application.Ability'; export default class MainAbility extends Ability { @@ -115,9 +114,9 @@ Triggers an event. | event | string | Yes| Event name.| | ...args | Object[] | Yes| Variable parameters, which are passed to the callback when the event is triggered.| -**Example** - - ```js +**Example** + + ```ts import Ability from '@ohos.application.Ability'; export default class MainAbility extends Ability { diff --git a/en/application-dev/reference/apis/js-apis-extension-context.md b/en/application-dev/reference/apis/js-apis-inner-application-extensionContext.md similarity index 87% rename from en/application-dev/reference/apis/js-apis-extension-context.md rename to en/application-dev/reference/apis/js-apis-inner-application-extensionContext.md index 71d3df6c294d62f2fafa0801df0d132b88c42fe3..1ed64e2a07cc8e92a7d8310d4fb4d0c42d36ff5b 100644 --- a/en/application-dev/reference/apis/js-apis-extension-context.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-extensionContext.md @@ -2,7 +2,7 @@ The **ExtensionContext** module, inherited from **Context**, implements the context for Extension abilities. -This module provides APIs for accessing resources of a specific Extension ability. An Extension ability can use the context directly provided by **ExtensionContext** or that extended from **ExtensionContext**. For example, **ServiceExtension** uses **[ServiceExtensionContext](js-apis-service-extension-context.md)**, which extends the capabilities of starting, stopping, binding, and unbinding abilities based on **ExtensionContext**. +This module provides APIs for accessing resources of a specific Extension ability. An Extension ability can use the context directly provided by **ExtensionContext** or that extended from **ExtensionContext**. For example, **ServiceExtension** uses [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md), which extends the capabilities of starting, stopping, binding, and unbinding abilities based on **ExtensionContext**. > **NOTE** > @@ -15,8 +15,8 @@ This module provides APIs for accessing resources of a specific Extension abilit | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the HAP file
(See **api\bundle\hapModuleInfo.d.ts** in the **SDK** directory.) | -| config | Configuration | Yes| No| Module configuration information.
(See **api\@ohos.application.Configuration.d.ts** in the **SDK** directory.)| +| currentHapModuleInfo | [HapModuleInfo](js-apis-bundle-HapModuleInfo.md) | Yes| No| Information about the HAP file
(See **api\bundle\hapModuleInfo.d.ts** in the **SDK** directory.) | +| config | [Configuration](js-apis-app-ability-configuration.md) | Yes| No| Module configuration information.
(See **api\@ohos.app.ability.Configuration.d.ts** in the **SDK** directory.)| | extensionAbilityInfo | [ExtensionAbilityInfo](js-apis-bundleManager-extensionAbilityInfo.md) | Yes| No| Extension ability information.
(See **api\bundle\extensionAbilityInfo.d.ts** in the **SDK** directory.)| ## When to Use @@ -30,7 +30,7 @@ To adapt to devices with different performance, an application provides three mo **Example** Define a **ServiceExtension** with the same name for the three modules. -``` js +```ts import ServiceExtension from '@ohos.app.ability.ServiceExtensionAbility' import Want from '@ohos.application.Want' export default class TheServiceExtension extends ServiceExtension { @@ -60,7 +60,7 @@ export default class TheServiceExtension extends ServiceExtension { ``` Start **ServiceExtension** within the **onCreate** callback of the main ability of the entry. -``` js +```ts import Ability from '@ohos.app.ability.Ability' export default class MainAbility extends Ability { onCreate(want, launchParam) { @@ -76,7 +76,7 @@ export default class MainAbility extends Ability { ``` Create a **ServiceModule.ts** file in the entry to execute service logic. -``` js +```ts export default class ServiceModel { moduleName: string; diff --git a/en/application-dev/reference/apis/js-apis-extensionrunninginfo.md b/en/application-dev/reference/apis/js-apis-inner-application-extensionRunningInfo.md similarity index 57% rename from en/application-dev/reference/apis/js-apis-extensionrunninginfo.md rename to en/application-dev/reference/apis/js-apis-inner-application-extensionRunningInfo.md index 841f7755273489a570865b41c63c5103c3af0c9a..9184ae6ce0f0b4b8dee355d96a4c28cf84013ef2 100644 --- a/en/application-dev/reference/apis/js-apis-extensionrunninginfo.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-extensionRunningInfo.md @@ -11,14 +11,6 @@ The **ExtensionRunningInfo** module provides running information and states for The Extension ability running information is obtained through an **abilityManager** instance. -```js -import abilityManager from '@ohos.application.abilityManager'; -let upperLimit=1 -abilityManager.getExtensionRunningInfos(upperLimit, (err,data) => { - console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); -}); -``` - ## Attributes **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -31,4 +23,23 @@ abilityManager.getExtensionRunningInfos(upperLimit, (err,data) => { | processName | string | Yes| No| Process name.| | startTime | number | Yes| No| Start time of the Extension ability.| | clientPackage | Array<String> | Yes| No| Names of all packages in the process.| -| type | [bundle.ExtensionAbilityType](js-apis-Bundle.md#extensionabilitytype9) | Yes| No| Extension ability type.| +| type | [bundle.ExtensionAbilityType](js-apis-Bundle.md) | Yes| No| Extension ability type.| + +**Example** +```ts +import abilityManager from '@ohos.application.abilityManager'; +let upperLimit=1; +abilityManager.getExtensionRunningInfos(upperLimit, (err,data) => { + console.log("getExtensionRunningInfos err: " + err + " data: " + JSON.stringify(data)); + for (let i=0; i { + if (error) { + console.log('FormExtensionContext startAbility, error:' + JSON.stringify(error)); + } else { + console.log(`FormExtensionContext startAbility success`); + } }) ``` -## FormExtensionContext.startAbility +## startAbility startAbility(want: Want): Promise<void> Starts an ability. This API uses a promise to return the result. -**System capability**: SystemCapability.Ability.Form +**System API**: This is a system API. -**System API**: This is a system API and cannot be called by third-party applications. +**System capability**: SystemCapability.Ability.Form **Parameters** | Name| Type | Mandatory| Description | | ------| --------------------------------- | ---- | -------------------------------------- | -| want| [Want](js-apis-application-Want.md) | Yes | Information about the ability to start, such as the ability name and bundle name.| +| want| [Want](js-apis-application-want.md) | Yes | Information about the ability to start, such as the bundle name, ability name, and custom parameters.| **Return value** | Type | Description | | ------------ | ---------------------------------- | -| Promise<void< | Promise used to return the result.| +| Promise<void< | Promise that returns no value.| **Example** -```js +```ts var want = { deviceId: "", bundleName: "com.example.formstartability", diff --git a/en/application-dev/reference/apis/js-apis-inner-application-missionCallbacks.md b/en/application-dev/reference/apis/js-apis-inner-application-missionCallbacks.md new file mode 100644 index 0000000000000000000000000000000000000000..e56a2a43e4603f1b2f8e0e2a9dfbaf303e938f7b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionCallbacks.md @@ -0,0 +1,34 @@ +# MissionCallbacks + +The **MissionCallbacks** module defines the callbacks that can be registered as a mission status listener. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Template | Readable | Writable | Description | +| --------------------- | -------- | ---- | ---- | ------------------ | +| notifyMissionsChanged | function | Yes | No | Callback used to notify the mission change event and return the device ID. | +| notifySnapshot | function | Yes | No | Callback used to notify the snapshot change event and return the device ID and mission ID.| +| notifyNetDisconnect | function | Yes | No | Callback used to notify the disconnection event and return the device ID and network status.| + +**Example** +```ts +import distributedMissionManager from '@ohos.distributedMissionManager'; + +let missionDeviceInfo = { + deviceId: "123456" +}; +let missionCallback = { + notifyMissionsChanged: function (deviceId) { + console.log("notifyMissionsChanged deviceId: " + JSON.stringify(deviceId)); + }, + notifySnapshot: function (mission, deviceId) { + console.log("notifySnapshot mission: " + JSON.stringify(mission)); + console.log("notifySnapshot deviceId: " + JSON.stringify(deviceId)); + }, + notifyNetDisconnect: function (mission, state) { + console.log("notifyNetDisconnect mission: " + JSON.stringify(mission)); + console.log("notifyNetDisconnect state: " + JSON.stringify(state)); + } +}; +distributedMissionManager.registerMissionListener(missionDeviceInfo, missionCallback); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-missionDeviceInfo.md b/en/application-dev/reference/apis/js-apis-inner-application-missionDeviceInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..028e5dafadb2c6b5c63486f82e08acb2e1f601c5 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionDeviceInfo.md @@ -0,0 +1,32 @@ +# MissionDeviceInfo + +The **MissionDeviceInfo** module defines the parameters required for registering a listener. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| -------- | ------ | ---- | ---- | ------- | +| deviceId | string | Yes | Yes | Device ID.| + +**Example** +```ts +import distributedMissionManager from '@ohos.distributedMissionManager'; + +let missionDeviceInfo = { + deviceId: "123456" +}; +let missionCallback = { + notifyMissionsChanged: function (deviceId) { + console.log("notifyMissionsChanged deviceId: " + JSON.stringify(deviceId)); + }, + notifySnapshot: function (mission, deviceId) { + console.log("notifySnapshot mission: " + JSON.stringify(mission)); + console.log("notifySnapshot deviceId: " + JSON.stringify(deviceId)); + }, + notifyNetDisconnect: function (mission, state) { + console.log("notifyNetDisconnect mission: " + JSON.stringify(mission)); + console.log("notifyNetDisconnect state: " + JSON.stringify(state)); + } +}; +distributedMissionManager.registerMissionListener(missionDeviceInfo, missionCallback); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-missionInfo.md b/en/application-dev/reference/apis/js-apis-inner-application-missionInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..5240d4229fb1222c91bcbddac116b26e23e69dd9 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionInfo.md @@ -0,0 +1,34 @@ +# MissionInfo + +The **MissionInfo** module defines the mission information of an ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| missionId | number | Yes| Yes| Mission ID.| +| runningState | number | Yes| Yes| Running state of the mission.| +| lockedState | boolean | Yes| Yes| Locked state of the mission.| +| timestamp | string | Yes| Yes| Latest time when the mission was created or updated.| +| want | [Want](js-apis-application-want.md) | Yes| Yes| Want information of the mission.| +| label | string | Yes| Yes| Label of the mission.| +| iconPath | string | Yes| Yes| Path of the mission icon.| +| continuable | boolean | Yes| Yes| Whether the mission can be continued on another device.| + +**Example** +```ts +import missionManager from '@ohos.application.missionManager' + +missionManager.getMissionInfo("12345", 1, (error, data) => { + console.info('getMissionInfo missionId is:' + JSON.stringify(data.missionId)); + console.info('getMissionInfo runningState is:' + JSON.stringify(data.runningState)); + console.info('getMissionInfo lockedState is:' + JSON.stringify(data.lockedState)); + console.info('getMissionInfo timestamp is:' + JSON.stringify(data.timestamp)); + console.info('getMissionInfo want is:' + JSON.stringify(data.want)); + console.info('getMissionInfo label is:' + JSON.stringify(data.label)); + console.info('getMissionInfo iconPath is:' + JSON.stringify(data.iconPath)); + console.info('getMissionInfo continuable is:' + JSON.stringify(data.continuable)); +}); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-missionListener.md b/en/application-dev/reference/apis/js-apis-inner-application-missionListener.md new file mode 100644 index 0000000000000000000000000000000000000000..1070334b0107b3e3e84101a287b7966f7e16dcff --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionListener.md @@ -0,0 +1,42 @@ +# MissionListener + +The **MissionListener** module defines the listeners used to observe the mission status. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Mandatory| Description | +| ----------- | -------- | ---- | ------------------------------------------------------------ | +| onMissionCreated | function | No | Called when the system creates a mission. | +| onMissionDestroyed | function | No | Called when the system destroys the mission.| +| onMissionSnapshotChanged | function | No | Called when the system updates the mission snapshot.| +| onMissionMovedToFront | function | No | Called when the system moves the mission to the foreground.| +| onMissionLabelUpdated | function | No | Called when the system updates the mission label.| +| onMissionIconUpdated | function | No | Called when the system updates the mission icon.| +| onMissionClosed | function | No | Called when the system closes the mission.| + +**Example** +```ts +import missionManager from '@ohos.application.missionManager' + +let listener = { + onMissionCreated: function (mission) { + console.log("onMissionCreated mission: " + JSON.stringify(mission)); + }, + onMissionDestroyed: function (mission) { + console.log("onMissionDestroyed mission: " + JSON.stringify(mission)); + }, + onMissionSnapshotChanged: function (mission) { + console.log("onMissionSnapshotChanged mission: " + JSON.stringify(mission)); + }, + onMissionMovedToFront: function (mission) { + console.log("onMissionMovedToFront mission: " + JSON.stringify(mission)); + }, + onMissionIconUpdated: function (mission, icon) { + console.log("onMissionIconUpdated mission: " + JSON.stringify(mission)); + }, + onMissionClosed: function (mission) { + console.log("onMissionClosed mission: " + JSON.stringify(mission)); + } +}; +let listenerid = missionManager.registerMissionListener(listener); +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-application-missionParameter.md b/en/application-dev/reference/apis/js-apis-inner-application-missionParameter.md new file mode 100644 index 0000000000000000000000000000000000000000..5dc8a425524082102b4a554e7b911a1e7a490e8b --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionParameter.md @@ -0,0 +1,31 @@ +# MissionParameter + +The **MissionParameter** module defines the parameters required for mission synchronization. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name | Type | Readable | Writable | Description | +| ----------- | ------- | ---- | ---- | ----------- | +| deviceId | string | Yes | Yes | Device ID. | +| fixConflict | boolean | Yes | Yes | Whether a version conflict occurs.| +| tag | number | Yes | Yes | Tag of the mission. | + +**Example** +```ts +import distributedMissionManager from '@ohos.distributedMissionManager'; + +let missionParameter = { + deviceId: "123456", + fixConflict: true, + tag: 123 +}; +try { + distributedMissionManager.startSyncRemoteMissions(missionParameter, + (err, data) => { + console.log("startSyncRemoteMissions, data: " + JSON.stringify(data)); + } + ); +} catch (err) { + console.error('startSyncRemoteMissions fail: ' + JSON.stringify(err)); +} +``` diff --git a/en/application-dev/reference/apis/js-apis-application-MissionSnapshot.md b/en/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md similarity index 95% rename from en/application-dev/reference/apis/js-apis-application-MissionSnapshot.md rename to en/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md index 45024751e4460258a696e7f7e883e84fb93d73c2..bac1c9f6c38951f0ba4f5ab25a7e07d7a9441dcd 100644 --- a/en/application-dev/reference/apis/js-apis-application-MissionSnapshot.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md @@ -7,11 +7,19 @@ The **MissionSnapshot** module provides the mission snapshot information of an a > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module are system APIs and cannot be called by third-party applications. -## Usage +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| ability | ElementName | Yes| Yes| Information that matches an ability.| +| snapshot | [image.PixelMap](js-apis-image.md) | Yes| Yes| Snapshot of the mission.| + +## How to Use The mission snapshot information can be obtained by using **getMissionSnapShot** in **missionManager**. -```js +**Example** +```ts import ElementName from '@ohos.bundle'; import image from '@ohos.multimedia.image'; import missionManager from '@ohos.application.missionManager'; @@ -28,13 +36,3 @@ missionManager.getMissionInfos("", 10, (error, missions) => { }) }) ``` -## MissionSnapshot - -Describes the mission snapshot. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Mission - -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| ability | ElementName | Yes| Yes| Information that matches an ability.| -| snapshot | [image.PixelMap](js-apis-image.md) | Yes| Yes| Snapshot of the mission.| diff --git a/en/application-dev/reference/apis/js-apis-permissionrequestresult.md b/en/application-dev/reference/apis/js-apis-inner-application-permissionRequestResult.md similarity index 97% rename from en/application-dev/reference/apis/js-apis-permissionrequestresult.md rename to en/application-dev/reference/apis/js-apis-inner-application-permissionRequestResult.md index b397ba221d3d570e3b5eca2f551ecee228bdfc35..7a415835191f7d66bdbd7d433df150d52c3d88ac 100644 --- a/en/application-dev/reference/apis/js-apis-permissionrequestresult.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-permissionRequestResult.md @@ -7,11 +7,21 @@ The **PermissionRequestResult** module provides the result of a permission reque > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. > The APIs of this module can be used only in the stage model. -## Usage +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + + | Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| permissions | Array<string> | Yes| No| Permissions requested.| +| authResults | Array<number> | Yes| No| Whether the requested permissions are granted or denied. The value **0** means that the requests permissions are granted, and a non-zero value means the opposite. | + +## How to Use The permission request result is obtained through an **AbilityStage** instance. -```js +**Example** +```ts import Ability from '@ohos.application.Ability' export default class MainAbility extends Ability { onWindowStageCreate(windowStage) { @@ -28,13 +38,3 @@ export default class MainAbility extends Ability { } } ``` - - -## Attributes - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - - | Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| permissions | Array<string> | Yes| No| Permissions requested.| -| authResults | Array<number> | Yes| No| Whether the requested permissions are granted or denied. The value **0** means that the requests permissions are granted, and a non-zero value means the opposite. | diff --git a/en/application-dev/reference/apis/js-apis-inner-application-processData.md b/en/application-dev/reference/apis/js-apis-inner-application-processData.md new file mode 100644 index 0000000000000000000000000000000000000000..75d7312c7144f725e0d47e6aed6e3bc594ce3989 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-processData.md @@ -0,0 +1,43 @@ +# ProcessData + +The **ProcessData** module defines process data. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +| Name | Type | Readable| Writable| Description | +| ----------------------- | ---------| ---- | ---- | ------------------------- | +| pid8+ | number | Yes | No | Process ID. | +| bundleName8+ | string | Yes | No | Bundle name of the application. | +| uid8+ | number | Yes | No | User ID. | +| isContinuousTask9+ | boolean | Yes | No | Whether the process is a continuous task. | +| isKeepAlive9+ | boolean | Yes | No | Whether the process remains active. | + +**Example** +```ts +import appManager from '@ohos.application.appManager' + +let applicationStateObserver = { + onForegroundApplicationChanged(appStateData) { + console.log('onForegroundApplicationChanged appStateData: ' + JSON.stringify(appStateData)); + }, + onAbilityStateChanged(abilityStateData) { + console.log('onAbilityStateChanged onAbilityStateChanged: ' + JSON.stringify(abilityStateData)); + }, + onProcessCreated(processData) { + console.log('onProcessCreated onProcessCreated: ' + JSON.stringify(processData)); + }, + onProcessDied(processData) { + console.log('onProcessDied onProcessDied: ' + JSON.stringify(processData)); + }, + onProcessStateChanged(processData) { + console.log('onProcessStateChanged processData.pid : ' + JSON.stringify(processData.pid)); + console.log('onProcessStateChanged processData.bundleName : ' + JSON.stringify(processData.bundleName)); + console.log('onProcessStateChanged processData.uid : ' + JSON.stringify(processData.uid)); + console.log('onProcessStateChanged processData.isContinuousTask : ' + JSON.stringify(processData.isContinuousTask)); + console.log('onProcessStateChanged processData.isKeepAlive : ' + JSON.stringify(processData.isKeepAlive)); + } +} +let observerCode = appManager.registerApplicationStateObserver(applicationStateObserver); +``` diff --git a/en/application-dev/reference/apis/js-apis-processrunninginfo.md b/en/application-dev/reference/apis/js-apis-inner-application-processRunningInfo.md similarity index 55% rename from en/application-dev/reference/apis/js-apis-processrunninginfo.md rename to en/application-dev/reference/apis/js-apis-inner-application-processRunningInfo.md index dfed42e70b0c506124341952c1fa5c8b724299c1..8534ed198099f17a00769d2627349752a38aef62 100644 --- a/en/application-dev/reference/apis/js-apis-processrunninginfo.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-processRunningInfo.md @@ -1,16 +1,28 @@ -# ProcessRunningInfo(deprecated) +# ProcessRunningInfo The **ProcessRunningInfo** module provides process running information. > **NOTE** -> - The APIs provided by this module are deprecated since API version 9. You are advised to use [ProcessRunningInformation9+](js-apis-processrunninginformation.md) instead. +> - The APIs provided by this module are deprecated since API version 9. You are advised to use [ProcessRunningInformation9+](js-apis-inner-application-processRunningInformation.md) instead. > - The initial APIs of this module are supported since API version 8. +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Mission + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| pid | number | Yes| No| Process ID.| +| uid | number | Yes| No| User ID.| +| processName | string | Yes| No| Process name.| +| bundleNames | Array<string> | Yes| No| Names of all running bundles in the process.| + ## Usage -The process running information is obtained by using [getProcessRunningInfos](js-apis-appmanager.md#appmanagergetprocessrunninginfosdeprecated) in **appManager**. +The process running information is obtained through [getProcessRunningInfos](js-apis-application-appManager.md##appManager.getProcessRunningInfos(deprecated)). -```js +**Example** +```ts import appManager from '@ohos.application.appManager'; app.getProcessRunningInfos().then((data) => { console.log('success:' + JSON.stringify(data)); @@ -18,14 +30,3 @@ app.getProcessRunningInfos().then((data) => { console.log('failed:' + JSON.stringify(error)); }); ``` - -## Attributes - -**System capability**: SystemCapability.Ability.AbilityRuntime.Mission - -| Name| Type| Readable| Writable| Description| -| -------- | -------- | -------- | -------- | -------- | -| pid | number | Yes| No| Process ID.| -| uid | number | Yes| No| User ID.| -| processName | string | Yes| No| Process name.| -| bundleNames | Array<string> | Yes| No| Names of all bundles running in the process.| diff --git a/en/application-dev/reference/apis/js-apis-processrunninginformation.md b/en/application-dev/reference/apis/js-apis-inner-application-processRunningInformation.md similarity index 87% rename from en/application-dev/reference/apis/js-apis-processrunninginformation.md rename to en/application-dev/reference/apis/js-apis-inner-application-processRunningInformation.md index a5add77380e1a9173f9d1d1b1e44b2dfee5be38c..bae1a6f2761c1f8de4873875d0578819a43ddea2 100644 --- a/en/application-dev/reference/apis/js-apis-processrunninginformation.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-processRunningInformation.md @@ -1,4 +1,4 @@ -# ProcessRunningInformation9+ +# ProcessRunningInformation The **ProcessRunningInformation** module provides process running information. @@ -6,11 +6,11 @@ The **ProcessRunningInformation** module provides process running information. > > The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. -## Usage Guidelines +## How to Use -The process running information is obtained through [appManager](js-apis-appmanager.md#appmanagergetprocessrunninginformation9). +The process running information is obtained through [appManager](js-apis-application-appManager.md#appmanagergetprocessrunninginformation9). -```js +```ts import appManager from '@ohos.application.appManager'; appManager.getProcessRunningInformation((error,data) => { console.log("getProcessRunningInformation error: " + error.code + " data: " + JSON.stringify(data)); diff --git a/en/application-dev/reference/apis/js-apis-service-extension-context.md b/en/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md similarity index 69% rename from en/application-dev/reference/apis/js-apis-service-extension-context.md rename to en/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md index e2af193a5c0e62c9c5081589243d0615669a51d5..bfe660ebd6d4f0fb64a0380a3fee7b2470e9a3b3 100644 --- a/en/application-dev/reference/apis/js-apis-service-extension-context.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md @@ -38,15 +38,32 @@ Starts an ability. This API uses an asynchronous callback to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + | want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -88,8 +105,8 @@ Starts an ability. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| - | options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| + | want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| + | options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| **Return value** @@ -101,8 +118,25 @@ Starts an ability. This API uses a promise to return the result. | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -147,16 +181,33 @@ Starts an ability with the start options specified. This API uses an asynchronou | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -202,7 +253,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -210,8 +261,26 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -255,17 +324,35 @@ Starts an ability with the account ID and start options specified. This API uses | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | Yes| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -313,9 +400,9 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-application-StartOptions.md) | No| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| **Return value** @@ -327,8 +414,26 @@ Starts an ability with the account ID specified. This API uses a promise to retu | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -375,15 +480,25 @@ Starts a new Service Extension ability. This API uses an asynchronous callback t | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -426,7 +541,7 @@ Starts a new Service Extension ability. This API uses a promise to return the re | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| **Return value** @@ -438,8 +553,18 @@ Starts a new Service Extension ability. This API uses a promise to return the re | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -484,7 +609,7 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -492,8 +617,19 @@ Starts a new Service Extension ability with the account ID specified. This API u | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -540,7 +676,7 @@ Starts a new Service Extension ability with the account ID specified. This API u | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Return value** @@ -553,8 +689,19 @@ Starts a new Service Extension ability with the account ID specified. This API u | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -598,15 +745,22 @@ Stops a Service Extension ability in the same application. This API uses an asyn | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -649,7 +803,7 @@ Stops a Service Extension ability in the same application. This API uses a promi | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| **Return value** @@ -661,8 +815,15 @@ Stops a Service Extension ability in the same application. This API uses a promi | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -707,7 +868,7 @@ Stops a Service Extension ability in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -715,8 +876,16 @@ Stops a Service Extension ability in the same application with the account ID sp | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -762,7 +931,7 @@ Stops a Service Extension ability in the same application with the account ID sp | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Return value** @@ -775,8 +944,16 @@ Stops a Service Extension ability in the same application with the account ID sp | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | **Example** @@ -820,14 +997,18 @@ Terminates this ability. This API uses an asynchronous callback to return the re | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -864,8 +1045,12 @@ Terminates this ability. This API uses a promise to return the result. | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -894,8 +1079,8 @@ Connects this ability to a Service ability. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| - | options | [ConnectOptions](js-apis-featureAbility.md#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.| + | want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability, such as the ability name and bundle name.| + | options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.| **Return value** @@ -907,8 +1092,13 @@ Connects this ability to a Service ability. | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -947,9 +1137,9 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | ConnectOptions | Yes| Remote object instance.| +| options | ConnectOptions | No| Remote object instance.| **Return value** @@ -961,8 +1151,14 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -1004,14 +1200,18 @@ Disconnects this ability from the Service ability. This API uses an asynchronous | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | | connection | number | Yes| Number returned after **connectAbility** is called.| - | callback | AsyncCallback<void> | Yes| Callback used to return the result.| + | callback | AsyncCallback<void> | No| Callback used to return the result.| **Error codes** | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000003 | Input error. The specified id does not exist. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -1063,8 +1263,12 @@ Disconnects this ability from the Service ability. This API uses a promise to re | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000003 | Input error. The specified id does not exist. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | **Example** @@ -1104,7 +1308,7 @@ Starts an ability in the foreground or background and obtains the caller object | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-Want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| +| want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| **Return value** @@ -1116,8 +1320,15 @@ Starts an ability in the foreground or background and obtains the caller object | ID| Error Message| | ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | | 401 | Invalid input parameter. | -| Other IDs| See [Ability Error Codes](../errorcodes/errorcode-ability.md).| +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000050 | Internal Error. | **Example** @@ -1185,4 +1396,3 @@ Starts an ability in the foreground or background and obtains the caller object ' error.message: ' + JSON.stringify(paramError.message)); } ``` - diff --git a/en/application-dev/reference/apis/js-apis-application-shellCmdResult.md b/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md similarity index 79% rename from en/application-dev/reference/apis/js-apis-application-shellCmdResult.md rename to en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md index 7f9e03d201873f689838a4a53c7519ec566b990d..23c4e8d48a1b3755c829c1a9e775a1eb9bdba908 100644 --- a/en/application-dev/reference/apis/js-apis-application-shellCmdResult.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md @@ -6,11 +6,19 @@ The **ShellCmdResult** module provides the shell command execution result. > > The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Readable| Writable| Description | +| --------- | ------ | ---- | ---- | ------------------------------------------------------------ | +| stdResult | string | Yes | Yes | Standard output content.| +| exitCode | number | Yes | Yes | Result code.| + ## Usage -The result is obtained by calling [executeShellCommand](js-apis-application-abilityDelegator.md#executeshellcommand) in **abilityDelegator**. +The result is obtained by calling [executeShellCommand](js-apis-inner-application-abilityDelegator.md#executeshellcommand) in **abilityDelegator**. -```js +**Example** +```ts import AbilityDelegatorRegistry from "@ohos.application.abilityDelegatorRegistry"; let abilityDelegator; let cmd = "cmd"; @@ -21,14 +29,3 @@ abilityDelegator.executeShellCommand(cmd, (err: any, data: any) => { console.info("executeShellCommand callback, success: ", data); }); ``` - -## ShellCmdResult - -Describes the shell command execution result. - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Type | Readable| Writable| Description | -| --------- | ------ | ---- | ---- | ------------------------------------------------------------ | -| stdResult | string | Yes | Yes | Standard output content. | -| exitCode | number | Yes | Yes | Result code. | diff --git a/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md b/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md new file mode 100644 index 0000000000000000000000000000000000000000..394f484144b3cf2f5fdf071ea22e2a38fe652739 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md @@ -0,0 +1,2164 @@ +# UIAbilityContext + +The **UIAbilityContext** module, inherited from **Context**, implements the context for abilities. + +This module provides APIs for accessing ability-specific resources. You can use the APIs to start and terminate an ability, obtain the caller interface, and request permissions from users by displaying a dialog box. + +> **NOTE** +> +> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> - The APIs of this module can be used only in the stage model. + +## Attributes + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | Yes| No| Ability information.| +| currentHapModuleInfo | [HapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) | Yes| No| Information about the current HAP.| +| config | [Configuration](js-apis-app-ability-configuration.md) | Yes| No| Configuration information.| + +## AbilityContext.startAbility + +startAbility(want: Want, callback: AsyncCallback<void>): void; + +Starts an ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + bundleName: "com.example.myapp", + abilityName: "MyAbility" + }; + + try { + this.context.startAbility(want, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startAbility succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbility + +startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; + +Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var options = { + windowMode: 0 + }; + + try { + this.context.startAbility(want, options, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startAbility succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startAbility + +startAbility(want: Want, options?: StartOptions): Promise<void>; + +Starts an ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + bundleName: "com.example.myapp", + abilityName: "MyAbility" + }; + var options = { + windowMode: 0, + }; + + try { + this.context.startAbility(want, options) + .then((data) => { + // Carry out normal service processing. + console.log('startAbility succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityForResult + +startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; + +Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + + try { + this.context.startAbilityForResult(want, (error, result) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log("startAbilityForResult succeed, result.resultCode = " + + result.resultCode) + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startAbilityForResult + +startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; + +Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var options = { + windowMode: 0, + }; + + try { + this.context.startAbilityForResult(want, options, (error, result) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log("startAbilityForResult succeed, result.resultCode = " + + result.resultCode) + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityForResult + +startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; + +Starts an ability. This API uses a promise to return the result when the ability is terminated. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| + + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + bundleName: "com.example.myapp", + abilityName: "MyAbility" + }; + var options = { + windowMode: 0, + }; + + try { + this.context.startAbilityForResult(want, options) + .then((result) => { + // Carry out normal service processing. + console.log("startAbilityForResult succeed, result.resultCode = " + result.resultCode); + }) + .catch((error) => { + // Process service logic errors. + console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startAbilityForResultWithAccount + +startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Starts an ability. This API uses an asynchronous callback to return the result when the account of the ability is destroyed. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.startAbilityForResultWithAccount(want, accountId, (error, result) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log("startAbilityForResultWithAccount succeed, result.resultCode = " + + result.resultCode) + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityForResultWithAccount + +startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void; + +Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the account of the ability is destroyed. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + var options = { + windowMode: 0 + }; + + try { + this.context.startAbilityForResultWithAccount(want, accountId, options, (error, result) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log("startAbilityForResultWithAccount succeed, result.resultCode = " + + result.resultCode) + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityForResultWithAccount + +startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; + +Starts an ability with the start options specified. This API uses a promise to return the result when the account of the ability is destroyed. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<AbilityResult> | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + var options = { + windowMode: 0 + }; + + try { + this.context.startAbilityForResultWithAccount(want, accountId, options) + .then((result) => { + // Carry out normal service processing. + console.log("startAbilityForResultWithAccount succeed, result.resultCode = " + + result.resultCode) + }) + .catch((error) => { + // Process service logic errors. + console.log('startAbilityForResultWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` +## AbilityContext.startServiceExtensionAbility + +startServiceExtensionAbility(want: Want, callback: AsyncCallback\): void; + +Starts a new Service Extension ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + + try { + this.context.startServiceExtensionAbility(want, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startServiceExtensionAbility succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startServiceExtensionAbility + +startServiceExtensionAbility(want: Want): Promise\; + +Starts a new Service Extension ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + + try { + this.context.startServiceExtensionAbility(want) + .then((data) => { + // Carry out normal service processing. + console.log('startServiceExtensionAbility succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('startServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startServiceExtensionAbilityWithAccount + +startServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Starts a new Service Extension ability with the account ID specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.startServiceExtensionAbilityWithAccount(want, accountId, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startServiceExtensionAbilityWithAccount succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startServiceExtensionAbilityWithAccount + +startServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\; + +Starts a new Service Extension ability with the account ID specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.startServiceExtensionAbilityWithAccount(want, accountId) + .then((data) => { + // Carry out normal service processing. + console.log('startServiceExtensionAbilityWithAccount succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('startServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` +## AbilityContext.stopServiceExtensionAbility + +stopServiceExtensionAbility(want: Want, callback: AsyncCallback\): void; + +Stops a Service Extension ability in the same application. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + + try { + this.context.stopServiceExtensionAbility(want, (error) => { + if (error.code) { + // Process service logic errors. + console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('stopServiceExtensionAbility succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.stopServiceExtensionAbility + +stopServiceExtensionAbility(want: Want): Promise\; + +Stops a Service Extension ability in the same application. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + + try { + this.context.stopServiceExtensionAbility(want) + .then((data) => { + // Carry out normal service processing. + console.log('stopServiceExtensionAbility succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('stopServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.stopServiceExtensionAbilityWithAccount + +stopServiceExtensionAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Stops a Service Extension ability in the same application with the account ID specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.stopServiceExtensionAbilityWithAccount(want, accountId, (error) => { + if (error.code) { + // Process service logic errors. + console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('stopServiceExtensionAbilityWithAccount succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.stopServiceExtensionAbilityWithAccount + +stopServiceExtensionAbilityWithAccount(want: Want, accountId: number): Promise\; + +Stops a Service Extension ability in the same application with the account ID specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.stopServiceExtensionAbilityWithAccount(want, accountId) + .then((data) => { + // Carry out normal service processing. + console.log('stopServiceExtensionAbilityWithAccount succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('stopServiceExtensionAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.terminateSelf + +terminateSelf(callback: AsyncCallback<void>): void; + +Terminates this ability. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + this.context.terminateSelf((error) => { + if (error.code) { + // Process service logic errors. + console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('terminateSelf succeed'); + }); + ``` + + +## AbilityContext.terminateSelf + +terminateSelf(): Promise<void>; + +Terminates this ability. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + this.context.terminateSelf().then((data) => { + // Carry out normal service processing. + console.log('terminateSelf succeed'); + }).catch((error) => { + // Process service logic errors. + console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + ``` + + +## AbilityContext.terminateSelfWithResult + +terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; + +Terminates this ability. This API uses an asynchronous callback to return the ability result information. It is used together with **startAbilityForResult**. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + bundleName: "com.extreme.myapplication", + abilityName: "SecondAbility" + } + var resultCode = 100; + // AbilityResult information returned to the caller. + var abilityResult = { + want, + resultCode + } + + try { + this.context.terminateSelfWithResult(abilityResult, (error) => { + if (error.code) { + // Process service logic errors. + console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('terminateSelfWithResult succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.terminateSelfWithResult + +terminateSelfWithResult(parameter: AbilityResult): Promise<void>; + +Terminates this ability. This API uses a promise to return the ability result information. It is used together with **startAbilityForResult**. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + + +**Example** + + ```ts + var want = { + bundleName: "com.extreme.myapplication", + abilityName: "SecondAbility" + } + var resultCode = 100; + // AbilityResult information returned to the caller. + var abilityResult = { + want, + resultCode + } + + try { + this.context.terminateSelfWithResult(abilityResult) + .then((data) => { + // Carry out normal service processing. + console.log('terminateSelfWithResult succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.connectServiceExtensionAbility + +connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; + +Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to another ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No| Parameters for the connection.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | Result code of the ability connection.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var options = { + onConnect(elementName, remote) { console.log('----------- onConnect -----------') }, + onDisconnect(elementName) { console.log('----------- onDisconnect -----------') }, + onFailed(code) { console.log('----------- onFailed -----------') } + } + + var connection = null; + try { + connection = this.context.connectServiceExtensionAbility(want, options); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.connectServiceExtensionAbilityWithAccount + +connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number; + +Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect this ability to another ability with the account ID specified. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No| Parameters for the connection.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| number | Result code of the ability connection.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000002 | Ability type error. The specified ability type is wrong. | +| 16000004 | Visibility verification failed. | +| 16000006 | Can not cross user operations. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + var options = { + onConnect(elementName, remote) { console.log('----------- onConnect -----------') }, + onDisconnect(elementName) { console.log('----------- onDisconnect -----------') }, + onFailed(code) { console.log('----------- onFailed -----------') } + } + + var connection = null; + try { + connection = this.context.connectServiceExtensionAbilityWithAccount(want, accountId, options); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.disconnectServiceExtensionAbility + +disconnectServiceExtensionAbility(connection: number): Promise\; + +Disconnects a connection. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| connection | number | Yes| Result code of the ability connection.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise\ | Promise used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000003 | Input error. The specified id does not exist. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + // connection is the return value of connectServiceExtensionAbility. + var connection = 1; + + try { + this.context.disconnectServiceExtensionAbility(connection) + .then((data) => { + // Carry out normal service processing. + console.log('disconnectServiceExtensionAbility succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.disconnectServiceExtensionAbility + +disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback\): void; + +Disconnects a connection. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| connection | number | Yes| Result code of the ability connection.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000003 | Input error. The specified id does not exist. | +| 16000011 | Context does not exist. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + // connection is the return value of connectServiceExtensionAbility. + var connection = 1; + + try { + this.context.disconnectServiceExtensionAbility(connection, (error) => { + if (error.code) { + // Process service logic errors. + console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('disconnectServiceExtensionAbility succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startAbilityByCall + +startAbilityByCall(want: Want): Promise<Caller>; + +Starts an ability in the foreground or background and obtains the caller object for communicating with the ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<Caller> | Promise used to return the caller object to communicate with.| + +**Example** + + Start an ability in the background. + + ```ts + var caller = undefined; + + // Start an ability in the background by not passing parameters. + var wantBackground = { + bundleName: "com.example.myservice", + moduleName: "entry", + abilityName: "MainAbility", + deviceId: "" + }; + + try { + this.context.startAbilityByCall(wantBackground) + .then((obj) => { + // Carry out normal service processing. + caller = obj; + console.log('startAbilityByCall succeed'); + }).catch((error) => { + // Process service logic errors. + console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + Start an ability in the foreground. + + ```ts + var caller = undefined; + + // Start an ability in the foreground with ohos.aafwk.param.callAbilityToForeground in parameters set to true. + var wantForeground = { + bundleName: "com.example.myservice", + moduleName: "entry", + abilityName: "MainAbility", + deviceId: "", + parameters: { + "ohos.aafwk.param.callAbilityToForeground": true + } + }; + + try { + this.context.startAbilityByCall(wantForeground) + .then((obj) => { + // Carry out normal service processing. + caller = obj; + console.log('startAbilityByCall succeed'); + }).catch((error) => { + // Process service logic errors. + console.log('startAbilityByCall failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; + +Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + + try { + this.context.startAbilityWithAccount(want, accountId, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startAbilityWithAccount succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void; + +Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + var options = { + windowMode: 0 + }; + + try { + this.context.startAbilityWithAccount(want, accountId, options, (error) => { + if (error.code) { + // Process service logic errors. + console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + return; + } + // Carry out normal service processing. + console.log('startAbilityWithAccount succeed'); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + + +## AbilityContext.startAbilityWithAccount + +startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; + +Starts an ability with the account ID specified. This API uses a promise to return the result. + +**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| + +**Error codes** + +| ID| Error Message| +| ------- | -------------------------------- | +| 201 | The application does not have permission to call the interface. | +| 401 | Invalid input parameter. | +| 16000001 | Input error. The specified ability name does not exist. | +| 16000004 | Visibility verification failed. | +| 16000005 | Static permission denied. The specified process does not have the permission. | +| 16000006 | Can not cross user operations. | +| 16000007 | Service busyness. There are concurrent tasks, waiting for retry. | +| 16000008 | Crowdtest App Expiration. | +| 16000009 | Can not start ability in wukong mode. | +| 16000010 | Can not operation with continue flag. | +| 16000011 | Context does not exist. | +| 16000051 | Network error. The network is abnormal. | +| 16000052 | Free install not support. The application does not support freeinstall | +| 16000053 | Not top ability. The application is not top ability. | +| 16000054 | Free install busyness. There are concurrent tasks, waiting for retry. | +| 16000055 | Free install timeout. | +| 16000056 | Can not free install other ability. | +| 16000057 | Not support cross device free install. | +| 16200001 | Caller released. The caller has been released. | +| 16000050 | Internal Error. | + +**Example** + + ```ts + var want = { + deviceId: "", + bundleName: "com.extreme.test", + abilityName: "MainAbility" + }; + var accountId = 100; + var options = { + windowMode: 0 + }; + + try { + this.context.startAbilityWithAccount(want, accountId, options) + .then((data) => { + // Carry out normal service processing. + console.log('startAbilityWithAccount succeed'); + }) + .catch((error) => { + // Process service logic errors. + console.log('startAbilityWithAccount failed, error.code: ' + JSON.stringify(error.code) + + ' error.message: ' + JSON.stringify(error.message)); + }); + } catch (paramError) { + // Process input parameter errors. + console.log('error.code: ' + JSON.stringify(paramError.code) + + ' error.message: ' + JSON.stringify(paramError.message)); + } + ``` + +## AbilityContext.requestPermissionsFromUser + +requestPermissionsFromUser(permissions: Array<string>, requestCallback: AsyncCallback<PermissionRequestResult>) : void; + +Requests permissions from the user by displaying a dialog box. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| permissions | Array<string> | Yes| Permissions to request.| +| callback | AsyncCallback<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Yes| Callback used to return the result.| + +**Example** + + ```ts + var permissions=['com.example.permission'] + this.context.requestPermissionsFromUser(permissions,(result) => { + console.log('requestPermissionsFromUserresult:' + JSON.stringify(result)); + }); + + ``` + + +## AbilityContext.requestPermissionsFromUser + +requestPermissionsFromUser(permissions: Array<string>) : Promise<PermissionRequestResult>; + +Requests permissions from the user by displaying a dialog box. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| permissions | Array<string> | Yes| Permissions to request.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Promise used to return the result.| + +**Example** + + ```ts + var permissions=['com.example.permission'] + this.context.requestPermissionsFromUser(permissions).then((data) => { + console.log('success:' + JSON.stringify(data)); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + + ``` + + +## AbilityContext.setMissionLabel + +setMissionLabel(label: string, callback:AsyncCallback<void>): void; + +Sets a label for this ability in the mission. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| label | string | Yes| Label of the ability to set.| +| callback | AsyncCallback<void> | Yes| Callback used to return the result.| + +**Example** + + ```ts + this.context.setMissionLabel("test",(result) => { + console.log('requestPermissionsFromUserresult:' + JSON.stringify(result)); + }); + ``` + + +## AbilityContext.setMissionLabel + +setMissionLabel(label: string): Promise<void>; + +Sets a label for this ability in the mission. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| label | string | Yes| Label of the ability to set.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + this.context.setMissionLabel("test").then(() => { + console.log('success'); + }).catch((error) => { + console.log('failed:' + JSON.stringify(error)); + }); + ``` +## AbilityContext.setMissionIcon + +setMissionIcon(icon: image.PixelMap, callback:AsyncCallback\): void; + +Sets an icon for this ability in the mission. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| icon | image.PixelMap | Yes| Icon of the ability to set.| +| callback | AsyncCallback\ | Yes| Callback used to return the result.| + +**Example** + + ```ts + import image from '@ohos.multimedia.image'; + var imagePixelMap; + var color = new ArrayBuffer(0); + var initializationOptions = { + size: { + height: 100, + width: 100 + } + }; + image.createPixelMap(color, initializationOptions) + .then((data) => { + imagePixelMap = data; + }) + .catch((err) => { + console.log('--------- createPixelMap fail, err: ---------', err) + }); + this.context.setMissionIcon(imagePixelMap, (err) => { + console.log('---------- setMissionIcon fail, err: -----------', err); + }) + ``` + + +## AbilityContext.setMissionIcon + +setMissionIcon(icon: image.PixelMap): Promise\; + +Sets an icon for this ability in the mission. This API uses a promise to return the result. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**System API**: This is a system API and cannot be called by third-party applications. + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| icon | image.PixelMap | Yes| Icon of the ability to set.| + +**Return value** + +| Type| Description| +| -------- | -------- | +| Promise<void> | Promise used to return the result.| + +**Example** + + ```ts + import image from '@ohos.multimedia.image'; + var imagePixelMap; + var color = new ArrayBuffer(0); + var initializationOptions = { + size: { + height: 100, + width: 100 + } + }; + image.createPixelMap(color, initializationOptions) + .then((data) => { + imagePixelMap = data; + }) + .catch((err) => { + console.log('--------- createPixelMap fail, err: ---------', err) + }); + this.context.setMissionIcon(imagePixelMap) + .then(() => { + console.log('-------------- setMissionIcon success -------------'); + }) + .catch((err) => { + console.log('-------------- setMissionIcon fail, err: -------------', err); + }); + ``` +## AbilityContext.restoreWindowStage + +restoreWindowStage(localStorage: LocalStorage) : void; + +Restores the window stage data for this ability. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Parameters** + +| Name| Type| Mandatory| Description| +| -------- | -------- | -------- | -------- | +| localStorage | image.LocalStorage | Yes| Storage used to store the restored window stage.| + +**Example** + + ```ts + var storage = new LocalStorage(); + this.context.restoreWindowStage(storage); + ``` + +## AbilityContext.isTerminating + +isTerminating(): boolean; + +Checks whether this ability is in the terminating state. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +**Return value** + +| Type| Description| +| -------- | -------- | +| boolean| The value **true** means that the ability is in the terminating state, and **false** means the opposite.| + +**Example** + + ```ts + var isTerminating = this.context.isTerminating(); + console.log('ability state :' + isTerminating); + ``` diff --git a/en/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md b/en/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..e659a4d80e43f59f06bfe7a8357ab6675886fad6 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md @@ -0,0 +1,66 @@ +# TriggerInfo + +The **TriggerInfo** module defines the information required for triggering the WantAgent. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Mandatory| Description | +| ---------- | --- |-------------------- | ----------- | +| code | number | Yes | Result code.| +| want | Want | No | Want. | +| permission | string | No | Permission. | +| extraInfo | {[key: string]: any} | No | Extra information. | + +**Example** +```ts +import wantAgent from '@ohos.wantAgent'; + +let wantAgentInfo = { + wants: [ + { + deviceId: "", + bundleName: "com.example.apicoverhaptest", + abilityName: "com.example.apicoverhaptest.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true.true,false}", + parameters: { + myKey0: 2222 + } + } + ], + operationType: wantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG], + extraInfo:{ + "key": "value" + } +} + +let triggerInfo = { + code: 0, + want: { + deviceId: "", + bundleName: "com.example.apicoverhaptest", + abilityName: "com.example.apicoverhaptest.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true.true,false}", + parameters: { + myKey0: 2222 + } + }, + permission: "" + extraInfo:{ + "key": "value" + } +} + +wantAgent.trigger(wantAgentInfo, triggerInfo).then((data) =>{ + console.info("trigger data: " + JSON.stringify(data)); +}).catch((err) => { + console.error("trigger err: " + JSON.stringify(err)); +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md b/en/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md new file mode 100644 index 0000000000000000000000000000000000000000..6d93123f0ca73a7089b640f2f1cb98cc3df4308c --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md @@ -0,0 +1,46 @@ +# WantAgentInfo + +The **WantAgentInfo** module defines the information required for triggering the WantAgent. + +**System capability**: SystemCapability.Ability.AbilityRuntime.Core + +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------- | ---- | ---------------------- | +| wants | Array\ | Yes | Array of all **Want** objects. | +| operationType | wantAgent.OperationType | Yes | Operation type. | +| requestCode | number | Yes | Request code defined by the user.| +| wantAgentFlags | Array<[wantAgent.WantAgentFlags](js-apis-wantAgent.md#WantAgentFlags)> | No | Array of flags for using the **WantAgent** object. | +| extraInfo | {[key: string]: any} | No | Extra information. | + +**Example** +```ts +import wantAgent from '@ohos.wantAgent'; + +let wantAgentInfo = { + wants: [ + { + deviceId: "", + bundleName: "com.example.apicoverhaptest", + abilityName: "com.example.apicoverhaptest.MainAbility", + action: "action1", + entities: ["entity1"], + type: "MIMETYPE", + uri: "key={true.true,false}", + parameters: { + myKey0: 2222 + } + } + ], + operationType: wantAgent.OperationType.START_ABILITIES, + requestCode: 0, + wantAgentFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG], + extraInfo:{ + "key": "value" + } +} +wantAgent.getWantAgent(wantAgentInfo).then((data) =>{ + console.info("getWantAgent data: " + JSON.stringify(data)); +}).catch((err) => { + console.error("getWantAgent err: " + JSON.stringify(err)); +}) +``` diff --git a/en/application-dev/reference/apis/js-apis-net-sharing.md b/en/application-dev/reference/apis/js-apis-net-sharing.md deleted file mode 100644 index 23284aeb1715a3f8aed9ec7b2d79ad55d1408319..0000000000000000000000000000000000000000 --- a/en/application-dev/reference/apis/js-apis-net-sharing.md +++ /dev/null @@ -1,746 +0,0 @@ -# Network Sharing Management - -The Network Sharing Management module allows you to share your device's Internet connection with other connected devices by means of Wi-Fi hotspot, Bluetooth, and USB sharing. It also allows you to query the network sharing state and shared mobile data volume. - -> **NOTE** -> -> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. - -## Modules to Import - -```js -import sharing from '@ohos.net.sharing' -``` - -## sharing.isSharingSupported - -isSharingSupported(callback: AsyncCallback\): void - -Checks whether network sharing is supported. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that network sharing is supported, and **false** means the opposite.| - -**Example** - -```js -sharing.isSharingSupported((error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.isSharingSupported - -isSharingSupported(): Promise\ - -Checks whether network sharing is supported. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the result. The value **true** means that network sharing is supported, and **false** means the opposite.| - -**Example** - -```js -sharing.isSharingSupported().then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.isSharing - -isSharing(callback: AsyncCallback\): void - -Checks whether network sharing is in progress. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the result. The value **true** means that network sharing is in progress, and **false** means the opposite.| - -**Example** - -```js -sharing.isSharing((error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.isSharing - -isSharing(): Promise\ - -Checks whether network sharing is in progress. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the result. The value **true** means that network sharing is in progress, and **false** means the opposite.| - -**Example** - -```js -sharing.isSharing().then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.startSharing - -startSharing(type: SharingIfaceType, callback: AsyncCallback\): void - -Starts network sharing of a specified type. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.startSharing(SharingIfaceType.SHARING_WIFI, (error) => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.startSharing - -startSharing(type: SharingIfaceType): Promise\ - -Starts network sharing of a specified type. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.startSharing(SharingIfaceType.SHARING_WIFI).then(() => { - console.log("start wifi sharing successful"); -}).catch(error => { - console.log("start wifi sharing failed"); -}); -``` - -## sharing.stopSharing - -stopSharing(type: SharingIfaceType, callback: AsyncCallback\): void - -Stops network sharing of a specified type. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| -| callback | AsyncCallback\ | Yes | Callback used to return the result.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.stopSharing(SharingIfaceType.SHARING_WIFI, (error) => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.stopSharing - -stopSharing(type: SharingIfaceType): Promise\ - -Stops network sharing of a specified type. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the result.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.stopSharing(SharingIfaceType.SHARING_WIFI).then(() => { - console.log("stop wifi sharing successful"); -}).catch(error => { - console.log("stop wifi sharing failed"); -}); -``` - -## sharing.getStatsRxBytes - -getStatsRxBytes(callback: AsyncCallback\): void - -Obtains the volume of mobile data traffic received via network sharing. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsRxBytes((error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getStatsRxBytes - -getStatsRxBytes(): Promise\ - -Obtains the volume of mobile data traffic received via network sharing. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsRxBytes().then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.getStatsTxBytes - -getStatsTxBytes(callback: AsyncCallback\): void - -Obtains the volume of mobile data traffic sent via network sharing. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsTxBytes((error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getStatsTxBytes - -getStatsTxBytes(): Promise\ - -Obtains the volume of mobile data traffic sent via network sharing. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsTxBytes().then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.getStatsTotalBytes - -getStatsTotalBytes(callback: AsyncCallback\): void - -Obtains the volume of mobile data traffic sent and received via network sharing. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| callback | AsyncCallback\ | Yes | Callback used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsTotalBytes((error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getStatsTotalBytes - -getStatsTotalBytes(): Promise\ - -Obtains the volume of mobile data traffic sent and received via network sharing. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\ | Promise used to return the data volume, in KB.| - -**Example** - -```js -sharing.getStatsTotalBytes().then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.getSharingIfaces - -getSharingIfaces(state: SharingIfaceState, callback: AsyncCallback\>): void - -Obtains the names of NICs in the specified network sharing state. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| state | state: [SharingIfaceState](#sharingifacestate) | Yes | Network sharing state.| -| callback | AsyncCallback\> | Yes | Callback used to return an array of NIC names.| - -**Example** - -```js -import SharingIfaceState from '@ohos.net.sharing' -sharing.getSharingIfaces(SharingIfaceState.SHARING_NIC_CAN_SERVER, (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getSharingIfaces - -getSharingIfaces(state: SharingIfaceState): Promise\> - -Obtains the names of NICs in the specified network sharing state. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| state | state: [SharingIfaceState](#sharingifacestate) | Yes | Network sharing state.| - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\> | Promise used to return an array of NIC names.| - -**Example** - -```js -import SharingIfaceState from '@ohos.net.sharing' -sharing.getSharingIfaces(SharingIfaceState.SHARING_NIC_CAN_SERVER).then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.getSharingState - -getSharingState(type: SharingIfaceType, callback: AsyncCallback\): void - -Obtains the network sharing state of the specified type. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| -| callback | AsyncCallback\<[SharingIfaceState](#sharingifacestate)> | Yes | Callback used to return the network sharing state.| - -**Example** - -```js -import SharingIfaceState from '@ohos.net.sharing' -sharing.getSharingState(SharingIfaceType.SHARING_WIFI, (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getSharingState - -getSharingState(type: SharingIfaceType): Promise\ - -Obtains the network sharing state of the specified type. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\<[SharingIfaceState](#sharingifacestate)> | Promise used to return the network sharing state.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.getSharingIfaces(SharingIfaceType.SHARING_WIFI).then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## sharing.getSharableRegexes - -getSharableRegexes(type: SharingIfaceType, callback: AsyncCallback\>): void - -Obtains regular expressions of NICs of a specified type. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| -| callback | AsyncCallback\> | Yes | Callback used to return an array of regular expressions.| - -**Example** - -```js -import SharingIfaceState from '@ohos.net.sharing' -sharing.getSharingState(SharingIfaceType.SHARING_WIFI, (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## sharing.getSharableRegexes - -getSharableRegexes(type: SharingIfaceType): Promise\> - -Obtains regular expressions of NICs of a specified type. This API uses a promise to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | [SharingIfaceType](#sharingifacetype) | Yes | Sharing type. The value **0** means Wi-Fi hotspot sharing, **1** means USB sharing, and **2** means Bluetooth sharing.| - -**Return value** - -| Type | Description | -| --------------------------------- | ------------------------------------- | -| Promise\> | Promise used to return an array of regular expressions.| - -**Example** - -```js -import SharingIfaceType from '@ohos.net.sharing' -sharing.getSharableRegexes(SharingIfaceType.SHARING_WIFI).then(data => { - console.log(JSON.stringify(data)); -}).catch(error => { - console.log(JSON.stringify(error)); -}); -``` - -## on('sharingStateChange') - -on(type: 'sharingStateChange', callback: Callback\): void - -Subscribes to network sharing state changes. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | Yes | Event name.| -| callback | AsyncCallback\ | Yes | Callback used to return the network sharing state.| - -**Example** - -```js -sharing.on('sharingStateChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## off('sharingStateChange') - -off(type: 'sharingStateChange', callback?: Callback\): void - -Unsubscribes from network sharing state changes. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | Yes | Event name.| -| callback | AsyncCallback\ | No | Callback used for unsubscription.| - -**Example** - -```js -sharing.off('sharingStateChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## on('interfaceSharingStateChange') - -on(type: 'interfaceSharingStateChange', callback: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void - -Subscribes to network sharing state changes of a specified NIC. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | Yes | Event name.| -| callback | AsyncCallback\<{ type: [SharingIfaceType](#sharingifacetype), iface: string, state: SharingIfaceState(#sharingifacestate) }> | Yes | Callback invoked when the network sharing state of the specified NIC changes.| - -**Example** - -```js -sharing.on('interfaceSharingStateChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## off('interfaceSharingStateChange') - -off(type: 'interfaceSharingStateChange', callback?: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void - -Unsubscribes from network sharing status changes of a specified NIC. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | No | Event name.| -| callback | AsyncCallback\<{ type: [SharingIfaceType](#sharingifacetype), iface: string, state: SharingIfaceState(#sharingifacestate) }> | No | Callback used for unsubscription.| - -**Example** - -```js -sharing.off('interfaceSharingStateChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## on('sharingUpstreamChange') - -on(type: 'sharingUpstreamChange', callback: Callback\): void - -Subscribes to upstream network changes. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | Yes | Event name.| -| callback | AsyncCallback\ | Yes | Callback invoked when the upstream network changes.| - -**Example** - -```js -sharing.on('sharingUpstreamChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## off('sharingUpstreamChange') - -off(type: 'sharingUpstreamChange', callback?: Callback\): void - -Unsubscribes from upstream network changes. This API uses an asynchronous callback to return the result. - -**Required permissions**: ohos.permission.CONNECTIVITY_INTERNAL - -**System capability**: SystemCapability.Communication.NetManager.Core - -**Parameters** - -| Name | Type | Mandatory| Description | -| -------- | --------------------------------------- | ---- | ---------- | -| type | string | Yes | Event name.| -| callback | AsyncCallback\ | No | Callback used for unsubscription.| - -**Example** - -```js -sharing.off('sharingUpstreamChange', (error, data) => { - console.log(JSON.stringify(error)); - console.log(JSON.stringify(data)); -}); -``` - -## SharingIfaceState - -Enumerates the network sharing states of an NIC. - -**System capability**: SystemCapability.Communication.NetManager.Core - -| Name | Value | Description | -| ------------------------ | ---- | ---------------------- | -| SHARING_NIC_SERVING | 1 | Network sharing is in progress.| -| SHARING_NIC_CAN_SERVER | 2 | Network sharing is supported.| -| SHARING_NIC_ERROR | 3 | An error occurred during network sharing.| - -## SharingIfaceType - -Enumerates the network sharing types of an NIC. - -**System capability**: SystemCapability.Communication.NetManager.Core - -| Name | Value | Description | -| ------------------------ | ---- | ---------------------- | -| SHARING_WIFI | 0 | Wi-Fi hotspot sharing.| -| SHARING_USB | 1 | USB sharing.| -| SHARING_BLUETOOTH | 2 | Bluetooth sharing.| diff --git a/en/application-dev/reference/apis/js-apis-wantAgent.md b/en/application-dev/reference/apis/js-apis-wantAgent.md index 5421d20c5fc129c726f31deaae6610d2bdc28d2e..252dc45b802251e8cf0eb7493ce51ef917a5fa99 100644 --- a/en/application-dev/reference/apis/js-apis-wantAgent.md +++ b/en/application-dev/reference/apis/js-apis-wantAgent.md @@ -1,10 +1,10 @@ -# WantAgent +# @ohos.wantAgent The **WantAgent** module provides APIs for triggering, canceling, and comparing **WantAgent** objects. You can use the APIs to create a **WantAgent** object, and obtain the user ID, bundle name, and want information of the object. > **NOTE** > -> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. +> The APIs of this module are supported since API version 7 and deprecated since API version 9. You are advised to use [@ohos.app.ability.wantAgent](js-apis-app-ability-wantAgent.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version. ## Modules to Import @@ -22,10 +22,10 @@ Obtains a **WantAgent** object. This API uses an asynchronous callback to return **Parameters** -| Name | Readable| Writable | Type | Mandatory| Description | -| -------- | --- | ---- | -------------------------- | ---- | ----------------------- | -| info | Yes | No | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the **WantAgent** object.| +| Name | Type | Mandatory| Description | +| -------- | -------------------------- | ---- | ----------------------- | +| info | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain. | +| callback | AsyncCallback\ | Yes | Callback used to return the **WantAgent** object.| **Example** @@ -79,9 +79,9 @@ Obtains a **WantAgent** object. This API uses a promise to return the result. **Parameters** -| Name| Readable| Writable | Type | Mandatory| Description | -| ---- | --- | ---- | ------------- | ---- | ------------- | -| info | Yes | No | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain.| +| Name| Type | Mandatory| Description | +| ---- | ------------- | ---- | ------------- | +| info | WantAgentInfo | Yes | Information about the **WantAgent** object to obtain.| **Return value** @@ -140,10 +140,10 @@ Obtains the bundle name of a **WantAgent** object. This API uses an asynchronous **Parameters** -| Name | Readable| Writable | Type | Mandatory| Description | -| -------- | --- | ---- | ----------------------- | ---- | --------------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the bundle name.| +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | --------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the bundle name.| **Example** @@ -212,9 +212,9 @@ Obtains the bundle name of a **WantAgent** object. This API uses a promise to re **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ----- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| **Return value** @@ -281,10 +281,10 @@ Obtains the user ID of a **WantAgent** object. This API uses an asynchronous cal **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| -------- | --- | ---- | ----------------------- | ---- | ----------------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the user ID.| +| Name | Type | Mandatory| Description | +| -------- | ----------------------- | ---- | ----------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the user ID.| **Example** @@ -353,9 +353,9 @@ Obtains the user ID of a **WantAgent** object. This API uses a promise to return **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ----- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| **Return value** @@ -424,10 +424,10 @@ Obtains the want in a **WantAgent** object. This API uses an asynchronous callba **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| -------- | --- | ---- | --------------------- | ---- | ------------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the want.| +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | ------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the want.| **Example** @@ -498,9 +498,9 @@ Obtains the want in a **WantAgent** object. This API uses a promise to return th **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ----- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| **Return value** @@ -567,10 +567,10 @@ Cancels a **WantAgent** object. This API uses an asynchronous callback to return **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| -------- | --- | ---- | --------------------- | ---- | --------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory| Description | +| -------- | --------------------- | ---- | --------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** @@ -639,9 +639,9 @@ Cancels a **WantAgent** object. This API uses a promise to return the result. **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ----- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ----- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| **Return value** @@ -708,11 +708,11 @@ Triggers a **WantAgent** object. This API uses an asynchronous callback to retur **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ----------- | --- | ---- | ----------------------------- | ---- | ------------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| triggerInfo | Yes | No | TriggerInfo | Yes | **TriggerInfo** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory| Description | +| ----------- | ----------------------------- | ---- | ------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| triggerInfo | TriggerInfo | Yes | **TriggerInfo** object. | +| callback | AsyncCallback\ | No | Callback used to return the result.| **Example** @@ -785,11 +785,11 @@ Checks whether two **WantAgent** objects are equal. This API uses an asynchronou **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ---------- | --- | ---- | ------------------------ | ---- | --------------------------------------- | -| agent | Yes | No | WantAgent | Yes | The first **WantAgent** object. | -| otherAgent | Yes | No | WantAgent | Yes | The second **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the result.| +| Name | Type | Mandatory| Description | +| ---------- | ------------------------ | ---- | --------------------------------------- | +| agent | WantAgent | Yes | The first **WantAgent** object. | +| otherAgent | WantAgent | Yes | The second **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the result.| **Example** @@ -860,10 +860,10 @@ Checks whether two **WantAgent** objects are equal. This API uses a promise to r **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ---------- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | The first **WantAgent** object.| -| otherAgent | Yes | No | WantAgent | Yes | The second **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ---------- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | The first **WantAgent** object.| +| otherAgent | WantAgent | Yes | The second **WantAgent** object.| **Return value** @@ -930,10 +930,10 @@ Obtains the operation type of a **WantAgent** object. This API uses an asynchron **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ---------- | --- | ---- | ------------------------ | ---- | --------------------------------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object. | -| callback | Yes | No | AsyncCallback\ | Yes | Callback used to return the operation type.| +| Name | Type | Mandatory| Description | +| ---------- | ------------------------ | ---- | --------------------------------------- | +| agent | WantAgent | Yes | Target **WantAgent** object. | +| callback | AsyncCallback\ | Yes | Callback used to return the operation type.| **Example** @@ -991,9 +991,9 @@ Obtains the operation type of a **WantAgent** object. This API uses a promise to **Parameters** -| Name | Readable| Writable| Type | Mandatory| Description | -| ---------- | --- | ---- | --------- | ---- | ------------- | -| agent | Yes | No | WantAgent | Yes | Target **WantAgent** object.| +| Name | Type | Mandatory| Description | +| ---------- | --------- | ---- | ------------- | +| agent | WantAgent | Yes | Target **WantAgent** object.| **Return value** @@ -1050,39 +1050,22 @@ WantAgent.getOperationType(wantAgent).then((OperationType) => { ``` - -## WantAgentInfo - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Readable| Writable| Type | Mandatory| Description | -| -------------- | --- | ---- | ------------------------------- | ---- | ---------------------- | -| wants | Yes | Yes | Array\ | Yes | Array of all **Want** objects. | -| operationType | Yes | Yes | wantAgent.OperationType | Yes | Operation type. | -| requestCode | Yes | Yes | number | Yes | Request code defined by the user.| -| wantAgentFlags | Yes | Yes | Array | No | Array of flags for using the **WantAgent** object. | -| extraInfo | Yes | Yes | {[key: string]: any} | No | Extra information. | - - - ## WantAgentFlags **System capability**: SystemCapability.Ability.AbilityRuntime.Core | Name | Value | Description | | ------------------- | -------------- | ------------------------------------------------------------ | -| ONE_TIME_FLAG | WantAgentFlags | The **WantAgent** object can be used only once. | -| NO_BUILD_FLAG | WantAgentFlags | The **WantAgent** object does not exist and hence it is not created. In this case, **null** is returned. | -| CANCEL_PRESENT_FLAG | WantAgentFlags | The existing **WantAgent** object should be canceled before a new object is generated.| -| UPDATE_PRESENT_FLAG | WantAgentFlags | Extra information of the existing **WantAgent** object is replaced with that of the new object.| -| CONSTANT_FLAG | WantAgentFlags | The **WantAgent** object is immutable. | -| REPLACE_ELEMENT | WantAgentFlags | The **element** attribute of the current **Want** can be replaced by the **element** attribute of the **Want** in **WantAgent.trigger()**.| -| REPLACE_ACTION | WantAgentFlags | The **action** attribute of the current **Want** can be replaced by the **action** attribute of the **Want** in **WantAgent.trigger()**.| -| REPLACE_URI | WantAgentFlags | The **uri** attribute of the current **Want** can be replaced by the **uri** attribute of the **Want** in **WantAgent.trigger()**.| -| REPLACE_ENTITIES | WantAgentFlags | The **entities** attribute of the current **Want** can be replaced by the **entities** attribute of the **Want** in **WantAgent.trigger()**.| -| REPLACE_BUNDLE | WantAgentFlags | The **bundleName** attribute of the current **Want** can be replaced by the **bundleName** attribute of **Want** in **WantAgent.trigger()**.| - - +| ONE_TIME_FLAG | 0 | The **WantAgent** object can be used only once. | +| NO_BUILD_FLAG | 1 | The **WantAgent** object does not exist and hence it is not created. In this case, **null** is returned. | +| CANCEL_PRESENT_FLAG | 2 | The existing **WantAgent** object should be canceled before a new object is generated.| +| UPDATE_PRESENT_FLAG | 3 | Extra information of the existing **WantAgent** object is replaced with that of the new object.| +| CONSTANT_FLAG | 4 | The **WantAgent** object is immutable. | +| REPLACE_ELEMENT | 5 | The **element** attribute of the current **Want** can be replaced by the **element** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_ACTION | 6 | The **action** attribute of the current **Want** can be replaced by the **action** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_URI | 7 | The **uri** attribute of the current **Want** can be replaced by the **uri** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_ENTITIES | 8 | The **entities** attribute of the current **Want** can be replaced by the **entities** attribute of the **Want** in **WantAgent.trigger()**.| +| REPLACE_BUNDLE | 9 | The **bundleName** attribute of the current **Want** can be replaced by the **bundleName** attribute of **Want** in **WantAgent.trigger()**.| ## OperationType @@ -1090,35 +1073,20 @@ WantAgent.getOperationType(wantAgent).then((OperationType) => { | Name | Value | Description | | ----------------- | ------------- | ------------------------- | -| UNKNOWN_TYPE | OperationType | Unknown operation type. | -| START_ABILITY | OperationType | Starts an ability with a UI.| -| START_ABILITIES | OperationType | Starts multiple abilities with a UI.| -| START_SERVICE | OperationType | Starts an ability without a UI.| -| SEND_COMMON_EVENT | OperationType | Sends a common event. | - - +| UNKNOWN_TYPE | 0 | Unknown operation type. | +| START_ABILITY | 1 | Starts an ability with a UI.| +| START_ABILITIES | 2 | Starts multiple abilities with a UI.| +| START_SERVICE | 3 | Starts an ability without a UI.| +| SEND_COMMON_EVENT | 4 | Sends a common event. | ## CompleteData **System capability**: SystemCapability.Ability.AbilityRuntime.Core -| Name | Readable| Writable| Type | Mandatory| Description | -| -------------- | --- | ---- | ------------------------------ | ---- | ---------------------- | -| info | Yes | Yes | WantAgent | Yes | A triggered **WantAgent** object. | -| want | Yes | Yes | Want | Yes | An existing triggered **want**. | -| finalCode | Yes | Yes | number | Yes | Request code that triggers the **WantAgent** object.| -| finalData | Yes | Yes | string | No | Final data collected by the common event. | -| extraInfo | Yes | Yes | {[key: string]: any} | No | Extra information. | - - - -## TriggerInfo - -**System capability**: SystemCapability.Ability.AbilityRuntime.Core - -| Name | Readable| Writable| Type | Mandatory| Description | -| ---------- | --- | ---- | -------------------- | ---- | ----------- | -| code | Yes | Yes | number | Yes | Result code.| -| want | Yes | Yes | Want | No | Want. | -| permission | Yes | Yes | string | No | Permission. | -| extraInfo | Yes | Yes | {[key: string]: any} | No | Extra information. | +| Name | Type | Mandatory| Description | +| -------------- | ------------------------------ | ---- | ---------------------- | +| info | WantAgent | Yes | A triggered **WantAgent** object. | +| want | Want | Yes | An existing triggered **want**. | +| finalCode | number | Yes | Request code that triggers the **WantAgent** object.| +| finalData | string | No | Final data collected by the common event. | +| extraInfo | {[key: string]: any} | No | Extra information. |