Describing a location using coordinates is accurate, but neither intuitive nor user-friendly. With the geocoding and reverse geocoding capabilities, you will be able to convert geographic description into specific coordinates and vice versa.
The geographic description helps users understand a location easily by providing several key attributes, for example, country, administrative region, street, house number, and address.
## Available APIs
The following table describes APIs available for mutual conversion between coordinates and geographic description. For details, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
**Table1** APIs for geocoding and reverse geocoding
| API | Description |
| -------- | -------- |
| isGeocoderAvailable(): boolean; | Checks whether the (reverse) geocoding service is available.|
| getAddressesFromLocation(request: ReverseGeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts coordinates into geographic description through reverse geocoding. This API uses an asynchronous callback to return the result. |
| getAddressesFromLocation(request: ReverseGeoCodeRequest): Promise<Array<GeoAddress>> | Converts coordinates into geographic description through reverse geocoding. This API uses a promise to return the result. |
| getAddressesFromLocationName(request: GeoCodeRequest, callback: AsyncCallback<Array<GeoAddress>>): void | Converts geographic description into coordinates through geocoding. This API uses an asynchronous callback to return the result. |
| getAddressesFromLocationName(request: GeoCodeRequest): Promise<Array<GeoAddress>> | Converts geographic description into coordinates through geocoding. This API uses a promise to return the result. |
## How to Develop
> **NOTE**
>
> The **GeoConvert** instance needs to access backend services to obtain information. Therefore, before performing the following steps, ensure that your device is connected to the network.
1. Import the **geoLocationManager** module by which you can implement all APIs related to the geocoding and reverse geocoding conversion capabilities.
```ts
importgeoLocationManagerfrom'@ohos.geolocation';
```
2. Query whether geocoder service is available.
- Call **isGeoServiceAvailable** to query whether the geocoder service is available. If the service is available, continue with step 3.
Your application can obtain the **GeoAddress** list that matches the specified coordinates and then read location information from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md).
- Call **getAddressesFromLocationName** to convert geographic description into coordinates.
```ts
vargeocodeRequest={"description":"No. xx, xx Road, Pudong District, Shanghai","maxItems":1};
Your application can obtain the **GeoAddress** list that matches the specified location information and read coordinates from it. For details, see [Geolocation](../reference/apis/js-apis-geolocation.md).
To improve the accuracy of location results, you can set the longitude and latitude ranges in **GeoCodeRequest**.
You can call location-related APIs in OpenHarmony to obtain the real-time location or last known location of a mobile device.
Real-time location of the device is recommended for location-sensitive services. If you want to lower power consumption when the real-time location of the device is not needed, you may consider obtaining the last known location of the device.
## Available APIs
For details about the APIs used to obtain the device location information, see [Geolocation Manager](../reference/apis/js-apis-geoLocationManager.md).
## How to Develop
To learn more about the APIs for obtaining device location information, see [Geolocation](../reference/apis/js-apis-geoLocationManager.md).
1. Before using basic location capabilities, check whether your application has been granted the permission to access the device location information. If not, your application needs to obtain the permission from the user as described below.
The system provides the following location permissions:
- ohos.permission.LOCATION
- ohos.permission.APPROXIMATELY_LOCATION
- ohos.permission.LOCATION_IN_BACKGROUND
If your application needs to access the device location information, it must first apply for required permissions. Specifically speaking:
API versions earlier than 9: Apply for **ohos.permission.LOCATION**.
API version 9 and later: Apply for **ohos.permission.APPROXIMATELY\_LOCATION**, or apply for **ohos.permission.APPROXIMATELY\_LOCATION** and **ohos.permission.LOCATION**. Note that **ohos.permission.LOCATION** cannot be applied for separately.
| Earlier than 9| ohos.permission.LOCATION | Success| Location accurate to meters|
| 9 and later| ohos.permission.LOCATION | Failure| No location obtained|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION | Success| Location accurate to 5 kilometers|
| 9 and later| ohos.permission.APPROXIMATELY_LOCATION and ohos.permission.LOCATION| Success| Location accurate to meters|
If your application needs to access the device location information when running on the background, it must be configured to be able to run on the background and be granted the **ohos.permission.LOCATION_IN_BACKGROUND** permission. In this way, the system continues to report device location information after your application moves to the background.
You can declare the required permission in your application's configuration file. For details, see [Access Control (Permission) Development](../security/accesstoken-guidelines.md).
2. Import the **geoLocationManager** module by which you can implement all APIs related to the basic location capabilities.
```ts
importgeoLocationManagerfrom'@ohos.geolocation';
```
3. Instantiate the **LocationRequest** object. This object provides APIs to notify the system of the location service type and the interval of reporting location information.<br>
**Method 1:**
To better serve your needs for using APIs, the system has categorized APIs into different packages to match your common use cases of the location function. In this way, you can directly use the APIs specific to a certain use case, making application development much easier. The following table lists the use cases currently supported.
```
export enum LocationRequestScenario {
UNSET = 0x300,
NAVIGATION,
TRAJECTORY_TRACKING,
CAR_HAILING,
DAILY_LIFE_SERVICE,
NO_POWER,
}
```
**Table 2** Common use cases of the location function
| Navigation | NAVIGATION | Applicable when your application needs to obtain the real-time location of a mobile device outdoors, such as navigation for driving or walking. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy. However, due to its limitations, the technology may be unable to provide the location service when navigation is just started or when the user moves into a shielded environment such as indoors or a garage. To resolve this issue, the system uses the network positioning technology as an alternative to provide the location service for your application until the GNSS can provide stable location results. This helps achieve a smooth navigation experience for users.<br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Trajectory tracking| TRAJECTORY_TRACKING | Applicable when your application needs to record user trajectories, for example, the track recording function of sports applications. In this scenario, the GNSS positioning technology is mainly used to ensure the location accuracy.<br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Ride hailing| CAR_HAILING | Applicable when your application needs to obtain the current location of a user who is hailing a taxi.<br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Life service| DAILY_LIFE_SERVICE | Applicable when your application only needs the approximate user location for recommendations and push notifications in scenarios such as when the user is browsing news, shopping online, and ordering food.<br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Power efficiency | NO_POWER | Applicable when your application does not proactively start the location service for a higher battery efficiency. When responding to another application requesting the same location service, the system marks a copy of the location result to your application. In this way, your application will not consume extra power for obtaining the user location.<br>By default, the system reports location results at a minimal interval of 1s. To adopt this use case, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
Sample code for initializing **requestInfo** for navigation:
| Location accuracy priority | ACCURACY | This policy mainly uses the GNSS positioning technology. In an open area, the technology can achieve the meter-level location accuracy, depending on the hardware performance of the device. However, in a shielded environment, the location accuracy may significantly decrease.<br>To use this policy, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Fast location priority | FAST_FIRST_FIX | This policy uses the GNSS positioning, base station positioning, WLAN positioning, and Bluetooth positioning technologies simultaneously to obtain the device location in both the indoor and outdoor scenarios. When all positioning technologies provide a location result, the system provides the most accurate location result for your application. This policy can lead to significant hardware resource consumption and power consumption.<br>To use this policy, you must declare the **ohos.permission.LOCATION** permission and obtain users' authorization.|
| Power efficiency priority| LOW_POWER | This policy mainly uses the base station positioning, WLAN positioning, and Bluetooth positioning technologies to obtain device location in both indoor and outdoor scenarios. The location accuracy depends on the distribution of surrounding base stations, visible WLANs, and Bluetooth devices and therefore may fluctuate greatly. This policy is recommended and can reduce power consumption when your application does not require high location accuracy or when base stations, visible WLANs, and Bluetooth devices are densely distributed.<br>To use this policy, you must declare at least the **ohos.permission.LOCATION** permission and obtain users' authorization.|
Sample code for initializing **requestInfo** for the location accuracy priority policy:
4. Instantiate the **Callback** object for the system to report location results.
Your application needs to implement the callback defined by the system. When the system successfully obtains the real-time location of a device, it will report the location result to your application through the callback interface. Your application can implement the callback interface in such a way to complete your own service logic.
People take their mobile devices wherever they go. Mobile devices have become a necessity in people's daily routines, whether it be for looking at the weather forecast, browsing news, hailing a taxi, navigating, or recording data from a workout. All these activities are so much associated with the location services on mobile devices.
With the location awareness capability offered by , mobile devices will be able to obtain real-time, accurate location data. Building location awareness into your application can also lead to a better contextual experience for application users.
Your application can call location-specific APIs to obtain the location information of a mobile device for offering location-based services such as drive navigation and motion track recording.
## Basic Concepts
Location awareness helps determine where a mobile device locates. The system identifies the location of a mobile device with its coordinates, and uses location technologies such as Global Navigation Satellite System (GNSS) and network positioning (for example, base station positioning or WLAN/Bluetooth positioning) to provide diverse location-based services. These advanced location technologies make it possible to obtain the accurate location of the mobile device, regardless of whether it is indoors or outdoors.
-**Coordinate**
A coordinate describes a location on the earth using the longitude and latitude in reference to the World Geodetic Coordinate System 1984.
-**GNSS positioning**
GNSS positioning locates a mobile device by using the location algorithm offered by the device chip to compute the location information provided by the Global Navigation Satellite System, for example, GPS, GLONASS, BeiDou, and Galileo. Whichever positioning system will be used during the location process depends on a hardware capability of the device.
-**Base station positioning**
Base station positioning estimates the current location of a mobile device based on the location of the resident base station in reference to the neighboring base stations. This technology provides only a low accuracy and requires access to the cellular network.
-**WLAN or Bluetooth positioning**
WLAN or Bluetooth positioning estimates the current location of a mobile device based on the locations of WLANs and Bluetooth devices that can be discovered by the device. The location accuracy of this technology depends on the distribution of fixed WLAN access points (APs) and Bluetooth devices around the device. A high density of WLAN APs and Bluetooth devices can produce a more accurate location result than base station positioning. This technology also requires access to the network.
## Working Principles
Location awareness is offered by the system as a basic service for applications. Depending on the service scenario, an application needs to initiate a location request to the system and stop the location request when the service scenario ends. In this process, the system reports the location information to the application on a real-time basis.
## Limitations and Constraints
Your application can use the location function only after the user has granted the permission and turned on the function. If the location function is off, the system will not provide the location service for any application.
Since the location information is considered sensitive, your application still needs to obtain the location access permission from the user even if the user has turned on the location function. The system will provide the location service for your application only after it has been granted the permission to access the device location information.
## Samples
The following sample is provided to help you better understand how to develop location services:
Starts an ability. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the start options specified. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#abilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the 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. After the ability is started, you can call [terminateSelfWithResult](#abilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses a promise to return the result when the ability is terminated.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#abilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses an asynchronous callback to return the result when the account of the ability is destroyed.
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
@@ -375,22 +416,23 @@ Starts an ability. This API uses an asynchronous callback to return the result w
| -------- | -------- | -------- | -------- |
| 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\<AbilityResult\> | Yes| Callback used to return the result.|
| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)\> | Yes| Callback used to return the result.|
**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).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"EntryAbility"
};
varaccountId=100;
...
...
@@ -418,9 +460,14 @@ For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
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.
Starts an ability with the start options and account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
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.
Starts an ability with the account ID specified. This API uses a promise to return the result when the ability is terminated.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Terminates this ability. This API uses an asynchronous callback to return the ability result information. It is used together with **startAbilityForResult**.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#abilitycontextstartabilityforresult), the result is returned to the caller in the form of a callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
Terminates this ability. This API uses a promise to return the ability result information. It is used together with **startAbilityForResult**.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#abilitycontextstartabilityforresult), the result is returned to the caller in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
Starts an ability in the foreground or background and obtains the caller object for communicating with the ability.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
| permissions | Array<string> | Yes| Permissions to request.|
| callback | AsyncCallback<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Yes| Callback used to return the result.|
The **DataUriUtils** module provides APIs to process URI objects. 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. This module will be replaced by the **app.ability.dataUriUtils** module in the near future. You are advised to use the **[@ohos.app.ability.dataUriUtils](js-apis-app-ability-dataUriUtils.md)** module.
The **ErrorCode** module defines the error codes that can be used when the ability is started.
**NOTE**
The **ErrorCode** module defines the error codes that may be returned when an ability is started.
> **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
...
...
@@ -14,13 +14,13 @@ import errorCode from '@ohos.ability.errorCode'
## ErrorCode
Defines the error codes used when the ability is started.
Enumerates the error codes that may be returned when an ability is started.
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.
The **FeatureAbility** module provides APIs that enable user interaction. You can use the APIs to start or terminate an ability, obtain a **dataAbilityHelper** object, obtain the window corresponding to the current ability, and connect to or disconnect from a ServiceAbility.
> **NOTE**
>
...
...
@@ -9,7 +9,7 @@ The **FeatureAbility** module provides a UI for interacting with users. You can
## Constraints
APIs of the **FeatureAbility** module can be called only by Page abilities.
The APIs of the **FeatureAbility** module can be called only by PageAbilities.
Starts an ability. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Starts an ability. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
- To access a DataAbility of another application, the target application must be configured with associated startup (**AssociateWakeUp** set to **true**).
- If an application running in the background needs to call this API to access a DataAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Starts an ability. This API uses an asynchronous callback to return the execution result when the ability is destroyed.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#featureabilityterminateselfwithresult7) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Starts an ability. This API uses a promise to return the execution result when the ability is destroyed.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#featureabilityterminateselfwithresult7) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Destroys this Page ability, with the result code and data sent to the caller. This API uses an asynchronous callback to return the result.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#featureabilitystartabilityforresult7), the result is returned to the caller in the form of a callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
Destroys this Page ability, with the result code and data sent to the caller. This API uses a promise to return the result.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#featureabilitystartabilityforresult7), the result is returned to the caller in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>Returns **true** if the main window of this ability has the focus; returns **false** otherwise.|
| callback | AsyncCallback\<boolean> | Yes | Callback used to return the result.<br>If the main window has the focus, **true** is returned. Otherwise, **false** is returned.|
**Example**
...
...
@@ -368,7 +400,7 @@ Checks whether the main window of this ability has the focus. This API uses a pr
connectAbility(request: Want, options:ConnectOptions): number
Connects this ability to a specific Service ability. This API uses an asynchronous callback to return the result.
Connects this ability to a ServiceAbility.
Observe the following when using this API:
- To connect to a ServiceAbility of another application, the target application must be configured with associated startup (**AssociateWakeUp** set to **true**)..
- If an application running in the background needs to call this API to connect to a ServiceAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | The Page ability is in an undefined window display mode.|
| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | The Page ability is in full screen mode. |
| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | The Page ability is displayed in the primary window when it is in split-screen mode.|
| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | The Page ability is displayed in the secondary window when it is in split-screen mode.|
| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | The Page ability is displayed in floating window mode.|
| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | The PageAbility is in an undefined window display mode.|
| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | The PageAbility is in full screen mode. |
| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | The PageAbility is displayed in the primary window when it is in split-screen mode.|
| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | The PageAbility is displayed in the secondary window when it is in split-screen mode.|
| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | The PageAbility is displayed in floating window mode.|
## AbilityStartSetting
The **AbilityStartSetting** attribute is an object defined as [key: string]: any. The key is a type of **AbilityStartSetting**, and the value is a type of **AbilityWindowConfiguration**.
Defines the window attribute corresponding to this ability. The **abilityStartSetting** attribute is an object defined in the format of [**key: string]: any**, where **key** is an enumerated value of **AbilityStartSetting** and **value** is an enumerated value of **AbilityWindowConfiguration**.
The value is obtained through the **featureAbility.AbilityStartSetting** API.
The value is obtained through **featureAbility.AbilityStartSetting**.
Enumerates the operation types of a DataAbility. The DataAbility can use an enumerated value to specify the operation type when operating data in batches.
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI. |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. |
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Grants the permission to read the URI. |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Grants 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 migrated to a remote device. |
| FLAG_ABILITY_CONTINUATION | 0x00000008 | Continues the ability on a remote device. |
| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS. |
| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether to enable an ability. |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent.<br>**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.<br>**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.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether the FormAbility is enabled. |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Grants the permission to make the URI persistent.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Grants the permission to verify URIs by prefix matching.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Indicates the support for cross-device startup in the distributed scheduler. |
| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the ability is started in the foreground regardless of whether the host application is started.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible. |
| 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 | Creates a mission on the historical 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.|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on an existing mission stack. |
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
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.
The **particleAbility** module provides APIs for operating a ServiceAbility. You can use the APIs to start and terminate a ParticleAbility, obtain a **dataAbilityHelper** object, and connect to or disconnect from a ServiceAbility.
> **NOTE**
>
...
...
@@ -21,7 +21,12 @@ import particleAbility from '@ohos.ability.particleAbility'
Starts a Particle ability. This API uses an asynchronous callback to return the result.
Starts a ParticleAbility. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Starts a Particle ability. This API uses a promise to return the result.
Starts a ParticleAbility. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
- To access a DataAbility of another application, the target application must be configured with associated startup (**AssociateWakeUp** set to **true**).
- If an application running in the background needs to call this API to access a DataAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
Requests a continuous task from the system. This API uses a promise to return the result. You are advised to use the new API [backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8-1).
Requests to cancel a continuous task from the system. This API uses a promise to return the result. You are advised to use the new API [backgroundTaskManager.stopBackgroundRunning](js-apis-backgroundTaskManager.md#backgroundtaskmanagerstopbackgroundrunning8-1).
connectAbility(request: Want, options:ConnectOptions): number
Connects this ability to a specific Service ability. This API uses a callback to return the result.
Connects this ability to a specific ServiceAbility.
Observe the following when using this API:
- To connect to a ServiceAbility of another application, the target application must be configured with associated startup (**AssociateWakeUp** set to **true**)..
- If an application running in the background needs to call this API to connect to a ServiceAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the FA model, see [Component Startup Rules (FA Model)](../../application-models/component-startup-rules-fa.md).
| 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_AUTH_READ_URI_PERMISSION | 0x00000001 | Grants the permission to read the URI. |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Grants 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.<br>**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.<br>**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_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Grants the permission to make the URI persistent.<br>**System API**: This is a system API and cannot be called by third-party applications. |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Grants the permission to verify URIs by prefix matching.<br>**System API**: This is a system API and cannot be called by third-party applications.|
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Indicates the support for cross-device startup in the distributed scheduler. |
| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the ServiceAbility is started regardless of whether the host application has been started. |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that ability continuation is reversible.<br>**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.|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the history mission stack. |
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Reuses an ability instance if it is on the top of an existing mission stack; creates an ability instance otherwise.|
The **AccessibilityExtensionContext** module, inherited from **ExtensionContext**, provides context for **Accessibility Extension** abilities.
You can use the APIs of this module to configure the concerned information, obtain root information, and inject gestures.
> **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.
## Usage
Before using the **AccessibilityExtensionContext** module, you must define a child class that inherits from **AccessibilityExtensionAbility**.
| windowId | number | No | Window for which you want to obtain the root element. If this parameter is not specified, it indicates the current active window.|
| displayId | number | No | Screen from which the window information is obtained. If this parameter is not specified, it indicates the default home screen.|
The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information.
This is the base class of [UIAbility](js-apis-app-ability-uiAbility.md) and [ExtensionAbility](js-apis-app-ability-extensionAbility.md). It provides the callbacks for system configuration updates and memory level updates. You cannot inherit from this base class.
> **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.
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.
| 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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| level | [AbilityConstant.MemoryLevel](js-apis-app-ability-abilityConstant.md#abilityconstantmemorylevel) | Yes| New memory level.|
**Example**
```ts
classmyAbilityextendsAbility{
// You are not allowed to inherit from the top-level base class Ability. Therefore, the derived class UIAbility is used as an example.
The **AbilityConstant** module provides ability launch parameters.
The parameters include the initial launch reasons, reasons for the last exit, and ability continuation results.
The **AbilityConstant** module defines the ability-related enums, including the initial launch reasons, reasons for the last exit, ability continuation results, and window modes.
> **NOTE**
>
...
...
@@ -17,31 +15,48 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant';
| lastExitReason | LastExitReason | Yes| Yes| Reason for the last exit.|
| launchReason | [LaunchReason](#abilityconstantlaunchreason)| Yes| Yes| Ability launch reason, which is an enumerated type.|
| lastExitReason | [LastExitReason](#abilityconstantlastexitreason) | Yes| Yes| Reason for the last exit, which is an enumerated type.|
## AbilityConstant.LaunchReason
Enumerates the ability launch reasons.
Enumerates the initial ability launch reasons. You can use it together with [onCreate(want, launchParam)](js-apis-app-ability-uiAbility.md#uiabilityoncreate) of [Ability](js-apis-app-ability-uiAbility.md) to complete different operations.
console.log("The ability has been started by the way of startAbility.");
}
}
}
```
## AbilityConstant.LastExitReason
Enumerates reasons for the last exit.
Enumerates the reasons for the last exit. You can use it together with [onCreate(want, launchParam)](js-apis-app-ability-uiAbility.md#uiabilityoncreate) of [Ability](js-apis-app-ability-uiAbility.md) to complete different operations.
console.log("The ability has exit last because the ability was not responding.");
}
}
}
```
## AbilityConstant.OnContinueResult
Enumerates ability continuation results.
Enumerates the ability continuation results. You can use it together with [onContinue(wantParam)](js-apis-app-ability-uiAbility.md#uiabilityoncontinue) of [Ability](js-apis-app-ability-uiAbility.md) to complete different operations.
Enumerates the window modes in which an ability can be displayed at startup.
Enumerates the window modes in which an ability can be displayed at startup. It can be used in **startAbility()** to specify the window mode when the ability is started.
console.log("Failed to start ability with error: "+JSON.stringify(error));
});
```
## AbilityConstant.MemoryLevel
Enumerates the memory levels.
Enumerates the memory levels. You can use it in [onMemoryLevel(level)](js-apis-app-ability-ability.md#abilityonmemorylevel) of [Ability](js-apis-app-ability-ability.md) to complete different operations.
console.log("The memory of device is critical, please release some memory.");
}
}
}
```
## AbilityConstant.OnSaveResult
Enumerates the result types for the operation of saving application data.
Enumerates the result types for the operation of saving application data. You can use it in [onSaveState(reason, wantParam)](js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of [Ability](js-apis-app-ability-uiAbility.md) to complete different operations.
| 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.|
| ALL_REJECT | 5 | Always rejected to save the status.|
**Example**
```ts
importUIAbilityfrom'@ohos.app.ability.UIAbility';
classMyAbilityextendsUIAbility{
onSaveState(reason,wantParam){
returnAbilityConstant.OnSaveResult.ALL_AGREE;
}
}
```
## AbilityConstant.StateType
Enumerates the scenarios for saving application data.
Enumerates the scenarios for saving application data. You can use it in [onSaveState(reason, wantParam)](js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of [Ability](js-apis-app-ability-uiAbility.md) to complete different operations.
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.
**AbilityDelegatorRegistry**, a module of the [Test Framework](../../ability-deprecated/ability-delegator.md), is used to obtain [AbilityDelegator](js-apis-inner-application-abilityDelegator.md) and [AbilityDelegatorArgs](js-apis-inner-application-abilityDelegatorArgs.md) objects. **AbilityDelegator** provides APIs for creating **AbilityMonitor** objects, which can be used to listen for ability lifecycle changes. **AbilityDelegatorArgs** provides APIs for obtaining test parameters.
> **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 can be used only in the test framework.
Enumerates the ability lifecycle states. It can be used in [getAbilityState(ability)](js-apis-inner-application-abilityDelegator.md#getabilitystate9) of [AbilityDelegator](js-apis-inner-application-abilityDelegator.md) to return different ability lifecycle states.
| [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.|
| [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) | [AbilityDelegator](js-apis-inner-application-abilityDelegator.md#AbilityDelegator) object, which can be used to schedule the functionalities of the test framework.|
The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context.
The **AbilityLifecycleCallback** module defines the callbacks to receive lifecycle changes of [ApplicationContext](js-apis-inner-application-applicationContext.md). The callbacks include [onAbilityCreate](#abilitylifecyclecallbackonabilitycreate), [onWindowStageCreate](#abilitylifecyclecallbackonwindowstagecreate), [onWindowStageActive](#abilitylifecyclecallbackonwindowstageactive), [onWindowStageInactive](#abilitylifecyclecallbackonwindowstageinactive), [onWindowStageDestroy](#abilitylifecyclecallbackonwindowstagedestroy), [onAbilityDestroy](#abilitylifecyclecallbackonabilitydestroy), [onAbilityForeground](#abilitylifecyclecallbackonabilityforeground), [onAbilityBackground](#abilitylifecyclecallbackonabilitybackground), and [onAbilityContinue](#abilitylifecyclecallbackonabilitycontinue).
> **NOTE**
>
...
...
@@ -25,10 +25,18 @@ Called when an ability is created.
Enumerates the ability states. This enum can be used together with [AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md) to return the ability state.
| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the result. |
| config | [Configuration](js-apis-app-ability-configuration.md) | Yes | New configuration. You only need to configure the items to be updated.|
| callback | AsyncCallback\<void> | Yes | Callback used to return the API call result. You can perform error handling or custom processing in this callback. |
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| callback | AsyncCallback\<Array\<AbilityRunningInfo>> | Yes | Callback used to return the result. |
| callback | AsyncCallback\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | Yes | Callback used to return the API call result and the ability running information. You can perform error handling or custom processing in this callback. |
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| Promise\<Array\<AbilityRunningInfo>> | Promise used to return the result.|
| Promise\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | Callback used to return the API call result and the ability running information. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| upperLimit | number | Yes| Maximum number of messages that can be obtained.|
| callback | AsyncCallback\<Array\<AbilityRunningInfo>> | Yes | Callback used to return the result. |
| upperLimit | number | Yes| Maximum number of messages that can be obtained. The maximum value is 2<sup>31</sup>-1.|
| callback | AsyncCallback\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo.md)>> | Yes | Callback used to return the API call result and the ExtensionAbility running information. You can perform error handling or custom processing in this callback. |
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| Promise\<Array\<AbilityRunningInfo>> | Promise used to return the result.|
| Promise\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo.md)>> | Promise used to return the API call result and the ExtensionAbility running information. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| callback | AsyncCallback\<ElementName> | Yes | Callback used to return the result. |
| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | Callback used to return the API call result and the element name of the top ability. You can perform error handling or custom processing in this callback. |
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| Promise\<ElementName>| Promise used to return the result.|
| Promise\<[ElementName](js-apis-bundleManager-elementName.md)>| Promise used to return the API call result and the element name of the top ability. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | Called when initialization is performed during ability startup.|
| context | [AbilityStageContext](js-apis-inner-application-abilityStageContext.md) | The context is obtained in the callback invoked when initialization is performed during ability startup.|
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.
...
...
@@ -12,7 +12,7 @@ The **appManager** module implements application management. You can use the API
@@ -22,21 +22,34 @@ Checks whether this application is undergoing a stability test. This API uses an
**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.|
| Type| Description|
| -------- | -------- |
|AsyncCallback<boolean> |Callback used to return the API call result and the result **true** or **false**. You can perform error handling or custom processing in this callback. The value **true** means that the application is undergoing a stability test, and **false** means the opposite.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -48,18 +61,27 @@ Checks whether this application is undergoing a stability test. This API uses a
| 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.|
| Promise<boolean> | Promise used to return the API call result and the result **true** or **false**. You can perform error handling or custom processing in this callback. The value **true** means that the application is undergoing a stability test, and **false** means the opposite.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
console.log("The result of isRunningInStabilityTest is:"+JSON.stringify(flag));
}).catch((error)=>{
console.log("error:"+JSON.stringify(error));
});
```
## appManager.isRamConstrainedDevice
...
...
@@ -74,17 +96,27 @@ Checks whether this application is running on a RAM constrained device. This API
| 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.|
| Promise<boolean> | Promise used to return the API call result and the result **true** or **false**. You can perform error handling or custom processing in this callback. The value **true** means that the application is running on a RAM constrained device, and **false** means the opposite.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
console.log("The result of isRamConstrainedDevice is:"+JSON.stringify(data));
}).catch((error)=>{
console.log("error:"+JSON.stringify(error));
});
```
## appManager.isRamConstrainedDevice
...
...
@@ -96,18 +128,31 @@ Checks whether this application is running on a RAM constrained device. This API
**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.|
| Type| Description|
| -------- | -------- |
| AsyncCallback<boolean> |Callback used to return the API call result and the result **true** or **false**. You can perform error handling or custom processing in this callback. The value **true** means that the application is running on a RAM constrained device, and **false** means the opposite.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
app.isRamConstrainedDevice((err,data)=>{
console.log('startAbility result failed:'+JSON.stringify(err));
console.log('startAbility result success:'+JSON.stringify(data));
console.log("The result of isRamConstrainedDevice is:"+JSON.stringify(data));
}
})
```
## appManager.getAppMemorySize
...
...
@@ -121,17 +166,27 @@ Obtains the memory size of this application. This API uses a promise to return t
| Type| Description|
| -------- | -------- |
| Promise<number> | Size of the application memory.|
| Promise<number> | Promise used to return the API call result and the memory size. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
console.log("The size of app memory is:"+JSON.stringify(data));
}).catch((error)=>{
console.log("error:"+JSON.stringify(error));
});
```
## appManager.getAppMemorySize
...
...
@@ -143,20 +198,33 @@ Obtains the memory size of this application. This API uses an asynchronous callb
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback<number> | Yes| Size of the application memory.|
| Type| Description|
| -------- | -------- |
|AsyncCallback<number> |Callback used to return the API call result and the memory size. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
app.getAppMemorySize((err,data)=>{
console.log('startAbility result failed :'+JSON.stringify(err));
console.log('startAbility result success:'+JSON.stringify(data));
@@ -172,17 +240,27 @@ Obtains information about the running processes. This API uses a promise to retu
| Type| Description|
| -------- | -------- |
| Promise\<Array\<[ProcessRunningInformation](js-apis-inner-application-processRunningInformation.md)>> | Promise used to return the process information.|
| Promise\<Array\<[ProcessRunningInformation](js-apis-inner-application-processRunningInformation.md)>> | Promise used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -198,18 +276,31 @@ Obtains information about the running processes. This API uses an asynchronous c
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback\<Array\<[ProcessRunningInformation](js-apis-inner-application-processRunningInformation.md)>> | Yes| Callback used to return the process information.|
| Type| Description|
| -------- | -------- |
|AsyncCallback\<Array\<[ProcessRunningInformation](js-apis-inner-application-processRunningInformation.md)>> | Callback used to return the API call result and the process running information. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
app.getProcessRunningInformation((err,data)=>{
console.log('startAbility result failed :'+JSON.stringify(err));
console.log('startAbility result success:'+JSON.stringify(data));
console.log("The process running information is:"+JSON.stringify(data));
}
})
```
## appManager.on
...
...
@@ -227,37 +318,52 @@ Registers an observer to listen for the state changes of all applications.
| 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.|
| type | string | Yes| Type of the API to call. It is fixed at **"applicationState"**.|
| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | Yes| Application state observer, which is used to observe the lifecycle change of an application.|
**Return value**
| Type| Description|
| --- | --- |
| number | Digital code of the observer, which will be used in **off()** to deregister the observer.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -275,39 +381,55 @@ Registers an observer to listen for the state changes of a specified application
| 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<string> | Yes| **bundleName** array of the application. A maximum of 128 bundle names can be passed.|
| type | string | Yes| Type of the API to call. It is fixed at **"applicationState"**.|
| observer | [ApplicationStateObserver](./js-apis-inner-application-applicationStateObserver.md) | Yes| Application state observer, which is used to observe the lifecycle change of an application.|
| bundleNameList | `Array<string>` | Yes| **bundleName** array of the application. A maximum of 128 bundle names can be passed.|
**Return value**
| Type| Description|
| --- | --- |
| number | Digital code of the observer, which will be used in **off()** to deregister the observer.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -324,26 +446,65 @@ Deregisters the application state observer. This API uses an asynchronous callba
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Type of the API to call.|
| observerId | number | Yes| Numeric code of the observer.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
| type | string | Yes| Type of the API to call. It is fixed at **"applicationState"**.|
| observerId | number | Yes| Digital code of the observer.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the API call result. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result.
Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result. The application information is defined by [AppStateData](js-apis-inner-application-appStateData.md).
**System API**: This is a system API and cannot be called by third-party applications.
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| observerId | number | Yes| Numeric code of the observer.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise\<void> | Promise used to return the result.|
| callback | AsyncCallback\<Array\<[AppStateData](js-apis-inner-application-appStateData.md)>> | Yes| Callback used to return the API call result and an array holding the application state data. You can perform error handling or custom processing in this callback.|
Obtains applications that are running in the foreground. This API uses a promise to return the result.
Obtains applications that are running in the foreground. This API uses a promise to return the result. The application information is defined by [AppStateData](js-apis-inner-application-appStateData.md).
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
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user) and ohos.permission.CLEAN_BACKGROUND_PROCESSES
@@ -529,27 +681,39 @@ Kills a process by bundle name and account ID. This API uses a promise to return
**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).|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -559,32 +723,42 @@ Kills a process by bundle name and account ID. This API uses an asynchronous cal
**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
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user) and ohos.permission.CLEAN_BACKGROUND_PROCESSES
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name of an application.|
| bundleName | string | Yes| Bundle name.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the API call result. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -600,24 +774,38 @@ Kills a process by bundle name. This API uses an asynchronous callback to return
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name of an application.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
| bundleName | string | Yes| Bundle name.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the API call result. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
@@ -670,24 +870,38 @@ Clears application data by bundle name. This API uses an asynchronous callback t
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name of an application.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
| bundleName | string | Yes| Bundle name.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the API call result. You can perform error handling or custom processing in this callback.|
**Error codes**
| ID| Error Message|
| ------- | -------- |
| 16000050 | Internal error. |
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
Enumerates the application states. This enum can be used together with [AbilityStateData](js-apis-inner-application-appStateData.md) to return the application state.
@@ -738,7 +966,9 @@ Clears application data by bundle name. This API uses a promise to return the re
| STATE_BACKGROUND | 4 | State indicating that the application is running in the background. |
| STATE_DESTROY | 5 | State indicating that the application is destroyed. |
## ProcessState<sup>9+</sup>
## ProcessState
Enumerates the process states. This enum can be used together with [ProcessData](js-apis-inner-application-processData.md) to return the process state.
@@ -28,7 +28,7 @@ Enumerates the application restart options used in [enableAppRecovery](#apprecov
## appRecovery.SaveOccasionFlag
Enumerates the scenarios for saving the application state, which is used in[enableAppRecovery](#apprecoveryenableapprecovery).
Enumerates the scenarios for saving the application state. This enum is used as an input parameter of[enableAppRecovery](#apprecoveryenableapprecovery).
@@ -107,15 +123,24 @@ Saves the application state. This API can be used together with APIs of [errorMa
| Type| Description|
| -------- | -------- |
| boolean | Whether the saving is successful.|
| boolean | Whether the application state is saved. The value **true** is returned if the application state is saved, and **false** is returned otherwise.|
| language | string | Yes| Yes| Language of the application.|
| language | string | Yes| Yes| Language of the application, for example, **zh**.|
| 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).|
| direction | [Direction](js-apis-app-ability-configurationConstant.md#configurationconstantdirection) | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.|
| screenDensity | [ScreenDensity](js-apis-app-ability-configurationConstant.md#configurationconstantscreendensity) | 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.|
...
...
@@ -28,6 +28,10 @@ For details about the fields, see the **ohos.app.ability.Configuration.d.ts** fi
The **DataUriUtils** module provides APIs to process URI objects. 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.
The **errorManager** module provides APIs for registering and deregistering error observers.
The **ErrorManager** module provides APIs for registering and deregistering error observers. For example, you can use the APIs to register an observer when your application wants to capture JS crashes.
> **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.
# @ohos.app.ability.ExtensionAbility (ExtensionAbility Base Class)
The **ExtensionAbility** module manages the Extension ability lifecycle and context, such as creating and destroying an Extension ability, and dumping client information.
**ExtensionAbility** is the base class for scenario-specific ExtensionAbilities. It is inherited from [Ability](js-apis-app-ability-ability.md), with no attribute or method added. You cannot inherit from this base class.
> **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.
@@ -449,27 +468,22 @@ Obtains the snapshot of a given mission. This API uses an asynchronous callback
| callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.|
@@ -539,27 +547,22 @@ Obtains the low-resolution snapshot of a given mission. This API uses an asynchr
| callback | AsyncCallback<[MissionSnapshot](js-apis-inner-application-missionSnapshot.md)> | Yes| Callback used to return the snapshot information obtained.|
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.
...
...
@@ -36,7 +36,7 @@ Defines the quick fix information at the application level.
The **ServiceExtensionAbility** module provides APIs for Service Extension abilities.
The **ServiceExtensionAbility** module provides lifecycle callbacks when a ServiceExtensionAbility (background service) is created, destroyed, connected, or disconnected.
> **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 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.
| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) | Yes| No| Service Extension context, which is inherited from **ExtensionContext**.|
| context | [ServiceExtensionContext](js-apis-inner-application-serviceExtensionContext.md) | Yes| No| ServiceExtensionContext, which is inherited from **ExtensionContext**.|
## ServiceExtensionAbility.onCreate
onCreate(want: Want): void;
Called when a Service Extension ability is created to initialize the service logic.
Called when a ServiceExtensionAbility is created to initialize the service logic.
@@ -40,9 +40,9 @@ Called when a Service Extension ability is created to initialize the service log
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.|
**Example**
...
...
@@ -59,7 +59,7 @@ Called when a Service Extension ability is created to initialize the service log
onDestroy(): void;
Called when this Service Extension ability is destroyed to clear resources.
Called when this ServiceExtensionAbility is destroyed to clear resources.
@@ -80,7 +80,7 @@ Called when this Service Extension ability is destroyed to clear resources.
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.
Called following **onCreate()** when a ServiceExtensionAbility is started by calling **startAbility()**. The value of **startId** is incremented for each ability that is started.
@@ -88,10 +88,10 @@ Called after **onCreate** is invoked when a Service Extension ability is started
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Want information related to this ServiceExtensionAbility, 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**
...
...
@@ -108,7 +108,7 @@ Called after **onCreate** is invoked when a Service Extension ability is started
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.
Called following **onCreate()** when a ServiceExtensionAbility is started by calling **connectAbility()**. A **RemoteObject** object is returned for communication between the server and client.
@@ -116,15 +116,15 @@ Called after **onCreate** is invoked when a Service Extension ability is started
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.|
**Return value**
| Type| Description|
| -------- | -------- |
| rpc.RemoteObject | A **RemoteObject** object used for communication with the client.|
| Type| Description|
| -------- | -------- |
| rpc.RemoteObject | A **RemoteObject** object used for communication between the server and client.|
**Example**
...
...
@@ -150,7 +150,7 @@ Called after **onCreate** is invoked when a Service Extension ability is started
onDisconnect(want: Want): void;
Called when this Service Extension ability is disconnected.
Called when a client is disconnected from this ServiceExtensionAbility.
@@ -158,9 +158,9 @@ Called when this Service Extension ability is disconnected.
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.|
**Example**
...
...
@@ -176,7 +176,7 @@ Called when this Service Extension ability is disconnected.
onReconnect(want: Want): void;
Called when this Service Extension ability is reconnected.
Called when a new client attempts to connect to this ServiceExtensionAbility after all previous clients are disconnected. This capability is reserved.
@@ -184,9 +184,9 @@ Called when this Service Extension ability is reconnected.
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-app-ability-want.md)| Yes| Want information related to this ServiceExtensionAbility, including the ability name and bundle name.|
**Example**
...
...
@@ -202,7 +202,7 @@ Called when this Service Extension ability is reconnected.
The **StartOptions** module implements ability startup options.
**StartOptions** is used as an input parameter of [startAbility()](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability-1) to specify the window mode of an ability.
> **NOTE**
>
...
...
@@ -21,4 +21,4 @@ import StartOptions from '@ohos.app.ability.StartOptions';
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| [windowMode](js-apis-application-abilityConstant.md#abilityconstantwindowmode) | number | No| Window mode.|
| displayId | number | No| Display ID.|
| displayId | number | No| Display ID. The default value is **0**, indicating the current display.|
The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information.
UIAbility is an application component that has the UI. The **UIAbility** module provides lifecycle callback such as component creation, destruction, and foreground/background switching. It also provides the following capabilities related to component collaboration:
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.
-[Caller](#caller): an object returned by [startAbilityByCall](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartabilitybycall). The CallerAbility (caller) uses this object to communicate with the CalleeAbility (callee).
-[Callee](#callee): an internal object of UIAbility. The CalleeAbility (callee) uses this object to communicate with the CallerAbility (caller).
> **NOTE**
>
...
...
@@ -15,7 +13,7 @@ This module provides the following common ability-related functions:
## Modules to Import
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
importUIAbilityfrom'@ohos.app.ability.UIAbility';
```
## Attributes
...
...
@@ -24,30 +22,30 @@ import Ability from '@ohos.app.ability.UIAbility';
| 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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this UIAbility, including the ability name and bundle name.|
| param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Parameters for starting the UIAbility, and the reason for the last abnormal exit.|
**Example**
```ts
classmyAbilityextendsAbility{
classMyUIAbilityextendsUIAbility{
onCreate(want,param){
console.log('onCreate, want:'+want.abilityName);
}
...
...
@@ -55,24 +53,24 @@ Called to initialize the service logic when an ability is created.
| 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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-app-ability-want.md) | Yes| Want information, such as the ability name and bundle name.|
| launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Reason for the UIAbility startup and the last abnormal exit.|
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).
Called when the framework automatically saves the UIAbility state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). If automatic state saving is enabled, **onSaveState** is called to save the state of this UIAbility.
| reason | [AbilityConstant.StateType](js-apis-application-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the ability state.|
| reason | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the UIAbility state.|
@@ -305,7 +304,7 @@ class myAbility extends Ability {
## Caller
Implements sending of sequenceable data to the target ability when an ability (caller ability) invokes the target ability (callee ability).
Implements sending of sequenceable data to the target ability when the CallerAbility invokes the target ability (CalleeAbility).
## Caller.call
...
...
@@ -317,29 +316,29 @@ Sends sequenceable data to the target ability.
**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.|
| 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](js-apis-rpc.md#sequenceabledeprecated) | Yes| Sequenceable data. You need to customize the data.|
**Return value**
| Type| Description|
| -------- | -------- |
| Promise<void> | Promise used to return a response.|
| 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).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
classMyMessageAble{// Custom sequenceable data structure
classMyMessageAble{// Custom sequenceable data structure.
name:""
str:""
num:1
...
...
@@ -360,13 +359,13 @@ For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
returntrue;
}
};
varmethod='call_Function';// Notification message string negotiated by the two abilities
varmethod='call_Function';// Notification message string negotiated by the two abilities.
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onWindowStageCreate(windowStage){
this.context.startAbilityByCall({
this.context.startUIAbilityByCall({
bundleName:"com.example.myservice",
abilityName:"MainAbility",
abilityName:"MainUIAbility",
deviceId:""
}).then((obj)=>{
caller=obj;
...
...
@@ -398,28 +397,28 @@ Sends sequenceable data to the target ability and obtains the sequenceable data
**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.|
| 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](js-apis-rpc.md#sequenceabledeprecated) | 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.|
| Type| Description|
| -------- | -------- |
| Promise<[rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)> | 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).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
classMyMessageAble{
name:""
str:""
...
...
@@ -443,11 +442,11 @@ For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
};
varmethod='call_Function';
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onWindowStageCreate(windowStage){
this.context.startAbilityByCall({
this.context.startUIAbilityByCall({
bundleName:"com.example.myservice",
abilityName:"MainAbility",
abilityName:"MainUIAbility",
deviceId:""
}).then((obj)=>{
caller=obj;
...
...
@@ -491,13 +490,12 @@ Releases the caller interface of the target ability.
**Example**
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onWindowStageCreate(windowStage){
this.context.startAbilityByCall({
this.context.startUIAbilityByCall({
bundleName:"com.example.myservice",
abilityName:"MainAbility",
abilityName:"MainUIAbility",
deviceId:""
}).then((obj)=>{
caller=obj;
...
...
@@ -525,20 +523,19 @@ Registers a callback that is invoked when the stub on the target ability is disc
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | OnReleaseCallBack | Yes| Callback used for the **onRelease** API.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | [OnReleaseCallBack](#onreleasecallback) | Yes| Callback used for the **onRelease** API.|
**Example**
```ts
importAbilityfrom'@ohos.application.Ability';
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onWindowStageCreate(windowStage){
this.context.startAbilityByCall({
this.context.startUIAbilityByCall({
bundleName:"com.example.myservice",
abilityName:"MainAbility",
abilityName:"MainUIAbility",
deviceId:""
}).then((obj)=>{
caller=obj;
...
...
@@ -568,28 +565,28 @@ Registers a callback that is invoked when the stub on the target ability is disc
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| type | string | Yes| Event type. The value is fixed at **release**.|
| callback | [OnReleaseCallBack](#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).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onWindowStageCreate(windowStage){
this.context.startAbilityByCall({
this.context.startUIAbilityByCall({
bundleName:"com.example.myservice",
abilityName:"MainAbility",
abilityName:"MainUIAbility",
deviceId:""
}).then((obj)=>{
caller=obj;
...
...
@@ -624,22 +621,22 @@ Registers a caller notification callback, which is invoked when the target abili
**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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| method | string | Yes| Notification message string negotiated between the two abilities.|
| callback | [CalleeCallback](#calleecallback) | Yes| JS notification synchronization callback of the [rpc.MessageParcel](js-apis-rpc.md#messageparceldeprecated) type. The callback must return at least one empty [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) 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).
For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
**Example**
```ts
importAbilityfrom'@ohos.app.ability.UIAbility';
classMyMessageAble{
name:""
str:""
...
...
@@ -668,7 +665,7 @@ For other IDs, see [Ability Error Codes](../errorcodes/errorcode-ability.md).
pdata.readSequenceable(msg);
returnnewMyMessageAble("test1","Callee test");
}
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainUIAbilityextendsUIAbility{
onCreate(want,launchParam){
console.log('Callee onCreate is called');
try{
...
...
@@ -691,24 +688,24 @@ Deregisters a caller notification callback, which is invoked when the target abi
| (indata: rpc.MessageParcel) | Yes| No| rpc.Sequenceable | Prototype of the listener function registered by the callee.|
| (indata: [rpc.MessageParcel](js-apis-rpc.md#messageparceldeprecated)) | Yes| No| [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) | Prototype of the listener function registered by the callee.|
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.
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 UIAbility A needs to start UIAbility B and transfer some data to UIAbility B, it can use Want a carrier to transfer the data.
> **NOTE**
>
...
...
@@ -18,26 +18,26 @@ import Want from '@ohos.app.ability.Want';
| 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.|
| deviceId | string | No | ID of the device running the ability. If this field is unspecified, the local device is used. |
| bundleName | string | No | Bundle name of the ability.|
| moduleName | string | No| Name of the module to which the ability belongs.|
| 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:<br>**ohos.aafwk.callerPid**: PID of the caller.<br>**ohos.aafwk.param.callerToken**: token of the caller.<br>**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\<string> | 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.|
| [action](js-apis-app-ability-wantConstant.md#wantConstant.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. For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](application-models/explicit-implicit-want-mappings.md). |
| [entities](js-apis-app-ability-wantConstant.md#wantConstant.Entity) | Array\<string> | No| Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types.|
| uri | string | No| Data carried. This field is used together with **type** to specify the data type. If **uri** is specified in a Want, the Want 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.|
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>- **ohos.aafwk.callerPid**: PID of the caller.<br>- **ohos.aafwk.param.callerToken**: token of the caller.<br>- **ohos.aafwk.param.callerUid**: UID in [BundleInfo](js-apis-bundleManager-bundleInfo.md#bundleinfo-1), that is, the application UID in the bundle information. |
| [flags](js-apis-ability-wantConstant.md#wantconstantflags) | number | No| How the **Want** object will be handled. By default, a number is passed in.<br>For example, **wantConstant.Flags.FLAG_ABILITY_CONTINUATION** specifies whether to start the ability in cross-device migration scenarios.|
**Example**
- Basic usage
- Basic usage (called in a UIAbility object, where context in the example is the context object of the UIAbility).
```ts
varwant={
letwant={
"deviceId":"",// An empty deviceId indicates the local device.
"bundleName":"com.extreme.test",
"abilityName":"MainAbility",
"bundleName":"com.example.myapplication",
"abilityName":"FuncAbility",
"moduleName":"entry"// moduleName is optional.
};
this.context.startAbility(want,(error)=>{
...
...
@@ -46,13 +46,13 @@ import Want from '@ohos.app.ability.Want';
})
```
- Data is transferred through user-defined fields. The following data types are supported:
- Data is transferred through user-defined fields. The following data types are supported (called in a UIAbility object, where context in the example is the context object of the UIAbility):
* String
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForString: "str",
},
...
...
@@ -61,8 +61,8 @@ import Want from '@ohos.app.ability.Want';
* Number
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForInt: 100,
keyForDouble: 99.99,
...
...
@@ -72,8 +72,8 @@ import Want from '@ohos.app.ability.Want';
* Boolean
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForBool: true,
},
...
...
@@ -82,8 +82,8 @@ import Want from '@ohos.app.ability.Want';
* Object
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForObject: {
keyForObjectString: "str",
...
...
@@ -97,8 +97,8 @@ import Want from '@ohos.app.ability.Want';
* Array
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "FuncAbility",
parameters: {
keyForArrayString: ["str1", "str2", "str3"],
keyForArrayInt: [100, 200, 300, 400],
...
...
@@ -110,16 +110,16 @@ import Want from '@ohos.app.ability.Want';
The **app.ability.WantAgent** module provides APIs for creating and comparing **WantAgent** objects, and obtaining the user ID and bundle name of a **WantAgent** object. You are advised to use this module, since it will replace the [@ohos.wantAgent](js-apis-wantAgent.md) module in the near future.
@@ -44,7 +44,7 @@ Enumerates the action constants of the **Want** object.
| 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. | |
| 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.<br>**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.<br>**System API**: This is a system API and cannot be called by third-party applications. |
...
...
@@ -56,7 +56,7 @@ Enumerates the action constants of the **Want** object.
## wantConstant.Entity
Enumerates the entity constants of the **Want** object.
Enumerates the entity constants of the **Want** object.**entity** specifies additional information of the target ability.
| 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.<br>**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.<br>**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.<br>**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.|
The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information.
...
...
@@ -48,20 +48,17 @@ Creates a **FormBindingData** object.
| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the **FormExtensionAbility**. This context is inherited from **ExtensionContext**.|
| context | [FormExtensionContext](js-apis-inner-application-formExtensionContext.md) | Yes | No | Context of the FormExtensionAbility. This context is inherited from [ExtensionContext](js-apis-inner-application-extensionContext.md).|
## onAddForm
...
...
@@ -33,7 +33,7 @@ Called to notify the widget provider that a **Form** instance (widget) has been
| 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.|
| want | [Want](js-apis-application-want.md) | Yes | Want information related to the FormExtensionAbility, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
**Return value**
...
...
@@ -45,17 +45,19 @@ Called to notify the widget provider that a **Form** instance (widget) has been
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.
Called to notify the widget provider that a widget has been updated. After obtaining the latest data, your application should call [updateForm](js-apis-app-form-formProvider.md#updateform) of **formProvider** to update the widget data.
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.
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**
>
...
...
@@ -28,31 +28,32 @@ Deletes a widget. After this API is called, the application can no longer use th
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is deleted, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -115,27 +118,29 @@ Releases a widget. After this API is called, the application can no longer use t
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -155,27 +160,29 @@ Releases a widget. After this API is called, the application can no longer use t
| -------------- | ------ | ---- | ----------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is released, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -239,27 +248,29 @@ Requests a widget update. This API uses an asynchronous callback to return the r
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is updated, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -323,27 +336,29 @@ Converts a temporary widget to a normal one. This API uses an asynchronous callb
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -406,27 +423,29 @@ Instructs the widget framework to make a widget visible. After this API is calle
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -489,27 +510,29 @@ Instructs the widget framework to make a widget invisible. After this API is cal
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -572,27 +597,29 @@ Instructs the widget framework to make a widget updatable. After this API is cal
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -655,27 +684,29 @@ Instructs the widget framework to make a widget not updatable. After this API is
| 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.|
| 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, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -735,20 +768,21 @@ Checks whether the system is ready. This API uses an asynchronous callback to re
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **error** is undefined; otherwise, **error** is an error object.|
@@ -795,21 +830,23 @@ Obtains the widget information provided by all applications on the device. This
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.|
@@ -858,28 +897,30 @@ Obtains the widget information provided by a given application on the device. Th
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -899,28 +940,30 @@ Obtains the widget information provided by a given application on the device. Th
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -983,22 +1028,24 @@ Deletes invalid widgets from the list. This API uses an asynchronous callback to
| 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.|
| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **error** is undefined and **data** is the number of widgets deleted; otherwise, **error** is an error object.|
@@ -1053,20 +1102,22 @@ Obtains the widget state. This API uses an asynchronous callback to return the r
| 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.|
| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.|
| callback | AsyncCallback<[formInfo.FormStateInfo](js-apis-app-form-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **error** is undefined and **data** is the widget state obtained; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -1103,25 +1154,27 @@ Obtains the widget state. This API uses a promise to return the result.
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------- |
| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state.|
| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.|
@@ -1160,6 +1213,8 @@ Subscribes to widget uninstall events. This API uses an asynchronous callback to
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letcallback=function(formId){
console.log('formHost on formUninstall, formId:'+formId);
}
...
...
@@ -1179,11 +1234,13 @@ Unsubscribes from widget uninstall events. This API uses an asynchronous callbac
| 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.|
| 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.<br> The value must be the same as that in **on("formUninstall")**.|
**Example**
```ts
importformHostfrom'@ohos.app.form.formHost';
letcallback=function(formId){
console.log('formHost on formUninstall, formId:'+formId);
}
...
...
@@ -1206,27 +1263,29 @@ Instructs the widgets to make themselves visible. This API uses an asynchronous
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -1291,27 +1352,29 @@ Instructs the widgets to enable or disable updates. This API uses an asynchronou
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -1375,29 +1440,30 @@ Shares a specified widget with a remote device. This API uses an asynchronous ca
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **error** is undefined; otherwise, **error** 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result. If privacy protection is set successfully, **error** is undefined; otherwise, **error** is an error object.|
The **FormInfo** module provides widget information and state.
The **formInfo** module provides types and enums related to the widget information and state.
> **NOTE**
>
...
...
@@ -30,11 +30,11 @@ Describes widget information.
| 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. |
| formVisibleNotify | boolean | 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.|
| updateDuration | number | 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. |
...
...
@@ -101,7 +101,7 @@ Enumerates the widget parameters.
| moduleName | Only the information about the widget whose **moduleName** is the same as the provided value is returned.|
| Name | Type | Description |
| ----------- | ---- | ------------ |
| moduleName | string | Optional. Only the information about the widget whose **moduleName** is the same as the provided value is returned.<br>If this parameter is not set, **moduleName** is not used for filtering. |
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.
...
...
@@ -31,23 +31,25 @@ Sets the next refresh time for a widget. This API uses an asynchronous callback
| 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
@@ -193,29 +201,31 @@ Obtains the application's widget information on the device. This API uses an asy
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------- |
| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.|
| callback | AsyncCallback<Array<[formInfo.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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
| callback | AsyncCallback<Array<[FormInfo](js-apis-app-form-formInfo.md)>> | Yes| Callback used to return the information obtained.|
| callback | AsyncCallback<Array<[formInfo.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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>"ohos.extra.param.key.form_dimension"<br>"ohos.extra.param.key.form_name"<br>"ohos.extra.param.key.module_name" |
| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.|
| 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>"ohos.extra.param.key.form_dimension"<br>"ohos.extra.param.key.form_name"<br>"ohos.extra.param.key.module_name" |
| formBindingData.FormBindingData | [FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | No | Data used for creating the widget. |
| formBindingData | [formBindingData.FormBindingData](js-apis-app-form-formBindingData.md#formbindingdata) | No | Data used for creating the widget. |
**Return value**
...
...
@@ -434,13 +451,15 @@ Requests to publish a widget to the widget host. This API uses a promise to retu
| 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).
| 401 | Incorrect input parameter.|
|For details about the error codes, see [Form Error Codes](../errorcodes/errorcode-form.md).|
The **appControl** module provides APIs for setting, obtaining, and deleting the disposed status of an application. An application in the disposed state is forbidden to run. When a user clicks the application icon on the home screen, the corresponding page is displayed based on the disposal intent.
The **AbilityConstant** module provides ability launch parameters.
The parameters include the initial launch reasons, reasons for the last exit, and ability continuation results.
The **AbilityConstant** module defines the ability-related enums, including the initial launch reasons, reasons for the last exit, ability continuation results, and window modes.
> **NOTE**
>
> 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 are supported since API version 9 and are deprecated in versions later than 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
...
...
@@ -21,12 +19,12 @@ import AbilityConstant from '@ohos.application.AbilityConstant';
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 8. 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 8 and deprecated since API version 9. You are advised to use [@ohos.app.ability.abilityDelegatorRegistry](js-apis-app-ability-abilityDelegatorRegistry.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version.
The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context.
The **AbilityLifecycleCallback** module provides callbacks, such as **onAbilityCreate**, **onWindowStageCreate**, and **onWindowStageDestroy**, to receive lifecycle state changes in the application context. These callbacks can be used as an input parameter of [registerAbilityLifecycleCallback](js-apis-inner-application-applicationContext.md#applicationcontextregisterabilitylifecyclecallback).
> **NOTE**
>
> 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 are supported since API version 9 and are deprecated in versions later than 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.
...
...
@@ -25,9 +25,9 @@ Called when an ability is created.
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 8. 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 8 and deprecated since API version 9. You are advised to use [@ohos.app.ability.abilityManager](js-apis-app-ability-abilityManager.md) instead. 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.
| callback | AsyncCallback\<Array\<AbilityRunningInfo>> | Yes | Callback used to return the result. |
| callback | AsyncCallback\<Array\<[AbilityRunningInfo](js-apis-inner-application-abilityRunningInfo.md)>> | Yes | Callback used to return the result. |
| upperLimit | number | Yes| Maximum number of messages that can be obtained.|
| callback | AsyncCallback\<Array\<AbilityRunningInfo>> | Yes | Callback used to return the result. |
| callback | AsyncCallback\<Array\<[ExtensionRunningInfo](js-apis-inner-application-extensionRunningInfo.md)>> | Yes | Callback used to return the result. |
| want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, such as the ability name and bundle name.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility, 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.|
| Type| Description|
| -------- | -------- |
| string | Returns a UIAbility ID. If this UIAbility has been started, no new instance is created and the UIAbility is placed at the top of the stack. Otherwise, a new instance is created and started.|
**Example**
...
...
@@ -76,9 +76,9 @@ Called when the global configuration is updated.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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**
...
...
@@ -100,9 +100,9 @@ Called when the system has decided to adjust the memory level. For example, this
**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.|
| 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**
...
...
@@ -118,10 +118,10 @@ Called when the system has decided to adjust the memory level. For example, this
context: AbilityStageContext;
Describes the configuration information about the context.
Defines the **Context** object of **AbilityStage**.
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.
...
...
@@ -9,7 +9,7 @@ The **appManager** module implements application management. You can use the API
console.log('The process running infos is:'+JSON.stringify(data));
}).catch((error)=>{
console.log('failed:'+JSON.stringify(error));
console.log('error:'+JSON.stringify(error));
});
```
...
...
@@ -199,14 +198,14 @@ Obtains information about the running processes. This API uses an asynchronous c
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback\<Array\<ProcessRunningInfo>> | Yes| Obtains information about the running processes. This API uses a promise to return the result.|
| callback | AsyncCallback\<Array\<[ProcessRunningInfo](js-apis-inner-application-processRunningInfo.md)>> | 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.getProcessRunningInfos((err,data)=>{
console.log('error:'+JSON.stringify(err));
console.log('The process running infos is:'+JSON.stringify(data));
})
```
...
...
@@ -229,10 +228,10 @@ Obtains information about the running processes. This API uses a promise to retu
Obtains applications that are running in the foreground. This API uses an asynchronous callback to return the result.
Obtains information about the applications that are running in the foreground. This API uses an asynchronous callback to return the result. The application information is defined by [AppStateData](js-apis-inner-application-appStateData.md).
@@ -432,7 +431,7 @@ Obtains applications that are running in the foreground. This API uses an asynch
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| callback | AsyncCallback\<Array\<AppStateData>> | Yes| Callback used to return the application state data.|
| callback | AsyncCallback\<Array\<[AppStateData](js-apis-inner-application-appStateData.md)>> | Yes| Callback used to return the application information.|
**Example**
...
...
@@ -444,14 +443,14 @@ Obtains applications that are running in the foreground. This API uses an asynch
Obtains applications that are running in the foreground. This API uses a promise to return the result.
Obtains information about the applications that are running in the foreground. This API uses a promise to return the result. The application information is defined by [AppStateData](js-apis-inner-application-appStateData.md).
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
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user) and ohos.permission.CLEAN_BACKGROUND_PROCESSES
@@ -491,17 +490,17 @@ Kills a process by bundle name and account ID. This API uses a promise to return
**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).|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
@@ -521,15 +520,15 @@ Kills a process by bundle name and account ID. This API uses an asynchronous cal
**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
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user) 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\<void\> | Yes| Callback used to return the result.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| bundleName | string | Yes| Bundle name.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Example**
...
...
@@ -543,7 +542,7 @@ function killProcessWithAccountCallback(err, data) {
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.
The **EnvironmentCallback** module provides the **onConfigurationUpdated** API for the application context to listen for system environment changes.
The **EnvironmentCallback** module provides APIs, such as **onConfigurationUpdated** and **onMemoryLevel**, for the application context to listen for system environment changes.
> **NOTE**
>
> 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 are supported since API version 9 and are deprecated in versions later than 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.
...
...
@@ -25,18 +25,32 @@ Called when the system environment changes.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-application-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.|
The **errorManager** module provides APIs for registering and deregistering error observers.
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.
> The APIs of this module are supported since API version 9 and are deprecated in versions later than API version 9. You are advised to use [@ohos.app.ability.errorManager](js-apis-app-ability-errorManager.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version.
The **ExtensionAbility** module manages the Extension ability lifecycle and context, such as creating and destroying an Extension ability, and dumping client information.
The **ExtensionAbility** module manages the ExtensionAbility lifecycle and context, such as creating and destroying an ExtensionAbility, and dumping client information.
The **FormBindingData** module provides APIs for widget data binding. You can use the APIs to create a **FormBindingData** object and obtain related information.
...
...
@@ -48,16 +48,17 @@ Creates a **FormBindingData** object.
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.
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.
> 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
...
...
@@ -34,10 +34,12 @@ Deletes a widget. After this API is called, the application can no longer use th
@@ -242,15 +260,17 @@ Converts a temporary widget to a normal one. This API uses an asynchronous callb
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is converted to a normal one, **error** is undefined; otherwise, **error** is an error object.|
@@ -303,15 +325,17 @@ Instructs the widget framework to make a widget visible. After this API is calle
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget visible, **error** is undefined; otherwise, **error** is an error object.|
@@ -364,15 +390,17 @@ Instructs the widget framework to make a widget invisible. After this API is cal
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget invisible, **error** is undefined; otherwise, **error** is an error object.|
@@ -425,15 +455,17 @@ Instructs the widget framework to make a widget updatable. After this API is cal
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If a notification is sent to the widget framework to make the widget updatable, **error** is undefined; otherwise, **error** is an error object.|
@@ -486,15 +520,17 @@ Instructs the widget framework to make a widget not updatable. After this API is
| 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.|
| 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, **error** is undefined; otherwise, **error** is an error object.|
@@ -544,15 +582,17 @@ Checks whether the system is ready. This API uses an asynchronous callback to re
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the check is successful, **error** is undefined; otherwise, **error** is an error object.|
@@ -596,14 +638,16 @@ Obtains the widget information provided by all applications on the device. This
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.|
@@ -651,14 +697,16 @@ Obtains the widget information provided by a given application on the device. Th
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.|
@@ -681,14 +729,16 @@ Obtains the widget information provided by a given application on the device. Th
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](js-apis-application-formInfo.md)>> | Yes| Callback used to return the result. If the widget information is obtained, **error** is undefined and **data** is the information obtained; otherwise, **error** is an error object.|
@@ -743,15 +795,17 @@ Deletes invalid widgets from the list. This API uses an asynchronous callback to
| 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.|
| callback | AsyncCallback<number> | Yes| Callback used to return the result. If the invalid widgets are deleted, **error** is undefined and **data** is the number of widgets deleted; otherwise, **error** is an error object.|
@@ -805,13 +861,15 @@ Obtains the widget state. This API uses an asynchronous callback to return the r
| 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.|
| want | [Want](js-apis-application-want.md) | Yes | **Want** information carried to query the widget state. The information must contain the bundle name, ability name, module name, widget name, and widget dimensions.|
| callback | AsyncCallback<[formInfo.FormStateInfo](js-apis-application-formInfo.md#formstateinfo)> | Yes| Callback used to return the result. If the widget state is obtained, **error** is undefined and **data** is the widget state obtained; otherwise, **error** is an error object.|
@@ -890,6 +950,8 @@ Subscribes to widget uninstall events. This API uses an asynchronous callback to
**Example**
```ts
importformHostfrom'@ohos.application.formHost';
letcallback=function(formId){
console.log('formHost on formUninstall, formId:'+formId);
}
...
...
@@ -909,11 +971,13 @@ Unsubscribes from widget uninstall events. This API uses an asynchronous callbac
| 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.|
| 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.<br> The value must be the same as that in **on("formUninstall")**.|
**Example**
```ts
importformHostfrom'@ohos.application.formHost';
letcallback=function(formId){
console.log('formHost on formUninstall, formId:'+formId);
}
...
...
@@ -936,15 +1000,17 @@ Instructs the widgets to make themselves visible. This API uses an asynchronous
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.|
@@ -999,15 +1067,17 @@ Instructs the widgets to enable or disable updates. This API uses an asynchronou
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the notification is sent, **error** is undefined; otherwise, **error** is an error object.|
@@ -1061,16 +1133,18 @@ Shares a specified widget with a remote device. This API uses an asynchronous ca
| ------ | ------ | ---- | ------- |
| 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.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result. If the widget is shared, **error** is undefined; otherwise, **error** is an error object.|
The **FormInfo** module provides widget information and state.
The **formInfo** module provides types and enums related to the 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.
> This module is deprecated since API version 9. You are advised to use [formInfo](js-apis-app-form-formInfo.md) instead.
## Modules to Import
...
...
@@ -31,11 +31,11 @@ Describes widget information.
| 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. |
| formVisibleNotify | boolean | 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.|
| updateDuration | number | 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. |
...
...
@@ -102,7 +102,7 @@ Enumerates the widget parameters.
| FORM_VISIBLE<sup>9+<sup> | 1 | The card is visible. |
| FORM_INVISIBLE<sup>9+<sup> | 2 | The card is invisible.|
## FormInfoFilter<sup>9+</sup>
Defines the widget information filter. Only the widget information that meets the filter is returned.
...
...
@@ -138,7 +127,7 @@ Defines the widget information filter. Only the widget information that meets th
| Name | Description |
| ----------- | ------------ |
| moduleName<sup>9+</sup> | Only the information about the widget whose **moduleName** is the same as the provided value is returned.|
| moduleName<sup>9+</sup> | Optional. Only the information about the widget whose **moduleName** is the same as the provided value is returned.<br>If this parameter is not set, **moduleName** is not used for filtering.|
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.
> This module is deprecated since API version 9. You are advised to use [formProvider](js-apis-app-form-formProvider.md) instead.
## Modules to Import
...
...
@@ -31,7 +31,9 @@ Sets the next refresh time for a widget. This API uses an asynchronous callback
| formId | string | Yes | ID of the widget to update.|
| formBindingData.FormBindingData | [FormBindingData](js-apis-application-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.|
| formId | string | Yes | ID of the widget to update.|
| formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdat) | 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. |
**Return value**
...
...
@@ -125,7 +131,9 @@ Updates a widget. This API uses a promise to return the result.
@@ -146,11 +154,13 @@ Obtains the application's widget information on the device. This API uses an asy
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ------- |
| callback | AsyncCallback<Array<[FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.|
| callback | AsyncCallback<Array<[FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.|
| callback | AsyncCallback<Array<[formInfo.FormInfo](./js-apis-application-formInfo.md#forminfo-1)>> | Yes| Callback used to return the information obtained.|
| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>"ohos.extra.param.key.form_dimension"<br>"ohos.extra.param.key.form_name"<br>"ohos.extra.param.key.module_name" |
| formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.|
| 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.|
| want | [Want](js-apis-application-want.md) | Yes | Request used for publishing. The following fields must be included:<br>Information about the target widget.<br>**abilityName**: ability of the target widget.<br>**parameters**:<br>"ohos.extra.param.key.form_dimension"<br>"ohos.extra.param.key.form_name"<br>"ohos.extra.param.key.module_name" |
| formBindingData.FormBindingData | [FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | No | Data used for creating the widget. |
| formBindingData | [formBindingData.FormBindingData](js-apis-application-formBindingData.md#formbindingdata) | Yes | Data used for creating the widget.|
**Return value**
...
...
@@ -329,7 +346,9 @@ Requests to publish a widget to the widget host. This API uses a promise to retu
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 8. 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 8 and deprecated since API version 9. You are advised to use [@ohos.app.ability.missionManager](js-apis-app-ability-missionManager.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
...
...
@@ -32,13 +32,13 @@ Registers a listener to observe the mission status.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listener | [MissionListener](js-apis-inner-application-missionListener.md) | Yes| Listener to register.|
| listener | [MissionListener](js-apis-inner-application-missionListener.md) | Yes| Mission status 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.|
| number | Index of the mission status listener, which is created by the system and allocated when the listener is registered.|
**Example**
...
...
@@ -73,7 +73,7 @@ Deregisters a mission status listener. This API uses an asynchronous callback to
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.|
| listenerId | number | Yes| Index of the mission status listener to deregister. It is returned by **registerMissionListener()**.|
| callback | AsyncCallback<void> | Yes| Callback used to return the result.|
**Example**
...
...
@@ -113,7 +113,7 @@ Deregisters a mission status listener. This API uses a promise to return the res
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| listenerId | number | Yes| Unique index of the mission status listener to unregister. It is returned by **registerMissionListener**.|
| listenerId | number | Yes| Index of the mission status listener to deregister. It is returned by **registerMissionListener()**.|
**Return value**
...
...
@@ -169,7 +169,12 @@ Obtains the information about a given mission. This API uses an asynchronous cal
The **ServiceExtensionAbility** module provides APIs for Service 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 are supported since API version 9 and are deprecated in versions later than 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
...
...
@@ -40,9 +43,9 @@ Called when a Service Extension ability is created to initialize the service log
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-want.md) | Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
**Example**
...
...
@@ -88,10 +91,10 @@ Called after **onCreate** is invoked when a Service Extension ability is started
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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**
...
...
@@ -116,15 +119,15 @@ Called after **onCreate** is invoked when a Service Extension ability is started
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want | [Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| 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**
| Type| Description|
| -------- | -------- |
| rpc.RemoteObject | A **RemoteObject** object used for communication with the client.|
| Type| Description|
| -------- | -------- |
| rpc.RemoteObject | A **RemoteObject** object used for communication with the client.|
**Example**
...
...
@@ -158,9 +161,9 @@ Called when this Service Extension ability is disconnected.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
**Example**
...
...
@@ -184,9 +187,9 @@ Called when this Service Extension ability is reconnected.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| want |[Want](js-apis-application-want.md)| Yes| Want information related to this Service Extension ability, including the ability name and bundle name.|
**Example**
...
...
@@ -210,9 +213,9 @@ Called when the configuration of this Service Extension ability is updated.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| config | [Configuration](js-apis-application-configuration.md) | Yes| New configuration.|
**Example**
...
...
@@ -236,9 +239,9 @@ Dumps the client information.
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| params | Array\<string> | Yes| Parameters in the form of a command.|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| params | Array\<string> | Yes| Parameters in the form of a command.|
The **StartOptions** module implements ability startup options.
> **NOTE**
>
> 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 are supported since API version 9 and are deprecated in versions later than 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.
The **StaticSubscriberExtensionAbility** module provides Extension abilities for static subscribers.
> **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
...
...
@@ -26,9 +27,10 @@ Callback of the common event of a static subscriber.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| event | [CommonEventData](js-apis-commonEvent.md#commoneventdata) | Yes| Common event of a static subscriber.|
| event | [CommonEventData](js-apis-commonEventManager.md#commoneventdata) | Yes| Common event of a static subscriber.|
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.
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.
> The APIs of this module are supported since API version 8 and deprecated since API version 9. You are advised to use [Want](js-apis-app-ability-want.md) instead. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
...
...
@@ -18,26 +18,26 @@ import Want from '@ohos.application.Want';
| 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.|
| deviceId | string | No | ID of the device running the ability. If this field is unspecified, the local device is used. |
| bundleName | string | No | Bundle name.|
| 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. |
| 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. For details, see [action](js-apis-app-ability-wantConstant.md#wantConstant.Action). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>**ohos.aafwk.callerPid**: PID of the caller.<br>**ohos.aafwk.param.callerToken**: token of the caller.<br>**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\<string> | 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. |
| entities | Array\<string> | No | Additional category information (such as browser and video player) of the ability. It is a supplement to the **action** field for implicit Want. and is used to filter ability types. For details, see [entity](js-apis-app-ability-wantConstant.md#wantConstant.Entity). |
| moduleName<sup>9+</sup> | string | No | Module to which the ability belongs.|
**Example**
- Basic usage
- Basic usage (called in a UIAbility object, where context in the example is the context object of the UIAbility).
```ts
varwant={
letwant={
"deviceId":"",// An empty deviceId indicates the local device.
"bundleName":"com.extreme.test",
"abilityName":"MainAbility",
"bundleName":"com.example.myapplication",
"abilityName":"EntryAbility",
"moduleName":"entry"// moduleName is optional.
};
this.context.startAbility(want,(error)=>{
...
...
@@ -46,13 +46,13 @@ import Want from '@ohos.application.Want';
})
```
- Data is transferred through user-defined fields. The following data types are supported:
- Data is transferred through user-defined fields. The following data types are supported (called in a UIAbility object, where context in the example is the context object of the UIAbility):
* String
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
parameters: {
keyForString: "str",
},
...
...
@@ -61,8 +61,8 @@ import Want from '@ohos.application.Want';
* Number
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
parameters: {
keyForInt: 100,
keyForDouble: 99.99,
...
...
@@ -72,8 +72,8 @@ import Want from '@ohos.application.Want';
* Boolean
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
parameters: {
keyForBool: true,
},
...
...
@@ -82,8 +82,8 @@ import Want from '@ohos.application.Want';
* Object
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
parameters: {
keyForObject: {
keyForObjectString: "str",
...
...
@@ -97,8 +97,8 @@ import Want from '@ohos.application.Want';
* Array
```ts
let want = {
bundleName: "com.example.demo",
abilityName: "com.example.demo.MainAbility",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
parameters: {
keyForArrayString: ["str1", "str2", "str3"],
keyForArrayInt: [100, 200, 300, 400],
...
...
@@ -110,16 +110,16 @@ import Want from '@ohos.application.Want';
**WindowExtensionAbility** inherits from **ExtensionAbility**. The content in a **WindowExtensionAbility** object can be displayed as an ability component in other application windows.
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.
| 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**.|
| direction<sup>9+</sup> | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.|
| screenDensity<sup>9+</sup> | 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<sup>9+</sup> | number | Yes| No| ID of the display where the application is located.|
| hasPointerDevice<sup>9+</sup> | boolean | Yes| No| Whether a pointer device, such as a keyboard, mouse, or touchpad, is connected.|
> 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 **distributedBundle** module provides APIs for managing distributed bundles.
> **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
```
import distributedBundle from '@ohos.bundle.distributedBundle';
| callback | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the **RemoteAbilityInfo** object obtained. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10. |
| callback | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)>> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the array of **RemoteAbilityInfo** objects obtained. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
|----------|-------------------------|
| 17700001 | The specified bundle name is not found. |
| 17700003 | The specified ability name is not found. |
| 17700007 | The specified device ID is not found. |
| 17700027 | The distributed service is not running. |
| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)>> | Promise used to return the array of **RemoteAbilityInfo** objects obtained.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
|----------|-------------------------|
| 17700001 | The specified bundle name is not found. |
| 17700003 | The specified ability name is not found. |
| 17700007 | The specified device ID is not found. |
| 17700027 | The distributed service is not running. |
Obtains information about the remote ability that matches the given element name and locale. This API uses an asynchronous callback to return the result.
| callback | AsyncCallback<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the **RemoteAbilityInfo** object obtained. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
|----------|-------------------------|
| 17700001 | The specified bundle name is not found. |
| 17700003 | The specified ability name is not found. |
| 17700007 | The specified device ID is not found. |
| 17700027 | The distributed service is not running. |
Obtains information about remote abilities that match the given element names and locales. This API uses an asynchronous callback to return the result.
| elementNames | Array<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | **ElementName** array, whose maximum length is 10. |
| locale | string |Yes| Target locale.|
| callback | AsyncCallback\<Array\<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)>> | Yes | Callback used to return the result. If the operation is successful, **err** is **null** and **data** is the array of **RemoteAbilityInfo** objects obtained. Otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID | Error Message |
|---------------|-------------------------|
| 17700001 | The specified bundle name is not found. |
| 17700003 | The specified ability name is not found. |
| 17700007 | The specified device ID is not found. |
| 17700027 | The distributed service is not running. |
| Promise\<Array<[RemoteAbilityInfo](js-apis-bundleManager-remoteAbilityInfo.md)>> | Promise used to return the array of **RemoteAbilityInfo** objects obtained.|
**Error codes**
For details about the error codes, see [Bundle Error Codes](../errorcodes/errorcode-bundle.md).
| ID| Error Message |
|----------|-------------------------|
| 17700001 | The specified bundle name is not found. |
| 17700003 | The specified ability name is not found. |
| 17700007 | The specified device ID is not found. |
| 17700027 | The distributed service is not running. |
The **AbilityResult** module defines the result code and data returned when an ability is started or destroyed.
The **AbilityResult** module defines the result code and data returned when an ability is terminated after being started. You can use [startAbilityForResult](js-apis-ability-context.md#abilitycontextstartabilityforresult) to obtain the **AbilityResult** object returned after the started ability is terminated. The startedability returns the **AbilityResult** object by calling [terminateSelfWithResult](js-apis-ability-context.md#abilitycontextterminateselfwithresult).
> **NOTE**
>
...
...
@@ -10,17 +10,5 @@ The **AbilityResult** module defines the result code and data returned when an a
| Name | Readable | Writable | Type | Mandatory| Description |
The **ConnectOptions** module defines the options for connection.
**ConnectOptions** can be used as an input parameter to receive status changes during the connection to a background service. For example, it is used as an input parameter of [connectServiceExtensionAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextconnectserviceextensionability) to connect to a ServiceExtensionAbility.
The **DataAbilityHelper** object is obtained through [acquireDataAbilityHelper](js-apis-ability-featureAbility.md#featureabilityacquiredataabilityhelper7).
> **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.
...
...
@@ -9,15 +11,15 @@
Import the following modules based on the actual situation before using the current module:
| type | string | Yes | Type of the event to observe. The value is **dataChange**. |
| type | string | Yes | The value **dataChange** means data changes. |
| uri | string | Yes | URI of the data.|
| callback | AsyncCallback\<void> | No | Callback used to return the result. |
| callback | AsyncCallback\<void> | No | Callback of the listener to deregister. If the callback is set to **null**, all data change listeners are canceled. |
| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".|
| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | A list of data operations on the database. |
| callback | AsyncCallback\<Array\<[DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md)>> | Yes |Callback used to return the result of each operation in the **DataAbilityResult** array. |
| uri | string | Yes | URI of the DataAbility. Example: "dataability:///com.example.xxx.xxxx".|
| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | An array holding the data operations on the database. |
| callback | AsyncCallback\<Array\<[DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md)>> | Yes |Callback used to return the result of each operation in the **DataAbilityResult** array. |
**Example**
...
...
@@ -955,7 +898,9 @@ import featureAbility from '@ohos.ability.featureAbility';
// Select the operations to be performed on the database according to the DataAbilityOperation array.
| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx".|
| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | A list of data operations on the database. |
| uri | string | Yes | URI of the DataAbility. Example: "dataability:///com.example.xxx.xxxx".|
| operations | Array\<[DataAbilityOperation](js-apis-inner-ability-dataAbilityOperation.md)> | Yes | An array holding the data operations on the database. |
**Return value**
| Type| Description|
|------ | ------- |
|Promise\<Array\<[DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md)>> | Callback used to return the result of each operation in the **DataAbilityResult** array.|
|Promise\<Array\<[DataAbilityResult](js-apis-inner-ability-dataAbilityResult.md)>> | Promise used to return the result of each operation in the **DataAbilityResult** array.|
**Example**
...
...
@@ -993,8 +938,10 @@ import featureAbility from '@ohos.ability.featureAbility';
// Select the operations to be performed on the database according to the DataAbilityOperation array.
The **DataAbilityOperation** module defines the operation on Data abilities.
The **DataAbilityOperation** module defines the operation on DataAbilities. It can be used as an input parameter of [executeBatch](js-apis-inner-ability-dataAbilityHelper.md#dataabilityhelperexecutebatch) to specify the database operation information.
> **NOTE**
>
...
...
@@ -11,7 +11,7 @@ The **DataAbilityOperation** module defines the operation on Data abilities.
| Name | Template | Mandatory| Description |
| -------- | -------- | --------| -------- |
| uri | string | Yes | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". |
| uri | string | Yes | URI of the DataAbility. 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. |
...
...
@@ -19,48 +19,3 @@ The **DataAbilityOperation** module defines the operation on Data abilities.
| predicatesBackReferences? | Map\<number, number> | 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. |
The **DataAbilityResult** module defines the operation result on Data abilities.
The **DataAbilityResult** module defines the operation result on DataAbilities. When you call [executeBatch](js-apis-inner-ability-dataAbilityHelper.md#dataabilityhelperexecutebatch) to operate the database, the operation result is returned through the **DataAbilityResult** object.
> **NOTE**
>
...
...
@@ -11,33 +11,36 @@ The **DataAbilityResult** module defines the operation result on Data abilities.
| Name | Type | Mandatory | Description |
| -------- | -------- | -------- | -------- |
| uri? | string | No | URI of the Data ability. Example: "dataability:///com.example.xxx.xxxx". |
| uri? | string | No | URI of the DataAbility. Example: "dataability:///com.example.xxx.xxxx". |
| count? | number | No | Number of rows affected by the operation. |
The **StartAbilityParameter** module defines the parameters for starting an ability.
The **StartAbilityParameter** module defines the parameters for starting an ability. The parameters can be used as input parameters in [startAbility](js-apis-ability-featureAbility.md#featureabilitystartability) to start the specified ability.
> **NOTE**
>
...
...
@@ -11,8 +11,8 @@ The **StartAbilityParameter** module defines the parameters for starting an abil
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.
Want is a carrier for information transfer between objects (application components). Want can be used as a parameter of [startAbility](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) 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**
>
...
...
@@ -10,26 +10,26 @@ Want is a carrier for information transfer between objects (application componen
| 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.|
| deviceId | string | No | ID of the device running the ability. If this field is unspecified, the local device is used. |
| bundleName | string | No | Bundle name.|
| 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. |
| 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. For details, see [action](js-apis-app-ability-wantConstant.md#wantConstant.Action). For details about the definition and matching rules of implicit Want, see [Matching Rules of Explicit Want and Implicit Want](application-models/explicit-implicit-want-mappings.md). |
| parameters | {[key: string]: any} | No | Want parameters in the form of custom key-value (KV) pairs. By default, the following keys are carried:<br>**ohos.aafwk.callerPid**: PID of the caller.<br>**ohos.aafwk.param.callerToken**: token of the caller.<br>**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\<string> | 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. |
| entities | Array\<string> | 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. For details, see [entity](js-apis-app-ability-wantConstant.md#wantConstant.Entity). |
| moduleName<sup>9+</sup> | string | No | Module to which the ability belongs.|
**Example**
- Basic usage
- Basic usage (called in a UIAbility object, where context in the example is the context object of the UIAbility).
```ts
varwant={
letwant={
"deviceId":"",// An empty deviceId indicates the local device.
"bundleName":"com.extreme.test",
"abilityName":"MainAbility",
"bundleName":"com.example.myapplication",
"abilityName":"EntryAbility",
"moduleName":"entry"// moduleName is optional.
};
this.context.startAbility(want,(error)=>{
...
...
@@ -38,20 +38,22 @@ Want is a carrier for information transfer between objects (application componen
})
```
- Passing a file descriptor (FD)
- Passing a file descriptor (FD) (called in the UIAbility object, where context in the example is the context object of the UIAbility):
The **AppVersionInfo** module defines the application version information.
The **AppVersionInfo** module defines the application version information. You can use [getAppVersionInfo](js-apis-inner-app-context.md#contextgetappversioninfo7) to obtain the version information of the current application.
> 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.
| Name | Type | Readable | Writable | Description |
| ----------- | ------ | ---- | ---- | ------- |
| appName | string | Yes | No | Module name. |
| versionCode | number | Yes | No | Module description.|
@@ -5,11 +5,12 @@ 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 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:
The **Context** object is created in a **featureAbility** and returned through its [getContext](js-apis-ability-featureAbility.md#featureabilitygetcontext) API. Therefore, you must import the **@ohos.ability.featureAbility** package before using the **Context** module. An example is as follows:
| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-Bundle.md#displayorientation)> | Yes | Callback used to return the display orientation.|
| callback | AsyncCallback\<[bundle.DisplayOrientation](js-apis-bundleManager.md#displayorientation)> | Yes | Callback used to return the display orientation.|
**Example**
...
...
@@ -376,7 +378,7 @@ Obtains the display orientation of this ability. This API uses a promise to retu
| callback | AsyncCallback\<[ElementName](js-apis-bundle-ElementName.md)> | Yes | Callback used to return the **ohos.bundle.ElementName** object.|
| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | Yes | Callback used to return the **ohos.bundle.ElementName** object.|
**Example**
...
...
@@ -701,7 +703,7 @@ This API is available only to Page abilities.
| callback | AsyncCallback\<string> | Yes | Callback used to return the distributed file path. If the distributed file path does not exist, the system will create one and return the created path.|
| callback | AsyncCallback\<string> | Yes | Callback used to return the distributed file path.<br>If the path does not exist, the system will create one and return the created path.|
**Example**
...
...
@@ -951,7 +953,7 @@ If the distributed file path does not exist, the system will create one and retu
The **ProcessInfo** module defines process information.
The **ProcessInfo** module defines process information. You can use [getProcessInfo](js-apis-inner-app-context.md#contextgetprocessinfo7) to obtain information about the processes running on the current ability.
> **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.
@@ -8,14 +8,11 @@ The **AbilityDelegator** module provides APIs for managing **AbilityMonitor** in
## Usage
The ability delegator can be obtained by calling **getAbilityDelegator** in **AbilityDelegatorRegistry**.
An **AbilityDelegator** object is obtained by calling [getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator) in **AbilityDelegatorRegistry**.
The **AbilityDelegatorArgs** module provides a global register to store the registered **AbilityDelegator** and **AbilityDelegatorArgs** instances during application startup.
The **AbilityDelegatorArgs** module provides APIs to obtain an **AbilityDelegatorArgs** object during the execution of test cases.
> **NOTE**
>
...
...
@@ -8,7 +8,7 @@ The **AbilityDelegatorArgs** module provides a global register to store the regi
## Usage
The ability delegator arguments are obtained by calling **getArguments** in **AbilityDelegatorRegistry**.
An **AbilityDelegatorArgs** object is obtained by calling [getArguments](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetarguments) in **AbilityDelegatorRegistry**.
@@ -8,7 +8,7 @@ The **AbilityMonitor** module provides monitors for abilities that meet specifie
## Usage
The ability monitor can be set by calling **addAbilityMonitor** in **abilityDelegator**.
**AbilityMonitor** can be used as an input parameter of [addAbilityMonitor](js-apis-inner-application-abilityDelegator.md#addabilitymonitor9) in **abilityDelegator** to listen for lifecycle changes of an ability.
@@ -8,7 +8,7 @@ The **AbilityRunningInfo** module defines the running information and state of a
## Usage
The ability running information is obtained by using the **getAbilityRunningInfos** API in **abilityManager**.
The ability running information is obtained by calling [getAbilityRunningInfos](js-apis-app-ability-abilityManager.md#getabilityrunninginfos) in **abilityManager**.
The **AbilityStateData** module defines the ability state information.
The **AbilityStateData** module defines the ability state information, which can be obtained through the **onAbilityStateChanged** lifecycle callback of [ApplicationStateObserver](js-apis-inner-application-applicationStateObserver.md). The callback can be invoked after a lifecycle change listener is registered through [registerApplicationStateObserver](js-apis-application-appManager.md#appmanagerregisterapplicationstateobserver8).
The **ApplicationStateObserver** module defines the listener to observe the application state.
The **ApplicationStateObserver** module defines an observer to listen for application state changes. It can be used as an input parameter in [registerApplicationStateObserver](js-apis-application-appManager.md#appmanagerregisterapplicationstateobserver8) to listen for lifecycle changes of the current application.
| onForegroundApplicationChanged<sup>8+</sup> | AsyncCallback\<void> | Yes | No | Callback invoked when the foreground or background state of an application changes. |
| onAbilityStateChanged<sup>8+</sup> | AsyncCallback\<void> | Yes | No | Callback invoked when the ability state changes. |
| onProcessCreated<sup>8+</sup> | AsyncCallback\<void> | Yes | No | Callback invoked when a process is created. |
| onProcessDied<sup>8+</sup> | AsyncCallback\<void> | Yes | No | Callback invoked when a process is destroyed. |
| onProcessStateChanged<sup>8+</sup> | AsyncCallback\<void> | Yes | No | Callback invoked when the process state is changed. |
| Name | | Type | Readable| Writable| Description |
| onForegroundApplicationChanged<sup>8+</sup> | [AppStateData](js-apis-inner-application-appStateData.md) | AsyncCallback\<void> | Yes | No | Callback invoked when the foreground or background state of an application changes. |
| onAbilityStateChanged<sup>8+</sup> | [AbilityStateData](js-apis-inner-application-abilityStateData.md) | AsyncCallback\<void> | Yes | No | Callback invoked when the ability state changes. |
| onProcessCreated<sup>8+</sup> | [ProcessData](js-apis-inner-application-processData.md) | AsyncCallback\<void> | Yes | No | Callback invoked when a process is created. |
| onProcessDied<sup>8+</sup> | [ProcessData](js-apis-inner-application-processData.md) | AsyncCallback\<void> | Yes | No | Callback invoked when a process is destroyed. |
| onProcessStateChanged<sup>8+</sup> | [ProcessData](js-apis-inner-application-processData.md) | AsyncCallback\<void> | Yes | No | Callback invoked when the process state is changed. |
The abstract class **BaseContext** specifies whether its child class **Context** is used for the stage model or FA model.
**BaseContext** is an abstract class that specifies whether a child class **Context** is used for the stage model or FA model. It is the parent class for all types of **Context**.
> **NOTE**
>
...
...
@@ -10,14 +10,19 @@ The abstract class **BaseContext** specifies whether its child class **Context**
| Name | Type | Readable | Writable | Description |
| -------- | ------ | ---- | ---- | ------- |
| stageMode | boolean | Yes | Yes | Whether the context is used for the stage model.|
| stageMode | boolean | Yes | Yes | Whether the child class **Context** is used for the stage model.<br>**true**: used for the stage model.<br>**false**: used for the FA model.|
**Example**
```ts
classMyContextextendsBaseContext{
constructor(stageMode){
this.stageMode=stageMode;
}
Take the stage model as an example. You can access the **stageMode** field through **UIAbilityContext**.
The **Context** module provides context for abilities or applications. It allows access to application-specific resources, as well as permission requests and verification.
The **Context** module provides context for abilities or applications. It allows access to application-specific resources.
> **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.
> - 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
...
...
@@ -13,8 +13,8 @@ The **Context** module provides context for abilities or applications. It allows
| Name | Type | Readable | Writable | Description |
| ----------- | ------ | ---- | ---- | ------- |
| resourceManager | resmgr.ResourceManager | Yes | No | Object for resource management. |
The **ContinueCallback** module defines the callback invoked when the mission continuation is complete.
The **ContinueCallback** module defines the callback function that indicates the result of mission continuation. For details about mission continuation, see [continueMission](js-apis-distributedMissionManager.md#distributedmissionmanagercontinuemission).
| onContinueDone | function | Yes | No | Callback used to notify the user that the mission continuation is complete and return the continuation result. |
**Parameters**
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| result | number | No| Mission continuation result.|
The **ContinueDeviceInfo** module defines the parameters required for mission continuation.
The **ContinueDeviceInfo** module defines the parameters required for initiating mission continuation. For details about mission continuation, see [continueMission](js-apis-distributedMissionManager.md#distributedmissionmanagercontinuemission).
The **ErrorObserver** module defines the listener to observe errors.
The **ErrorObserver** module defines an observer to listen for application errors. It can be used as an input parameter in [ErrorManager.on](js-apis-app-ability-errorManager.md#errormanageron) to listen for errors that occur in the current application.
## onUnhandledException
## ErrorObserver.onUnhandledException
onUnhandledException(errMsg: string): void;
...
...
@@ -19,12 +19,18 @@ Called when an unhandled exception occurs in the JS runtime.
@@ -4,21 +4,23 @@ The **EventHub** module provides APIs to subscribe to, unsubscribe from, and tri
> **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.
> - 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
Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **Ability** instance.
Before using any APIs in the **EventHub**, you must obtain an **EventHub** instance through the member variable **context** of the **UIAbility** instance.
// Anonymous functions can be used to subscribe to events.
this.context.eventHub.on("myEvent",()=>{
console.log("call anonymous eventFunc");
});
// Result
// func1 is called
// call anonymous func 1
this.context.eventHub.emit("123");
}
func1(){
console.log("func1 is called");
}
// eventFunc is called
// call anonymous eventFunc
this.context.eventHub.emit("myEvent");
}
```
eventFunc(){
console.log("eventFunc is called");
}
}
```
## EventHub.off
off(event: string, callback?: Function): void;
Unsubscribes from an event. If **callback** is specified, this API unsubscribes from the specified callback. If **callback** is not specified, this API unsubscribes from all callbacks in the event.
Unsubscribes from an event.
- If **callback** is specified, this API unsubscribes from the given event with the specified callback.
- If **callback** is not specified, this API unsubscribes from the given event with all callbacks.
The **ExtensionRunningInfo** module provides running information and states for Extension abilities.
The **ExtensionRunningInfo** module encapsulates ExtensionAbility running information, which can be obtained through [getExtensionRunningInfos](js-apis-app-ability-abilityManager.md#getextensionrunninginfos).
> **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.
> - 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 marked as @systemapi and not visible to third-party applications.
## Usage
The Extension ability running information is obtained through an **abilityManager** instance.
Import the **abilityManager** module and obtain the ExtensionAbility running information by calling the method in the **abilityManager** module.
## Attributes
...
...
@@ -17,21 +17,28 @@ The Extension ability running information is obtained through an **abilityManage
The **MissionCallbacks** module defines the callbacks that can be registered as a mission status listener.
The **MissionCallback** module defines the callbacks invoked after synchronization starts. These callbacks can be used as input parameters in [registerMissionListener](js-apis-distributedMissionManager.md#distributedmissionmanagerregistermissionlistener).
| notifyMissionsChanged(deviceId: string) | function | Yes | No | Callback used to notify the mission change event and return the device ID. |
| notifySnapshot(deviceId: string, mission: number) | function | Yes | No | Callback used to notify the snapshot change event and return the device ID and mission ID. |
| notifyNetDisconnect(deviceId: string, state: number) | function | Yes | No | Callback used to notify the disconnection event and return the device ID and network status.|
The **MissionDeviceInfo** module defines the parameters required for registering a listener.
The **MissionDeviceInfo** module defines the parameters required for registering a listener. It can be used as an input parameter in [registerMissionListener](js-apis-distributedMissionManager.md#distributedmissionmanagerregistermissionlistener).
The **MissionInfo** module defines the mission information of an ability.
The **MissionInfo** module defines detailed information about a mission. The information can be obtained through [getMissionInfo](js-apis-app-ability-missionManager.md#missionmanagergetmissioninfo).
The **MissionParameter** module defines the parameters required for mission synchronization.
The **MissionParameter** module defines the parameters required for mission synchronization. It can be used an input parameter in [startSyncRemoteMissions](js-apis-distributedMissionManager.md#distributedmissionmanagerstartsyncremotemissions).
The **MissionSnapshot** module provides the mission snapshot information of an ability.
The **MissionSnapshot** module defines the snapshot of a mission. The snapshot can be obtained through [getMissionSnapShot](js-apis-app-ability-missionManager.md#missionmanagergetmissionsnapshot).
> **NOTE**
>
...
...
@@ -11,7 +11,7 @@ The **MissionSnapshot** module provides the mission snapshot information of an a
The **ProcessData** module defines process data. If a lifecycle change listener is registered by calling [registerApplicationStateObserver](js-apis-application-appManager.md#appmanagerregisterapplicationstateobserver8), the **onProcessCreated** callback in [ApplicationStateObserver](js-apis-inner-application-applicationStateObserver.md) is invoked when the lifecycle of an application or ability changes.
| pid<sup>8+</sup> | number | Yes | No | Process ID. |
| bundleName<sup>8+</sup> | string | Yes | No | Bundle name of the application. |
| uid<sup>8+</sup> | number | Yes | No | User ID. |
| isContinuousTask<sup>9+</sup> | boolean | Yes | No | Whether the process is a continuous task. |
| isKeepAlive<sup>9+</sup> | boolean | Yes | No | Whether the process remains active. |
| uid<sup>8+</sup> | number | Yes | No | UID of the application. |
| isContinuousTask<sup>9+</sup> | boolean | Yes | No | Whether the task is a continuous task. The value **true** means that the task is a continuous task, and **false** means the opposite. |
| isKeepAlive<sup>9+</sup> | boolean | Yes | No | Whether the process is a resident task. The value **true** means that the process is a resident, and **false** means the opposite. |
| state<sup>9+</sup> | number | Yes | No | Application state. The value can be **0** (newly created), **2** (foreground), **4** (background), or **5** (terminated). |
The **ProcessRunningInfo** module provides process running information.
The **ProcessRunningInfo** module defines the running information of a process.
> **NOTE**
> - The APIs provided by this module are deprecated since API version 9. You are advised to use [ProcessRunningInformation<sup>9+</sup>](js-apis-inner-application-processRunningInformation.md) instead.
...
...
@@ -19,12 +19,13 @@ The **ProcessRunningInfo** module provides process running information.
## Usage
The process running information is obtained through [getProcessRunningInfos](js-apis-application-appManager.md##appManager.getProcessRunningInfos<sup>(deprecated)</sup>).
The process running information is obtained by using [getProcessRunningInfos](js-apis-application-appManager.md#appmanagergetprocessrunninginfosdeprecated) in **appManager**.
The **ProcessRunningInformation** module provides process running information.
The **ProcessRunningInformation** module defines the running information of a process.
> **NOTE**
>
...
...
@@ -8,12 +8,13 @@ The **ProcessRunningInformation** module provides process running information.
## How to Use
The process running information is obtained through [appManager](js-apis-application-appManager.md#appmanagergetprocessrunninginformation9).
The process running information is obtained through [getProcessRunningInformation](js-apis-application-appManager.md#appmanagergetprocessrunninginformation9) in **appManager**.
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the account ID and start options specified. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the account ID specified. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
@@ -1077,16 +1092,16 @@ Connects this ability to a Service ability.
**Parameters**
| 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-inner-ability-connectOptions.md) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
| 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-inner-ability-connectOptions.md) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
**Return value**
| Type| Description|
| -------- | -------- |
| number | A number, based on which the connection will be interrupted.|
| Type| Description|
| -------- | -------- |
| number | A number, based on which the connection will be interrupted.|
**Error codes**
...
...
@@ -1165,8 +1180,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"EntryAbility"
};
varaccountId=100;
varoptions={
...
...
@@ -1189,7 +1204,7 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect
Starts an ability in the foreground or background and obtains the caller object for communicating with the ability.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
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.
**UIAbilityContext**, inherited from [Context](js-apis-inner-application-context.md), provides the context environment for [UIAbility](js-apis-app-ability-uiAbility.md). **UIAbilityContext** provides UIAbility-related configuration and APIs for operating UIAbilities and ServiceExtensionAbilities. For example, you can use the APIs to start a UIAbility, terminate a UIAbility to which the UIAbilityContext belongs, and start, terminate, connect to, or disconnect from a ServiceExtensionAbility.
> **NOTE**
>
...
...
@@ -15,16 +13,24 @@ This module provides APIs for accessing ability-specific resources. You can use
| config | [Configuration](js-apis-app-ability-configuration.md) | Yes| No| UIAbility configuration, such as the language and color mode.|
> **NOTE**
> - In the sample code provided in this topic, **this.context** is used to obtain **UIAbilityContext**, where **this** indicates a UIAbility instance inherited from **UIAbility**. To use **UIAbilityContext** capabilities on pages, see [Obtaining the Context of UIAbility](../../application-models/uiability-usage.md#obtaining-the-context-of-uiability).
Starts an ability. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the start options specified. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability with the 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. After the ability is started, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses an asynchronous callback to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses a promise to return the result when the ability is terminated.
Starts an ability. After the ability is started, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability and return the result to the caller. If an exception occurs, for example, the ability is killed, exception information is returned to the caller. This API uses a promise to return the result.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
Starts an ability. This API uses an asynchronous callback to return the result when the account of the ability is destroyed.
Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
@@ -461,8 +493,8 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| callback | AsyncCallback\<AbilityResult\> | Yes| Callback used to return the result.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.|
**Error codes**
...
...
@@ -494,7 +526,7 @@ Starts an ability. This API uses an asynchronous callback to return the result w
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -509,23 +541,28 @@ Starts an ability. This API uses an asynchronous callback to return the result w
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.
Starts an ability with the start options and account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
@@ -536,9 +573,9 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| 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.|
| callback | AsyncCallback\<void\> | Yes| Callback invoked when the ability is terminated.|
**Error codes**
...
...
@@ -570,7 +607,7 @@ Starts an ability with the start options specified. This API uses an asynchronou
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -579,7 +616,7 @@ Starts an ability with the start options specified. This API uses an asynchronou
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
@@ -615,14 +656,14 @@ Starts an ability with the start options specified. This API uses a promise to r
| 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).|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| 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.|
| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise used to return the ability result when the ability is terminated.|
**Error codes**
...
...
@@ -654,7 +695,7 @@ Starts an ability with the start options specified. This API uses a promise to r
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -676,15 +717,15 @@ Starts an ability with the start options specified. This API uses a promise to r
@@ -817,8 +858,8 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ServiceExtensionAbility.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Error codes**
...
...
@@ -840,8 +881,8 @@ Starts a new Service Extension ability with the account ID specified. This API u
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"ServiceExtensionAbility"
};
varaccountId=100;
...
...
@@ -858,18 +899,18 @@ Starts a new Service Extension ability with the account ID specified. This API u
@@ -880,7 +921,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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
**Error codes**
...
...
@@ -905,8 +946,8 @@ Starts a new Service Extension ability with the account ID specified. This API u
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"ServiceExtensionAbility"
};
varaccountId=100;
...
...
@@ -923,15 +964,15 @@ Starts a new Service Extension ability with the account ID specified. This API u
@@ -1058,8 +1099,8 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ServiceExtensionAbility.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Error codes**
...
...
@@ -1082,8 +1123,8 @@ Stops a Service Extension ability in the same application with the account ID sp
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"ServiceExtensionAbility"
};
varaccountId=100;
...
...
@@ -1100,18 +1141,18 @@ Stops a Service Extension ability in the same application with the account ID sp
@@ -1121,8 +1162,8 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ServiceExtensionAbility.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
**Error codes**
...
...
@@ -1144,8 +1185,8 @@ Stops a Service Extension ability in the same application with the account ID sp
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
abilityName:"MainAbility"
bundleName:"com.example.myapplication",
abilityName:"ServiceExtensionAbility"
};
varaccountId=100;
...
...
@@ -1162,12 +1203,12 @@ Stops a Service Extension ability in the same application with the account ID sp
Terminates this ability. This API uses an asynchronous callback to return the ability result information. It is used together with **startAbilityForResult**.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of a callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
Terminates this ability. This API uses a promise to return the ability result information. It is used together with **startAbilityForResult**.
Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called.
@@ -1384,8 +1439,8 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to
| 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.|
| want | [Want](js-apis-application-want.md) | Yes| Want information for connecting to the ServiceExtensionAbility.|
| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.|
**Return value**
...
...
@@ -1410,13 +1465,19 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template to connect this ability to
@@ -1447,8 +1508,8 @@ 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.|
| 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | Yes| Instance of the callback function after the connection to the ServiceExtensionAbility is set up.|
**Return value**
...
...
@@ -1474,14 +1535,20 @@ Uses the **AbilityInfo.AbilityType.SERVICE** template and account ID to connect
@@ -1508,7 +1575,7 @@ Disconnects a connection. This API uses a promise to return the result.
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| connection | number | Yes| Result code of the ability connection.|
| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.|
**Return value**
...
...
@@ -1551,11 +1618,11 @@ Disconnects a connection. This API uses a promise to return the result.
@@ -1565,7 +1632,7 @@ Disconnects a connection. This API uses an asynchronous callback to return the r
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| connection | number | Yes| Result code of the ability connection.|
| connection | number | Yes| Digital code of the connected ServiceExtensionAbility, that is, connectionId returned by **connectServiceExtensionAbility**.|
| callback | AsyncCallback\<void> | Yes| Callback used to return the result.|
**Error codes**
...
...
@@ -1603,12 +1670,17 @@ Disconnects a connection. This API uses an asynchronous callback to return the r
Starts an ability in the foreground or background and obtains the caller object for communicating with the ability.
Observe the following when using this API:
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- The rules for using this API in the same-device and cross-device scenarios are different. For details, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
@@ -1707,7 +1784,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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| callback | AsyncCallback\<void\> | Yes| Callback used to return the result.|
**Error codes**
...
...
@@ -1740,7 +1817,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -1764,13 +1841,18 @@ Starts an ability with the account ID specified. This API uses an asynchronous c
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
@@ -1781,8 +1863,8 @@ 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.|
| 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| 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**
...
...
@@ -1815,7 +1897,7 @@ Starts an ability with the account ID and start options specified. This API uses
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -1836,19 +1918,24 @@ Starts an ability with the account ID and start options specified. This API uses
- If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission.
- If **visible** of the target ability is **false** in cross-application scenarios, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission.
- For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md).
**Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS (required only when the account ID is not the current user)
@@ -1859,7 +1946,7 @@ 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.|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).|
| accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getCreatedOsAccountsCount).|
| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.|
**Error codes**
...
...
@@ -1892,7 +1979,7 @@ Starts an ability with the account ID specified. This API uses a promise to retu
```ts
varwant={
deviceId:"",
bundleName:"com.extreme.test",
bundleName:"com.example.myapplication",
abilityName:"MainAbility"
};
varaccountId=100;
...
...
@@ -1913,71 +2000,12 @@ Starts an ability with the account ID specified. This API uses a promise to retu
| permissions | Array<string> | Yes| Permissions to request.|
| callback | AsyncCallback<[PermissionRequestResult](js-apis-inner-application-permissionRequestResult.md)> | Yes| Callback used to return the result.|
The **WantAgentInfo** module defines the information required for triggering the WantAgent.
The **WantAgentInfo** module defines the information required for triggering a **WantAgent** object. The information can be used as an input parameter in [getWantAgent](js-apis-app-ability-wantAgent.md#wantagentgetwantagent) to obtain a specified **WantAgent** object.
| 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. |
| wantAgentFlags | Array<[wantAgent.WantAgentFlags](js-apis-app-ability-wantAgent.md#wantagentflags)> | No | Array of flags for using the **WantAgent** object. |
| extraInfo | {[key: string]: any} | No | Extra information. |
The **PermissionRequestResult** module defines the result of a permission request. The result is returned when [requestPermissionsFromUser](js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9) is called to request permissions.
> **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.
| authResults | Array<number> | Yes| No| Whether the requested permissions are granted. The value **0** means that the requests permissions are granted, and a non-zero value means the opposite.|
## Usage
The permission request result is obtained through an **atManager** instance.
Checks whether two **WantAgent** objects are equal to determine whether the same operation is from the same application. This API uses an asynchronous callback to return the result.
Checks whether two **WantAgent** objects are equal to determine whether the same operation is from the same application. This API uses a promise to return the result.
