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 { DragEvent, DragPreviewOptions, DragItemInfo, ICurve } from './arkui/component/common'; 23import { CustomBuilder } from './arkui/component/builder'; 24import { TouchPoint, ResourceColor } from './arkui/component/units'; 25import { Curve } from './arkui/component/enums'; 26/*** endif */ 27 28 29import type { AsyncCallback, BusinessError, Callback } from './@ohos.base'; 30import type unifiedDataChannel from './@ohos.data.unifiedDataChannel'; 31 32/** 33 * This module allows developers to trigger a drag event. 34 * @namespace dragController 35 * @syscap SystemCapability.ArkUI.ArkUI.Full 36 * @since 10 37 */ 38/** 39 * This module allows developers to trigger a drag event. 40 * @namespace dragController 41 * @syscap SystemCapability.ArkUI.ArkUI.Full 42 * @atomicservice 43 * @since 12 44 */ 45/** 46 * This module allows developers to trigger a drag event. 47 * @namespace dragController 48 * @syscap SystemCapability.ArkUI.ArkUI.Full 49 * @crossplatform 50 * @atomicservice 51 * @since arkts {'1.1':'18','1.2':'20'} 52 * @arkts 1.1&1.2 53 */ 54declare namespace dragController { 55 /** 56 * Defines the Drag Status. 57 * 58 * @enum { number } 59 * @syscap SystemCapability.ArkUI.ArkUI.Full 60 * @since 11 61 */ 62 /** 63 * Defines the Drag Status. 64 * 65 * @enum { number } 66 * @syscap SystemCapability.ArkUI.ArkUI.Full 67 * @atomicservice 68 * @since 12 69 */ 70 /** 71 * Defines the Drag Status. 72 * 73 * @enum { number } 74 * @syscap SystemCapability.ArkUI.ArkUI.Full 75 * @crossplatform 76 * @atomicservice 77 * @since arkts {'1.1':'18','1.2':'20'} 78 * @arkts 1.1&1.2 79 */ 80 const enum DragStatus { 81 /** 82 * Drag has started. 83 * @syscap SystemCapability.ArkUI.ArkUI.Full 84 * @since 11 85 */ 86 /** 87 * Drag has started. 88 * @syscap SystemCapability.ArkUI.ArkUI.Full 89 * @atomicservice 90 * @since 12 91 */ 92 /** 93 * Drag has started. 94 * @syscap SystemCapability.ArkUI.ArkUI.Full 95 * @crossplatform 96 * @atomicservice 97 * @since arkts {'1.1':'18','1.2':'20'} 98 * @arkts 1.1&1.2 99 */ 100 STARTED = 0, 101 /** 102 * Drag has ended. 103 * @syscap SystemCapability.ArkUI.ArkUI.Full 104 * @since 11 105 */ 106 /** 107 * Drag has ended. 108 * @syscap SystemCapability.ArkUI.ArkUI.Full 109 * @atomicservice 110 * @since 12 111 */ 112 /** 113 * Drag has ended. 114 * @syscap SystemCapability.ArkUI.ArkUI.Full 115 * @crossplatform 116 * @atomicservice 117 * @since arkts {'1.1':'18','1.2':'20'} 118 * @arkts 1.1&1.2 119 */ 120 ENDED = 1, 121 } 122 123 /** 124 * Drag and drop information 125 * 126 * @interface DragAndDropInfo 127 * @syscap SystemCapability.ArkUI.ArkUI.Full 128 * @since 11 129 */ 130 /** 131 * Drag and drop information 132 * 133 * @interface DragAndDropInfo 134 * @syscap SystemCapability.ArkUI.ArkUI.Full 135 * @atomicservice 136 * @since 12 137 */ 138 /** 139 * Drag and drop information 140 * 141 * @interface DragAndDropInfo 142 * @syscap SystemCapability.ArkUI.ArkUI.Full 143 * @crossplatform 144 * @atomicservice 145 * @since arkts {'1.1':'18','1.2':'20'} 146 * @arkts 1.1&1.2 147 */ 148 interface DragAndDropInfo { 149 /** 150 * The drag status. 151 * @type { DragStatus } 152 * @syscap SystemCapability.ArkUI.ArkUI.Full 153 * @since 11 154 */ 155 /** 156 * The drag status. 157 * @type { DragStatus } 158 * @syscap SystemCapability.ArkUI.ArkUI.Full 159 * @atomicservice 160 * @since 12 161 */ 162 /** 163 * The drag status. 164 * @type { DragStatus } 165 * @syscap SystemCapability.ArkUI.ArkUI.Full 166 * @crossplatform 167 * @atomicservice 168 * @since arkts {'1.1':'18','1.2':'20'} 169 * @arkts 1.1&1.2 170 */ 171 status: DragStatus; 172 /** 173 * The information containing the drag event. 174 * @type { DragEvent } 175 * @syscap SystemCapability.ArkUI.ArkUI.Full 176 * @since 11 177 */ 178 /** 179 * The information containing the drag event. 180 * @type { DragEvent } 181 * @syscap SystemCapability.ArkUI.ArkUI.Full 182 * @atomicservice 183 * @since 12 184 */ 185 /** 186 * The information containing the drag event. 187 * @type { DragEvent } 188 * @syscap SystemCapability.ArkUI.ArkUI.Full 189 * @crossplatform 190 * @atomicservice 191 * @since arkts {'1.1':'18','1.2':'20'} 192 * @arkts 1.1&1.2 193 */ 194 event: DragEvent; 195 /** 196 * Additional information about the drag info. 197 * @type { ?string } 198 * @syscap SystemCapability.ArkUI.ArkUI.Full 199 * @since 11 200 */ 201 /** 202 * Additional information about the drag info. 203 * @type { ?string } 204 * @syscap SystemCapability.ArkUI.ArkUI.Full 205 * @atomicservice 206 * @since 12 207 */ 208 /** 209 * Additional information about the drag info. 210 * @type { ?string } 211 * @syscap SystemCapability.ArkUI.ArkUI.Full 212 * @crossplatform 213 * @atomicservice 214 * @since arkts {'1.1':'18','1.2':'20'} 215 * @arkts 1.1&1.2 216 */ 217 extraParams?: string; 218 } 219 220 /** 221 * One drag action object for drag process 222 * 223 * @interface DragAction 224 * @syscap SystemCapability.ArkUI.ArkUI.Full 225 * @since 11 226 */ 227 /** 228 * One drag action object for drag process 229 * 230 * @interface DragAction 231 * @syscap SystemCapability.ArkUI.ArkUI.Full 232 * @atomicservice 233 * @since 12 234 */ 235 /** 236 * One drag action object for drag process 237 * 238 * @interface DragAction 239 * @syscap SystemCapability.ArkUI.ArkUI.Full 240 * @crossplatform 241 * @atomicservice 242 * @since arkts {'1.1':'18','1.2':'20'} 243 * @arkts 1.1&1.2 244 */ 245 interface DragAction { 246 /** 247 * trigger drag action 248 * 249 * @returns { Promise<void> } A Promise can indicate the start result. 250 * @throws { BusinessError } 100001 - Internal handling failed. 251 * @syscap SystemCapability.ArkUI.ArkUI.Full 252 * @since 11 253 */ 254 /** 255 * trigger drag action 256 * 257 * @returns { Promise<void> } A Promise can indicate the start result. 258 * @throws { BusinessError } 100001 - Internal handling failed. 259 * @syscap SystemCapability.ArkUI.ArkUI.Full 260 * @atomicservice 261 * @since 12 262 */ 263 /** 264 * trigger drag action 265 * 266 * @returns { Promise<void> } A Promise can indicate the start result. 267 * @throws { BusinessError } 100001 - Internal handling failed. 268 * @syscap SystemCapability.ArkUI.ArkUI.Full 269 * @crossplatform 270 * @atomicservice 271 * @since arkts {'1.1':'18','1.2':'20'} 272 * @arkts 1.1&1.2 273 */ 274 startDrag(): Promise<void>; 275 /** 276 * Registers a callback for listening on drag status changes. 277 * This callback is triggered when the drag status change. 278 * 279 * @param { 'statusChange' } type for status changing 280 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 281 * @syscap SystemCapability.ArkUI.ArkUI.Full 282 * @since 11 283 */ 284 /** 285 * Registers a callback for listening on drag status changes. 286 * This callback is triggered when the drag status change. 287 * 288 * @param { 'statusChange' } type for status changing 289 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 290 * @syscap SystemCapability.ArkUI.ArkUI.Full 291 * @atomicservice 292 * @since 12 293 */ 294 /** 295 * Registers a callback for listening on drag status changes. 296 * This callback is triggered when the drag status change. 297 * 298 * @param { 'statusChange' } type for status changing 299 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 300 * @syscap SystemCapability.ArkUI.ArkUI.Full 301 * @crossplatform 302 * @atomicservice 303 * @since arkts {'1.1':'18','1.2':'20'} 304 * @arkts 1.1&1.2 305 */ 306 on(type: 'statusChange', callback: Callback<DragAndDropInfo>): void; 307 308 /** 309 * Deregisters a callback for listening on drag status changes. 310 * This callback is not triggered when the drag status change. 311 * 312 * @param { 'statusChange' } type for status changing 313 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 314 * @syscap SystemCapability.ArkUI.ArkUI.Full 315 * @since 11 316 */ 317 /** 318 * Deregisters a callback for listening on drag status changes. 319 * This callback is not triggered when the drag status change. 320 * 321 * @param { 'statusChange' } type for status changing 322 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 323 * @syscap SystemCapability.ArkUI.ArkUI.Full 324 * @atomicservice 325 * @since 12 326 */ 327 /** 328 * Deregisters a callback for listening on drag status changes. 329 * This callback is not triggered when the drag status change. 330 * 331 * @param { 'statusChange' } type for status changing 332 * @param { Callback<DragAndDropInfo> } callback with drag event and status information 333 * @syscap SystemCapability.ArkUI.ArkUI.Full 334 * @crossplatform 335 * @atomicservice 336 * @since arkts {'1.1':'18','1.2':'20'} 337 * @arkts 1.1&1.2 338 */ 339 off(type: 'statusChange', callback?: Callback<DragAndDropInfo>): void; 340 } 341 342 /** 343 * DragInfo object description 344 * 345 * @interface DragInfo 346 * @syscap SystemCapability.ArkUI.ArkUI.Full 347 * @since 10 348 */ 349 /** 350 * DragInfo object description 351 * 352 * @interface DragInfo 353 * @syscap SystemCapability.ArkUI.ArkUI.Full 354 * @atomicservice 355 * @since 12 356 */ 357 /** 358 * DragInfo object description 359 * 360 * @interface DragInfo 361 * @syscap SystemCapability.ArkUI.ArkUI.Full 362 * @crossplatform 363 * @atomicservice 364 * @since arkts {'1.1':'18','1.2':'20'} 365 * @arkts 1.1&1.2 366 */ 367 interface DragInfo { 368 /** 369 * A unique identifier to identify which touch point. 370 * @type { number } 371 * @syscap SystemCapability.ArkUI.ArkUI.Full 372 * @since 10 373 */ 374 /** 375 * A unique identifier to identify which touch point. 376 * @type { number } 377 * @syscap SystemCapability.ArkUI.ArkUI.Full 378 * @atomicservice 379 * @since 12 380 */ 381 /** 382 * A unique identifier to identify which touch point. 383 * @type { number } 384 * @syscap SystemCapability.ArkUI.ArkUI.Full 385 * @crossplatform 386 * @atomicservice 387 * @since arkts {'1.1':'18','1.2':'20'} 388 * @arkts 1.1&1.2 389 */ 390 pointerId: number; 391 392 /** 393 * Drag data. 394 * @type { ?unifiedDataChannel.UnifiedData } 395 * @syscap SystemCapability.ArkUI.ArkUI.Full 396 * @since 10 397 */ 398 /** 399 * Drag data. 400 * @type { ?unifiedDataChannel.UnifiedData } 401 * @syscap SystemCapability.ArkUI.ArkUI.Full 402 * @atomicservice 403 * @since 12 404 */ 405 /** 406 * Drag data. 407 * @type { ?unifiedDataChannel.UnifiedData } 408 * @syscap SystemCapability.ArkUI.ArkUI.Full 409 * @crossplatform 410 * @atomicservice 411 * @since arkts {'1.1':'18','1.2':'20'} 412 * @arkts 1.1&1.2 413 */ 414 data?: unifiedDataChannel.UnifiedData; 415 416 /** 417 * Additional information about the drag info. 418 * @type { ?string } 419 * @syscap SystemCapability.ArkUI.ArkUI.Full 420 * @since 10 421 */ 422 /** 423 * Additional information about the drag info. 424 * @type { ?string } 425 * @syscap SystemCapability.ArkUI.ArkUI.Full 426 * @atomicservice 427 * @since 12 428 */ 429 /** 430 * Additional information about the drag info. 431 * @type { ?string } 432 * @syscap SystemCapability.ArkUI.ArkUI.Full 433 * @crossplatform 434 * @atomicservice 435 * @since arkts {'1.1':'18','1.2':'20'} 436 * @arkts 1.1&1.2 437 */ 438 extraParams?: string; 439 440 /** 441 * Touch point coordinates. 442 * @type { ?TouchPoint } 443 * @syscap SystemCapability.ArkUI.ArkUI.Full 444 * @since 11 445 */ 446 /** 447 * Touch point coordinates. 448 * @type { ?TouchPoint } 449 * @syscap SystemCapability.ArkUI.ArkUI.Full 450 * @atomicservice 451 * @since 12 452 */ 453 /** 454 * Touch point coordinates. 455 * @type { ?TouchPoint } 456 * @syscap SystemCapability.ArkUI.ArkUI.Full 457 * @crossplatform 458 * @atomicservice 459 * @since arkts {'1.1':'18','1.2':'20'} 460 * @arkts 1.1&1.2 461 */ 462 touchPoint?: TouchPoint; 463 464 /** 465 * Drag preview options. 466 * @type { ?DragPreviewOptions } 467 * @syscap SystemCapability.ArkUI.ArkUI.Full 468 * @since 11 469 */ 470 /** 471 * Drag preview options. 472 * @type { ?DragPreviewOptions } 473 * @syscap SystemCapability.ArkUI.ArkUI.Full 474 * @atomicservice 475 * @since 12 476 */ 477 /** 478 * Drag preview options. 479 * @type { ?DragPreviewOptions } 480 * @syscap SystemCapability.ArkUI.ArkUI.Full 481 * @crossplatform 482 * @atomicservice 483 * @since arkts {'1.1':'18','1.2':'20'} 484 * @arkts 1.1&1.2 485 */ 486 previewOptions?: DragPreviewOptions; 487 488 /** 489 * Provide a data representation to the system instead of providing a complete data 490 * object directly. When the user releases the drag over the target application, the system will use this data 491 * representation to request the actual data from drag source. This approach significantly improves the 492 * efficiency of initiating drag operations for large volumes of data and enhances the effectiveness of data 493 * reception. It is recommended to use this instead of the data field. 494 * 495 * @type { ?unifiedDataChannel.DataLoadParams } 496 * @syscap SystemCapability.ArkUI.ArkUI.Full 497 * @atomicservice 498 * @since 20 499 */ 500 dataLoadParams?: unifiedDataChannel.DataLoadParams; 501 } 502 503 /** 504 * Defines the animation options for drag preview. 505 * 506 * @interface AnimationOptions 507 * @syscap SystemCapability.ArkUI.ArkUI.Full 508 * @since 11 509 */ 510 /** 511 * Defines the animation options for drag preview. 512 * 513 * @interface AnimationOptions 514 * @syscap SystemCapability.ArkUI.ArkUI.Full 515 * @atomicservice 516 * @since 12 517 */ 518 /** 519 * Defines the animation options for drag preview. 520 * 521 * @interface AnimationOptions 522 * @syscap SystemCapability.ArkUI.ArkUI.Full 523 * @crossplatform 524 * @atomicservice 525 * @since arkts {'1.1':'18','1.2':'20'} 526 * @arkts 1.1&1.2 527 */ 528 interface AnimationOptions { 529 /** 530 * Animation duration, in ms. 531 * @type { ?number } 532 * @syscap SystemCapability.ArkUI.ArkUI.Full 533 * @since 11 534 */ 535 /** 536 * Animation duration, in ms. 537 * @type { ?number } 538 * @syscap SystemCapability.ArkUI.ArkUI.Full 539 * @atomicservice 540 * @since 12 541 */ 542 /** 543 * Animation duration, in ms. 544 * @type { ?number } 545 * @syscap SystemCapability.ArkUI.ArkUI.Full 546 * @crossplatform 547 * @atomicservice 548 * @since arkts {'1.1':'18','1.2':'20'} 549 * @arkts 1.1&1.2 550 */ 551 duration?: number; 552 /** 553 * Animation curve. 554 * @type { ?(Curve | ICurve) } 555 * @syscap SystemCapability.ArkUI.ArkUI.Full 556 * @since 11 557 */ 558 /** 559 * Animation curve. 560 * @type { ?(Curve | ICurve) } 561 * @syscap SystemCapability.ArkUI.ArkUI.Full 562 * @atomicservice 563 * @since 12 564 */ 565 /** 566 * Animation curve. 567 * @type { ?(Curve | ICurve) } 568 * @syscap SystemCapability.ArkUI.ArkUI.Full 569 * @crossplatform 570 * @atomicservice 571 * @since arkts {'1.1':'18','1.2':'20'} 572 * @arkts 1.1&1.2 573 */ 574 curve?: Curve | ICurve; 575 } 576 577 /** 578 * Provides the functions of setting color or updating animation. 579 * @syscap SystemCapability.ArkUI.ArkUI.Full 580 * @since 11 581 */ 582 /** 583 * Provides the functions of setting color or updating animation. 584 * @syscap SystemCapability.ArkUI.ArkUI.Full 585 * @atomicservice 586 * @since 12 587 */ 588 /** 589 * Provides the functions of setting color or updating animation. 590 * @syscap SystemCapability.ArkUI.ArkUI.Full 591 * @crossplatform 592 * @atomicservice 593 * @since arkts {'1.1':'18','1.2':'20'} 594 * @arkts 1.1&1.2 595 */ 596 export class DragPreview { 597 /** 598 * change foreground color of preview 599 * @param { ResourceColor } color - color value 600 * @syscap SystemCapability.ArkUI.ArkUI.Full 601 * @since 11 602 */ 603 /** 604 * change foreground color of preview 605 * @param { ResourceColor } color - color value 606 * @syscap SystemCapability.ArkUI.ArkUI.Full 607 * @atomicservice 608 * @since 12 609 */ 610 /** 611 * change foreground color of preview 612 * @param { ResourceColor } color - color value 613 * @syscap SystemCapability.ArkUI.ArkUI.Full 614 * @crossplatform 615 * @atomicservice 616 * @since arkts {'1.1':'18','1.2':'20'} 617 * @arkts 1.1&1.2 618 */ 619 setForegroundColor(color: ResourceColor): void; 620 /** 621 * update preview style with animation 622 * @param { AnimationOptions } options - animation options 623 * @param { function } handler - change style functions 624 * @syscap SystemCapability.ArkUI.ArkUI.Full 625 * @since 11 626 */ 627 /** 628 * update preview style with animation 629 * @param { AnimationOptions } options - animation options 630 * @param { function } handler - change style functions 631 * @syscap SystemCapability.ArkUI.ArkUI.Full 632 * @atomicservice 633 * @since 12 634 */ 635 /** 636 * update preview style with animation 637 * @param { AnimationOptions } options - animation options 638 * @param { function } handler - change style functions 639 * @syscap SystemCapability.ArkUI.ArkUI.Full 640 * @crossplatform 641 * @atomicservice 642 * @since arkts {'1.1':'18','1.2':'20'} 643 * @arkts 1.1&1.2 644 */ 645 animate(options: AnimationOptions, handler: () =>void): void; 646 } 647 648 /** 649 * Define the drag event paramters 650 * 651 * @interface DragEventParam 652 * @syscap SystemCapability.ArkUI.ArkUI.Full 653 * @atomicservice 654 * @since 12 655 */ 656 /** 657 * Define the drag event paramters 658 * 659 * @interface DragEventParam 660 * @syscap SystemCapability.ArkUI.ArkUI.Full 661 * @crossplatform 662 * @atomicservice 663 * @since arkts {'1.1':'18','1.2':'20'} 664 * @arkts 1.1&1.2 665 */ 666 interface DragEventParam { 667 668 /** 669 * The information containing the drag event. 670 * @type { DragEvent } 671 * @syscap SystemCapability.ArkUI.ArkUI.Full 672 * @since 10 673 */ 674 /** 675 * The information containing the drag event. 676 * @type { DragEvent } 677 * @syscap SystemCapability.ArkUI.ArkUI.Full 678 * @atomicservice 679 * @since 12 680 */ 681 /** 682 * The information containing the drag event. 683 * @type { DragEvent } 684 * @syscap SystemCapability.ArkUI.ArkUI.Full 685 * @crossplatform 686 * @atomicservice 687 * @since arkts {'1.1':'18','1.2':'20'} 688 * @arkts 1.1&1.2 689 */ 690 event: DragEvent; 691 692 /** 693 * Additional information about the drag info. 694 * @type { string } 695 * @syscap SystemCapability.ArkUI.ArkUI.Full 696 * @since 10 697 */ 698 /** 699 * Additional information about the drag info. 700 * @type { string } 701 * @syscap SystemCapability.ArkUI.ArkUI.Full 702 * @atomicservice 703 * @since 12 704 */ 705 /** 706 * Additional information about the drag info. 707 * @type { string } 708 * @syscap SystemCapability.ArkUI.ArkUI.Full 709 * @crossplatform 710 * @atomicservice 711 * @since arkts {'1.1':'18','1.2':'20'} 712 * @arkts 1.1&1.2 713 */ 714 extraParams: string; 715 } 716 717 /** 718 * Execute a drag event. 719 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 720 * @param { DragInfo } dragInfo - Information about the drag event. 721 * @param { AsyncCallback<{ event: DragEvent, extraParams: string }> } callback - Callback that contains the drag 722 * event information. 723 * @throws { BusinessError } 401 - Parameter error. Possible causes: 724 * <br> 1. Mandatory parameters are left unspecified. 725 * <br> 2. Incorrect parameters types. 726 * <br> 3. Parameter verification failed. 727 * @throws { BusinessError } 100001 - Internal handling failed. 728 * @syscap SystemCapability.ArkUI.ArkUI.Full 729 * @since 10 730 */ 731 /** 732 * Execute a drag event. 733 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 734 * @param { DragInfo } dragInfo - Information about the drag event. 735 * @param { AsyncCallback<DragEventParam> } callback - Callback that contains the drag event information. 736 * @throws { BusinessError } 401 - Parameter error. Possible causes: 737 * <br> 1. Mandatory parameters are left unspecified. 738 * <br> 2. Incorrect parameters types. 739 * <br> 3. Parameter verification failed. 740 * @throws { BusinessError } 100001 - Internal handling failed. 741 * @syscap SystemCapability.ArkUI.ArkUI.Full 742 * @atomicservice 743 * @since 12 744 */ 745 /** 746 * Execute a drag event. 747 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 748 * @param { DragInfo } dragInfo - Information about the drag event. 749 * @param { AsyncCallback<DragEventParam> } callback - Callback that contains the drag event information. 750 * @throws { BusinessError } 401 - Parameter error. Possible causes: 751 * <br> 1. Mandatory parameters are left unspecified. 752 * <br> 2. Incorrect parameters types. 753 * <br> 3. Parameter verification failed. 754 * @throws { BusinessError } 100001 - Internal handling failed. 755 * @syscap SystemCapability.ArkUI.ArkUI.Full 756 * @crossplatform 757 * @atomicservice 758 * @since arkts {'1.1':'18','1.2':'20'} 759 * @deprecated since 18 760 * @useinstead ohos.arkui.UIContext.DragController#executeDrag 761 * @arkts 1.1&1.2 762 */ 763 function executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo, 764 callback: AsyncCallback<DragEventParam>): void; 765 766 /** 767 * Execute a drag event. 768 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 769 * @param { DragInfo } dragInfo - Information about the drag event. 770 * @returns { Promise<{ event: DragEvent, extraParams: string }> } A Promise with the drag event information. 771 * @throws { BusinessError } 401 - Parameter error. Possible causes: 772 * <br> 1. Mandatory parameters are left unspecified. 773 * <br> 2. Incorrect parameters types. 774 * <br> 3. Parameter verification failed. 775 * @throws { BusinessError } 100001 - Internal handling failed. 776 * @syscap SystemCapability.ArkUI.ArkUI.Full 777 * @since 10 778 */ 779 /** 780 * Execute a drag event. 781 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 782 * @param { DragInfo } dragInfo - Information about the drag event. 783 * @returns { Promise<DragEventParam> } A Promise with the drag event information. 784 * @throws { BusinessError } 401 - Parameter error. Possible causes: 785 * <br> 1. Mandatory parameters are left unspecified. 786 * <br> 2. Incorrect parameters types. 787 * <br> 3. Parameter verification failed. 788 * @throws { BusinessError } 100001 - Internal handling failed. 789 * @syscap SystemCapability.ArkUI.ArkUI.Full 790 * @atomicservice 791 * @since 12 792 */ 793 /** 794 * Execute a drag event. 795 * @param { CustomBuilder | DragItemInfo } custom - Object used for prompts displayed when the object is dragged. 796 * @param { DragInfo } dragInfo - Information about the drag event. 797 * @returns { Promise<DragEventParam> } A Promise with the drag event information. 798 * @throws { BusinessError } 401 - Parameter error. Possible causes: 799 * <br> 1. Mandatory parameters are left unspecified. 800 * <br> 2. Incorrect parameters types. 801 * <br> 3. Parameter verification failed. 802 * @throws { BusinessError } 100001 - Internal handling failed. 803 * @syscap SystemCapability.ArkUI.ArkUI.Full 804 * @crossplatform 805 * @atomicservice 806 * @since arkts {'1.1':'18','1.2':'20'} 807 * @deprecated since 18 808 * @useinstead ohos.arkui.UIContext.DragController#executeDrag 809 * @arkts 1.1&1.2 810 */ 811 function executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<DragEventParam>; 812 813 /** 814 * Create one drag action object, which can be used for starting drag later or monitoring 815 * the drag status after drag started. 816 * @param { Array<CustomBuilder | DragItemInfo> } customArray - Objects used for prompts 817 * displayed when the objects are dragged. 818 * @param { DragInfo } dragInfo - Information about the drag event. 819 * @returns { DragAction } one drag action object 820 * @throws { BusinessError } 401 - Parameter error. Possible causes: 821 * <br> 1. Mandatory parameters are left unspecified. 822 * <br> 2. Incorrect parameters types. 823 * <br> 3. Parameter verification failed. 824 * @throws { BusinessError } 100001 - Internal handling failed. 825 * @syscap SystemCapability.ArkUI.ArkUI.Full 826 * @since 11 827 */ 828 /** 829 * Create one drag action object, which can be used for starting drag later or monitoring 830 * the drag status after drag started. 831 * @param { Array<CustomBuilder | DragItemInfo> } customArray - Objects used for prompts 832 * displayed when the objects are dragged. 833 * @param { DragInfo } dragInfo - Information about the drag event. 834 * @returns { DragAction } one drag action object 835 * @throws { BusinessError } 401 - Parameter error. Possible causes: 836 * <br> 1. Mandatory parameters are left unspecified. 837 * <br> 2. Incorrect parameters types. 838 * <br> 3. Parameter verification failed. 839 * @throws { BusinessError } 100001 - Internal handling failed. 840 * @syscap SystemCapability.ArkUI.ArkUI.Full 841 * @atomicservice 842 * @since 12 843 */ 844 /** 845 * Create one drag action object, which can be used for starting drag later or monitoring 846 * the drag status after drag started. 847 * @param { Array<CustomBuilder | DragItemInfo> } customArray - Objects used for prompts 848 * displayed when the objects are dragged. 849 * @param { DragInfo } dragInfo - Information about the drag event. 850 * @returns { DragAction } one drag action object 851 * @throws { BusinessError } 401 - Parameter error. Possible causes: 852 * <br> 1. Mandatory parameters are left unspecified. 853 * <br> 2. Incorrect parameters types. 854 * <br> 3. Parameter verification failed. 855 * @throws { BusinessError } 100001 - Internal handling failed. 856 * @syscap SystemCapability.ArkUI.ArkUI.Full 857 * @crossplatform 858 * @atomicservice 859 * @since arkts {'1.1':'18','1.2':'20'} 860 * @deprecated since 18 861 * @useinstead ohos.arkui.UIContext.DragController#createDragAction 862 * @arkts 1.1&1.2 863 */ 864 function createDragAction(customArray: Array<CustomBuilder | DragItemInfo>, dragInfo: DragInfo): DragAction; 865 866 /** 867 * Get drag preview object. 868 * @returns { DragPreview } An drag preview object. 869 * @syscap SystemCapability.ArkUI.ArkUI.Full 870 * @since 11 871 */ 872 /** 873 * Get drag preview object. 874 * @returns { DragPreview } An drag preview object. 875 * @syscap SystemCapability.ArkUI.ArkUI.Full 876 * @atomicservice 877 * @since 12 878 */ 879 /** 880 * Get drag preview object. 881 * @returns { DragPreview } An drag preview object. 882 * @syscap SystemCapability.ArkUI.ArkUI.Full 883 * @crossplatform 884 * @atomicservice 885 * @since arkts {'1.1':'18','1.2':'20'} 886 * @deprecated since 18 887 * @useinstead ohos.arkui.UIContext.DragController#getDragPreview 888 * @arkts 1.1&1.2 889 */ 890 function getDragPreview(): DragPreview; 891 892 /** 893 * Define the status for the application to notify the framework whether to execute drag. 894 * 895 * @enum { number } 896 * @syscap SystemCapability.ArkUI.ArkUI.Full 897 * @atomicservice 898 * @since arkts {'1.1':'18','1.2':'20'} 899 * @arkts 1.1&1.2 900 */ 901 const enum DragStartRequestStatus { 902 /** 903 * Notify the framework that the application is not yet ready and needs to temporarily block 904 * the start of drag, only effective in onDragStart calls. 905 * 906 * @syscap SystemCapability.ArkUI.ArkUI.Full 907 * @atomicservice 908 * @since arkts {'1.1':'18','1.2':'20'} 909 * @arkts 1.1&1.2 910 */ 911 WAITING = 0, 912 913 /** 914 * Notify the framework that the drag can continue to be started, but only during the start 915 * of drag, and will not take effect when the drag is started. 916 * 917 * @syscap SystemCapability.ArkUI.ArkUI.Full 918 * @atomicservice 919 * @since arkts {'1.1':'18','1.2':'20'} 920 * @arkts 1.1&1.2 921 */ 922 READY = 1, 923 } 924 925 /** 926 * Defines the drag spring loading state. 927 * Under default system configuration, if no CANCEL occurs, the state reporting is as follows: 928 * Hover still--500ms-->BEGIN-->100ms-->UPDATE-->100ms-->UPDATE-->100ms-->UPDATE-->100ms-->END 929 * 930 * @enum { number } 931 * @syscap SystemCapability.ArkUI.ArkUI.Full 932 * @atomicservice 933 * @since 20 934 */ 935 const enum DragSpringLoadingState { 936 /** 937 * The user has remained stationary for a period, initiating the spring loading process. 938 * This state allows for some preparatory operations during spring loading. 939 * 940 * @syscap SystemCapability.ArkUI.ArkUI.Full 941 * @atomicservice 942 * @since 20 943 */ 944 BEGIN, 945 /** 946 * Already in the spring loading state. The system periodically checks the user's hover status. 947 * If the user remains stationary, it triggers an UPDATE state notification at regular intervals. 948 * This state allows for UI effect refreshes to emphasize the hover state. 949 * 950 * @syscap SystemCapability.ArkUI.ArkUI.Full 951 * @atomicservice 952 * @since 20 953 */ 954 UPDATE, 955 /** 956 * The entire spring loading state ends. The application can perform cleanup operations 957 * and execute navigation or view switching actions when this state occurs. 958 * 959 * @syscap SystemCapability.ArkUI.ArkUI.Full 960 * @atomicservice 961 * @since 20 962 */ 963 END, 964 /** 965 * After entering the BEGIN state, if the user moves out of the component range, exceeds the displacement 966 * threshold, lifts the finger, or switches windows (pull out), the CANCEL state is triggered. 967 * The application should restore the UI style and cancel any pending navigation or view switching actions. 968 * 969 * @syscap SystemCapability.ArkUI.ArkUI.Full 970 * @atomicservice 971 * @since 20 972 */ 973 CANCEL 974 } 975 976 /** 977 * Defines parameters affecting spring loading detection. Typically, default system configurations suffice. 978 * Customization can be done by specifying the config when binding onDragSpringLoading or dynamically modifying it 979 * using the updateConfiguration method during the BEGIN state. 980 * 981 * @typedef { DragSpringLoadingConfiguration } 982 * @syscap SystemCapability.ArkUI.ArkUI.Full 983 * @atomicservice 984 * @since 20 985 */ 986 interface DragSpringLoadingConfiguration { 987 /** 988 * Time interval to maintain a stationary state before entering spring loading. Default: 500 ms. 989 * 990 * @type { ?number } 991 * @syscap SystemCapability.ArkUI.ArkUI.Full 992 * @atomicservice 993 * @since 20 994 */ 995 stillTimeLimit?: number; 996 997 /** 998 * Interval between update notifications after entering the spring loading state. Default: 100ms. 999 * 1000 * @type { ?number } 1001 * @syscap SystemCapability.ArkUI.ArkUI.Full 1002 * @atomicservice 1003 * @since 20 1004 */ 1005 updateInterval?: number; 1006 1007 /** 1008 * Maximum number of update notifications to report while in the spring loading state. Default: 3. 1009 * 1010 * @type { ?number } 1011 * @syscap SystemCapability.ArkUI.ArkUI.Full 1012 * @atomicservice 1013 * @since 20 1014 */ 1015 updateNotifyCount?: number; 1016 1017 /** 1018 * Maximum wait time from the last UPDATE state to the end of spring loading. Default: 100ms. 1019 * 1020 * @type { ?number } 1021 * @syscap SystemCapability.ArkUI.ArkUI.Full 1022 * @atomicservice 1023 * @since 20 1024 */ 1025 updateToFinishInterval?: number; 1026 } 1027 1028 /** 1029 * Defines drag-related information when triggering spring loading callbacks. 1030 * This interface provides drag data summaries and additional drag information, useful for applications 1031 * needing to dynamically determine whether to respond to spring loading callbacks based on drag data. 1032 * 1033 * @typedef { SpringLoadingDragInfos } 1034 * @syscap SystemCapability.ArkUI.ArkUI.Full 1035 * @atomicservice 1036 * @since 20 1037 */ 1038 interface SpringLoadingDragInfos { 1039 /** 1040 * Summary of the dragged data. This field is absent if the source application did not configure data. 1041 * 1042 * @type { ?unifiedDataChannel.Summary } 1043 * @syscap SystemCapability.ArkUI.ArkUI.Full 1044 * @atomicservice 1045 * @since 20 1046 */ 1047 dataSummary?: unifiedDataChannel.Summary; 1048 1049 /** 1050 * Additional information provided by the source application when initiating the drag operation. 1051 * This field is absent if the source application did not configure it. 1052 * 1053 * @type { ?string } 1054 * @syscap SystemCapability.ArkUI.ArkUI.Full 1055 * @atomicservice 1056 * @since 20 1057 */ 1058 extraInfos?: string; 1059 } 1060 1061 /** 1062 * Context information for the current spring loading trigger. This object is passed to the application 1063 * in the spring loading callback, allowing it to obtain the current state, dynamically refresh UI effects, 1064 * and access drag data to determine whether to handle the drag operation. 1065 * 1066 * @syscap SystemCapability.ArkUI.ArkUI.Full 1067 * @atomicservice 1068 * @since 20 1069 */ 1070 class SpringLoadingContext { 1071 /** 1072 * Current spring loading state. Refer to the DragSpringLoadingState enum for details. 1073 * 1074 * @type { DragSpringLoadingState } 1075 * @syscap SystemCapability.ArkUI.ArkUI.Full 1076 * @atomicservice 1077 * @since 20 1078 */ 1079 state: DragSpringLoadingState; 1080 /** 1081 * Sequence number of the current spring loading state notification. Begins at 0 for BEGIN and increments 1082 * with each callback. 1083 * 1084 * @type { number } 1085 * @syscap SystemCapability.ArkUI.ArkUI.Full 1086 * @atomicservice 1087 * @since 20 1088 */ 1089 currentNotifySequence: number; 1090 /** 1091 * Drag-related information. Absent when the state is CANCEL. 1092 * 1093 * @type { ?SpringLoadingDragInfos } 1094 * @syscap SystemCapability.ArkUI.ArkUI.Full 1095 * @atomicservice 1096 * @since 20 1097 */ 1098 dragInfos?: SpringLoadingDragInfos; 1099 /** 1100 * Current spring loading configuration. Absent when the state is CANCEL. 1101 * 1102 * @type { ?DragSpringLoadingConfiguration } 1103 * @syscap SystemCapability.ArkUI.ArkUI.Full 1104 * @atomicservice 1105 * @since 20 1106 */ 1107 currentConfig?: DragSpringLoadingConfiguration; 1108 /** 1109 * Aborts subsequent spring loading triggers. 1110 * Note: Aborting does not trigger a CANCEL notification, the application must handle state cleanup when aborting. 1111 * 1112 * @syscap SystemCapability.ArkUI.ArkUI.Full 1113 * @atomicservice 1114 * @since 20 1115 */ 1116 abort(): void; 1117 /** 1118 * Updates the spring loading configuration for the current trigger. Only effective during the BEGIN state. 1119 * This method does not modify the original configuration set during onDragSpringLoading binding. 1120 * It provides an opportunity for dynamic configuration updates during the current trigger. 1121 * Typically, applications should use default configurations or set them once during binding. 1122 * Use this method sparingly, e.g., for different drag data types requiring varied UX timing. 1123 * 1124 * @param { DragSpringLoadingConfiguration } config - The spring loading detection configuration 1125 * @syscap SystemCapability.ArkUI.ArkUI.Full 1126 * @atomicservice 1127 * @since 20 1128 */ 1129 updateConfiguration(config: DragSpringLoadingConfiguration): void; 1130 } 1131} 1132 1133export default dragController; 1134