HarmonyOS API:UIAbilityContext

joytrian
发布于 2023-4-2 10:03
浏览
0收藏

版本:v3.1 Beta

UIAbilityContext

更新时间: 2023-02-17 09:19


UIAbilityContext是Ability的上下文环境,继承自Context。


UIAbilityContext模块提供允许访问特定Ability的资源的能力,包括对Ability的启动、停止的设置、获取caller通信接口、拉起弹窗请求用户授权等。


说明

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

属性

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

名称

类型

可读

可写

说明

abilityInfo

​AbilityInfo​

Abilityinfo相关信息

currentHapModuleInfo

​HapModuleInfo​

当前hap包的信息

config

​Configuration​

表示配置信息。

UIAbilityContext.startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void;

启动Ability(callback形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

callback

AsyncCallback<void>

callback形式返回启动结果

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};

try {
  this.context.startAbility(want, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void;

启动Ability(callback形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

options

​StartOptions​

启动Ability所携带的参数。

callback

AsyncCallback<void>

callback形式返回启动结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var options = {
  windowMode: 0
};

try {
  this.context.startAbility(want, options, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('startAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.startAbility

startAbility(want: Want, options?: StartOptions): Promise<void>;

启动Ability(promise形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

options

​StartOptions​

启动Ability所携带的参数。

返回值:

类型

说明

Promise<void>

Promise形式返回启动结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};
var options = {
    windowMode: 0,
};

try {
  this.context.startAbility(want, options)
    .then((data) => {
      // 执行正常业务
      console.log('startAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void;

启动Ability并在该Ability退出的时候返回执行结果(callback形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

callback

AsyncCallback<​​AbilityResult​​>

执行结果回调函数。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};

try {
  this.context.startAbilityForResult(want, (error, result) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log("startAbilityForResult succeed, result.resultCode = " +
      result.resultCode)
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void;

启动Ability并在该Ability退出的时候返回执行结果(callback形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

options

​StartOptions​

启动Ability所携带的参数。

callback

AsyncCallback<​​AbilityResult​​>

执行结果回调函数。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var options = {
  windowMode: 0,
};

try {
  this.context.startAbilityForResult(want, options, (error, result) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log("startAbilityForResult succeed, result.resultCode = " +
      result.resultCode)
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>;

启动Ability并在该Ability退出的时候返回执行结果(promise形式)。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

options

​StartOptions​

启动Ability所携带的参数。

返回值:

类型

说明

Promise<​​AbilityResult​​>

Promise形式返回执行结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000004

Visibility verification failed.

16000005

Static permission denied. The specified process does not have the permission.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000008

Crowdtest App Expiration.

16000009

Can not start ability in wukong mode.

16000010

Can not operation with continue flag.

16000011

Context does not exist.

16000051

Network error. The network is abnormal.

16000052

Free install not support. The application does not support freeinstall

16000053

Not top ability. The application is not top ability.

16000054

Free install busyness. There are concurrent tasks, waiting for retry.

16000055

Free install timeout.

16000056

Can not free install other ability.

16000057

Not support cross device free install.

16200001

Caller released. The caller has been released.

16000050

Internal Error.

示例:

var want = {
  bundleName: "com.example.myapp",
  abilityName: "MyAbility"
};
var options = {
    windowMode: 0,
};

try {
  this.context.startAbilityForResult(want, options)
    .then((result) => {
      // 执行正常业务
      console.log("startAbilityForResult succeed, result.resultCode = " + result.resultCode);
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('startAbilityForResult failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void;

停止Ability自身(callback形式)。

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

参数:

参数名

类型

必填

说明

callback

AsyncCallback<void>

回调函数,返回接口调用是否成功的结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000011

Context does not exist.

16000050

Internal Error.

示例:

this.context.terminateSelf((error) => {
  if (error.code) {
    // 处理业务逻辑错误
    console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
      ' error.message: ' + JSON.stringify(error.message));
    return;
  }
  // 执行正常业务
  console.log('terminateSelf succeed');
});

UIAbilityContext.terminateSelf

terminateSelf(): Promise<void>;

停止Ability自身(promise形式)。

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

返回值:

类型

说明

Promise<void>

返回一个Promise,包含接口的结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000011

Context does not exist.

16000050

Internal Error.

示例:

this.context.terminateSelf().then((data) => {
  // 执行正常业务
  console.log('terminateSelf succeed');
}).catch((error) => {
  // 处理业务逻辑错误
  console.log('terminateSelf failed, error.code: ' + JSON.stringify(error.code) +
    ' error.message: ' + JSON.stringify(error.message));
});

UIAbilityContext.terminateSelfWithResult

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

停止Ability,配合startAbilityForResult使用,返回给接口调用方AbilityResult信息(callback形式)。

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

参数:

参数名

类型

必填

说明

parameter

​AbilityResult​

返回给调用startAbilityForResult 接口调用方的相关信息。

callback

AsyncCallback<void>

callback形式返回停止结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000011

Context does not exist.

16000050

Internal Error.

示例:

var want = {
  bundleName: "com.extreme.myapplication",
  abilityName: "SecondAbility"
}
var resultCode = 100;
// 返回给接口调用方AbilityResult信息
var abilityResult = {
  want,
  resultCode
}

try {
  this.context.terminateSelfWithResult(abilityResult, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('terminateSelfWithResult succeed');
  });
} catch (paramError) {
    // 处理入参错误异常
    console.log('error.code: ' + JSON.stringify(paramError.code) +
      ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>;

停止Ability,配合startAbilityForResult使用,返回给接口调用方AbilityResult信息(promise形式)。

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

参数:

参数名

类型

必填

说明

parameter

​AbilityResult​

返回给startAbilityForResult 调用方的信息。

返回值:

类型

说明

Promise<void>

promise形式返回停止结果。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000007

Service busyness. There are concurrent tasks, waiting for retry.

16000011

Context does not exist.

16000050

Internal Error.

示例:

var want = {
  bundleName: "com.extreme.myapplication",
  abilityName: "SecondAbility"
}
var resultCode = 100;
// 返回给接口调用方AbilityResult信息
var abilityResult = {
  want,
  resultCode
}

try {
  this.context.terminateSelfWithResult(abilityResult)
    .then((data) => {
      // 执行正常业务
      console.log('terminateSelfWithResult succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('terminateSelfWithResult failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.connectServiceExtensionAbility

connectServiceExtensionAbility(want: Want, options: ConnectOptions): number;

使用AbilityInfo.AbilityType.SERVICE模板将当前Ability连接到一个Ability。

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

参数:

参数名

类型

必填

说明

want

​Want​

启动Ability的want信息。

options

​ConnectOptions​

远端对象实例。

返回值:

类型

说明

number

返回Ability连接的结果code。

错误码:

错误码ID

错误信息

201

The application does not have permission to call the interface.

401

Invalid input parameter.

16000001

Input error. The specified ability name does not exist.

16000002

Ability type error. The specified ability type is wrong.

16000004

Visibility verification failed.

16000011

Context does not exist.

16000050

Internal Error.

示例:

var want = {
  deviceId: "",
  bundleName: "com.extreme.test",
  abilityName: "MainAbility"
};
var options = {
  onConnect(elementName, remote) { console.log('----------- onConnect -----------') },
  onDisconnect(elementName) { console.log('----------- onDisconnect -----------') },
  onFailed(code) { console.log('----------- onFailed -----------') }
}

var connection = null;
try {
  connection = this.context.connectServiceExtensionAbility(want, options);
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>;

断开与ServiceExtensionAbility的连接(promise形式)。

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

参数:

参数名

类型

必填

说明

connection

number

连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。

返回值:

类型

说明

Promise<void>

返回一个Promise,包含接口的结果。

错误码:

错误码ID

错误信息

16000001

The specified ability does not exist.

16000005

The specified process does not have the permission.

16000011

The context does not exist.

16000050

Internal error.

示例:

// connection为connectServiceExtensionAbility中的返回值
let connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection)
    .then(() => {
      // 执行正常业务
      console.log('disconnectServiceExtensionAbility succeed');
    })
    .catch((error) => {
      // 处理业务逻辑错误
      console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
    ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback<void>): void;

断开与ServiceExtensionAbility的连接(callback形式)。

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

参数:

参数名

类型

必填

说明

connection

number

连接的ServiceExtensionAbility的数字代码,即connectServiceExtensionAbility返回的connectionId。

callback

AsyncCallback<void>

callback形式返回断开连接的结果。

错误码:

错误码ID

错误信息

16000001

The specified ability does not exist.

16000005

The specified process does not have the permission.

16000011

The context does not exist.

16000050

Internal error.

示例:

// connection为connectServiceExtensionAbility中的返回值
let connection = 1;

try {
  this.context.disconnectServiceExtensionAbility(connection, (error) => {
    if (error.code) {
      // 处理业务逻辑错误
      console.log('disconnectServiceExtensionAbility failed, error.code: ' + JSON.stringify(error.code) +
      ' error.message: ' + JSON.stringify(error.message));
      return;
    }
    // 执行正常业务
    console.log('disconnectServiceExtensionAbility succeed');
  });
} catch (paramError) {
  // 处理入参错误异常
  console.log('error.code: ' + JSON.stringify(paramError.code) +
  ' error.message: ' + JSON.stringify(paramError.message));
}

UIAbilityContext.setMissionLabel

setMissionLabel(label: string, callback:AsyncCallback<void>): void;

设置ability在任务中显示的名称(callback形式)。

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

参数:

参数名

类型

必填

说明

label

string

显示名称。

callback

AsyncCallback<void>

回调函数,返回接口调用是否成功的结果。

示例:

this.context.setMissionLabel("test",(result) => {
    console.log('setMissionLabel:' + JSON.stringify(result));
});

UIAbilityContext.setMissionLabel

setMissionLabel(label: string): Promise<void>;

设置ability在任务中显示的名称(promise形式)。

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

参数:

参数名

类型

必填

说明

label

string

显示名称。

返回值:

类型

说明

Promise<void>

返回一个Promise,包含接口的结果。

示例:

this.context.setMissionLabel("test").then(() => {
    console.log('success');
}).catch((error) => {
    console.log('failed:' + JSON.stringify(error));
});

UIAbilityContext.restoreWindowStage

restoreWindowStage(localStorage: LocalStorage) : void;

恢复ability中的window stage数据。

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

参数:

参数名

类型

必填

说明

localStorage

image.LocalStorage

用于恢复window stage的存储数据。

示例:

  var storage = new LocalStorage();
  this.context.restoreWindowStage(storage);

UIAbilityContext.isTerminating

isTerminating(): boolean;

查询ability是否在terminating状态。

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

返回值:

类型

说明

bool

true:ability当前处于terminating状态;false:不处于terminating状态。

示例:

var isTerminating = this.context.isTerminating();
console.log('ability state :' + isTerminating);


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-inner-application-uiabilitycontext-0000001478341321-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478341321__abilitycontextterminateself-1​

已于2023-4-2 10:03:57修改
收藏
回复
举报
回复
    相关推荐