1# UIExtensionContext 2 3UIExtensionContext是[UIExtensionAbility](js-apis-app-ability-uiExtensionAbility.md)的上下文环境，继承自[ExtensionContext](js-apis-inner-application-extensionContext.md)，提供UIExtensionAbility的相关配置信息以及操作UIAbility的方法，如启动UIAbility等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口仅可在Stage模型下使用。 9 10## 导入模块 11 12```ts 13import common from '@ohos.app.ability.common'; 14``` 15 16## UIExtensionContext.startAbility 17 18startAbility(want: Want, callback: AsyncCallback<void>): void; 19 20启动Ability（callback形式）。 21 22使用规则： 23 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 24 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 25 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 26 27**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 28 29**参数：** 30 31| 参数名 | 类型 | 必填 | 说明 | 32| -------- | -------- | -------- | -------- | 33| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 34| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 35 36**错误码：** 37 38| 错误码ID | 错误信息 | 39| ------- | -------------------------------- | 40| 16000001 | The specified ability does not exist. | 41| 16000002 | Incorrect ability type. | 42| 16000004 | Can not start invisible component. | 43| 16000005 | The specified process does not have the permission. | 44| 16000006 | Cross-user operations are not allowed. | 45| 16000008 | The crowdtesting application expires. | 46| 16000009 | An ability cannot be started or stopped in Wukong mode. | 47| 16000010 | The call with the continuation flag is forbidden. | 48| 16000011 | The context does not exist. | 49| 16000012 | The application is controlled. | 50| 16000013 | The application is controlled by EDM. | 51| 16000050 | Internal error. | 52| 16000053 | The ability is not on the top of the UI. | 53| 16000055 | Installation-free timed out. | 54| 16200001 | The caller has been released. | 55 56错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 57 58## UIExtensionContext.startAbility 59 60startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; 61 62启动Ability（callback形式）。 63 64使用规则： 65 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 66 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 67 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 68 69**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 70 71**参数：** 72 73| 参数名 | 类型 | 必填 | 说明 | 74| -------- | -------- | -------- | -------- | 75| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 76| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 77| callback | AsyncCallback<void> | 是 | callback形式返回启动结果。 | 78 79**错误码：** 80 81| 错误码ID | 错误信息 | 82| ------- | -------------------------------- | 83| 16000001 | The specified ability does not exist. | 84| 16000004 | Can not start invisible component. | 85| 16000005 | The specified process does not have the permission. | 86| 16000006 | Cross-user operations are not allowed. | 87| 16000008 | The crowdtesting application expires. | 88| 16000009 | An ability cannot be started or stopped in Wukong mode. | 89| 16000011 | The context does not exist. | 90| 16000012 | The application is controlled. | 91| 16000013 | The application is controlled by EDM. | 92| 16000050 | Internal error. | 93| 16000053 | The ability is not on the top of the UI. | 94| 16000055 | Installation-free timed out. | 95| 16200001 | The caller has been released. | 96 97错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 98 99## UIExtensionContext.startAbility 100 101startAbility(want: Want, options?: StartOptions): Promise<void>; 102 103启动Ability（promise形式）。 104 105使用规则： 106 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 107 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 108 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 109 110**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 111 112**参数：** 113 114| 参数名 | 类型 | 必填 | 说明 | 115| -------- | -------- | -------- | -------- | 116| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 117| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 118 119**返回值：** 120 121| 类型 | 说明 | 122| -------- | -------- | 123| Promise<void> | Promise形式返回启动结果。 | 124 125**错误码：** 126 127| 错误码ID | 错误信息 | 128| ------- | -------------------------------- | 129| 16000001 | The specified ability does not exist. | 130| 16000002 | Incorrect ability type. | 131| 16000004 | Can not start invisible component. | 132| 16000005 | The specified process does not have the permission. | 133| 16000006 | Cross-user operations are not allowed. | 134| 16000008 | The crowdtesting application expires. | 135| 16000009 | An ability cannot be started or stopped in Wukong mode. | 136| 16000010 | The call with the continuation flag is forbidden. | 137| 16000011 | The context does not exist. | 138| 16000012 | The application is controlled. | 139| 16000013 | The application is controlled by EDM. | 140| 16000050 | Internal error. | 141| 16000053 | The ability is not on the top of the UI. | 142| 16000055 | Installation-free timed out. | 143| 16200001 | The caller has been released. | 144 145错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 146 147## UIExtensionContext.startAbilityForResult 148 149startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; 150 151启动一个Ability。Ability被启动后，有如下情况(callback形式): 152 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 153 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 154 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 155 156使用规则： 157 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 158 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 159 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 160 161**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 162 163**参数：** 164 165| 参数名 | 类型 | 必填 | 说明 | 166| -------- | -------- | -------- | -------- | 167| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 168| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 执行结果回调函数。 | 169 170**错误码：** 171 172| 错误码ID | 错误信息 | 173| ------- | -------------------------------- | 174| 16000001 | The specified ability does not exist. | 175| 16000002 | Incorrect ability type. | 176| 16000004 | Can not start invisible component. | 177| 16000005 | The specified process does not have the permission. | 178| 16000006 | Cross-user operations are not allowed. | 179| 16000008 | The crowdtesting application expires. | 180| 16000009 | An ability cannot be started or stopped in Wukong mode. | 181| 16000010 | The call with the continuation flag is forbidden. | 182| 16000011 | The context does not exist. | 183| 16000012 | The application is controlled. | 184| 16000013 | The application is controlled by EDM. | 185| 16000050 | Internal error. | 186| 16000053 | The ability is not on the top of the UI. | 187| 16000055 | Installation-free timed out. | 188| 16200001 | The caller has been released. | 189 190错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 191 192## UIExtensionContext.startAbilityForResult 193 194startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; 195 196启动一个Ability。Ability被启动后，有如下情况(callback形式): 197 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 198 - 异常情况下比如杀死Ability会返回异常信息给调用方，异常信息中resultCode为-1。 199 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方，其它调用方返回异常信息, 异常信息中resultCode为-1。 200 201使用规则： 202 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 203 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 204 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 205 206**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 207 208**参数：** 209 210| 参数名 | 类型 | 必填 | 说明 | 211| -------- | -------- | -------- | -------- | 212| want |[Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 213| options | [StartOptions](js-apis-app-ability-startOptions.md) | 是 | 启动Ability所携带的参数。 | 214| callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 执行结果回调函数。 | 215 216**错误码：** 217 218| 错误码ID | 错误信息 | 219| ------- | -------------------------------- | 220| 16000001 | The specified ability does not exist. | 221| 16000004 | Can not start invisible component. | 222| 16000005 | The specified process does not have the permission. | 223| 16000006 | Cross-user operations are not allowed. | 224| 16000008 | The crowdtesting application expires. | 225| 16000009 | An ability cannot be started or stopped in Wukong mode. | 226| 16000011 | The context does not exist. | 227| 16000012 | The application is controlled. | 228| 16000013 | The application is controlled by EDM. | 229| 16000050 | Internal error. | 230| 16000053 | The ability is not on the top of the UI. | 231| 16000055 | Installation-free timed out. | 232| 16200001 | The caller has been released. | 233 234错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 235 236## UIExtensionContext.startAbilityForResult 237 238startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; 239 240启动一个Ability。Ability被启动后，有如下情况(promise形式): 241 - 正常情况下可通过调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用方。 242 - 异常情况下比如杀死Ability会返回异常信息给调用方, 异常信息中resultCode为-1。 243 - 如果被启动的Ability模式是单实例模式, 不同应用多次调用该接口启动这个Ability，当这个Ability调用[terminateSelfWithResult](js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult)接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息, 异常信息中resultCode为-1。 244 245使用规则： 246 - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 247 - 跨应用场景下，目标Ability的exported属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 248 - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) 249 250**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 251 252**参数：** 253 254| 参数名 | 类型 | 必填 | 说明 | 255| -------- | -------- | -------- | -------- | 256| want | [Want](js-apis-app-ability-want.md) | 是 | 启动Ability的want信息。 | 257| options | [StartOptions](js-apis-app-ability-startOptions.md) | 否 | 启动Ability所携带的参数。 | 258 259 260**返回值：** 261 262| 类型 | 说明 | 263| -------- | -------- | 264| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise形式返回执行结果。 | 265 266**错误码：** 267 268| 错误码ID | 错误信息 | 269| ------- | -------------------------------- | 270| 16000001 | The specified ability does not exist. | 271| 16000002 | Incorrect ability type. | 272| 16000004 | Can not start invisible component. | 273| 16000005 | The specified process does not have the permission. | 274| 16000006 | Cross-user operations are not allowed. | 275| 16000008 | The crowdtesting application expires. | 276| 16000009 | An ability cannot be started or stopped in Wukong mode. | 277| 16000010 | The call with the continuation flag is forbidden. | 278| 16000011 | The context does not exist. | 279| 16000012 | The application is controlled. | 280| 16000013 | The application is controlled by EDM. | 281| 16000050 | Internal error. | 282| 16000053 | The ability is not on the top of the UI. | 283| 16000055 | Installation-free timed out. | 284| 16200001 | The caller has been released. | 285 286错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 287 288 289## UIExtensionContext.connectServiceExtensionAbility 290 291connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; 292 293将当前Ability连接到一个使用AbilityInfo.AbilityType.SERVICE模板的Ability。 294 295**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 296 297**参数：** 298 299| 参数名 | 类型 | 必填 | 说明 | 300| -------- | -------- | -------- | -------- | 301| want | [Want](js-apis-app-ability-want.md) | 是 | 连接ServiceExtensionAbility的want信息。 | 302| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 与ServiceExtensionAbility建立连接后回调函数的实例。 | 303 304**返回值：** 305 306| 类型 | 说明 | 307| -------- | -------- | 308| number | 返回Ability连接的结果code。 | 309 310**错误码：** 311 312| 错误码ID | 错误信息 | 313| ------- | -------------------------------- | 314| 16000001 | The specified ability does not exist. | 315| 16000002 | Incorrect ability type. | 316| 16000004 | Can not start invisible component. | 317| 16000005 | The specified process does not have the permission. | 318| 16000006 | Cross-user operations are not allowed. | 319| 16000008 | The crowdtesting application expires. | 320| 16000053 | The ability is not on the top of the UI. | 321| 16000055 | Installation-free timed out. | 322| 16000011 | The context does not exist. | 323| 16000050 | Internal error. | 324 325错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 326 327 328## UIExtensionContext.disconnectServiceExtensionAbility 329 330disconnectServiceExtensionAbility(connection: number): Promise\<void>; 331 332断开与ServiceExtensionAbility的连接，断开连接之后需要将连接成功时返回的remote对象置空（promise形式）。 333 334**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 335 336**参数：** 337 338| 参数名 | 类型 | 必填 | 说明 | 339| -------- | -------- | -------- | -------- | 340| connection | number | 是 | 连接的ServiceExtensionAbility的数字代码，即connectServiceExtensionAbility返回的connectionId。 | 341 342**返回值：** 343 344| 类型 | 说明 | 345| -------- | -------- | 346| Promise\<void> | 返回执行结果。 | 347 348**错误码：** 349 350| 错误码ID | 错误信息 | 351| ------- | -------------------------------- | 352| 16000011 | The context does not exist. | 353| 16000050 | Internal error. | 354 355错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md) 356 357## UIExtensionContext.disconnectServiceExtensionAbility 358 359disconnectServiceExtensionAbility(connection: number, callback:AsyncCallback\<void>): void; 360 361断开与ServiceExtensionAbility的连接，断开连接之后需要将连接成功时返回的remote对象置空（callback形式）。 362 363**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 364 365**参数：** 366 367| 参数名 | 类型 | 必填 | 说明 | 368| -------- | -------- | -------- | -------- | 369| connection | number | 是 | 连接的ServiceExtensionAbility的数字代码，即connectServiceExtensionAbility返回的connectionId。 | 370| callback | AsyncCallback\<void> | 是 | callback形式返回断开连接的结果。 | 371 372**错误码：** 373 374| 错误码ID | 错误信息 | 375| ------- | -------------------------------- | 376| 16000011 | The context does not exist. | 377| 16000050 | Internal error. | 378 379错误码详细介绍请参考[errcode-ability](../errorcodes/errorcode-ability.md)