@ohos.ability.featureAbility (FeatureAbility模块)


@ohos.ability.featureAbility (FeatureAbility模块)

FeatureAbility模块提供与用户进行交互的Ability的能力,包括启动新的Ability、停止Ability、获取dataAbilityHelper对象、获取当前Ability对应的窗口,连接断连Service等。

说明:

本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
本模块接口仅可在FA模型下使用。

使用限制

FeatureAbility模块的接口只能在Page类型的Ability中调用

导入模块

import featureAbility from '@ohos.ability.featureAbility';
1

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter, callback: AsyncCallback<number>): void

启动新的Ability(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter StartAbilityParameter 表示被启动的Ability。
callback AsyncCallback<number> 以callback的形式返回启动Ability的结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.startAbility(
    {
        want:
        {
            action: "",
            entities: [""],
            type: "",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
            uri: ""
        },
    },
    (err, data) => {
        console.info("startAbility err: " + JSON.stringify(err) + "data: " + JSON.stringify(data));
    }
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter): Promise<number>

启动新的Ability(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter StartAbilityParameter 表示被启动的Ability。

返回值:

类型 说明
Promise<number> Promise形式返回启动Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.startAbility(
    {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
            uri: ""
        },
    }
).then((data) => {
    console.info("startAbility data: " + JSON.stringify(data));
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

featureAbility.acquireDataAbilityHelper7+

acquireDataAbilityHelper(uri: string): DataAbilityHelper

获取dataAbilityHelper对象。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
uri string 表示要打开的文件的路径。

返回值:

类型 说明
DataAbilityHelper 用来协助其他Ability访问DataAbility的工具类。

示例:

import featureAbility from '@ohos.ability.featureAbility';
var dataAbilityHelper = featureAbility.acquireDataAbilityHelper(
    "dataability:///com.example.DataAbility"
);
1
2
3
4

featureAbility.startAbilityForResult7+

startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback<AbilityResult>): void

启动一个Ability。Ability被启动后,正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter StartAbilityParameter 表示被启动的Ability。
callback AsyncCallback<AbilityResult> 以callback的形式返回启动Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.startAbilityForResult(
   {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.secondAbility",
            uri:""
        },
    },
    (err, data) => {
        console.info("startAbilityForResult err: " + JSON.stringify(err) + "data: " + JSON.stringify(data));
    }
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

featureAbility.startAbilityForResult7+

startAbilityForResult(parameter: StartAbilityParameter): Promise<AbilityResult>

启动一个Ability。Ability被启动后,正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter StartAbilityParameter 表示被启动的Ability

返回值:

类型 说明
Promise<AbilityResult> Promise形式返回启动Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.startAbilityForResult(
    {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.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));
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

featureAbility.terminateSelfWithResult7+

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void

停止当前的Ability。如果该Ability是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时会将结果返回给调用者,如果该Ability不是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时不会有结果返回给调用者(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter AbilityResult 表示停止Ability之后返回的结果。
callback AsyncCallback<void> 以callback的形式返回停止Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.terminateSelfWithResult(
    {
        resultCode: 1,
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.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,
            }
        },
    },
    (err) => {
        console.info("err: " + JSON.stringify(err))
    }
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

featureAbility.terminateSelfWithResult7+

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

停止当前的Ability。如果该Ability是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时会将结果返回给调用者,如果该Ability不是通过调用startAbilityForResult接口被拉起的,调用terminateSelfWithResult接口时不会有结果返回给调用者(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
parameter AbilityResult 表示停止Ability之后返回的结果

返回值:

类型 说明
Promise<void> 以Promise形式返回停止当前Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
import wantConstant from '@ohos.ability.wantConstant';
featureAbility.terminateSelfWithResult(
    {
        resultCode: 1,
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            flags: wantConstant.Flags.FLAG_AUTH_READ_URI_PERMISSION,
            deviceId: "",
            bundleName: "com.example.myapplication",
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: "com.example.entry.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((data) => {
    console.info("==========================>terminateSelfWithResult=======================>");
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

featureAbility.hasWindowFocus7+

hasWindowFocus(callback: AsyncCallback<boolean>): void

检查Ability的主窗口是否具有窗口焦点(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
callback AsyncCallback<boolean> 以callback的形式返回结果。
如果此Ability当前具有视窗焦点,则返回true;否则返回false。

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus((err, data) => {
    console.info("hasWindowFocus err: " + JSON.stringify(err) + "data: " + JSON.stringify(data));
});
1
2
3
4

featureAbility.hasWindowFocus7+

hasWindowFocus(): Promise<boolean>

检查Ability的主窗口是否具有窗口焦点(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

返回值:

类型 说明
Promise<boolean> Promise形式返回结果,如果此Ability当前具有视窗焦点,则返回true;否则返回false。

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus().then((data) => {
    console.info("hasWindowFocus data: " + JSON.stringify(data));
});
1
2
3
4

featureAbility.getWant

getWant(callback: AsyncCallback<Want>): void

获取要拉起的Ability对应的Want(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
callback AsyncCallback<Want> 以callback的形式返回want。

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant((err, data) => {
    console.info("getWant err: " + JSON.stringify(err) + "data: " + JSON.stringify(data));
});
1
2
3
4

featureAbility.getWant

getWant(): Promise<Want>

获取要拉起的Ability对应的Want(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

返回值:

类型 说明
Promise<Want> 以Promise的形式返回want。

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant().then((data) => {
    console.info("getWant data: " + JSON.stringify(data));
});
1
2
3
4

featureAbility.getContext

getContext(): Context

获取应用上下文。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

返回值:

类型 说明
Context 返回应用程序上下文。

示例:

import featureAbility from '@ohos.ability.featureAbility';
var context = featureAbility.getContext()
context.getBundleName((err, data) => {
    console.info("getBundleName err: " + JSON.stringify(err) + "data: " + JSON.stringify(data));
});
1
2
3
4
5

featureAbility.terminateSelf7+

terminateSelf(callback: AsyncCallback<void>): void

停止当前的Ability(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 以callback的形式返回停止当前Ability结果

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf(
    (err) => {
        console.info("err: " + JSON.stringify(err))
    }
)
1
2
3
4
5
6

featureAbility.terminateSelf7+

terminateSelf(): Promise<void>

停止当前的Ability(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

返回值:

类型 说明
Promise<void> 以Promise的形式返回停止当前Ability结果。

示例:

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf().then((data) => {
    console.info("==========================>terminateSelf=======================>");
});
1
2
3
4

featureAbility.connectAbility7+

connectAbility(request: Want, options:ConnectOptions): number

将当前Ability与指定的ServiceAbility进行连接。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
request Want 表示被连接的ServiceAbility。
options ConnectOptions 表示连接回调函数。

返回值:

类型 说明
number 连接的ServiceAbility的ID。

示例:

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connectId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

featureAbility.disconnectAbility7+

disconnectAbility(connection: number, callback:AsyncCallback<void>): void

断开与指定ServiceAbility的连接(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
connection number 表示断开连接的ServiceAbility的ID
callback AsyncCallback<void> 以callback的形式返回断开连接结果

示例:

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connectId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
var result = featureAbility.disconnectAbility(connectId,
    (error) => {
        console.log('featureAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code)
    },
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

featureAbility.disconnectAbility7+

disconnectAbility(connection: number): Promise<void>

断开与指定ServiceAbility的连接(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
connection number 表示断开连接的ServiceAbility的ID

返回值:

类型 说明
Promise<void> 以Promise形式返回断开连接结果。

示例:

import rpc from '@ohos.rpc';
import featureAbility from '@ohos.ability.featureAbility';
function onConnectCallback(element, remote){
    console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy));
}
function onDisconnectCallback(element){
    console.log('ConnectAbility onDisconnect element.deviceId : ' + element.deviceId)
}
function onFailedCallback(code){
    console.log('featureAbilityTest ConnectAbility onFailed errCode : ' + code)
}
var connectId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

featureAbility.disconnectAbility(connectId).then((data) => {
    console.log('data : '  + data);
}).catch((error)=>{
    console.log('featureAbilityTest result errCode : ' + error.code);
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

featureAbility.getWindow7+

getWindow(callback: AsyncCallback<window.Window>): void

获取当前Ability对应的窗口(callback形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

参数:

参数名 类型 必填 说明
callback AsyncCallback<window.Window> callback形式返回当前Ability对应的窗口。

示例:

featureAbility.getWindow((err, data) => {
    console.info("getWindow err: " + JSON.stringify(err) + "data: " + typeof(data));
});
1
2
3

featureAbility.getWindow7+

getWindow(): Promise<window.Window>;

获取当前Ability对应的窗口(Promise形式)。

系统能力:SystemCapability.Ability.AbilityRuntime.FAModel

返回值:

类型 说明
Promise<window.Window> Promise形式返回当前Ability对应的窗口。

示例:

featureAbility.getWindow().then((data) => {
    console.info("getWindow data: " + typeof(data));
});
1
2
3

AbilityWindowConfiguration

表示当前Ability对应的窗口配置项,使用时通过featureAbility.AbilityWindowConfiguration获取。

示例:

featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED
1

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

名称 说明
WINDOW_MODE_UNDEFINED7+ 0 未定义。
WINDOW_MODE_FULLSCREEN7+ 1 全屏。
WINDOW_MODE_SPLIT_PRIMARY7+ 100 分屏主屏。
WINDOW_MODE_SPLIT_SECONDARY7+ 101 分屏次屏。
WINDOW_MODE_FLOATING7+ 102 悬浮窗。

AbilityStartSetting

表示当前Ability对应的窗口属性,abilityStartSetting属性是一个定义为[key: string]: any的对象,key对应设定类型为:AbilityStartSetting枚举类型,value对应设定类型为:AbilityWindowConfiguration枚举类型。

使用时通过featureAbility.AbilityStartSetting获取。

示例:

featureAbility.AbilityStartSetting.BOUNDS_KEY
1

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

名称 说明
BOUNDS_KEY7+ "abilityBounds" 窗口显示大小属性的参数名。
WINDOW_MODE_KEY7+ "windowMode" 窗口显示模式属性的参数名。
DISPLAY_ID_KEY7+ "displayId" 窗口显示设备ID属性的参数名。

ErrorCode

表示错误码。

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

名称 说明
NO_ERROR7+ 0 没有错误。
INVALID_PARAMETER7+ -1 无效的参数。
ABILITY_NOT_FOUND7+ -2 找不到ABILITY。
PERMISSION_DENY7+ -3 权限拒绝。

DataAbilityOperationType

表示数据的操作类型。DataAbility批量操作数据时可以通过该枚举值指定操作类型

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel

名称 说明
TYPE_INSERT7+ 1 插入类型。
TYPE_UPDATE7+ 2 修改类型。
TYPE_DELETE7+ 3 删除类型。
TYPE_ASSERT7+ 4 声明类型。

flags说明

表示处理Want的方式。

系统能力:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase

名称 说明
FLAG_AUTH_READ_URI_PERMISSION 0x00000001 表示对URI执行读取操作的授权。
FLAG_AUTH_WRITE_URI_PERMISSION 0x00000002 表示对URI执行写入操作的授权。
FLAG_ABILITY_FORWARD_RESULT 0x00000004 表示将结果返回给源Ability。
FLAG_ABILITY_CONTINUATION 0x00000008 表示是否可以将本地设备上的Ability迁移到远端设备。
FLAG_NOT_OHOS_COMPONENT 0x00000010 表示组件是否不属于OHOS。
FLAG_ABILITY_FORM_ENABLED 0x00000020 表示某个Ability是否已经启动。
FLAG_AUTH_PERSISTABLE_URI_PERMISSION 0x00000040 表示URI上可能持久化的授权。
系统API: 此接口为系统接口,三方应用不支持调用。
FLAG_AUTH_PREFIX_URI_PERMISSION 0x00000080 表示按照前缀匹配的方式验证URI权限。
系统API: 此接口为系统接口,三方应用不支持调用。
FLAG_ABILITYSLICE_MULTI_DEVICE 0x00000100 表示支持分布式调度系统中的多设备启动。
FLAG_START_FOREGROUND_ABILITY 0x00000200 表示无论宿主应用是否已启动,都将使用前台模式启动Ability。
系统API: 此接口为系统接口,三方应用不支持调用。
FLAG_ABILITY_CONTINUATION_REVERSIBLE 0x00000400 表示迁移是否是可反向的。
FLAG_INSTALL_ON_DEMAND 0x00000800 表示如果未安装指定的Ability,将安装该Ability。
FLAG_INSTALL_WITH_BACKGROUND_MODE 0x80000000 表示如果未安装指定的Ability,将在后台安装该Ability。
FLAG_ABILITY_CLEAR_MISSION 0x00008000 表示清除其他任务的操作。可以为传递给 ohos.app.ContextstartAbility方法的Want设置此标志,并且必须与flag_ABILITY_NEW_MISSION一起使用。
FLAG_ABILITY_NEW_MISSION 0x10000000 表示在已有的任务栈上创建任务的操作。
FLAG_ABILITY_MISSION_TOP 0x20000000 表示如果启动的Ability的现有实例已位于任务栈顶,则将重用该实例。否则,将创建一个新的Ability实例。