@ohos.ability.featureAbility (FeatureAbility)
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
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.
Constraints
The APIs of the FeatureAbility module can be called only by PageAbilities.
Modules to Import
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.startAbility
startAbility(parameter: StartAbilityParameter, callback: AsyncCallback<number>): void
Starts an ability. This API uses an asynchronous callback to return the result.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | StartAbilityParameter | Yes | Ability to start. |
callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, err is undefined and data is 0; otherwise, err is a non-zero value. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.startAbility(
{
want:
{
action: '',
entities: [''],
type: '',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri: ''
},
},
(error, data) => {
if (error && error.code !== 0) {
console.error(`startAbility fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`startAbility success, data: ${JSON.stringify(data)}`);
}
}
);
featureAbility.startAbility
startAbility(parameter: StartAbilityParameter): Promise<number>
Starts an ability. This API uses a promise to return the result.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | StartAbilityParameter | Yes | Ability to start. |
Return value
Type | Description |
---|---|
Promise<number> | Promise used to return the result. If the operation is successful, 0 is returned; otherwise, a non-zero value is returned. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.startAbility(
{
want:
{
action: 'ohos.want.action.home',
entities: ['entity.system.home'],
type: 'MIMETYPE',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri: ''
},
}
).then((data) => {
console.info(`startAbility data: ${JSON.stringify(data)}`);
});
featureAbility.acquireDataAbilityHelper7+
acquireDataAbilityHelper(uri: string): DataAbilityHelper
Obtains a dataAbilityHelper object.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model). To access a DataAbility of another application, the target application must be configured with associated startup (AssociateWakeUp set to true).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
uri | string | Yes | URI of the file to open. |
Return value
Type | Description |
---|---|
DataAbilityHelper | A utility class used to help other abilities access the Data ability. |
Example
import featureAbility from '@ohos.ability.featureAbility';
let dataAbilityHelper = featureAbility.acquireDataAbilityHelper(
'dataability:///com.example.DataAbility'
);
featureAbility.startAbilityForResult7+
startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback<AbilityResult>): void
Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability:
- Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller.
- If an exception occurs, for example, the ability is killed, an exception message, in which resultCode is -1, is returned to the caller.
- If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an exception message, in which resultCode is -1, is returned to others.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | StartAbilityParameter | Yes | Ability to start. |
callback | AsyncCallback<AbilityResult> | Yes | Callback used to return the result. If the operation is successful, err is undefined and data is an AbilityResult object; otherwise, err is an error object. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.startAbilityForResult(
{
want:
{
action: 'ohos.want.action.home',
entities: ['entity.system.home'],
type: 'MIMETYPE',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri:''
},
},
(error, data) => {
if (error && error.code !== 0) {
console.error(`startAbilityForResult fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`startAbilityForResult success, data: ${JSON.stringify(data)}`);
}
}
);
featureAbility.startAbilityForResult7+
startAbilityForResult(parameter: StartAbilityParameter): Promise<AbilityResult>
Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible for a started ability:
- Normally, you can call terminateSelfWithResult to terminate the ability. The result is returned to the caller.
- If an exception occurs, for example, the ability is killed, an exception message, in which resultCode is -1, is returned to the caller.
- If different applications call this API to start an ability that uses the singleton mode and then call terminateSelfWithResult to terminate the ability, the normal result is returned to the last caller, and an exception message, in which resultCode is -1, is returned to others.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model. Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | StartAbilityParameter | Yes | Ability to start. |
Return value
Type | Description |
---|---|
Promise<AbilityResult> | Promise used to return the result. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.startAbilityForResult(
{
want:
{
action: 'ohos.want.action.home',
entities: ['entity.system.home'],
type: 'MIMETYPE',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri:'',
parameters:
{
mykey0: 1111,
mykey1: [1, 2, 3],
mykey2: '[1, 2, 3]',
mykey3: 'xxxxxxxxxxxxxxxxxxxxxx',
mykey4: [1, 15],
mykey5: [false, true, false],
mykey6: ['aaaaaa', 'bbbbb', 'ccccccccccc'],
mykey7: true,
},
},
},
).then((data) => {
console.info(`startAbilityForResult data: ${JSON.stringify(data)}`);
});
featureAbility.terminateSelfWithResult7+
terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void
Terminates this ability. This API uses an asynchronous callback to return the result. If the ability is started by calling startAbilityForResult, the result is returned to the caller when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Result returned after the ability is terminated. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.terminateSelfWithResult(
{
resultCode: 1,
want:
{
action: 'ohos.want.action.home',
entities: ['entity.system.home'],
type: 'MIMETYPE',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri:'',
parameters: {
mykey0: 2222,
mykey1: [1, 2, 3],
mykey2: '[1, 2, 3]',
mykey3: 'ssssssssssssssssssssssssss',
mykey4: [1, 15],
mykey5: [false, true, false],
mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
mykey7: true,
}
},
},
(error) => {
console.error(`error: ${JSON.stringify(error)}`);
}
);
featureAbility.terminateSelfWithResult7+
terminateSelfWithResult(parameter: AbilityResult): Promise<void>
Terminates this ability. This API uses a promise to return the result. If the ability is started by calling startAbilityForResult, the result is returned to the caller when terminateSelfWithResult is called. Otherwise, no result is returned to the caller when terminateSelfWithResult is called.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
parameter | AbilityResult | Yes | Result returned after the ability is terminated. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.app.ability.wantConstant';
featureAbility.terminateSelfWithResult(
{
resultCode: 1,
want:
{
action: 'ohos.want.action.home',
entities: ['entity.system.home'],
type: 'MIMETYPE',
flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
deviceId: '',
bundleName: 'com.example.myapplication',
/* In the FA model, abilityName consists of package and ability names. */
abilityName: 'com.example.myapplication.secondAbility',
uri:'',
parameters: {
mykey0: 2222,
mykey1: [1, 2, 3],
mykey2: '[1, 2, 3]',
mykey3: 'ssssssssssssssssssssssssss',
mykey4: [1, 15],
mykey5: [false, true, false],
mykey6: ['qqqqq', 'wwwwww', 'aaaaaaaaaaaaaaaaa'],
mykey7: true,
}
},
}
).then(() => {
console.info('==========================>terminateSelfWithResult=======================>');
});
featureAbility.hasWindowFocus7+
hasWindowFocus(callback: AsyncCallback<boolean>): void
Checks whether the main window of this ability has the focus. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the main window has the focus, true is returned. Otherwise, false is returned. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus((error, data) => {
if (error && error.code !== 0) {
console.error(`hasWindowFocus fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`hasWindowFocus success, data: ${JSON.stringify(data)}`);
}
});
featureAbility.hasWindowFocus7+
hasWindowFocus(): Promise<boolean>
Checks whether the main window of this ability has the focus. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Return value
Type | Description |
---|---|
Promise<boolean> | Promise used to return the result. If the main window has the focus, true is returned. Otherwise, false is returned. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus().then((data) => {
console.info(`hasWindowFocus data: ${JSON.stringify(data)}`);
});
featureAbility.getWant
getWant(callback: AsyncCallback<Want>): void
Obtains the Want corresponding to the ability to start. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<Want> | Yes | Callback used to return the Want. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant((error, data) => {
if (error && error.code !== 0) {
console.error(`getWant fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`getWant success, data: ${JSON.stringify(data)}`);
}
});
featureAbility.getWant
getWant(): Promise<Want>
Obtains the Want corresponding to the ability to start. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Return value
Type | Description |
---|---|
Promise<Want> | Promise used to return the Want. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant().then((data) => {
console.info(`getWant data: ${JSON.stringify(data)}`);
});
featureAbility.getContext
getContext(): Context
Obtains the application context.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Return value
Type | Description |
---|---|
Context | Application context. |
Example
import featureAbility from '@ohos.ability.featureAbility';
let context = featureAbility.getContext();
context.getBundleName((error, data) => {
if (error && error.code !== 0) {
console.error(`getBundleName fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`getBundleName success, data: ${JSON.stringify(data)}`);
}
});
featureAbility.terminateSelf7+
terminateSelf(callback: AsyncCallback<void>): void
Terminates this ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the ability is terminated, err is undefined; otherwise, err is an error object. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf(
(error) => {
console.error(`error: ${JSON.stringify(error)}`);
}
)
featureAbility.terminateSelf7+
terminateSelf(): Promise<void>
Terminates this ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf().then(() => {
console.info('==========================>terminateSelf=======================>');
});
featureAbility.connectAbility7+
connectAbility(request: Want, options:ConnectOptions): number
Connects this ability to a ServiceAbility.
NOTE
For details about the startup rules for the components in the FA model, see Component Startup Rules (FA Model). To connect to a ServiceAbility of another application, the target application must be configured with associated startup (AssociateWakeUp set to true).
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
request | Want | Yes | ServiceAbility to connect. |
options | ConnectOptions | Yes | Connection options. |
Return value
Type | Description |
---|---|
number | ID of the connected ServiceAbility. The ID starts from 0 and is incremented by 1 each time a connection is set up. |
Example
import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
let connectId = featureAbility.connectAbility(
{
deviceId: '',
bundleName: 'com.ix.ServiceAbility',
abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
},
{
onConnect: (element, remote) => {
console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
},
onDisconnect: (element) => {
console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`)
},
onFailed: (code) => {
console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`)
},
},
);
featureAbility.disconnectAbility7+
disconnectAbility(connection: number, callback:AsyncCallback<void>): void
Disconnects this ability from a specific ServiceAbility. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
connection | number | Yes | ID of the ServiceAbility to disconnect. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. If the disconnection is successful, err is undefined. Otherwise, err is an error object. |
Example
import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
let connectId = featureAbility.connectAbility(
{
bundleName: 'com.ix.ServiceAbility',
abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
},
{
onConnect: (element, remote) => {
console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
},
onDisconnect: (element) => {
console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`);
},
onFailed: (code) => {
console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`);
},
},
);
featureAbility.disconnectAbility(connectId, (error) => {
if (error && error.code !== 0) {
console.error(`disconnectAbility fail, connectId: ${connectId}, error: ${JSON.stringify(error)}`);
} else {
console.log(`disconnectAbility success, connectId: ${connectId}`);
}
});
featureAbility.disconnectAbility7+
disconnectAbility(connection: number): Promise<void>
Disconnects this ability from a specific ServiceAbility. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
connection | number | Yes | ID of the ServiceAbility to disconnect. |
Return value
Type | Description |
---|---|
Promise<void> | Promise that returns no value. |
Example
import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
import { BusinessError } from '@ohos.base';
let connectId = featureAbility.connectAbility(
{
bundleName: 'com.ix.ServiceAbility',
abilityName: 'com.ix.ServiceAbility.ServiceAbilityA',
},
{
onConnect: (element, remote) => {
console.log(`ConnectAbility onConnect remote is proxy: ${(remote instanceof rpc.RemoteProxy)}`);
},
onDisconnect: (element) => {
console.log(`ConnectAbility onDisconnect element.deviceId : ${element.deviceId}`);
},
onFailed: (code) => {
console.error(`featureAbilityTest ConnectAbility onFailed errCode : ${code}`);
},
},
);
featureAbility.disconnectAbility(connectId).then(() => {
console.log('disconnectAbility success')
}).catch((error: BusinessError)=>{
console.error(`featureAbilityTest result errCode : ${error.code}`);
});
featureAbility.getWindow7+
getWindow(callback: AsyncCallback<window.Window>): void
Obtains the window corresponding to this ability. This API uses an asynchronous callback to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
callback | AsyncCallback<window.Window> | Yes | Callback used to return the window. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';
featureAbility.getWindow((error: BusinessError, data: window.Window) => {
if (error && error.code !== 0) {
console.error(`getWindow fail, error: ${JSON.stringify(error)}`);
} else {
console.log(`getWindow success, data: ${typeof(data)}`);
}
});
featureAbility.getWindow7+
getWindow(): Promise<window.Window>
Obtains the window corresponding to this ability. This API uses a promise to return the result.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Note: This API can be used only in the FA model.
Return value
Type | Description |
---|---|
Promise<window.Window> | Promise used to return the window. |
Example
import featureAbility from '@ohos.ability.featureAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';
featureAbility.getWindow().then((data: window.Window) => {
console.log(`getWindow success, data: ${typeof(data)}`);
}).catch((error: BusinessError)=>{
console.error(`getWindow fail, error: ${JSON.stringify(error)}`);
});
AbilityWindowConfiguration7+
Defines the window configuration corresponding to this ability. The configuration is obtained through featureAbility.AbilityWindowConfiguration.
Example
featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Name | Value | Description |
---|---|---|
WINDOW_MODE_UNDEFINED | 0 | The PageAbility is in an undefined window display mode. |
WINDOW_MODE_FULLSCREEN | 1 | The PageAbility is in full screen mode. |
WINDOW_MODE_SPLIT_PRIMARY | 100 | The left screen in horizontal direction or the upper screen in vertical direction is the primary window. |
WINDOW_MODE_SPLIT_SECONDARY | 101 | The right screen in horizontal direction or the lower screen in vertical direction is the secondary window. |
WINDOW_MODE_FLOATING | 102 | The PageAbility is displayed in floating window mode. |
AbilityStartSetting7+
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 featureAbility.AbilityStartSetting.
Example
featureAbility.AbilityStartSetting.BOUNDS_KEY
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Name | Value | Description |
---|---|---|
BOUNDS_KEY | 'abilityBounds' | Ability window size. |
WINDOW_MODE_KEY | 'windowMode' | Ability window display mode. |
DISPLAY_ID_KEY | 'displayId' | Display device ID. |
ErrorCode7+
Enumerates the error codes that may be returned when an ability is started.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Name | Value | Description |
---|---|---|
NO_ERROR | 0 | No error. |
INVALID_PARAMETER | -1 | Invalid parameter. |
ABILITY_NOT_FOUND | -2 | The ability is not found. |
PERMISSION_DENY | -3 | Permission denied. |
DataAbilityOperationType7+
Enumerates the operation types of a DataAbility. The DataAbility can use an enumerated value to specify the operation type when operating data in batches.
System capability: SystemCapability.Ability.AbilityRuntime.FAModel
Name | Value | Description |
---|---|---|
TYPE_INSERT | 1 | Insert operation. |
TYPE_UPDATE | 2 | Update operation. |
TYPE_DELETE | 3 | Deletion operation. |
TYPE_ASSERT | 4 | Assert operation. |