@@ -7,7 +7,7 @@ import featureAbility from '@ohos.ability.featureAbility'
...
@@ -7,7 +7,7 @@ import featureAbility from '@ohos.ability.featureAbility'
importbundlefrom'@ohos.bundle'
importbundlefrom'@ohos.bundle'
```
```
The **Context** object is created in a **featureAbility** and returned through its **getContext()**method. 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()**API. Therefore, you must import the **@ohos.ability.featureAbility** package before using the Context module. An example is as follows:
| 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.|
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
## Modules to Import
```js
```js
...
@@ -12,15 +15,17 @@ getId(uri: string): number
...
@@ -12,15 +15,17 @@ getId(uri: string): number
Obtains the ID attached to the end of a given URI.
Obtains the ID attached to the end of a given URI.
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.|
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core|
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information about the ability to start, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started.|
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information about the ability to start, including the ability name, bundle name, and device ID. If the device ID is left blank or the default value is used, the local ability will be started.|
- Return value
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<> | Promise used to return the caller object to communicate with.|
| Promise<Caller> | Promise used to return the caller object to communicate with.|
| permissions | Array<string> | Yes| Permissions to request.|
| permissions | Array<string> | Yes| Permissions to request.|
| callback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback used to return the result indicating whether the method is successfully called.|
| callback | AsyncCallback<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Yes| Callback used to return the result indicating whether the API is successfully called.|
| permissions | Array<string> | Yes| Permissions to request.|
| permissions | Array<string> | Yes| Permissions to request.|
**Return value**
- Return value
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result indicating whether the method is successfully called.|
| Promise<[PermissionRequestResult](js-apis-permissionrequestresult.md)> | Promise used to return the result indicating whether the API is successfully called.|
> The 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 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Manages the ability lifecycle and context.
Manages the ability lifecycle and context.
...
@@ -14,31 +14,33 @@ Manages the ability lifecycle and context.
...
@@ -14,31 +14,33 @@ Manages the ability lifecycle and context.
| context | [AbilityContext](js-apis-ability-context.md) | Yes| No| Context of an ability.|
| context | [AbilityContext](js-apis-ability-context.md) | Yes| No| Context of an ability.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore|
| launchWant | [Want](js-apis-featureAbility.md#Want)| Yes| No| Parameters for starting the ability.|
| launchWant | [Want](js-apis-featureAbility.md#Want)| Yes| No| Parameters for starting the ability.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore|
| lastRequestWant | [Want](js-apis-featureAbility.md#Want)| Yes| No| Parameters used when the ability was started last time.|
| lastRequestWant | [Want](js-apis-featureAbility.md#Want)| Yes| No| Parameters used when the ability was started last time.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore|
| 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.|
| 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.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
- Return value
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<void> | Promise used to return a response.|
| Promise<void> | Promise used to return a response.|
- Example
**Example**
```
```js
importAbilityfrom'@ohos.application.Ability';
importAbilityfrom'@ohos.application.Ability';
classMyMessageAble{// Custom sequenceable data structure
classMyMessageAble{// Custom sequenceable data structure
num: 0
constructor(name,str){
str: ''
this.name=name;
constructor() {}
this.str=str;
}
marshalling(messageParcel){
marshalling(messageParcel){
messageParcel.writeInt(this.num);
messageParcel.writeInt(this.num);
messageParcel.writeString(this.str);
messageParcel.writeString(this.str);
...
@@ -279,47 +310,59 @@ Sends sequenceable data to the target ability.
...
@@ -279,47 +310,59 @@ Sends sequenceable data to the target ability.
varcaller;
varcaller;
exportdefaultclassMainAbilityextendsAbility{
exportdefaultclassMainAbilityextendsAbility{
onWindowStageCreate(windowStage){
onWindowStageCreate(windowStage){
caller = await this.context.startAbilityByCall({
this.context.startAbilityByCall({
bundleName: "com.example.myservice",
bundleName:"com.example.myservice",
abilityName: "com.example.myservice.MainAbility",
abilityName:"com.example.myservice.MainAbility",
deviceId: ""
deviceId:""
});
}).then((obj)=>{
let msg = new MyMessageAble(1, "world"); // See the definition of Sequenceable.
caller=obj;
caller.call(method, msg)
letmsg=newMyMessageAble(1,"world");// See the definition of Sequenceable.
| 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.|
| 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.|
| data | rpc.Sequenceable | Yes| Sequenceable data. You need to customize the data.|
- Return value
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| Promise<rpc.MessageParcel> | Promise used to return the sequenceable data from the target ability.|
| Promise<rpc.MessageParcel> | Promise used to return the sequenceable data from the target ability.|
- Example
**Example**
```
```js
importAbilityfrom'@ohos.application.Ability';
importAbilityfrom'@ohos.application.Ability';
classMyMessageAble{
classMyMessageAble{
num: 0
constructor(name,str){
str: ''
this.name=name;
this.str=str;
}
constructor(){}
constructor(){}
marshalling(messageParcel){
marshalling(messageParcel){
messageParcel.writeInt(this.num);
messageParcel.writeInt(this.num);
...
@@ -338,83 +381,104 @@ Sends sequenceable data to the target ability and obtains the sequenceable data
...
@@ -338,83 +381,104 @@ Sends sequenceable data to the target ability and obtains the sequenceable data
| method | string | Yes| Notification message string negotiated between the two abilities.|
| method | string | Yes| Notification message string negotiated between the two abilities.|
| callback | function | 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.|
| callback | CaleeCallBack | 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.|
- Example
**Example**
```
```js
importAbilityfrom'@ohos.application.Ability';
importAbilityfrom'@ohos.application.Ability';
classMyMessageAble{
classMyMessageAble{
num: 0
constructor(name,str){
str: ''
this.name=name;
constructor() {}
this.str=str;
}
marshalling(messageParcel){
marshalling(messageParcel){
messageParcel.writeInt(this.num);
messageParcel.writeInt(this.num);
messageParcel.writeString(this.str);
messageParcel.writeString(this.str);
...
@@ -474,20 +542,23 @@ Registers a caller notification callback, which is invoked when the target abili
...
@@ -474,20 +542,23 @@ Registers a caller notification callback, which is invoked when the target abili
```
```
### off
## Callee.off
off(method: string): void;
off(method: string): void;
Unregisters a caller notification callback, which is invoked when the target ability registers a function.
Unregisters a caller notification callback, which is invoked when the target ability registers a function.
| (msg: string) | function | Yes| No| Prototype of the listener function interface registered by the caller.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore |
| (indata: rpc.MessageParcel) | rpc.Sequenceable | Yes| No| Prototype of the message listener function interface registered by the callee.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore |
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Runtime class for HAP files. It provides methods to notify you when a HAP file starts loading. You can then initialize the HAP file, for example, pre-load resources and create threads.
Runtime class for HAP files. It provides APIs to notify you when a HAP file starts loading. You can then initialize the HAP file, for example, pre-load resources and create threads.
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information about the ability to start, such as the ability name and bundle name.|
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information about the ability to start, such as the ability name and bundle name.|
- Return value
**Return value**
| Type| Description|
| 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.|
| 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.|
| config | [Configuration](js-apis-configuration.md) | Yes| Callback invoked when the global configuration is updated. The global configuration indicates the configuration of the environment where the application is running and includes the language and color mode.|
| config | [Configuration](js-apis-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.|
| context | [AbilityStageContext](js-apis-featureAbility.md) | Called when initialization is performed during ability startup.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core|
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
| callback | AsyncCallback<boolean> | No| Callback used to return the result.|
| callback | AsyncCallback<boolean> | No| Callback used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.|
| Promise<boolean> | Promise used to return the result.|
| Promise<boolean> | Promise used to return the result. If the application is undergoing a stability test, **true** will be returned; otherwise, **false** will be returned.|
- Example
**Example**
```
```js
importappfrom'@ohos.application.appManager';
importappfrom'@ohos.application.appManager';
app.isRunningInStabilityTest().then((flag)=>{
app.isRunningInStabilityTest().then((flag)=>{
console.log('success:'+JSON.stringfy(flag));
console.log('success:'+JSON.stringfy(flag));
)).catch((error) => {
}).catch((error)=>{
console.log('failed:'+JSON.stringfy(error));
console.log('failed:'+JSON.stringfy(error));
});
});
```
```
## appManager.isRamConstrainedDevice
isRamConstrainedDevice(): Promise\<boolean>;
Checks whether this application is running in a RAM constrained device. This API uses a promise to return the result.
| Promise<boolean> | Promise used to return whether the the application is running in a RAM constrained device. If the the application is running in a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.|
| callback | AsyncCallback<boolean> | No| Callback used to return whether the the application is running in a RAM constrained device. If the the application is running in a RAM constrained device, **true** will be returned; otherwise, **false** will be returned.|
**Example**
```js
IsRamConstrainedDeviceCallBack(){
app.isRamConstrainedDevicePromise((err,data)=>{
console.log('startAbility result failed:'+JSON.stringify(err));
console.log('startAbility result success:'+JSON.stringify(data));
})
}
```
## appManager.getAppMemorySize
getAppMemorySize(): Promise\<number>;
Obtains the memory size of this application. This API uses a promise to return the result.
| language | string | Yes| Yes| Language of the application.|
| 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**.|
| 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 | Direction | Yes| No| Screen orientation, which can be **DIRECTION_HORIZONTAL** or **DIRECTION_VERTICAL**.|
| direction<sup>9+</sup> | 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).|
| 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 | number | Yes| No| ID of the display where the application is located.|
| displayId<sup>9+</sup> | number | Yes| No| ID of the display where the application is located.|
| Promise\<string> | Promise used to return the normalized URI object if the Data ability supports URI normalization. If the Data ability does not support URI normalization, **null** is returned.|
| Promise\<string> | Promise used to return the normalized URI object if the Data ability supports URI normalization. If the Data ability does not support URI normalization, **null** is returned.|
Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: string, callback: AsyncCallback\<string>)** to a denormalized one. This method uses a callback to return the result.
Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: string, callback: AsyncCallback\<string>)** to a denormalized one. This API uses an asynchronous callback to return the result.
Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: string)** to a denormalized one. This method uses a promise to return the result.
Converts a normalized URI generated by **DataAbilityHelper.normalizeUri(uri: string)** to a denormalized one. This API uses a promise to return the result.
@@ -10,11 +10,11 @@ Implements event subscription, unsubscription, and triggering.
...
@@ -10,11 +10,11 @@ Implements event subscription, unsubscription, and triggering.
## Usage
## Usage
Before using any methods 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 **Ability** instance.
Unsubscribes from an event. If **callback** is specified, this method unsubscribes from the specified callback. If **callback** is not specified, this method unsubscribes from all callbacks in the event.
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.
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
...
@@ -11,4 +11,4 @@ Implements the extension context. This module is inherited from **Context**.
...
@@ -11,4 +11,4 @@ Implements the extension context. This module is inherited from **Context**.
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.<br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| currentHapModuleInfo | HapModuleInfo | Yes| No| Information about the current HAP.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core |
> 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.
## Constraints
## Constraints
APIs of the **FeatureAbility** module can be called only by Page abilities.
APIs of the **FeatureAbility** module can be called only by Page abilities.
| deviceId | Read-only | string | No | Device ID of the Service ability to connect. The default value is the local device ID.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| deviceId | Read-only | string | No | Device ID of the Service ability to connect. The default value is the local device ID.|
| bundleName | Read-only | string | Yes | Bundle name of the Service ability to connect.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| bundleName | Read-only | string | Yes | Bundle name of the Service ability to connect. |
| abilityName | Read-only | string | Yes | Class name of the Service ability to connect.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| abilityName | Read-only | string | Yes | Class name of the Service ability to connect. |
| onConnect | Read-only | function | Yes | Callback invoked when the connection is successful.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.Core |
| onConnect | Read-only | function | Yes | Callback invoked when the connection is successful. |
| onDisconnect | Read-only | function | Yes | Callback invoked when the connection fails.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.Core |
| onDisconnect | Read-only | function | Yes | Callback invoked when the connection fails. |
| onFailed | Read-only | function | Yes | Callback invoked when **connectAbility** fails to be called.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.Core|
| onFailed | Read-only | function | Yes | Callback invoked when **connectAbility** fails to be called.|
**Return value**
**Return value**
| Type | Description |
| Type | Description |
| ------ | ------------------------ |
| ------ | ------------------------ |
| number | Returns the ID of the Service ability connected.|
| number | Returns the ID of the Service ability connected.|
...
@@ -566,15 +549,13 @@ var connId = featureAbility.connectAbility(
...
@@ -566,15 +549,13 @@ var connId = featureAbility.connectAbility(
| WINDOW_MODE_UNDEFINED<sup>7+</sup> | 0 | The Page ability is in an undefined window display mode.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel |
| WINDOW_MODE_FULLSCREEN<sup>7+</sup> | 1 | The Page ability is in full screen mode.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel |
| WINDOW_MODE_SPLIT_PRIMARY<sup>7+</sup> | 100 | The Page ability is displayed in the primary window when it is in split-screen mode.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel|
| WINDOW_MODE_SPLIT_SECONDARY<sup>7+</sup> | 101 | The Page ability is displayed in the secondary window when it is in split-screen mode.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel|
| WINDOW_MODE_FLOATING<sup>7+</sup> | 102 | The Page ability is displayed in floating window mode.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.FAModel |
## 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**.
The value is obtained through the **featureAbility.AbilityStartSetting** API.
| resultCode | Read-only | number | Yes | Result code returned after the ability is destroyed. The feature for defining error-specific result codes is coming soon.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| resultCode<sup>7+</sup> | Read-only | number | Yes | Result code returned after the ability is destroyed. The feature for defining error-specific result codes is coming soon.|
| want | Read-only | [Want](#want) | No | Data returned after the ability is destroyed. You can define the data to be returned. This parameter can be **null**.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| want<sup>7+</sup> | Read-only | [Want](#want) | No | Data returned after the ability is destroyed. You can define the data to be returned. This parameter can be **null**. |
| want | Read-only | [Want](#want) | Yes | Information about the ability to start.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel |
| want | Read-only | [Want](#want) | Yes | Information about the ability to start. |
| abilityStartSetting | Read-only | {[key: string]: any} | No | Special attribute of the ability to start. This attribute can be passed in the method call.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel|
| abilityStartSetting | Read-only | {[key: string]: any} | No | Special attribute of the ability to start. This attribute can be passed in the method call.|
| deviceId | Read-only | string | No | ID of the device that runs the ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| deviceId<sup>8+</sup> | Read-only | string | No | ID of the device that runs the ability. |
| bundleName | Read-only | string | No | Bundle name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| bundleName<sup>8+</sup> | Read-only | string | No | Bundle name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.|
| abilityName | Read-only | string | No | Name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| abilityName<sup>8+</sup> | Read-only | string | No | Name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.|
| uri | Read-only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| uri<sup>8+</sup> | Read-only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.|
| type | Read-only | string | No | MIME type, for example, text/plain or image/*.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| type<sup>8+</sup> | Read-only | string | No | MIME type, for example, text/plain or image/*. |
| flags | Read-only | number | No | How the **Want** object will be handled. By default, a number is passed. For details, see [flags](#flags).<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| flags<sup>8+</sup> | Read-only | number | No | How the **Want** object will be handled. By default, a number is passed. For details, see [flags](#flags).|
| parameters | Read-only | {[key: string]: any} | No | List of parameters in a **Want** object.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| parameters<sup>8+</sup> | Read-only | {[key: string]: any} | No | List of parameters in a **Want** object. |
| entities | Read-only | Array\<string> | No | List of entities.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| entities<sup>8+</sup> | Read-only | Array\<string> | No | List of entities. |
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI. |
| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be migrated to a remote device. |
| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent. |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching. |
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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 the migration is reversible.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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 passed to **ohos.app.Context#startAbility** and must be used together with **flag_ABILITY_NEW_MISSION**.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object passed to **ohos.app.Context#startAbility** and must be used together with **flag_ABILITY_NEW_MISSION**.|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the historical mission stack.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| 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.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| 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 initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
| obj | Object or string| No| Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
| obj | Object or string| No | Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
| obj | Object or string| Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
| data | Object or string| Data to be displayed on the JS service widget. The value can be an object containing multiple key-value pairs or a string in JSON format.|
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
| context | [FormExtensionContext](js-apis-formextensioncontext.md) | Yes| No| Context of the **FormExtension**. This class is inherited from **ExtensionContext**.|
| context | [FormExtensionContext](js-apis-formextensioncontext.md) | Yes | No | Context of the **FormExtension**. This class is inherited from **ExtensionContext**.<br>**System capability**: SystemCapability.Ability.Form|
| want | [Want](js-apis-featureAbility.md#want) | Yes| Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
| want | [Want](js-apis-featureAbility.md#want) | Yes| Information related to the extension, including the widget ID, name, and style. The information must be managed as persistent data to facilitate subsequent widget update and deletion.|
| [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.|
| [formBindingData.FormBindingData](js-apis-formbindingdata.md#formbindingdata) | A **formBindingData.FormBindingData** object containing the data to be displayed on the widget.|
| formId | string | Yes| ID of the widget that requests to be converted to a normal one.|
| formId | string | Yes| ID of the widget that requests to be converted to a normal one.|
- Example
**Example**
```
```
export default class MyFormExtension extends FormExtension {
export default class MyFormExtension extends FormExtension {
...
@@ -77,21 +81,23 @@ Called to notify the widget provider that a temporary widget has been converted
...
@@ -77,21 +81,23 @@ Called to notify the widget provider that a temporary widget has been converted
}
}
```
```
## onUpdate
## FormExtension.onUpdate
onUpdate(formId: string): void
onUpdate(formId: string): void
Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-formextensioncontext.md) class to update the widget data.
Called to notify the widget provider that a widget has been updated. After obtaining the latest data, the caller invokes **updateForm** of the [FormExtensionContext](js-apis-formextensioncontext.md) class to update the widget data.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
Implements the context that provides the capabilities and APIs of **FormExtension**. This class is inherited from **ExtensionContext**.
Implements the context that provides the capabilities and APIs of **FormExtension**. This class is inherited from **ExtensionContext**.
> 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.
## Constraints
## Constraints
The ParticleAbility module is used to perform operations on abilities of the Data and Service types.
The ParticleAbility module is used to perform operations on abilities of the Data and Service types.
...
@@ -12,13 +15,11 @@ import particleAbility from '@ohos.ability.particleAbility'
...
@@ -12,13 +15,11 @@ import particleAbility from '@ohos.ability.particleAbility'
| want | Read-only | [Want](#want) | Yes | Information about the ability to start.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel |
| abilityStartSetting | Read-only | {[key: string]: any} | No | Special attribute of the ability to start. This attribute can be passed in the method call.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel|
## Want
| Name | Readable/Writable| Type | Mandatory| Description |
| deviceId | Read-only | string | No | ID of the device running the ability to start.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| bundleName | Read-only | string | No | Bundle name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| abilityName | Read-only | string | No | Name of the ability to start. If both **bundleName** and **abilityName** are specified in a **Want** object, the **Want** object can directly match the specified ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| uri | Read-only | string | No | URI information to match. If **uri** is specified in a **Want** object, the **Want** object will match the specified URI information, including **scheme**, **schemeSpecificPart**, **authority**, and **path**.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| type | Read-only | string | No | MIME type, for example, **text/plain** or **image/***.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| flags | Read-only | number | No | How the **Want** object will be handled. By default, numbers are passed in. For details, see [flags](#flags).<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| parameters | Read-only | {[key: string]: any} | No | List of parameters in the **Want** object.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| entities | Read-only | Array\<string> | No | List of entities.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | Indicates the permission to read the URI.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | Indicates the permission to write the URI.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | Returns the result to the ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_CONTINUATION | 0x00000008 | Indicates whether the ability on the local device can be migrated to a remote device.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | Indicates that a component does not belong to OHOS.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | Indicates whether to enable an ability.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | Indicates the permission to make the URI persistent.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | Indicates the permission to verify URIs by prefix matching.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | Supports cross-device startup in a distributed scheduler.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | Indicates that the Service ability is started regardless of whether the host application has been started.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | Indicates that the migration is reversible.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_INSTALL_ON_DEMAND | 0x00000800 | Indicates that the specific ability will be installed if it has not been installed.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | Indicates that the specific ability will be installed in the background if it has not been installed.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | Clears other operation missions. This flag can be set for the **Want** object passed to **ohos.app.Context#startAbility** and must be used together with **flag_ABILITY_NEW_MISSION**.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
| FLAG_ABILITY_NEW_MISSION | 0x10000000 | Creates a mission on the historical mission stack.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase |
| FLAG_ABILITY_MISSION_TOP | 0x20000000 | Starts the mission on the top of the existing mission stack; creates an ability instance if no mission exists.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityBase|
## 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 special attributes of an ability, for example, **featureAbility.AbilityStartSetting.BOUNDS_KEY**.
| WINDOW_MODE_UNDEFINED | 0 | The Page ability is in an undefined window display mode.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel |
| WINDOW_MODE_FULLSCREEN | 1 | The Page ability is in full screen mode.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel |
| WINDOW_MODE_SPLIT_PRIMARY | 100 | The Page ability is displayed in the primary window when it is in split-screen mode.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel|
| WINDOW_MODE_SPLIT_SECONDARY | 101 | The Page ability is displayed in the secondary window when it is in split-screen mode.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel|
| WINDOW_MODE_FLOATING | 102 | The Page ability is displayed in floating window mode.<br><b>System capabilities:</b> SystemCapability.Ability.AbilityRuntime.FAModel |
Requests a continuous task from the system. This method uses an asynchronous callback to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests a continuous task from the system. This API uses an asynchronous callback to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests a continuous task from the system. This method uses a promise to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests a continuous task from the system. This API uses a promise to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
**Parameters**
**Parameters**
| Name| Type| Mandatory| Description|
| Name| Type| Mandatory| Description|
| -------- | -------- | -------- | -------- |
| -------- | -------- | -------- | -------- |
| id | number | Yes| Notification ID of a continuous task.|
| id | number | Yes| Notification ID of a continuous task.|
| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.|
| request | NotificationRequest | Yes| Notification parameter, which is used to display information in the notification bar.|
**Return value**
**Return value**
| Type | Description |
| Type | Description |
| -------------- | ------------------------- |
| -------------- | ------------------------- |
| Promise\<void> | Promise used to return the result.|
| Promise\<void> | Promise used to return the result.|
Requests to cancel a continuous task from the system. This method uses an asynchronous callback to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests to cancel a continuous task from the system. This API uses an asynchronous callback to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests to cancel a continuous task from the system. This method uses a promise to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
Requests to cancel a continuous task from the system. This API uses a promise to return the result. (This method is of API 7 and will be deprecated. Use the counterpart in API 8.)
| authResults | Array<number> | Yes| No| Whether the requested permissions are granted or denied. The value **0** means that the requests permissions are granted, and **-1** means the opposite. <br><b>System capability</b>: SystemCapability.Ability.AbilityRuntime.Core|
| authResults | Array<number> | Yes| No| Whether the requested permissions are granted or denied. The value **0** means that the requests permissions are granted, and **-1** means the opposite. |
| bundleNames | Array<string> | Yes| No| Names of all bundles running in the process.<br><b>System capability</b>: SystemCapability.Ability.AbilityRuntime.Core|
| bundleNames | Array<string> | Yes| No| Names of all bundles running in the process.|
| want | [Want](js-apis-featureAbility.md#Want) | Yes| Information about the ability to connect to, such as the ability name and bundle name.|
| want | [Want](js-apis-featureAbility.md#Want) | Yes| Information about the ability to connect to, such as the ability name and bundle name.|
| options | [ConnectOptions](#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
| options | [ConnectOptions](#connectoptions) | Yes| Callback used to return the information indicating that the connection is successful, interrupted, or failed.|
- Return value
**Return value**
| Type| Description|
| Type| Description|
| -------- | -------- |
| -------- | -------- |
| number | A number, based on which the connection will be interrupted.|
| number | A number, based on which the connection will be interrupted.|
| onConnect(elementName:ElementName, remote:IRemoteObject) | Called when this ability is connected to a Service ability.<br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| onConnect(elementName:ElementName, remote:IRemoteObject) | Called when this ability is connected to a Service ability.|
| onDisconnect(elementName:ElementName) | Called when the peer service is abnormal or killed.<br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| onDisconnect(elementName:ElementName) | Called when the peer service is abnormal or killed.|
| onFailed(code: number) | Called when the connection fails.<br><b>System capabilities: </b>SystemCapability.Ability.AbilityRuntime.Core|
| onFailed(code: number) | Called when the connection fails.|
| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service extension context, which is inherited from **ExtensionContext**.|
| context | [ServiceExtensionContext](js-apis-service-extension-context.md) | Yes| No| Service extension context, which is inherited from **ExtensionContext**.<br>**System capability**: SystemCapability.Ability.AbilityRuntime.Core|
## onCreate
## onCreate
...
@@ -32,17 +32,17 @@ onCreate(want: Want): void;
...
@@ -32,17 +32,17 @@ onCreate(want: Want): void;
Called when an extension is created to initialize the service logic.
Called when an extension is created to initialize the service logic.
Called after **onCreate** is invoked when an ability is started by calling **startAbility**. The value of **startId** is incremented for each ability that is started.
Called after **onCreate** is invoked when an ability is started by calling **startAbility**. The value of **startId** is incremented for each ability that is started.
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information related to this extension, including the ability name and bundle name.|
| want | [Want](js-apis-featureAbility.md#Want)| Yes| Information related to this extension, 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.|
| startId | number | Yes| Number of ability start times. The initial value is **1**, and the value is automatically incremented for each ability started.|
Called after **onCreate** is invoked when an ability is started by calling **connectAbility**. A **RemoteObject** object is returned for communication with the client.
Called after **onCreate** is invoked when an ability is started by calling **connectAbility**. A **RemoteObject** object is returned for communication with the client.
