1/* 2 * Copyright (c) 2022-2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"), 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit AbilityKit 19 */ 20 21import Ability from './@ohos.app.ability.Ability'; 22import AbilityConstant from './@ohos.app.ability.AbilityConstant'; 23import Want from './@ohos.app.ability.Want'; 24import window from './@ohos.window'; 25import UIAbilityContext from './application/UIAbilityContext'; 26/*** if arkts 1.1 */ 27import rpc from './@ohos.rpc'; 28/*** endif */ 29 30/** 31 * The prototype of the listener function interface registered by the Caller. 32 * 33 * @typedef OnReleaseCallback 34 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 35 * @stagemodelonly 36 * @since 9 37 */ 38export interface OnReleaseCallback { 39/** 40 * Defines the callback that is invoked when the stub on the target UIAbility is disconnected. 41 * 42 * @param { string } msg - Message used for disconnection. 43 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 44 * @stagemodelonly 45 * @since 9 46 */ 47 (msg: string): void; 48} 49 50/** 51 * The prototype of the listener function interface registered by the Caller. 52 * Defines the callback of OnRelease. 53 * 54 * @typedef OnReleaseCallback 55 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 56 * @param { string } msg - The notification event string listened to by the OnRelease. 57 * @stagemodelonly 58 * @since 20 59 * @arkts 1.2 60 */ 61export type OnReleaseCallback = (msg: string)=> void; 62 63 64/** 65 * The prototype of the listener function interface registered by the Caller. 66 * 67 * @typedef OnRemoteStateChangeCallback 68 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 69 * @stagemodelonly 70 * @since 10 71 */ 72export interface OnRemoteStateChangeCallback { 73/** 74 * Defines the callback that is invoked when the remote UIAbility state changes in the collaboration scenario. 75 * 76 * @param { string } msg - Message used for disconnection. 77 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 78 * @stagemodelonly 79 * @since 10 80 */ 81 (msg: string): void; 82} 83 84/** 85 * The prototype of the message listener function interface registered by the Callee. 86 * 87 * @typedef CalleeCallback 88 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 89 * @stagemodelonly 90 * @since 9 91 */ 92export interface CalleeCallback { 93/** 94 * Defines the callback of the registration message notification of the UIAbility. 95 * 96 * @param { rpc.MessageSequence } indata - Data to be transferred. 97 * @returns { rpc.Parcelable } Returned data object. 98 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 99 * @stagemodelonly 100 * @since 9 101 */ 102 (indata: rpc.MessageSequence): rpc.Parcelable; 103} 104 105/** 106 * Implements sending of parcelable data to the target UIAbility when the CallerAbility invokes the target UIAbility (CalleeAbility). 107 * 108 * @interface Caller 109 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 110 * @stagemodelonly 111 * @since arkts {'1.1':'9', '1.2':'20'} 112 * @arkts 1.1&1.2 113 */ 114export interface Caller { 115 /** 116 * Sends parcelable data to the target UIAbility. This API uses a promise to return the result. 117 * 118 * @param { string } method - Notification message string negotiated between the two UIAbilities. The message is used 119 * to instruct the callee to register a function to receive the parcelable data. 120 * @param { rpc.Parcelable } data - Parcelable data. You need to customize the data. 121 * @returns { Promise<void> } Promise that returns no value. 122 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 123 * 2. Incorrect parameter types. 124 * @throws { BusinessError } 16200001 - The caller has been released. 125 * @throws { BusinessError } 16200002 - The callee does not exist. 126 * @throws { BusinessError } 16000050 - Internal error. 127 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 128 * @stagemodelonly 129 * @since 9 130 */ 131 call(method: string, data: rpc.Parcelable): Promise<void>; 132 133 /** 134 * Sends parcelable data to the target UIAbility and obtains the parcelable data returned by the target UIAbility. 135 * This API uses a promise to return the result. 136 * 137 * @param { string } method - Notification message string negotiated between the two UIAbilities. The message is used 138 * to instruct the callee to register a function to receive the parcelable data. 139 * @param { rpc.Parcelable } data - Parcelable data. You need to customize the data. 140 * @returns { Promise<rpc.MessageSequence> } Promise used to return the parcelable data from the target UIAbility. 141 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 142 * 2. Incorrect parameter types. 143 * @throws { BusinessError } 16200001 - The caller has been released. 144 * @throws { BusinessError } 16200002 - The callee does not exist. 145 * @throws { BusinessError } 16000050 - Internal error. 146 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 147 * @stagemodelonly 148 * @since 9 149 */ 150 callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence>; 151 152 /** 153 * Releases the caller interface of the target UIAbility. 154 * 155 * @throws { BusinessError } 16200001 - The caller has been released. 156 * @throws { BusinessError } 16200002 - The callee does not exist. 157 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 158 * @stagemodelonly 159 * @since 9 160 */ 161 release(): void; 162 163 /** 164 * Called when the stub on the target UIAbility is disconnected. 165 * This API uses an asynchronous callback to return the result. 166 * 167 * @param { OnReleaseCallback } callback - Callback used to return the result. 168 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 169 * 2. Incorrect parameter types. 170 * @throws { BusinessError } 16200001 - The caller has been released. 171 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 172 * @stagemodelonly 173 * @since arkts {'1.1':'9', '1.2':'20'} 174 * @arkts 1.1&1.2 175 */ 176 onRelease(callback: OnReleaseCallback): void; 177 178 /** 179 * Called when the remote UIAbility state changes in the collaboration scenario. 180 * This API uses an asynchronous callback to return the result. 181 * 182 * @param { OnRemoteStateChangeCallback } callback - Callback used to return the result. 183 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 184 * 2. Incorrect parameter types. 185 * @throws { BusinessError } 16200001 - The caller has been released. 186 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 187 * @stagemodelonly 188 * @since 10 189 */ 190 onRemoteStateChange(callback: OnRemoteStateChangeCallback): void; 191 192 /** 193 * Called when the stub on the target UIAbility is disconnected. 194 * This API uses an asynchronous callback to return the result. 195 * 196 * @param { 'release' } type - Event type. The value is fixed at '**release**'. 197 * @param { OnReleaseCallback } callback - Callback used to return the result. 198 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 199 * 2. Incorrect parameter types; 3. Parameter verification failed. 200 * @throws { BusinessError } 16200001 - The caller has been released. 201 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 202 * @stagemodelonly 203 * @since 9 204 */ 205 on(type: 'release', callback: OnReleaseCallback): void; 206 207 /** 208 * Unregisters a callback that is invoked when the stub on the target UIAbility is disconnected. 209 * This capability is reserved. This API uses an asynchronous callback to return the result. 210 * 211 * @param { 'release' } type - Event type. The value is fixed at '**release**'. 212 * @param { OnReleaseCallback } callback - Callback used to return the result. 213 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 214 * 2. Incorrect parameter types; 3. Parameter verification failed. 215 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 216 * @stagemodelonly 217 * @since 9 218 */ 219 off(type: 'release', callback: OnReleaseCallback): void; 220 221 /** 222 * Unregisters a callback that is invoked when the stub on the target UIAbility is disconnected. 223 * This capability is reserved. 224 * 225 * @param { 'release' } type - Event type. The value is fixed at '**release**'. 226 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 227 * 2. Incorrect parameter types; 3. Parameter verification failed. 228 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 229 * @stagemodelonly 230 * @since 9 231 */ 232 off(type: 'release'): void; 233} 234 235/** 236 * Implements callbacks for caller notification registration and deregistration. 237 * 238 * @interface Callee 239 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 240 * @stagemodelonly 241 * @since 9 242 */ 243export interface Callee { 244 /** 245 * Registers a caller notification callback, which is invoked when the target UIAbility registers a function. 246 * 247 * @param { string } method - Notification message string negotiated between the two UIAbilities. 248 * @param { CalleeCallback } callback - JS notification synchronization callback of the rpc.MessageSequence type. The 249 * callback must return at least one empty rpc.Parcelable object. Otherwise, the function execution fails. 250 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 251 * 2. Incorrect parameter types; 3. Parameter verification failed. 252 * @throws { BusinessError } 16200004 - The method has been registered. 253 * @throws { BusinessError } 16000050 - Internal error. 254 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 255 * @stagemodelonly 256 * @since 9 257 */ 258 on(method: string, callback: CalleeCallback): void; 259 260 /** 261 * Unregisters a caller notification callback, which is invoked when the target UIAbility registers a function. 262 * 263 * @param { string } method - Registered notification message string. 264 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 265 * 2. Incorrect parameter types; 3. Parameter verification failed. 266 * @throws { BusinessError } 16200005 - The method has not been registered. 267 * @throws { BusinessError } 16000050 - Internal error. 268 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 269 * @stagemodelonly 270 * @since 9 271 */ 272 off(method: string): void; 273} 274 275/** 276 * The class of a UI ability. 277 * 278 * @extends Ability 279 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 280 * @stagemodelonly 281 * @since 9 282 */ 283/** 284 * The class of a UI ability. 285 * 286 * @extends Ability 287 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 288 * @stagemodelonly 289 * @crossplatform 290 * @since 10 291 */ 292/** 293 * UIAbility is an application component that has the UI. 294 * The UIAbility module, inherited from Ability, provides lifecycle callbacks such as component creation, destruction, 295 * and foreground/background switching. It also provides the following capabilities related to component collaboration: 296 * <br>Caller: an object returned by startAbilityByCall. The CallerAbility (caller) uses this object to communicate 297 * with the CalleeAbility (callee). 298 * <br>Callee: an internal object of UIAbility. The CalleeAbility (callee) uses this object to communicate with the 299 * CallerAbility (caller). 300 * 301 * @extends Ability 302 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 303 * @stagemodelonly 304 * @crossplatform 305 * @atomicservice 306 * @since arkts {'1.1':'11', '1.2':'20'} 307 * @arkts 1.1&1.2 308 */ 309declare class UIAbility extends Ability { 310 /** 311 * Indicates configuration information about an ability context. 312 * 313 * @type { UIAbilityContext } 314 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 315 * @stagemodelonly 316 * @since 9 317 */ 318 /** 319 * Indicates configuration information about an ability context. 320 * 321 * @type { UIAbilityContext } 322 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 323 * @stagemodelonly 324 * @crossplatform 325 * @since 10 326 */ 327 /** 328 * Context of the UIAbility. 329 * 330 * @type { UIAbilityContext } 331 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 332 * @stagemodelonly 333 * @crossplatform 334 * @atomicservice 335 * @since arkts {'1.1':'11', '1.2':'20'} 336 * @arkts 1.1&1.2 337 */ 338 context: UIAbilityContext; 339 340 /** 341 * Indicates ability launch want. 342 * 343 * @type { Want } 344 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 345 * @stagemodelonly 346 * @since 9 347 */ 348 /** 349 * Parameters for starting the UIAbility. 350 * 351 * @type { Want } 352 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 353 * @stagemodelonly 354 * @atomicservice 355 * @since arkts {'1.1':'11', '1.2':'20'} 356 * @arkts 1.1&1.2 357 */ 358 launchWant: Want; 359 360 /** 361 * Indicates ability last request want. 362 * 363 * @type { Want } 364 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 365 * @stagemodelonly 366 * @since 9 367 */ 368 /** 369 * Latest Want received through onCreate or onNewWant when the UIAbility is started for multiple times. 370 * 371 * @type { Want } 372 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 373 * @stagemodelonly 374 * @atomicservice 375 * @since arkts {'1.1':'11', '1.2':'20'} 376 * @arkts 1.1&1.2 377 */ 378 lastRequestWant: Want; 379 380 /** 381 * Object that invokes the stub service. 382 * 383 * @type { Callee } 384 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 385 * @stagemodelonly 386 * @since 9 387 */ 388 callee: Callee; 389 390 /** 391 * Called back when an ability is started for initialization. 392 * 393 * @param { Want } want - Indicates the want info of the created ability. 394 * @param { AbilityConstant.LaunchParam } launchParam - Indicates the launch param. 395 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 396 * @stagemodelonly 397 * @since 9 398 */ 399 /** 400 * Called back when an ability is started for initialization. 401 * 402 * @param { Want } want - Indicates the want info of the created ability. 403 * @param { AbilityConstant.LaunchParam } launchParam - Indicates the launch param. 404 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 405 * @stagemodelonly 406 * @crossplatform 407 * @since 10 408 */ 409 /** 410 * Called to initialize the service logic when a UIAbility instance in the completely closed state is created. 411 * In other words, a UIAbility instance enters this lifecycle callback from a cold start. This API returns the 412 * result synchronously and does not support asynchronous callback. 413 * 414 * @param { Want } want - Want information, including the ability name and bundle name. 415 * @param { AbilityConstant.LaunchParam } launchParam - Parameters for starting the UIAbility, and the reason for 416 * the last abnormal exit. 417 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 418 * @stagemodelonly 419 * @crossplatform 420 * @atomicservice 421 * @since arkts {'1.1':'11', '1.2':'20'} 422 * @arkts 1.1&1.2 423 */ 424 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void; 425 426 /** 427 * Called back when an ability window stage is created. 428 * 429 * @param { window.WindowStage } windowStage - Indicates the created WindowStage. 430 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 431 * @stagemodelonly 432 * @since 9 433 */ 434 /** 435 * Called back when an ability window stage is created. 436 * 437 * @param { window.WindowStage } windowStage - Indicates the created WindowStage. 438 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 439 * @stagemodelonly 440 * @crossplatform 441 * @since 10 442 */ 443 /** 444 * Called when a WindowStage is created for this UIAbility. 445 * 446 * @param { window.WindowStage } windowStage - WindowStage information. 447 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 448 * @stagemodelonly 449 * @crossplatform 450 * @atomicservice 451 * @since arkts {'1.1':'11', '1.2':'20'} 452 * @arkts 1.1&1.2 453 */ 454 onWindowStageCreate(windowStage: window.WindowStage): void; 455 456 /** 457 * Called when the WindowStage is about to be destroyed. 458 * 459 * @param { window.WindowStage } windowStage - WindowStage information. 460 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 461 * @stagemodelonly 462 * @atomicservice 463 * @since arkts {'1.1':'12', '1.2':'20'} 464 * @arkts 1.1&1.2 465 */ 466 onWindowStageWillDestroy(windowStage: window.WindowStage): void; 467 468 /** 469 * Called back when an ability window stage is destroyed. 470 * 471 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 472 * @stagemodelonly 473 * @since 9 474 */ 475 /** 476 * Called back when an ability window stage is destroyed. 477 * 478 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 479 * @stagemodelonly 480 * @crossplatform 481 * @since 10 482 */ 483 /** 484 * Called when the WindowStage is destroyed for this UIAbility. 485 * 486 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 487 * @stagemodelonly 488 * @crossplatform 489 * @atomicservice 490 * @since arkts {'1.1':'11', '1.2':'20'} 491 * @arkts 1.1&1.2 492 */ 493 onWindowStageDestroy(): void; 494 495 /** 496 * Called back when an ability window stage is restored. 497 * 498 * @param { window.WindowStage } windowStage - window stage to restore 499 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 500 * @stagemodelonly 501 * @since 9 502 */ 503 /** 504 * Called when the WindowStage is restored during the migration of this UIAbility, which is a multi-instance ability. 505 * 506 * @param { window.WindowStage } windowStage - WindowStage information. 507 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 508 * @stagemodelonly 509 * @atomicservice 510 * @since arkts {'1.1':'11', '1.2':'20'} 511 * @arkts 1.1&1.2 512 */ 513 onWindowStageRestore(windowStage: window.WindowStage): void; 514 515 /** 516 * Called back before an ability is destroyed. 517 * 518 * @returns { void | Promise<void> } the promise returned by the function. 519 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 520 * @stagemodelonly 521 * @since 9 522 */ 523 /** 524 * Called back before an ability is destroyed. 525 * 526 * @returns { void | Promise<void> } the promise returned by the function. 527 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 528 * @stagemodelonly 529 * @crossplatform 530 * @since 10 531 */ 532 /** 533 * Called to clear resources when this UIAbility is destroyed. 534 * This API returns the result synchronously or uses a promise to return the result. 535 * 536 * <p>**NOTE**: 537 * <br>After the onDestroy() lifecycle callback is executed, the application may exit. Consequently, 538 * the asynchronous function (for example, asynchronously writing data to the database) in onDestroy() may fail to be 539 * executed. You can use the asynchronous lifecycle to ensure that the subsequent lifecycle continues only after the 540 * asynchronous function in onDestroy() finishes the execution. 541 * </p> 542 * 543 * @returns { void | Promise<void> } the promise returned by the function. 544 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 545 * @stagemodelonly 546 * @crossplatform 547 * @atomicservice 548 * @since 11 549 */ 550 onDestroy(): void | Promise<void>; 551 552 /** 553 * Called to clear resources when this UIAbility is destroyed. 554 * This API returns the result synchronously or uses a promise to return the result. 555 * 556 * <p>**NOTE**: 557 * <br>After the onDestroy() lifecycle callback is executed, the application may exit. Consequently, 558 * the asynchronous function (for example, asynchronously writing data to the database) in onDestroy() may fail to be 559 * executed. You can use the asynchronous lifecycle to ensure that the subsequent lifecycle continues only after the 560 * asynchronous function in onDestroy() finishes the execution. 561 * </p> 562 * 563 * @returns { void } the promise returned by the function. 564 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 565 * @stagemodelonly 566 * @crossplatform 567 * @atomicservice 568 * @since 20 569 * @arkts 1.2 570 */ 571 onDestroy(): void; 572 573 /** 574 * Called to clear resources when this UIAbility is destroyed. 575 * This API returns the result synchronously or uses a promise to return the result. 576 * 577 * <p>**NOTE**: 578 * <br>After the onDestroyAsync() lifecycle callback is executed, the application may exit. Consequently, 579 * the asynchronous function (for example, asynchronously writing data to the database) in onDestroyAsync() may fail to be 580 * executed. You can use the asynchronous lifecycle to ensure that the subsequent lifecycle continues only after the 581 * asynchronous function in onDestroyAsync() finishes the execution. 582 * </p> 583 * 584 * @returns { Promise<void> } the promise returned by the function. 585 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 586 * @stagemodelonly 587 * @crossplatform 588 * @atomicservice 589 * @since 20 590 * @arkts 1.2 591 */ 592 onDestroyAsync(): Promise<void>; 593 594 /** 595 * Called back when the state of an ability changes to foreground. 596 * 597 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 598 * @stagemodelonly 599 * @since 9 600 */ 601 /** 602 * Called back when the state of an ability changes to foreground. 603 * 604 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 605 * @stagemodelonly 606 * @crossplatform 607 * @since 10 608 */ 609 /** 610 * Triggered when the application transitions from the background to the foreground. 611 * It is called between onWillForeground and onDidForeground. 612 * It can be used to request system resources required, for example, requesting location services when the 613 * application transitions to the foreground. 614 * 615 * <p>**NOTE**: 616 * <br>This API returns the result synchronously and does not support asynchronous callback. 617 * </p> 618 * 619 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 620 * @stagemodelonly 621 * @crossplatform 622 * @atomicservice 623 * @since arkts {'1.1':'11', '1.2':'20'} 624 * @arkts 1.1&1.2 625 */ 626 onForeground(): void; 627 628 /** 629 * Triggered just before the application transitions to the foreground. 630 * It is called before onForeground. 631 * It can be used to capture the moment when the application starts to transition to the foreground. 632 * When paired with onDidForeground, it can also measure the duration from the application's initial 633 * foreground entry to its full transition into the foreground state. 634 * 635 * <p>**NOTE**: 636 * <br>This API returns the result synchronously and does not support asynchronous callback. 637 * </p> 638 * 639 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 640 * @stagemodelonly 641 * @atomicservice 642 * @since 20 643 */ 644 onWillForeground(): void; 645 646 /** 647 * Triggered after the application has transitioned to the foreground. 648 * It is called after onForeground. 649 * It can be used to capture the moment when the application fully transitions to the foreground. 650 * When paired with onWillForeground, it can also measure the duration from the application's initial foreground 651 * entry to its full transition into the foreground state. 652 * 653 * <p>**NOTE**: 654 * <br>This API returns the result synchronously and does not support asynchronous callback. 655 * </p> 656 * 657 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 658 * @stagemodelonly 659 * @atomicservice 660 * @since 20 661 */ 662 onDidForeground(): void; 663 664 /** 665 * Called back when the state of an ability changes to background. 666 * 667 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 668 * @stagemodelonly 669 * @since 9 670 */ 671 /** 672 * Called back when the state of an ability changes to background. 673 * 674 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 675 * @stagemodelonly 676 * @crossplatform 677 * @since 10 678 */ 679 /** 680 * Triggered when the application transitions from the foreground to the background. 681 * It is called between onWillBackground and onDidBackground. 682 * It can be used to release resources when the UI is no longer visible, for example, stopping location services. 683 * 684 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 685 * @stagemodelonly 686 * @crossplatform 687 * @atomicservice 688 * @since arkts {'1.1':'11', '1.2':'20'} 689 * @arkts 1.1&1.2 690 */ 691 onBackground(): void; 692 693 /** 694 * Triggered just when the application transitions to the background. 695 * It is called before onBackground. 696 * It can be used to log various types of data, such as faults, statistics, security information, and user behavior 697 * that occur during application running. 698 * 699 * <p>**NOTE**: 700 * <br>This API returns the result synchronously and does not support asynchronous callback. 701 * </p> 702 * 703 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 704 * @stagemodelonly 705 * @atomicservice 706 * @since 20 707 */ 708 onWillBackground(): void; 709 710 /** 711 * Triggered after the application has transitioned to the background. 712 * It is called after onBackground. 713 * It can be used to release resources after the application has entered the background, for example, stopping 714 * audio playback. 715 * 716 * <p>**NOTE**: 717 * <br>This API returns the result synchronously and does not support asynchronous callback. 718 * <p/> 719 * 720 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 721 * @stagemodelonly 722 * @atomicservice 723 * @since 20 724 */ 725 onDidBackground(): void; 726 727 /** 728 * Called back when an ability prepares to continue. 729 * 730 * @param { object } wantParam - Indicates the want parameter. 731 * @returns { AbilityConstant.OnContinueResult } Return the result of onContinue. 732 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 733 * @stagemodelonly 734 * @since 9 735 */ 736 /** 737 * Called back when an ability prepares to continue. 738 * 739 * @param { Record<string, Object> } wantParam - Indicates the want parameter. 740 * @returns { AbilityConstant.OnContinueResult } Return the result of onContinue. 741 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 742 * @stagemodelonly 743 * @atomicservice 744 * @since 11 745 */ 746 /** 747 * Called to save data during the UIAbility migration preparation process. 748 * 749 * <p>**NOTE**: 750 * <br>Since API version 12, UIAbility.onContinue supports the return value in the form of 751 * Promise<AbilityConstant.OnContinueResult>. 752 * </p> 753 * 754 * @param { Record<string, Object> } wantParam - want parameter. 755 * @returns { AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult> } Continuation result or 756 * Promise used to return the continuation result. 757 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 758 * @stagemodelonly 759 * @atomicservice 760 * @since 12 761 */ 762 onContinue(wantParam: Record<string, Object>): 763 AbilityConstant.OnContinueResult | Promise<AbilityConstant.OnContinueResult>; 764 765 /** 766 * Called when the launch mode of an ability is set to singleton. 767 * This happens when you re-launch an ability that has been at the top of the ability stack. 768 * 769 * @param { Want } want - Indicates the want info of ability. 770 * @param { AbilityConstant.LaunchParam } launchParam - Indicates the launch parameters. 771 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 772 * @stagemodelonly 773 * @since 9 774 */ 775 /** 776 * Called when the launch mode of an ability is set to singleton. 777 * This happens when you re-launch an ability that has been at the top of the ability stack. 778 * 779 * @param { Want } want - Indicates the want info of ability. 780 * @param { AbilityConstant.LaunchParam } launchParam - Indicates the launch parameters. 781 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 782 * @stagemodelonly 783 * @crossplatform 784 * @since 10 785 */ 786 /** 787 * Called when a UIAbility instance that has undergone the following states is started again: 788 * started in the foreground, running in the foreground, and switched to the background. 789 * 790 * The triggering of the onNewWant lifecycle of a UIAbility instance indicates that this launch is a hot launch. 791 * Note that a hot launch does not necessarily trigger the onNewWant lifecycle. 792 * 793 * If you need to prevent the onNewWant lifecycle from being triggered in specific scenarios, 794 * you must call the {@link UIAbilityContext.setOnNewWantSkipScenarios} interface to suppress its callback. 795 * 796 * @param { Want } want - Want information, such as the ability name and bundle name. 797 * @param { AbilityConstant.LaunchParam } launchParam - Reason for the UIAbility startup and the last abnormal exit. 798 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 799 * @stagemodelonly 800 * @crossplatform 801 * @atomicservice 802 * @since arkts {'1.1':'11', '1.2':'20'} 803 * @arkts 1.1&1.2 804 */ 805 onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void; 806 807 /** 808 * Called when dump client information is required. 809 * It is recommended that developers don't DUMP sensitive information. 810 * 811 * @param { Array<string> } params - Indicates the params from command. 812 * @returns { Array<string> } Return the dump info array. 813 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 814 * @stagemodelonly 815 * @since 9 816 */ 817 /** 818 * Called when dump client information is required. 819 * This API can be used to dump non-sensitive information. 820 * 821 * @param { Array<string> } params - Parameters in the form of a command. 822 * @returns { Array<string> } Dumped information array. 823 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 824 * @stagemodelonly 825 * @atomicservice 826 * @since 11 827 */ 828 onDump(params: Array<string>): Array<string>; 829 830 /** 831 * Called back when an ability prepares to save. 832 * 833 * @param { AbilityConstant.StateType } reason - state type when save. 834 * @param { object } wantParam - Indicates the want parameter. 835 * @returns { AbilityConstant.OnSaveResult } agree with the current UIAbility status or not.return 0 if ability 836 * agrees to save data successfully, otherwise errcode. 837 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 838 * @stagemodelonly 839 * @since 9 840 */ 841 /** 842 * Called when the framework automatically saves the UIAbility state in the case of an application fault. 843 * When an application is faulty, the framework calls onSaveState to save the status of the UIAbility if 844 * auto-save is enabled. 845 * 846 * <p>**NOTE**: 847 * <br>This API is used together with appRecovery. 848 * </p> 849 * 850 * @param { AbilityConstant.StateType } reason - Reason for triggering the callback to save the UIAbility state. 851 * @param { Record<string, Object> } wantParam - want parameter. 852 * @returns { AbilityConstant.OnSaveResult } Whether the UIAbility state is saved. 853 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 854 * @stagemodelonly 855 * @atomicservice 856 * @since 11 857 */ 858 onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>): AbilityConstant.OnSaveResult; 859 860 /** 861 * Called back asynchronously when an ability prepares to save. 862 * 863 * @param { AbilityConstant.StateType } stateType - state type when save. 864 * @param { Record<string, Object> } wantParam - Indicates the want parameter. 865 * @returns { Promise<AbilityConstant.OnSaveResult> } agree with the current UIAbility status or not.return 0 if ability 866 * agrees to save data successfully, otherwise errcode. 867 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 868 * @stagemodelonly 869 * @atomicservice 870 * @since 20 871 */ 872 onSaveStateAsync(stateType: AbilityConstant.StateType, wantParam: Record<string, Object>): Promise<AbilityConstant.OnSaveResult>; 873 874 /** 875 * Called back when an ability shares data. 876 * 877 * @param { object } wantParam - Indicates the want parameter. 878 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 879 * @stagemodelonly 880 * @since 10 881 */ 882 /** 883 * Called by this UIAbility to set data to share in the cross-device sharing scenario. 884 * 885 * @param { Record<string, Object> } wantParam - Data to share. 886 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 887 * @stagemodelonly 888 * @atomicservice 889 * @since 11 890 */ 891 onShare(wantParam: Record<string, Object>): void; 892 893 /** 894 * Called back when an ability prepare to terminate. 895 * 896 * @permission ohos.permission.PREPARE_APP_TERMINATE 897 * @returns { boolean } Returns {@code true} if the ability need to top terminating; returns {@code false} if the 898 * ability need to terminate. 899 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 900 * @stagemodelonly 901 * @since 10 902 */ 903 /** 904 * Called when this UIAbility is about to terminate. It allows for additional actions to be performed before the 905 * UIAbility is officially terminated. 906 * For example, you can prompt the user to confirm whether they want to terminate the UIAbility. If the user 907 * confirms, you can call terminateSelf to terminate it. 908 * 909 * <p>**NOTE**: 910 * <br>Currently, this API takes effect only on 2-in-1 devices. 911 * <br>Since API version 15, this callback is not executed when UIAbility.onPrepareToTerminateAsync is implemented. 912 * <br>When AbilityStage.onPrepareTerminationAsync or AbilityStage.onPrepareTermination is implemented, this callback 913 * is not executed if the user right-clicks the dock bar or system tray to close the UIAbility. 914 * </p> 915 * 916 * @permission ohos.permission.PREPARE_APP_TERMINATE 917 * @returns { boolean } Whether to terminate the UIAbility. 918 * <br>The value <code>true</code> means that the termination process is canceled. 919 * <br>The value <code>false</code> means to continue terminating the UIAbility. 920 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 921 * @stagemodelonly 922 * @atomicservice 923 * @since 11 924 */ 925 onPrepareToTerminate(): boolean; 926 927 /** 928 * Called when this UIAbility is about to terminate. It allows for additional actions to be performed before the 929 * UIAbility is officially terminated. 930 * This API uses a promise to return the result. 931 * For example, you can prompt the user to confirm whether they want to terminate the UIAbility. If the user 932 * confirms, you can call terminateSelf to terminate it. 933 * 934 * <p>**NOTE**: 935 * <br>Currently, this API takes effect only on 2-in-1 devices. 936 * <br>When AbilityStage.onPrepareTerminationAsync or AbilityStage.onPrepareTermination is implemented, this callback 937 * is not executed if the user right-clicks the dock bar or system tray to close the UIAbility. 938 * <br>If an asynchronous callback crashes, it will be handled as a timeout. If the UIAbility does not respond within 939 * 10 seconds, it will be terminated forcibly. 940 * </P> 941 * 942 * @permission ohos.permission.PREPARE_APP_TERMINATE 943 * @returns { Promise<boolean> } Promise used to return the result. 944 * <br>The value <code>true</code> means that the termination process is canceled. 945 * <br>The value <code>false</code> means to continue terminating the UIAbility. 946 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 947 * @stagemodelonly 948 * @atomicservice 949 * @since 15 950 */ 951 onPrepareToTerminateAsync(): Promise<boolean>; 952 953 /** 954 * Called back when back press is dispatched. 955 * 956 * @returns { boolean } Returns {@code true} means the ability will move to background when back is pressed; 957 * Returns {@code false} means the ability will be destroyed when back is pressed. 958 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 959 * @stagemodelonly 960 * @since 10 961 */ 962 /** 963 * Called when an operation of going back to the previous page is triggered on this UIAbility. The return value 964 * determines whether to destroy the UIAbility instance. 965 * 966 * <p>**NOTE**: 967 * <br>When the target SDK version is earlier than 12, the default return value is false, indicating that the 968 * UIAbility will be destroyed. 969 * <br>When the target SDK version is 12 or later, the default return value is true, indicating that the UIAbility 970 * will be moved to the background and will not be destroyed. 971 * </p> 972 * 973 * @returns { boolean } The value <code>true</code> means that the UIAbility instance will be moved to the background 974 * and will not be destroyed, and <code>false</code> means that the UIAbility instance will be destroyed. 975 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 976 * @stagemodelonly 977 * @atomicservice 978 * @since arkts {'1.1':'11', '1.2':'20'} 979 * @arkts 1.1&1.2 980 */ 981 onBackPressed(): boolean; 982 983 /** 984 * Callback invoked to return the collaboration result in multi-device collaboration scenarios. 985 * 986 * <p>**NOTE**: 987 * <br>This callback does not support ability launch in specified mode. 988 * <br>When you use methods such as startAbility() to start an application, you must include 989 * FLAG_ABILITY_ON_COLLABORATE in Flags in the Want object. 990 * <br>During a cold start, this callback must be invoked before onForeground or after onBackground. During a hot 991 * start, this callback must be invoked before onNewWant. 992 * </p> 993 * 994 * @param { Record<string, Object> } wantParam - Want parameter, which supports only the key 995 * "ohos.extra.param.key.supportCollaborateIndex". The key can be used to obtain the data passed by the caller and 996 * perform corresponding processing. 997 * @returns { AbilityConstant.CollaborateResult } Collaborator result, that is, whether the target application 998 * accepts the collaboration request. 999 * @syscap SystemCapability.Ability.AbilityRuntime.AbilityCore 1000 * @stagemodelonly 1001 * @since 18 1002 */ 1003 onCollaborate(wantParam: Record<string, Object>): AbilityConstant.CollaborateResult; 1004} 1005 1006export default UIAbility;