@ohos.ability.featureAbility (FeatureAbility模块)

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

说明：

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

使用限制

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

导入模块

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

featureAbility.startAbility

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

启动新的Ability。使用callback异步回调。

说明：

组件启动规则详见：组件启动规则（FA模型）。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
parameter StartAbilityParameter 是 表示被启动的Ability。
callback AsyncCallback<number> 是 回调函数。当启动Ability成功，err为undefined，data为0表示启动成功，data为其他表示启动失败；否则为错误对象。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            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>

启动新的Ability。使用Promise异步回调。

说明：

组件启动规则详见：组件启动规则（FA模型）。

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

说明：本接口仅可在FA模型下使用。

参数：

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

返回值：

类型 说明
Promise<number> Promise对象。返回0表示启动成功，返回其他表示启动失败。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            abilityName: 'com.example.myapplication.secondAbility',
            uri: ''
        },
    }
).then((data) => {
    console.info(`startAbility data: ${JSON.stringify(data)}`);
});

featureAbility.acquireDataAbilityHelper7+

acquireDataAbilityHelper(uri: string): DataAbilityHelper

获取dataAbilityHelper对象。

说明：

组件启动规则详见：组件启动规则（FA模型）。 跨应用访问dataAbility，对端应用需配置关联启动。

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

说明：本接口仅可在FA模型下使用。

参数：

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

返回值：

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

示例：

import featureAbility from '@ohos.ability.featureAbility';
let dataAbilityHelper = featureAbility.acquireDataAbilityHelper(
    'dataability:///com.example.DataAbility'
);

featureAbility.startAbilityForResult7+

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

启动一个Ability。使用callback异步回调。启动Ability后，存在如下几种情况：

  • 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。
  • 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。
  • 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。

说明：

组件启动规则详见：组件启动规则（FA模型）。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
parameter StartAbilityParameter 是 表示被启动的Ability。
callback AsyncCallback<AbilityResult> 是 回调函数。当启动Ability成功，err为undefined，data为ability的启动结果；否则为错误对象。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            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>

启动一个Ability。使用Promise异步回调。启动Ability后，存在如下几种情况：

  • 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。
  • 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。
  • 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。

说明：

组件启动规则详见：组件启动规则（FA模型）。

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

说明：本接口仅可在FA模型下使用。 参数：

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

返回值：

类型 说明
Promise<AbilityResult> Promise对象，返回启动Ability的结果。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            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

停止当前的Ability。使用callback异步回调。如果该Ability是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
parameter AbilityResult 是 表示停止Ability之后返回的结果。
callback AsyncCallback<void> 是 回调函数。当停止当前Ability成功，err为undefined，否则为错误对象。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            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>

停止当前的Ability。使用Promise异步回调。如果该Ability是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者。

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

说明：本接口仅可在FA模型下使用。

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

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',
            /* FA模型中abilityName由package + Ability name组成 */
            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

检查Ability的主窗口是否具有窗口焦点。使用callback异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
callback AsyncCallback<boolean> 是 回调函数。
如果此Ability当前具有视窗焦点，则返回true；否则返回false。

示例：

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>

检查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)}`);
});

featureAbility.getWant

getWant(callback: AsyncCallback<Want>): void

获取要拉起的Ability对应的Want。使用callback异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
callback AsyncCallback<Want> 是 回调函数，返回want信息。

示例：

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>

获取要拉起的Ability对应的Want。使用Promise异步回调。

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

说明：本接口仅可在FA模型下使用。

返回值：

类型 说明
Promise<Want> Promise对象，返回want信息。

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.getWant().then((data) => {
    console.info(`getWant data: ${JSON.stringify(data)}`);
});

featureAbility.getContext

getContext(): Context

获取应用上下文。

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

说明：本接口仅可在FA模型下使用。

返回值：

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

示例：

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

停止当前的Ability。使用callback异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
callback AsyncCallback<void> 是 回调函数。当停止当前的Ability成功，err为undefined，否则为错误对象。

示例：

import featureAbility from '@ohos.ability.featureAbility';
featureAbility.terminateSelf(
    (error) => {
        console.error(`error: ${JSON.stringify(error)}`);
    }
)

featureAbility.terminateSelf7+

terminateSelf(): Promise<void>

停止当前的Ability。使用Promise异步回调。

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

说明：本接口仅可在FA模型下使用。

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

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

featureAbility.connectAbility7+

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

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

说明：

组件启动规则详见：组件启动规则（FA模型）。 跨应用连接serviceAbility，对端应用需配置关联启动。

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

说明：本接口仅可在FA模型下使用。

参数：

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

返回值：

类型 说明
number 连接的ServiceAbility的ID(ID从0开始自增，每连接成功一次ID加1)。

示例：

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

断开与指定ServiceAbility的连接。使用callback异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

参数名 类型 必填 说明
connection number 是 表示断开连接的ServiceAbility的ID。
callback AsyncCallback<void> 是 回调函数。当断开与指定ServiceAbility的连接成功，err为undefined，否则为错误对象。

示例：

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>

断开与指定ServiceAbility的连接。使用Promise异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

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

获取当前Ability对应的窗口。使用callback异步回调。

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

说明：本接口仅可在FA模型下使用。

参数：

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

示例：

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>

获取当前Ability对应的窗口。使用Promise异步回调。

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

说明：本接口仅可在FA模型下使用。

返回值：

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

示例：

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+

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

示例：

featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED

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

名称 值 说明
WINDOW_MODE_UNDEFINED 0 未定义。
WINDOW_MODE_FULLSCREEN 1 全屏。
WINDOW_MODE_SPLIT_PRIMARY 100 屏幕如果是水平方向表示左分屏，屏幕如果是竖直方向表示上分屏。
WINDOW_MODE_SPLIT_SECONDARY 101 屏幕如果是水平方向表示右分屏，屏幕如果是竖直方向表示下分屏。
WINDOW_MODE_FLOATING 102 悬浮窗。

AbilityStartSetting7+

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

使用时通过featureAbility.AbilityStartSetting获取。

示例：

featureAbility.AbilityStartSetting.BOUNDS_KEY

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

名称 值 说明
BOUNDS_KEY 'abilityBounds' 窗口显示大小属性的参数名。
WINDOW_MODE_KEY 'windowMode' 窗口显示模式属性的参数名。
DISPLAY_ID_KEY 'displayId' 窗口显示设备ID属性的参数名。

ErrorCode7+

定义启动Ability时返回的错误码。

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

名称 值 说明
NO_ERROR 0 没有异常。
INVALID_PARAMETER -1 无效的参数。
ABILITY_NOT_FOUND -2 找不到ABILITY。
PERMISSION_DENY -3 权限拒绝。

DataAbilityOperationType7+

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

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

名称 值 说明
TYPE_INSERT 1 插入类型。
TYPE_UPDATE 2 修改类型。
TYPE_DELETE 3 删除类型。
TYPE_ASSERT 4 声明类型。