FeatureAbility模塊(JS端SDK接口)

FeatureAbility模塊提供帶有UI設(shè)計(jì)與用戶交互的能力，包括啟動新的ability、獲取dataAbilityHelper、設(shè)置此Page Ability、獲取當(dāng)前Ability對應(yīng)的窗口，連接服務(wù)等。

說明：

本模塊首批接口從API version 6開始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨(dú)標(biāo)記接口的起始版本。
本模塊接口僅可在FA模型下使用。

使用限制

FeatureAbility模塊的接口只能在Page類型的Ability調(diào)用

導(dǎo)入模塊

import featureAbility from '@ohos.ability.featureAbility'

鴻蒙開發(fā)指導(dǎo)文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter, callback: AsyncCallback): void

啟動新的ability（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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: ""
        },
    },
);

featureAbility.startAbility

startAbility(parameter: StartAbilityParameter): Promise

啟動新的ability（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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======================= >");
});

featureAbility.acquireDataAbilityHelper7+

acquireDataAbilityHelper(uri: string): DataAbilityHelper

獲取dataAbilityHelper。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

import featureAbility from '@ohos.ability.featureAbility'
featureAbility.acquireDataAbilityHelper(
    "dataability:///com.example.DataAbility"
)

featureAbility.startAbilityForResult7+

startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback): void

啟動一個(gè)ability，并在該ability被銷毀時(shí)返回執(zhí)行結(jié)果（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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("err: " + JSON.stringify(err) + "data: " + JSON.stringify(data))
    }
)

featureAbility.startAbilityForResult7+

startAbilityForResult(parameter: StartAbilityParameter): Promise

啟動一個(gè)ability，并在該ability被銷毀時(shí)返回執(zhí)行結(jié)果（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

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======================= >");
});

featureAbility.terminateSelfWithResult7+

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

設(shè)置此Page Ability將返回給調(diào)用者的結(jié)果代碼和數(shù)據(jù)并破壞此Page Ability（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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,
            }
        },
    },
);

featureAbility.terminateSelfWithResult7+

terminateSelfWithResult(parameter: AbilityResult): Promise

設(shè)置此Page Ability將返回給調(diào)用者的結(jié)果代碼和數(shù)據(jù)并破壞此Page Ability（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

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======================= >");
});

featureAbility.hasWindowFocus7+

hasWindowFocus(callback: AsyncCallback): void

檢查Ability的主窗口是否具有窗口焦點(diǎn)（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.hasWindowFocus()

featureAbility.hasWindowFocus7+

hasWindowFocus(): Promise

檢查Ability的主窗口是否具有窗口焦點(diǎn)（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

import featureAbility from '@ohos.ability.featureability';
featureAbility.hasWindowFocus().then((data) = > {
    console.info("========================== >hasWindowFocus======================= >");
});

featureAbility.getWant

getWant(callback: AsyncCallback): void

獲取從Ability發(fā)送的Want（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant()

featureAbility.getWant

getWant(): Promise

獲取從Ability發(fā)送的Want（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant().then((data) = > {
	console.info("========================== >getWantCallBack======================= >");
});

featureAbility.getContext

getContext(): Context

獲取應(yīng)用上下文。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

import featureAbility from '@ohos.ability.featureAbility';
var context = featureAbility.getContext()
context.getBundleName()

featureAbility.terminateSelf7+

terminateSelf(callback: AsyncCallback): void

設(shè)置Page Ability返回給被調(diào)用方的結(jié)果代碼和數(shù)據(jù)，并銷毀此Page Ability（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf()

featureAbility.terminateSelf7+

terminateSelf(): Promise

設(shè)置Page Ability返回給被調(diào)用方的結(jié)果代碼和數(shù)據(jù)，并銷毀此Page Ability（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

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

featureAbility.connectAbility7+

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

將當(dāng)前ability連接到指定ServiceAbility（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

Want

want類型說明

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityBase

ConnectOptions

ConnectOptions類型說明

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.Core

返回值：

示例：

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 connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

featureAbility.disconnectAbility7+

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

斷開與指定ServiceAbility的連接（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

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 connId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);
var result = featureAbility.disconnectAbility(connId,
    (error,data) = > {
        console.log('featureAbilityTest DisConnectJsSameBundleName result errCode : ' + error.code + " data: " + data)
    },
);

featureAbility.disconnectAbility7+

disconnectAbility(connection: number): Promise

斷開與指定ServiceAbility的連接（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

返回值：

示例：

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 connId = featureAbility.connectAbility(
    {
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

featureAbility.disconnectAbility(connId).then((data) = > {
    console.log('data : '  + data);
}).catch((error)= >{
    console.log('featureAbilityTest result errCode : ' + error.code);
});

featureAbility.getWindow7+

getWindow(callback: AsyncCallback): void

獲取當(dāng)前Ability對應(yīng)的窗口（callback形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

參數(shù)：

示例：

featureAbility.getWindow()

featureAbility.getWindow7+

getWindow(): Promise;

獲取當(dāng)前Ability對應(yīng)的窗口（Promise形式）。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.FAModel

返回值：

示例：

featureAbility.getWindow().then((data) = > {
  console.info("=============getWindowPromise========== " +  JSON.stringify(data)); 
});

[](https://gitee.com/openharmony/docs/blob/OpenHarmony-3.2-Beta1/zh-cn/application-dev/reference/apis/js-apis-featureAbility.md#connectoptionsonconnect7)ConnectOptions.onConnect7+

onConnect(elementName: ElementName, remote: rpc.IRemoteObject): void;

連接成功時(shí)的回調(diào)函數(shù)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.Core

參數(shù)：

示例：

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 connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

ConnectOptions.onDisconnect7+

onDisconnect(elementName: ElementName): void;

連接失敗時(shí)的回調(diào)函數(shù)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.Core

參數(shù)：

示例：

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 connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

ConnectOptions.onFailed7+

onFailed(code: number): void;

ConnectAbility調(diào)用失敗時(shí)的回調(diào)函數(shù)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.Core

參數(shù)：

示例：

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 connId = featureAbility.connectAbility(
    {
        deviceId: "",
        bundleName: "com.ix.ServiceAbility",
        abilityName: "ServiceAbilityA",
    },
    {
        onConnect: onConnectCallback,
        onDisconnect: onDisconnectCallback,
        onFailed: onFailedCallback,
    },
);

AbilityWindowConfiguration

使用時(shí)通過featureAbility.AbilityWindowConfiguration獲取。

示例：

featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.FAModel

AbilityStartSetting

abilityStartSetting屬性是一個(gè)定義為[key: string]: any的對象，key對應(yīng)設(shè)定類型為：AbilityStartSetting枚舉類型，value對應(yīng)設(shè)定類型為：AbilityWindowConfiguration枚舉類型。

使用時(shí)通過featureAbility.AbilityStartSetting獲取。

示例：

featureAbility.AbilityStartSetting.BOUNDS_KEY

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.FAModel

ErrorCode

獲取錯(cuò)誤代碼。

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.FAModel

DataAbilityOperationType

指示數(shù)據(jù)的操作類型。

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.FAModel

AbilityResult

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityBase

StartAbilityParameter

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.FAModel

flags說明

系統(tǒng)能力 ：以下各項(xiàng)對應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityBase

審核編輯 黃宇