1/* 2 * Copyright (c) 2023 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 ArkUI 19 */ 20 21/*** if arkts 1.2 */ 22import Want from '../../@ohos.app.ability.Want' 23import { Callback, ErrorCallback, BusinessError } from '../../@ohos.base' 24import { CommonMethod, TerminationInfo } from './common' 25import { ComponentContent } from '../ComponentContent' 26/*** endif */ 27 28/** 29 * Enumeration of different types of DpiFollowStrategy. 30 * 31 * @enum { number } 32 * @syscap SystemCapability.ArkUI.ArkUI.Full 33 * @systemapi 34 * @since arkts {'1.1':'12','1.2':'20'} 35 * @arkts 1.1&1.2 36 */ 37declare enum DpiFollowStrategy { 38 /** 39 * Followed the host DPI. 40 * 41 * @syscap SystemCapability.ArkUI.ArkUI.Full 42 * @systemapi 43 * @since arkts {'1.1':'12','1.2':'20'} 44 * @arkts 1.1&1.2 45 */ 46 FOLLOW_HOST_DPI = 0, 47 48 /** 49 * Followed the UIExtensionAbility. 50 * 51 * @syscap SystemCapability.ArkUI.ArkUI.Full 52 * @systemapi 53 * @since arkts {'1.1':'12','1.2':'20'} 54 * @arkts 1.1&1.2 55 */ 56 FOLLOW_UI_EXTENSION_ABILITY_DPI = 1, 57} 58 59/** 60 * Enumeration of different types of WindowModeFollowStrategy. 61 * @enum { number } 62 * @syscap SystemCapability.ArkUI.ArkUI.Full 63 * @systemapi 64 * @since 18 65 */ 66declare enum WindowModeFollowStrategy { 67 /** 68 * Followed the host Window Mode. 69 * @syscap SystemCapability.ArkUI.ArkUI.Full 70 * @systemapi 71 * @since 18 72 */ 73 FOLLOW_HOST_WINDOW_MODE = 0, 74 75 /** 76 * Followed the UIExtensionAbility. 77 * @syscap SystemCapability.ArkUI.ArkUI.Full 78 * @systemapi 79 * @since 18 80 */ 81 FOLLOW_UI_EXTENSION_ABILITY_WINDOW_MODE = 1 82} 83 84/** 85 * This interface is used to set the options for UIExtensionComponentAttribute during construction 86 * 87 * @interface UIExtensionOptions 88 * @syscap SystemCapability.ArkUI.ArkUI.Full 89 * @systemapi 90 * @since arkts {'1.1':'11','1.2':'20'} 91 * @arkts 1.1&1.2 92 */ 93declare interface UIExtensionOptions { 94 /** 95 * Set whether the current capability is used as a Caller.<br/> 96 * If set to true, as a Caller, the current token of UIExtensionComponent is set to rootToken. 97 * 98 * @type { ?boolean } 99 * @default false 100 * @syscap SystemCapability.ArkUI.ArkUI.Full 101 * @systemapi 102 * @since arkts {'1.1':'11','1.2':'20'} 103 * @arkts 1.1&1.2 104 */ 105 isTransferringCaller?: boolean; 106 107 /** 108 * Set placeholder. 109 * If set placeholder ComponentContent, show placeholder node when connection is not established. 110 * 111 * @type { ?ComponentContent } 112 * @syscap SystemCapability.ArkUI.ArkUI.Full 113 * @systemapi 114 * @since arkts {'1.1':'12','1.2':'20'} 115 * @arkts 1.1&1.2 116 */ 117 placeholder?: ComponentContent; 118 119 /** 120 * Set Areachange placeholder. 121 * If the Areachange placeholder ComponentContent is set, the placeholder node is displayed until 122 * the UIExtensionComponent size change is complete. 123 * 124 * @type { ?Record<string, ComponentContent> } 125 * @syscap SystemCapability.ArkUI.ArkUI.Full 126 * @systemapi 127 * @since arkts {'1.1':'14','1.2':'20'} 128 * @arkts 1.1&1.2 129 */ 130 areaChangePlaceholder?: Record<string, ComponentContent>; 131 132 /** 133 * Set UIExtensionComponent Content Dpi Follow Strategy. 134 * 135 * @type { ?DpiFollowStrategy } 136 * @default DpiFollowStrategy.FOLLOW_UI_EXTENSION_ABILITY_DPI 137 * @syscap SystemCapability.ArkUI.ArkUI.Full 138 * @systemapi 139 * @since arkts {'1.1':'12','1.2':'20'} 140 * @arkts 1.1&1.2 141 */ 142 dpiFollowStrategy?: DpiFollowStrategy; 143 144 /** 145 * Set UIExtensionComponent Content Window Mode Follow Strategy. 146 * @type { ?WindowModeFollowStrategy } 147 * @default WindowModeFollowStrategy.FOLLOW_UI_EXTENSION_ABILITY_WINDOW_MODE 148 * @syscap SystemCapability.ArkUI.ArkUI.Full 149 * @systemapi 150 * @since 18 151 */ 152 windowModeFollowStrategy?: WindowModeFollowStrategy; 153} 154 155/** 156 * Indicates the information when the provider of the embedded UI is terminated. 157 * 158 * @interface TerminationInfo 159 * @syscap SystemCapability.ArkUI.ArkUI.Full 160 * @systemapi 161 * @since 12 162 */ 163declare interface TerminationInfo { 164 /** 165 * Defines the termination code. 166 * 167 * @type { number } 168 * @syscap SystemCapability.ArkUI.ArkUI.Full 169 * @systemapi 170 * @since 12 171 */ 172 code: number; 173 174 /** 175 * Defines the additional termination information. 176 * 177 * @type { ?import('../api/@ohos.app.ability.Want').default } 178 * @syscap SystemCapability.ArkUI.ArkUI.Full 179 * @systemapi 180 * @since 12 181 */ 182 want?: import('../api/@ohos.app.ability.Want').default; 183} 184 185/** 186 * Get Callback from @ohos.base. 187 * AnonyMous Object Rectification 188 * 189 * @typedef { import('../api/@ohos.base').Callback<Record<string, Object>> } 190 * @syscap SystemCapability.ArkUI.ArkUI.Full 191 * @systemapi 192 * @since 18 193 */ 194declare type ReceiveCallback = import('../api/@ohos.base').Callback<Record<string, Object>>; 195 196/** 197 * Get Callback from @ohos.base. 198 * 199 * @typedef { Callback<Record<string, Object>> } 200 * @syscap SystemCapability.ArkUI.ArkUI.Full 201 * @systemapi 202 * @since 20 203 * @arkts 1.2 204 */ 205type ReceiveCallback = Callback<Record<string, Object>>; 206 207/** 208 * This interface is used for send data to the UIExtensionAbility.<br/> 209 * It is returned from onRemoteReady callback of UIExtensionComponent<br/> 210 * when UIExtensionAbility connects successfully 211 * 212 * @interface UIExtensionProxy 213 * @syscap SystemCapability.ArkUI.ArkUI.Full 214 * @systemapi 215 * @since arkts {'1.1':'10','1.2':'20'} 216 * @arkts 1.1&1.2 217 */ 218declare interface UIExtensionProxy { 219 /** 220 * This function is for sending data to the UIExtensionAbility. 221 * 222 * @param { object } data 223 * @syscap SystemCapability.ArkUI.ArkUI.Full 224 * @systemapi 225 * @since 10 226 */ 227 /** 228 * This function is for sending data to the UIExtensionAbility. 229 * AnonyMous Object Rectification 230 * 231 * @param { Record<string, Object> } data 232 * @syscap SystemCapability.ArkUI.ArkUI.Full 233 * @systemapi 234 * @since arkts {'1.1':'18','1.2':'20'} 235 * @arkts 1.1&1.2 236 */ 237 send(data: Record<string, Object>): void; 238 239 /** 240 * This function is for sending data to the UIExtensionAbility and waiting the result in blocking mode. 241 * 242 * @param { object } data - data send to the UIExtensionAbility 243 * @returns { object } data - data transferred from the UIExtensionAbility 244 * @throws { BusinessError } 100011 - No callback has been registered to respond to this request. 245 * @throws { BusinessError } 100012 - Transferring data failed. 246 * @syscap SystemCapability.ArkUI.ArkUI.Full 247 * @systemapi 248 * @since 11 249 */ 250 /** 251 * This function is for sending data to the UIExtensionAbility and waiting the result in blocking mode. 252 * AnonyMous Object Rectification 253 * 254 * @param { Record<string, Object> } data - Data send to the UIExtensionAbility. 255 * @returns { Record<string, Object> } data - Data transferred from the UIExtensionAbility. 256 * @throws { BusinessError } 100011 - No callback has been registered to respond to this request. 257 * @throws { BusinessError } 100012 - Transferring data failed. 258 * @syscap SystemCapability.ArkUI.ArkUI.Full 259 * @systemapi 260 * @since arkts {'1.1':'18','1.2':'20'} 261 * @arkts 1.1&1.2 262 */ 263 sendSync(data: Record<string, Object>): Record<string, Object>; 264 265 /** 266 * Register the listener that watches for async data receiver callback being registered by UIExtensionAbility. 267 * 268 * @param { 'asyncReceiverRegister' } type - Indicates the type of event. 269 * @param { function } callback - callback of the listened event. 270 * @syscap SystemCapability.ArkUI.ArkUI.Full 271 * @systemapi 272 * @since 11 273 */ 274 /** 275 * Register the listener that watches for async data receiver callback being registered by UIExtensionAbility. 276 * AnonyMous Object Rectification 277 * 278 * @param { 'asyncReceiverRegister' } type - Indicates the type of event. 279 * @param { Callback<UIExtensionProxy> } callback - Callback of the listened event. 280 * @syscap SystemCapability.ArkUI.ArkUI.Full 281 * @systemapi 282 * @since arkts {'1.1':'18','1.2':'20'} 283 * @arkts 1.1&1.2 284 */ 285 on(type: 'asyncReceiverRegister', callback: Callback<UIExtensionProxy>): void; 286 287 /** 288 * Register the listener that watches for sync data receiver callback being registered by UIExtensionAbility. 289 * 290 * @param { 'syncReceiverRegister' } type - Indicates the type of event. 291 * @param { function } callback - callback of the listened event. 292 * @syscap SystemCapability.ArkUI.ArkUI.Full 293 * @systemapi 294 * @since 11 295 */ 296 /** 297 * Register the listener that watches for sync data receiver callback being registered by UIExtensionAbility. 298 * AnonyMous Object Rectification 299 * 300 * @param { 'syncReceiverRegister' } type - Indicates the type of event. 301 * @param { Callback<UIExtensionProxy> } callback - Callback of the listened event. 302 * @syscap SystemCapability.ArkUI.ArkUI.Full 303 * @systemapi 304 * @since arkts {'1.1':'18','1.2':'20'} 305 * @arkts 1.1&1.2 306 */ 307 on(type: 'syncReceiverRegister', callback: Callback<UIExtensionProxy>): void; 308 309 /** 310 * Deregisters the listener that watches for async data receiver callback being registered by UIExtensionAbility. 311 * 312 * @param { 'asyncReceiverRegister' } type - type of the listened event. 313 * @param { function } callback - callback of the listened event. 314 * @syscap SystemCapability.ArkUI.ArkUI.Full 315 * @systemapi 316 * @since 11 317 */ 318 /** 319 * Deregisters the listener that watches for async data receiver callback being registered by UIExtensionAbility. 320 * AnonyMous Object Rectification 321 * 322 * @param { 'asyncReceiverRegister' } type - Type of the listened event. 323 * @param { Callback<UIExtensionProxy> } [callback] - Callback of the listened event. 324 * @syscap SystemCapability.ArkUI.ArkUI.Full 325 * @systemapi 326 * @since arkts {'1.1':'18','1.2':'20'} 327 * @arkts 1.1&1.2 328 */ 329 off(type: 'asyncReceiverRegister', callback?: Callback<UIExtensionProxy>): void; 330 331 /** 332 * Deregisters the listener that watches for sync data receiver callback being registered by UIExtensionAbility. 333 * 334 * @param { 'syncReceiverRegister' } type - type of the listened event. 335 * @param { function } callback - callback of the listened event. 336 * @syscap SystemCapability.ArkUI.ArkUI.Full 337 * @systemapi 338 * @since 11 339 */ 340 /** 341 * Deregisters the listener that watches for sync data receiver callback being registered by UIExtensionAbility. 342 * AnonyMous Object Rectification 343 * 344 * @param { 'syncReceiverRegister' } type - Type of the listened event. 345 * @param { Callback<UIExtensionProxy> } [callback] - Callback of the listened event. 346 * @syscap SystemCapability.ArkUI.ArkUI.Full 347 * @systemapi 348 * @since arkts {'1.1':'18','1.2':'20'} 349 * @arkts 1.1&1.2 350 */ 351 off(type: 'syncReceiverRegister', callback?: Callback<UIExtensionProxy>): void; 352} 353 354/** 355 * Provide an interface for the UIExtensionComponent, which is used 356 * <br/>to render UI of a remote UIExtensionAbility 357 * 358 * @interface UIExtensionComponentInterface 359 * @syscap SystemCapability.ArkUI.ArkUI.Full 360 * @systemapi 361 * @since arkts {'1.1':'10','1.2':'20'} 362 * @arkts 1.1&1.2 363 */ 364interface UIExtensionComponentInterface { 365 /** 366 * Construct the UIExtensionComponent.<br/> 367 * Called when the UIExtensionComponent is used. 368 * 369 * @param { import('../api/@ohos.app.ability.Want').default } want - indicates the want of UIExtensionAbility 370 * @returns { UIExtensionComponentAttribute } 371 * @syscap SystemCapability.ArkUI.ArkUI.Full 372 * @systemapi 373 * @since 10 374 */ 375 /** 376 * Construct the UIExtensionComponent.<br/> 377 * Called when the UIExtensionComponent is used. 378 * 379 * @param { import('../api/@ohos.app.ability.Want').default } want - indicates the want of UIExtensionAbility 380 * @param { UIExtensionOptions } [options] - Construction configuration of UIExtensionComponentAttribute 381 * @returns { UIExtensionComponentAttribute } 382 * @syscap SystemCapability.ArkUI.ArkUI.Full 383 * @systemapi 384 * @since 11 385 */ 386 ( 387 want: import('../api/@ohos.app.ability.Want').default, 388 options?: UIExtensionOptions 389 ): UIExtensionComponentAttribute; 390 391 /** 392 * Construct the UIExtensionComponent.<br/> 393 * Called when the UIExtensionComponent is used. 394 * 395 * @param { Want } want - indicates the want of UIExtensionAbility 396 * @param { UIExtensionOptions } [options] - Construction configuration of UIExtensionComponentAttribute 397 * @returns { UIExtensionComponentAttribute } 398 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 399 * @syscap SystemCapability.ArkUI.ArkUI.Full 400 * @systemapi 401 * @since 20 402 * @arkts 1.2 403 */ 404 ( 405 want: Want, 406 options?: UIExtensionOptions 407 ): UIExtensionComponentAttribute; 408} 409 410/** 411 * Define the attribute functions of UIExtensionComponent. 412 * 413 * @extends CommonMethod<UIExtensionComponentAttribute> 414 * @syscap SystemCapability.ArkUI.ArkUI.Full 415 * @systemapi 416 * @since arkts {'1.1':'10','1.2':'20'} 417 * @arkts 1.1&1.2 418 */ 419declare class UIExtensionComponentAttribute extends CommonMethod<UIExtensionComponentAttribute> { 420 /** 421 * @param { import('../api/@ohos.base').Callback<UIExtensionProxy> } callback 422 * - callback called when remote UIExtensionAbility object is 423 * <br/>ready for receive data 424 * @returns { UIExtensionComponentAttribute } 425 * @syscap SystemCapability.ArkUI.ArkUI.Full 426 * @systemapi 427 * @since 10 428 */ 429 onRemoteReady( 430 callback: import('../api/@ohos.base').Callback<UIExtensionProxy> 431 ): UIExtensionComponentAttribute; 432 433 /** 434 * callback called when remote UIExtensionAbility object is ready for receive data 435 * 436 * @param { Callback<UIExtensionProxy> } callback 437 * @returns { UIExtensionComponentAttribute } 438 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 439 * @syscap SystemCapability.ArkUI.ArkUI.Full 440 * @systemapi 441 * @since 20 442 * @arkts 1.2 443 */ 444 onRemoteReady( 445 callback: Callback<UIExtensionProxy> 446 ): UIExtensionComponentAttribute; 447 448 /** 449 * @param { import('../api/@ohos.base').Callback<{ [key: string]: Object }> } callback 450 * - called when data received from UIExtensionAbility 451 * @returns { UIExtensionComponentAttribute } 452 * @syscap SystemCapability.ArkUI.ArkUI.Full 453 * @systemapi 454 * @since 10 455 */ 456 /** 457 * AnonyMous Object Rectification 458 * 459 * @param { ReceiveCallback } callback - Called when data received from UIExtensionAbility 460 * @returns { UIExtensionComponentAttribute } 461 * @syscap SystemCapability.ArkUI.ArkUI.Full 462 * @systemapi 463 * @since arkts {'1.1':'18','1.2':'20'} 464 * @arkts 1.1&1.2 465 */ 466 onReceive(callback: ReceiveCallback): UIExtensionComponentAttribute; 467 468 /** 469 * @param { import('../api/@ohos.base').Callback<{code: number;want?: import('../api/@ohos.app.ability.Want').default;}> } callback 470 * - called when the UIExtensionAbility is terminated with result data. 471 * @returns { UIExtensionComponentAttribute } 472 * @syscap SystemCapability.ArkUI.ArkUI.Full 473 * @systemapi 474 * @since 10 475 * @deprecated since 12 476 * @useinstead UIExtensionComponentAttribute#onTerminated 477 */ 478 onResult( 479 callback: import('../api/@ohos.base').Callback<{ 480 code: number; 481 want?: import('../api/@ohos.app.ability.Want').default; 482 }> 483 ): UIExtensionComponentAttribute; 484 485 /** 486 * @param { import('../api/@ohos.base').Callback<number> } callback 487 * - number returned from callback function if disconnected from UIExtensionAbility, 0 means the 488 * <br/>UIExtensionAbility is terminate by itself, otherwise the connect is broken abnormal. 489 * @returns { UIExtensionComponentAttribute } 490 * @syscap SystemCapability.ArkUI.ArkUI.Full 491 * @systemapi 492 * @since 10 493 * @deprecated since 12 494 * @useinstead UIExtensionComponentAttribute#onTerminated or UIExtensionComponentAttribute#onError 495 */ 496 onRelease( 497 callback: import('../api/@ohos.base').Callback<number> 498 ): UIExtensionComponentAttribute; 499 500 /** 501 * @param { import('../api/@ohos.base').ErrorCallback } callback 502 * - called when some error occurred except disconnected from UIExtensionAbility. 503 * @returns { UIExtensionComponentAttribute } 504 * @syscap SystemCapability.ArkUI.ArkUI.Full 505 * @systemapi 506 * @since 10 507 */ 508 onError( 509 callback: import('../api/@ohos.base').ErrorCallback 510 ): UIExtensionComponentAttribute; 511 512 /** 513 * called when some error occurred except disconnected from UIExtensionAbility. 514 * 515 * @param { ErrorCallback<BusinessError> } callback 516 * @returns { UIExtensionComponentAttribute } 517 * @throws { BusinessError } 202 - Non-system applications are not allowed to use system APIs. 518 * @syscap SystemCapability.ArkUI.ArkUI.Full 519 * @systemapi 520 * @since 20 521 * @arkts 1.2 522 */ 523 onError( 524 callback: ErrorCallback<BusinessError> 525 ): UIExtensionComponentAttribute; 526 527 /** 528 * Called when the provider of the embedded UI is terminated. 529 * 530 * @param { Callback<TerminationInfo> } callback 531 * @returns { UIExtensionComponentAttribute } 532 * @syscap SystemCapability.ArkUI.ArkUI.Full 533 * @systemapi 534 * @since arkts {'1.1':'12','1.2':'20'} 535 * @arkts 1.1&1.2 536 */ 537 onTerminated(callback: Callback<TerminationInfo>): UIExtensionComponentAttribute; 538 539 /** 540 * Callback called when the UIExtensionAbility draw the first frame. 541 * @param { Callback<void> } callback 542 * @returns { UIExtensionComponentAttribute } 543 * @syscap SystemCapability.ArkUI.ArkUI.Full 544 * @systemapi 545 * @since 18 546 */ 547 onDrawReady(callback: Callback<void>): UIExtensionComponentAttribute; 548} 549 550/** 551 * Defines UIExtensionComponent Component. 552 * 553 * @syscap SystemCapability.ArkUI.ArkUI.Full 554 * @systemapi 555 * @since 10 556 */ 557declare const UIExtensionComponent: UIExtensionComponentInterface; 558 559/** 560 * Defines UIExtensionComponent Component instance. 561 * 562 * @syscap SystemCapability.ArkUI.ArkUI.Full 563 * @systemapi 564 * @since 10 565 */ 566declare const UIExtensionComponentInstance: UIExtensionComponentAttribute; 567