1# @ohos.arkui.dragController (DragController) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9The **dragController** module provides APIs for initiating drag actions. When receiving a gesture event, such as a touch or long-press event, an application can initiate a drag action and carry drag information therein. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14> The functionality of this module depends on UI context. This means that the APIs of this module cannot be used where [the UI context is ambiguous](../../ui/arkts-global-interface.md#ambiguous-ui-context). For details, see [UIContext](arkts-apis-uicontext-uicontext.md). 15> You can preview how this component looks on a real device, but not in DevEco Studio Previewer. 16 17## Modules to Import 18 19```ts 20import { dragController } from '@kit.ArkUI'; 21``` 22 23## dragController.executeDrag<sup>(deprecated)</sup> 24 25executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo,callback:AsyncCallback\<DragEventParam>): void 26 27Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses an asynchronous callback to return the result. 28 29> **NOTE** 30> 31> This API is deprecated since API version 18. You are advised to use [executeDrag](arkts-apis-uicontext-dragcontroller.md#executedrag11) instead on the obtained [DragController](arkts-apis-uicontext-dragcontroller.md) object. 32> 33> Since API version 11, you can use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) API in [UIContext](arkts-apis-uicontext-uicontext.md) to obtain the [DragController](arkts-apis-uicontext-dragcontroller.md) object associated with the current UI context. 34 35**Atomic service API**: This API can be used in atomic services since API version 12. 36 37**System capability**: SystemCapability.ArkUI.ArkUI.Full 38 39**Parameters** 40 41| Name | Type | Mandatory| Description | 42| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 43| custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.<br>**NOTE**<br>The global builder is not supported. If the [Image](arkui-ts/ts-basic-components-image.md) component is used in the builder, enable synchronous loading, that is, set the [syncLoad](arkui-ts/ts-basic-components-image.md#syncload8) attribute of the component to **true**. The builder is used only to generate the image displayed during the current dragging. If the root component of the builder has zero width or height, it will cause failure in drag image generation, which in turn breaks the entire drag operation. Changes to the builder, if any, apply to the next dragging, but not to the current dragging.| 44| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | 45| callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<[DragEventParam](#drageventparam12)> | Yes | Callback used to return the result. | 46 47**Error codes** 48 49For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 50 51| ID| Error Message | 52| -------- | ------------- | 53| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 54| 100001 | Internal handling failed. | 55 56**Example** 57 58> **NOTE** 59> 60> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 61 62```ts 63import { dragController } from '@kit.ArkUI'; 64import { unifiedDataChannel } from '@kit.ArkData'; 65 66@Entry 67@Component 68struct DragControllerPage { 69 @State text: string = '' 70 71 @Builder DraggingBuilder() { 72 Column() { 73 Text("DraggingBuilder") 74 .fontColor(Color.White) 75 .fontSize(12) 76 } 77 .width(100) 78 .height(100) 79 .backgroundColor(Color.Blue) 80 } 81 82 build() { 83 Column() { 84 Button('touch to execute drag') 85 .margin(10) 86 .onTouch((event?:TouchEvent) => { 87 if(event){ 88 if (event.type == TouchType.Down) { 89 let text = new unifiedDataChannel.PlainText() 90 text.textContent = 'drag text' 91 text.abstract = 'abstract' 92 let unifiedData = new unifiedDataChannel.UnifiedData(text) 93 94 let dragInfo: dragController.DragInfo = { 95 pointerId: 0, 96 data: unifiedData, 97 extraParams: '' 98 } 99 class tmp{ 100 event:DragEvent|undefined = undefined 101 extraParams:string = '' 102 } 103 let eve:tmp = new tmp() 104 this.getUIContext().getDragController().executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { // You are advised to use this.getUIContext().getDragController().executeDrag(). 105 if(eve.event){ 106 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 107 // ... 108 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 109 // ... 110 } 111 } 112 }) 113 } 114 } 115 }) 116 Text(this.text) 117 .height(100) 118 .width(150) 119 .margin({top:20}) 120 .border({color:Color.Black,width:1}) 121 .onDrop((dragEvent?:DragEvent)=>{ 122 if(dragEvent){ 123 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 124 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 125 this.text = plainText.textContent; 126 } 127 }) 128 } 129 .width('100%') 130 .height('100%') 131 } 132} 133``` 134  135## dragController.executeDrag<sup>(deprecated)</sup> 136 137executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise\<DragEventParam> 138 139Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses a promise to return the result. 140 141> **NOTE** 142> 143> This API is deprecated since API version 18. You are advised to use [executeDrag](arkts-apis-uicontext-dragcontroller.md#executedrag11-1) instead on the obtained [DragController](arkts-apis-uicontext-dragcontroller.md) object. 144> 145> Since API version 11, you can use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) API in [UIContext](arkts-apis-uicontext-uicontext.md) to obtain the [DragController](arkts-apis-uicontext-dragcontroller.md) object associated with the current UI context. 146 147**Atomic service API**: This API can be used in atomic services since API version 12. 148 149**System capability**: SystemCapability.ArkUI.ArkUI.Full 150 151**Parameters** 152 153| Name | Type | Mandatory| Description | 154| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 155| custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.| 156| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | 157 158**Return value** 159 160| Type | Description | 161| -------------------------------------------------- | ------------------------ | 162| Promise<[DragEventParam](#drageventparam12)> | Promise used to return the result.| 163 164**Error codes** 165For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 166| ID| Error Message | 167| -------- | ------------- | 168| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 169| 100001 | Internal handling failed. | 170 171**Example** 172 173> **NOTE** 174> 175> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 176 177```ts 178import { dragController } from '@kit.ArkUI'; 179import { image } from '@kit.ImageKit'; 180import { unifiedDataChannel } from '@kit.ArkData'; 181 182@Entry 183@Component 184struct DragControllerPage { 185 @State pixmap: image.PixelMap|undefined = undefined 186 @State text: string = '' 187 188 @Builder DraggingBuilder() { 189 Column() { 190 Text("DraggingBuilder") 191 .fontColor(Color.White) 192 } 193 .width(100) 194 .height(100) 195 .backgroundColor(Color.Blue) 196 } 197 198 @Builder PixmapBuilder() { 199 Column() { 200 Text("PixmapBuilder") 201 .fontColor(Color.White) 202 .fontSize(15) 203 } 204 .width(100) 205 .height(100) 206 .backgroundColor(Color.Blue) 207 } 208 209 aboutToAppear() { 210 let pb: CustomBuilder = (): void => { 211 this.PixmapBuilder() 212 } 213 this.getUIContext().getComponentSnapshot().createFromBuilder(pb).then((pix: image.PixelMap) => { 214 this.pixmap = pix; 215 }) 216 } 217 218 build() { 219 Column() { 220 Button('touch to execute drag') 221 .margin(10) 222 .onTouch((event?:TouchEvent) => { 223 if(event){ 224 if (event.type == TouchType.Down) { 225 let text = new unifiedDataChannel.PlainText() 226 text.textContent = 'drag text' 227 text.abstract = 'abstract' 228 let unifiedData = new unifiedDataChannel.UnifiedData(text) 229 230 let dragInfo: dragController.DragInfo = { 231 pointerId: 0, 232 data: unifiedData, 233 extraParams: '' 234 } 235 let dragItemInfo: DragItemInfo = { 236 pixelMap: this.pixmap, 237 builder: ()=>{this.DraggingBuilder()}, 238 extraInfo: "DragItemInfoTest" 239 } 240 241 class tmp{ 242 event:DragResult|undefined = undefined 243 extraParams:string = '' 244 } 245 let eve:tmp = new tmp() 246 this.getUIContext().getDragController().executeDrag(dragItemInfo, dragInfo) // You are advised to use this.getUIContext().getDragController().executeDrag(). 247 .then((eve) => { 248 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 249 // ... 250 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 251 // ... 252 } 253 }) 254 .catch((err:Error) => { 255 }) 256 } 257 } 258 }) 259 Text(this.text) 260 .height(100) 261 .width(150) 262 .margin({top:20}) 263 .border({color:Color.Black,width:1}) 264 .onDrop((dragEvent?:DragEvent)=>{ 265 if(dragEvent){ 266 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 267 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 268 this.text = plainText.textContent; 269 } 270 }) 271 } 272 .width('100%') 273 .height('100%') 274 } 275} 276``` 277  278## DragInfo 279 280Defines the attributes required for initiating a drag action and information carried in the dragging process. 281 282**System capability**: SystemCapability.ArkUI.ArkUI.Full 283 284| Name | Type | Mandatory| Description | 285| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 286| pointerId | number | Yes | ID of the touch point on the screen when dragging is started. The value is an integer ranging from 0 to 9.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 287| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | No | Data carried in the dragging process.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 288| extraParams | string | No | Additional information about the drag action. Not supported currently. The default value is null.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 289| touchPoint<sup>11+</sup> | [TouchPoint](arkui-ts/ts-types.md#touchpoint11) | No | Coordinates of the touch point. If this parameter is not set, the touch point is centered horizontally and shifted downward by 20% from the top.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 290| previewOptions<sup>11+</sup>| [DragPreviewOptions](arkui-ts/ts-universal-attributes-drag-drop.md#dragpreviewoptions11) | No | Processing mode of the drag preview and the display of the number badge during dragging.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 291| dataLoadParams<sup>20+</sup>| [unifiedDataChannel.DataLoadParams](../apis-arkdata/js-apis-data-unifiedDataChannel.md#dataloadparams20) | No | Parameters for deferred data loading from the drag source. This API provides data loading parameters to the system instead of directly providing complete data objects. When the user drops data on the target application, the system will use these parameters to request the actual data from the drag source. If set together with **data**, **dataLoadParams** takes effect. The default value is null.<br>**Atomic service API**: This API can be used in atomic services since API version 20.| 292 293## dragController.createDragAction<sup>(deprecated)</sup> 294 295createDragAction(customArray: Array<CustomBuilder \| DragItemInfo>, dragInfo: DragInfo): DragAction 296 297Creates a drag action object for initiating drag and drop operations. You need to explicitly specify one or more drag previews, the drag data, and the drag handle point. If a drag operation initiated by an existing drag action object is not completed, no new object can be created, and calling the API will throw an exception. After the lifecycle of the drag action object ends, the callback functions registered on this object become invalid. Therefore, it is necessary to hold this object within a longer scope and replace the old value with a new object returned by **createDragAction** before each drag initiation. 298 299> **NOTE** 300> 301> This API is supported since API version 11 and deprecated since API version 18. You are advised to use [createDragAction](arkts-apis-uicontext-dragcontroller.md#createdragaction11) instead on the obtained [DragController](arkts-apis-uicontext-dragcontroller.md) object. 302> 303> Since API version 11, you can use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) API in [UIContext](arkts-apis-uicontext-uicontext.md) to obtain the [DragController](arkts-apis-uicontext-dragcontroller.md) object associated with the current UI context. 304> 305> For optimal drag and drop performance, limit the number of drag previews. 306 307**Atomic service API**: This API can be used in atomic services since API version 12. 308 309**System capability**: SystemCapability.ArkUI.ArkUI.Full 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 315| customArray | Array<[CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo)> | Yes | Object to be dragged.| 316| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | 317 318**Return value** 319 320| Type | Description | 321| ------------------------------------------------------ | ------------------ | 322| [DragAction](#dragaction11)| **DragAction** object, which is used to subscribe to drag state changes and start the drag service.| 323 324**Error codes** 325 326For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 327| ID| Error Message | 328| -------- | ------------- | 329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 330| 100001 | Internal handling failed. | 331 332**Example** 333 334> **NOTE** 335> 336> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 337 338```ts 339import { dragController } from '@kit.ArkUI'; 340import { image } from '@kit.ImageKit'; 341import { unifiedDataChannel } from '@kit.ArkData'; 342 343@Entry 344@Component 345struct DragControllerPage { 346 @State pixmap: image.PixelMap | null = null 347 @State text: string = '' 348 private dragAction: dragController.DragAction | null = null; 349 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 350 @Builder DraggingBuilder() { 351 Column() { 352 Text("DraggingBuilder") 353 .fontColor(Color.White) 354 .fontSize(12) 355 } 356 .width(100) 357 .height(100) 358 .backgroundColor(Color.Blue) 359 } 360 361 build() { 362 Column() { 363 364 Column() { 365 Text(this.text) 366 .width('100%') 367 .height('100%') 368 .fontColor(Color.White) 369 .fontSize(18) 370 .onDrop((dragEvent?:DragEvent)=>{ 371 if(dragEvent){ 372 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 373 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 374 this.text = plainText.textContent; 375 } 376 }) 377 } 378 .width(100) 379 .height(100) 380 .backgroundColor(Color.Red) 381 .margin(10) 382 383 Button('Drag Multiple Objects').onTouch((event?:TouchEvent) => { 384 if(event){ 385 if (event.type == TouchType.Down) { 386 console.info("multi drag Down by listener"); 387 this.customBuilders.splice(0, this.customBuilders.length); 388 this.customBuilders.push(()=>{this.DraggingBuilder()}); 389 this.customBuilders.push(()=>{this.DraggingBuilder()}); 390 this.customBuilders.push(()=>{this.DraggingBuilder()}); 391 let text = new unifiedDataChannel.PlainText() 392 text.textContent = 'drag text' 393 let unifiedData = new unifiedDataChannel.UnifiedData(text) 394 let dragInfo: dragController.DragInfo = { 395 pointerId: 0, 396 data: unifiedData, 397 extraParams: '' 398 } 399 try{ 400 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // You are advised to use this.getUIContext().getDragController().createDragAction(). 401 if(!this.dragAction){ 402 console.info("listener dragAction is null"); 403 return 404 } 405 this.dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 406 if (dragAndDropInfo.status == dragController.DragStatus.STARTED) { 407 console.info("drag has start"); 408 } else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){ 409 console.info("drag has end"); 410 if (!this.dragAction) { 411 return 412 } 413 this.dragAction.off('statusChange') 414 } 415 }) 416 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 417 console.info("start drag Error:" + err.message); 418 }) 419 } catch(err) { 420 console.info("create dragAction Error:" + err.message); 421 } 422 } 423 } 424 }).margin({top:20}) 425 } 426 } 427} 428``` 429  430## DragAction<sup>11+</sup> 431 432Implements a **DragAction** object to subscribe to drag state changes and start the drag service. 433 434**Atomic service API**: This API can be used in atomic services since API version 12. 435 436**System capability**: SystemCapability.ArkUI.ArkUI.Full 437 438### startDrag<sup>11+</sup> 439 440startDrag(): Promise<void> 441 442Starts the drag service. This API uses a promise to return the result. 443 444**Atomic service API**: This API can be used in atomic services since API version 12. 445 446**System capability**: SystemCapability.ArkUI.ArkUI.Full 447 448**Return value** 449 450| Type| Description| 451| -------- | -------- | 452| Promise<void> | Promise that returns no value.| 453 454**Error codes** 455 456| ID| Error Message | 457| -------- | ------------- | 458| 100001 | Internal handling failed. | 459 460**Example 1** 461 462> **NOTE** 463> 464> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 465 466```ts 467import { dragController } from '@kit.ArkUI'; 468import { unifiedDataChannel } from '@kit.ArkData'; 469 470@Entry 471@Component 472struct DragControllerPage { 473 private dragAction: dragController.DragAction | null = null; 474 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 475 @Builder DraggingBuilder() { 476 Column() { 477 Text("DraggingBuilder") 478 .fontColor(Color.White) 479 .fontSize(12) 480 } 481 .width(100) 482 .height(100) 483 .backgroundColor(Color.Blue) 484 } 485 486 build() { 487 Column() { 488 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 489 if(event){ 490 if (event.type == TouchType.Down) { 491 this.customBuilders.splice(0, this.customBuilders.length); 492 this.customBuilders.push(()=>{this.DraggingBuilder()}); 493 let text = new unifiedDataChannel.PlainText() 494 text.textContent = 'drag text' 495 let unifiedData = new unifiedDataChannel.UnifiedData(text) 496 let dragInfo: dragController.DragInfo = { 497 pointerId: 0, 498 data: unifiedData, 499 extraParams: '' 500 } 501 try{ 502 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // You are advised to use this.getUIContext().getDragController().createDragAction(). 503 if(!this.dragAction){ 504 console.info("listener dragAction is null"); 505 return; 506 } 507 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 508 console.info("start drag Error:" + err.message); 509 }) 510 } catch(err) { 511 console.info("create dragAction Error:" + err.message); 512 } 513 } 514 } 515 }).margin({top:20}) 516 } 517 } 518} 519``` 520 521**Example 2** 522 523This example shows how to configure **dataLoadParams** in [DragInfo](#draginfo) to enable deferred data loading from the drag source. 524 525```ts 526import { unifiedDataChannel, uniformTypeDescriptor, uniformDataStruct } from '@kit.ArkData'; 527import { fileUri, fileIo as fs } from '@kit.CoreFileKit'; 528import { common } from '@kit.AbilityKit'; 529import { dragController } from '@kit.ArkUI'; 530 531@Entry 532@Component 533struct ImageExample { 534 private dragAction: dragController.DragAction | null = null; 535 customBuilders: Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 536 @State uri: string = ""; 537 @State blockArr: string[] = []; 538 uiContext = this.getUIContext(); 539 udKey: string = ''; 540 541 @Builder 542 DraggingBuilder() { 543 Video({ src: $rawfile('test1.mp4'), controller: new VideoController() }) 544 .width(100) 545 .height(100) 546 } 547 548 build() { 549 Column() { 550 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceAround }) { 551 Button('touch to execute drag') 552 .margin(10) 553 .onTouch((event?: TouchEvent) => { 554 if (event) { 555 if (event.type == TouchType.Down) { 556 this.customBuilders.splice(0, this.customBuilders.length); 557 this.customBuilders.push(() => { 558 this.DraggingBuilder() 559 }); 560 const context: Context | undefined = this.uiContext.getHostContext(); 561 if (context) { 562 let loadHandler: unifiedDataChannel.DataLoadHandler = () => { 563 let data = 564 context.resourceManager.getRawFdSync('test1.mp4'); 565 let filePath = context.filesDir + '/test1.mp4'; 566 let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 567 let bufferSize = data.length as number; 568 let buf = new ArrayBuffer(bufferSize); 569 fs.readSync(data.fd, buf, { offset: data.offset, length: bufferSize }); 570 fs.writeSync(file.fd, buf, { offset: 0, length: bufferSize }); 571 fs.closeSync(file.fd); 572 context.resourceManager.closeRawFdSync('test1.mp4') 573 this.uri = fileUri.getUriFromPath(filePath); 574 let videoMp: uniformDataStruct.FileUri = { 575 uniformDataType: 'general.file-uri', 576 oriUri: this.uri, 577 fileType: 'general.video', 578 } 579 let unifiedRecord = new unifiedDataChannel.UnifiedRecord(); 580 let unifiedData = new unifiedDataChannel.UnifiedData(); 581 unifiedRecord.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, videoMp); 582 unifiedData.addRecord(unifiedRecord); 583 return unifiedData; 584 } 585 586 let dragInfo: dragController.DragInfo = { 587 pointerId: 0, 588 extraParams: '', 589 dataLoadParams: { 590 loadHandler: loadHandler, 591 dataLoadInfo: { types: new Set([uniformTypeDescriptor.UniformDataType.VIDEO]), recordCount: 1 } 592 } 593 } 594 595 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 596 console.info("ndq Register to listen on drag status", JSON.stringify(dragAndDropInfo)); 597 } 598 try { 599 this.dragAction = this.getUIContext() 600 .getDragController() 601 .createDragAction(this.customBuilders, 602 dragInfo) 603 if (!this.dragAction) { 604 console.info("listener dragAction is null"); 605 return; 606 } 607 this.dragAction.on('statusChange', func); 608 this.dragAction.startDrag().then(() => { 609 }).catch((err: Error) => { 610 console.error("start drag Error:" + err.message); 611 }) 612 } catch (err) { 613 console.error("create dragAction Error:" + err.message); 614 } 615 } 616 } 617 } 618 }) 619 } 620 .margin({ bottom: 20 }) 621 622 Row() { 623 Column() { 624 Text('Valid drop target') 625 .fontSize('15dp') 626 .height('10%') 627 List() { 628 ForEach(this.blockArr, (item: string, index) => { 629 ListItem() { 630 Video({ src: item, controller: new VideoController() }) 631 .width(100) 632 .height(100) 633 .border({ width: 1 }) 634 } 635 .margin({ left: 30, top: 30 }) 636 }, (item: string) => item) 637 } 638 .border({ width: 1 }) 639 .height('90%') 640 .width('100%') 641 .allowDrop([uniformTypeDescriptor.UniformDataType.VIDEO]) 642 .onDrop((event?: DragEvent, extraParams?: string) => { 643 let context = this.uiContext.getHostContext() as common.UIAbilityContext; 644 let pathDir: string = context.distributedFilesDir; 645 let destUri = fileUri.getUriFromPath(pathDir); 646 let progressListener: unifiedDataChannel.DataProgressListener = 647 (progress: unifiedDataChannel.ProgressInfo, dragData: UnifiedData | null) => { 648 if (dragData != null) { 649 let arr: Array<unifiedDataChannel.UnifiedRecord> = dragData.getRecords(); 650 if (arr.length > 0) { 651 if (arr[0].getType() === uniformTypeDescriptor.UniformDataType.VIDEO) { 652 this.blockArr.splice(JSON.parse(extraParams as string).insertIndex, 0, this.uri); 653 } 654 } else { 655 console.info('dragData arr is null'); 656 } 657 } else { 658 console.info('dragData is undefined'); 659 } 660 console.info(`percentage: ${progress.progress}`); 661 }; 662 let options: DataSyncOptions = { 663 destUri: destUri, 664 fileConflictOptions: unifiedDataChannel.FileConflictOptions.OVERWRITE, 665 progressIndicator: unifiedDataChannel.ProgressIndicator.DEFAULT, 666 dataProgressListener: progressListener, 667 } 668 try { 669 this.udKey = (event as DragEvent).startDataLoading(options); 670 console.info('udKey: ', this.udKey); 671 } catch (e) { 672 console.error(`startDataLoading errorCode: ${e.code}, errorMessage: ${e.message}`); 673 } 674 }, { disableDataPrefetch: true }) 675 } 676 .height("50%") 677 .width("90%") 678 .border({ width: 1 }) 679 } 680 681 Button('Cancel Data Transfer') 682 .onClick(() => { 683 try { 684 this.getUIContext().getDragController().cancelDataLoading(this.udKey); 685 } catch (e) { 686 console.error(`cancelDataLoading errorCode: ${e.code}, errorMessage: ${e.message}`); 687 } 688 }) 689 .margin({ top: 10 }) 690 }.width('100%') 691 } 692} 693``` 694 695 696### on('statusChange')<sup>11+</sup> 697 698on(type: 'statusChange', callback: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 699 700Subscribes to drag state changes. 701 702**Atomic service API**: This API can be used in atomic services since API version 12. 703 704**System capability**: SystemCapability.ArkUI.ArkUI.Full 705 706**Parameters** 707| Name | Type | Mandatory | Description | 708| ------ | ------ | ------- | ---------------- | 709| type | string | Yes | Event type. The value is fixed at **'statusChange'**, which indicates the drag state change event.| 710| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | Yes | Callback used to return a [DragAndDropInfo](#draganddropinfo11) instance.| 711 712**Example** 713 714> **NOTE** 715> 716> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 717 718```ts 719import { dragController } from '@kit.ArkUI'; 720import { unifiedDataChannel } from '@kit.ArkData'; 721 722@Entry 723@Component 724struct DragControllerPage { 725 private dragAction: dragController.DragAction | null = null; 726 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 727 @Builder DraggingBuilder() { 728 Column() { 729 Text("DraggingBuilder") 730 .fontColor(Color.White) 731 .fontSize(12) 732 } 733 .width(100) 734 .height(100) 735 .backgroundColor(Color.Blue) 736 } 737 738 build() { 739 Column() { 740 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 741 if(event){ 742 if (event.type == TouchType.Down) { 743 this.customBuilders.splice(0, this.customBuilders.length); 744 this.customBuilders.push(()=>{this.DraggingBuilder()}); 745 let text = new unifiedDataChannel.PlainText() 746 text.textContent = 'drag text' 747 let unifiedData = new unifiedDataChannel.UnifiedData(text) 748 let dragInfo: dragController.DragInfo = { 749 pointerId: 0, 750 data: unifiedData, 751 extraParams: '' 752 } 753 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 754 console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo)); 755 } 756 try{ 757 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // You are advised to use this.getUIContext().getDragController().createDragAction(). 758 if(!this.dragAction){ 759 console.info("listener dragAction is null"); 760 return; 761 } 762 // Subscribe to drag state changes. The information in func will be logged once a change is detected. 763 this.dragAction.on('statusChange', func); 764 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 765 console.info("start drag Error:" + err.message); 766 }) 767 } catch(err) { 768 console.info("create dragAction Error:" + err.message); 769 } 770 } 771 } 772 }).margin({top:20}) 773 } 774 } 775} 776``` 777 778### off('statusChange')<sup>11+</sup> 779 780 off(type: 'statusChange', callback?: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 781 782Unsubscribes from drag state changes. 783 784**Atomic service API**: This API can be used in atomic services since API version 12. 785 786**System capability**: SystemCapability.ArkUI.ArkUI.Full 787 788**Parameters** 789| Name | Type | Mandatory | Description | 790| ------ | ------ | ------- | ---------------- | 791| type | string | Yes | Event type. The value is fixed at **'statusChange'**, which indicates the drag state change event.| 792| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | No | Callback to unregister. If this parameter is not specified, this API unregisters all callbacks for the specified event.| 793 794**Example** 795 796> **NOTE** 797> 798> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 799 800```ts 801import { dragController } from '@kit.ArkUI'; 802import { unifiedDataChannel } from '@kit.ArkData'; 803 804@Entry 805@Component 806struct DragControllerPage { 807 private dragAction: dragController.DragAction | null = null; 808 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 809 @Builder DraggingBuilder() { 810 Column() { 811 Text("DraggingBuilder") 812 .fontColor(Color.White) 813 .fontSize(12) 814 } 815 .width(100) 816 .height(100) 817 .backgroundColor(Color.Blue) 818 } 819 820 build() { 821 Column() { 822 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 823 if(event){ 824 if (event.type == TouchType.Down) { 825 this.customBuilders.splice(0, this.customBuilders.length); 826 this.customBuilders.push(()=>{this.DraggingBuilder()}); 827 let text = new unifiedDataChannel.PlainText() 828 text.textContent = 'drag text' 829 let unifiedData = new unifiedDataChannel.UnifiedData(text) 830 let dragInfo: dragController.DragInfo = { 831 pointerId: 0, 832 data: unifiedData, 833 extraParams: '' 834 } 835 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 836 console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo)); 837 } 838 try{ 839 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // You are advised to use this.getUIContext().getDragController().createDragAction(). 840 if(!this.dragAction){ 841 console.info("listener dragAction is null"); 842 return; 843 } 844 this.dragAction.on('statusChange', func); 845 // Unsubscribe from drag state changes. The information in func will not be logged after a drag operation starts. 846 this.dragAction.off('statusChange', func); 847 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 848 console.info("start drag Error:" + err.message); 849 }) 850 } catch(err) { 851 console.info("create dragAction Error:" + err.message); 852 } 853 } 854 } 855 }).margin({top:20}) 856 } 857 } 858} 859``` 860 861## DragAndDropInfo<sup>11+</sup> 862 863Provides the data reported when the state changes during dragging. 864 865**Atomic service API**: This API can be used in atomic services since API version 12. 866 867**System capability**: SystemCapability.ArkUI.ArkUI.Full 868 869| Name | Type | Mandatory| Description | 870| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 871| status | [DragStatus](#dragstatus11) | Yes | Current dragging state (started or ended). | 872| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent7) | Yes | Drag event corresponding to the current state. The drag event initiated by **dragController** only supports the APIs for obtaining the result and behavior, and is used exclusively for the dragging end state.| 873| extraParams| string | No | Additional information about the drag action. Not supported currently. The default value is null.| 874 875## DragStatus<sup>11+</sup> 876 877Describes the dragging start and end states. 878 879**Atomic service API**: This API can be used in atomic services since API version 12. 880 881**System capability**: SystemCapability.ArkUI.ArkUI.Full 882 883| Name | Value | Description | 884| ----------- | ------------------------------------------------------| ---------------------------------------- | 885| STARTED | 0 | Dragging is started. | 886| ENDED | 1 | Dragging ends. | 887 888## AnimationOptions<sup>11+</sup> 889 890Defines parameters related to drag-and-drop animation effects. 891 892**Atomic service API**: This API can be used in atomic services since API version 12. 893 894**System capability**: SystemCapability.ArkUI.ArkUI.Full 895 896| Name | Type | Mandatory| Description | 897| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 898| duration | number | No | Animation duration, in ms.<br>Default value: **1000**<br>**NOTE**<br>- If this parameter is set to a value less than 0, the value **0** is used.<br>- Floating-point values will be rounded down to integers. For example, if the value set is 1.2, **1** will be used.| 899| curve | [Curve](arkui-ts/ts-appendix-enums.md#curve) \| [ICurve](js-apis-curve.md#icurve9) | No | Animation curve.<br>Default value: **Curve.EaseInOut**| | 900 901## DragEventParam<sup>12+</sup> 902 903Callback used to return the result. 904 905**Atomic service API**: This API can be used in atomic services since API version 12. 906 907**System capability**: SystemCapability.ArkUI.ArkUI.Full 908 909| Name | Type | Mandatory| Description | 910| ----------- | ------------------------------------------------------------ | ---- | ------------------------------ | 911| event<sup>10+</sup> | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent7) | Yes | Drag event information that includes only the drag result.| 912| extraParams<sup>10+</sup> | string | Yes | Additional information about the drag event. | 913 914## dragController.getDragPreview<sup>(deprecated)</sup> 915 916getDragPreview(): DragPreview 917 918Obtains the **DragPreview** object, which represents the preview displayed during a drag operation. 919 920> **NOTE** 921> 922> This API is supported since API version 11 and deprecated since API version 18. You are advised to use [getDragPreview](arkts-apis-uicontext-dragcontroller.md#getdragpreview11) instead on the obtained [DragController](arkts-apis-uicontext-dragcontroller.md) object. 923> 924> Since API version 11, you can use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) API in [UIContext](arkts-apis-uicontext-uicontext.md) to obtain the [DragController](arkts-apis-uicontext-dragcontroller.md) object associated with the current UI context. 925 926**Atomic service API**: This API can be used in atomic services since API version 12. 927 928**System capability**: SystemCapability.ArkUI.ArkUI.Full 929 930**Return value** 931 932| Type | Description | 933| ------------| ------------------------------------------------| 934| [DragPreview](#dragpreview11) | **DragPreview** object. It provides the API for setting the preview style. It does not work in the **OnDrop** and **OnDragEnd** callbacks.| 935 936**Example** 937 938For details, see [animate](#animate11). 939 940## DragPreview<sup>11+</sup> 941 942Implements a **DragPreview** object. This API does not work in the **OnDrop** and **OnDragEnd** callbacks. 943 944**Atomic service API**: This API can be used in atomic services since API version 12. 945 946**System capability**: SystemCapability.ArkUI.ArkUI.Full 947 948### setForegroundColor<sup>11+</sup> 949 950setForegroundColor(color: ResourceColor): void 951 952Sets the foreground color of the drag preview. This API does not work in the **OnDrop** and **OnDragEnd** callbacks. It can only be used on the object obtained through the [getDragPreview()](arkts-apis-uicontext-dragcontroller.md#getdragpreview11) API. 953 954**Atomic service API**: This API can be used in atomic services since API version 12. 955 956**System capability**: SystemCapability.ArkUI.ArkUI.Full 957 958**Parameters** 959 960| Name | Type | Mandatory| Description | 961| -------- | -------------------------------- | ---- | ------------------------ | 962| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | Yes | Foreground color of the drag preview. | 963 964**Example** 965 966For details, see [animate](#animate11). 967 968### animate<sup>11+</sup> 969 970animate(options: AnimationOptions, handler: () => void): void 971 972Applies a foreground color animation to the drag preview. This API does not work in the **OnDrop** and **OnDragEnd** callbacks. It can only be used on the object obtained through the [getDragPreview()](arkts-apis-uicontext-dragcontroller.md#getdragpreview11) API. 973 974**Atomic service API**: This API can be used in atomic services since API version 12. 975 976**System capability**: SystemCapability.ArkUI.ArkUI.Full 977 978**Parameters** 979 980| Name | Type | Mandatory| Description | 981| -------- | -------------------------------- | ---- | -----------------------------------| 982| options | [AnimationOptions](#animationoptions11) | Yes | Animation settings. | 983| handler | () => void | Yes | Callback used to change attributes such as the background mask color. | 984 985**Example** 986 987> **NOTE** 988> 989> You are advised to use the [getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11) to obtain the **DragController** object associated with the current UI context. 990 9911. In the **EntryAbility.ets** file, obtain the UI context and save it to LocalStorage. 992 ```ts 993import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 994import { hilog } from '@kit.PerformanceAnalysisKit'; 995import { window, UIContext } from '@kit.ArkUI'; 996 997let uiContext: UIContext; 998let localStorage: LocalStorage = new LocalStorage('uiContext'); 999 1000export default class EntryAbility extends UIAbility { 1001 storage: LocalStorage = localStorage; 1002 1003 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 1004 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 1005 } 1006 1007 onDestroy(): void { 1008 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 1009 } 1010 1011 onWindowStageCreate(windowStage: window.WindowStage): void { 1012 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 1013 1014 windowStage.loadContent('pages/Index', this.storage, (err, data) => { 1015 if (err.code) { 1016 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', `Code is ${err.code}, message is ${err.message}`); 1017 return; 1018 } 1019 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', `Code is ${err.code}, message is ${err.message}`); 1020 windowStage.getMainWindow((err, data) => { 1021 if (err.code) { 1022 hilog.error(0x0000, `Failed to obtain the main window. Cause: ${err.message}`, ''); 1023 return; 1024 } 1025 let windowClass: window.Window = data; 1026 uiContext = windowClass.getUIContext(); 1027 this.storage.setOrCreate<UIContext>('uiContext', uiContext); 1028 }) 1029 }); 1030 } 1031} 1032 ``` 10332. In the **Index.ets** file, call **this.getUIContext().getSharedLocalStorage()** to obtain the UI context and then use the **DragController** object obtained to perform subsequent operations. 1034 ```ts 1035 1036import { unifiedDataChannel } from '@kit.ArkData'; 1037import { hilog } from '@kit.PerformanceAnalysisKit'; 1038import { dragController, curves, promptAction, UIContext } from '@kit.ArkUI'; 1039import { image } from '@kit.ImageKit'; 1040import { BusinessError } from '@kit.BasicServicesKit'; 1041 1042@Entry() 1043@Component 1044struct DragControllerPage { 1045 @State pixmap: image.PixelMap|null = null; 1046 storages = this.getUIContext().getSharedLocalStorage(); 1047 1048 @Builder DraggingBuilder() { 1049 Column() { 1050 Text("DraggingBuilder") 1051 .fontColor(Color.White) 1052 .fontSize(12) 1053 } 1054 .width(100) 1055 .height(100) 1056 .backgroundColor(Color.Blue) 1057 } 1058 1059 @Builder PixmapBuilder() { 1060 Column() { 1061 Text("PixmapBuilder") 1062 } 1063 .width(100) 1064 .height(100) 1065 .backgroundColor(Color.Blue) 1066 } 1067 1068 build() { 1069 Column() { 1070 Button('Drag Here') 1071 .margin(10) 1072 .onDragEnter(() => { 1073 try { 1074 let uiContext: UIContext = this.storages?.get<UIContext>('uiContext') as UIContext; 1075 let previewObj: dragController.DragPreview = uiContext.getDragController().getDragPreview(); 1076 let foregroundColor: ResourceColor = Color.Green; 1077 1078 let previewAnimation: dragController.AnimationOptions = { 1079 curve: curves.cubicBezierCurve(0.2,0,0,1), 1080 } 1081 previewObj.animate(previewAnimation, () => { 1082 previewObj.setForegroundColor(foregroundColor); 1083 }); 1084 } catch (error) { 1085 let msg = (error as BusinessError).message; 1086 let code = (error as BusinessError).code; 1087 hilog.error(0x0000, `show error code is ${code}, message is ${msg}`, ''); 1088 } 1089 }) 1090 .onDrop(() => { 1091 this.getUIContext().getPromptAction().showToast({duration: 100, message: 'Drag Success', bottom: 400}) 1092 }) 1093 Button('Drag').onTouch((event?:TouchEvent) => { 1094 if(event){ 1095 if (event.type == TouchType.Down) { 1096 let text = new unifiedDataChannel.Text() 1097 let unifiedData = new unifiedDataChannel.UnifiedData(text) 1098 let dragInfo: dragController.DragInfo = { 1099 pointerId: 0, 1100 data: unifiedData, 1101 extraParams: '' 1102 } 1103 class tmp{ 1104 event:DragEvent|undefined = undefined 1105 extraParams:string = '' 1106 } 1107 let eve:tmp = new tmp() 1108 this.getUIContext().getDragController().executeDrag(() => { // You are advised to usethis.getUIContext().getDragController().executeDrag(). 1109 this.DraggingBuilder() 1110 }, dragInfo, (err , eve) => { 1111 hilog.info(0x0000, `${JSON.stringify(err)}`, '') 1112 if (eve && eve.event) { 1113 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 1114 hilog.info(0x0000, 'success', ''); 1115 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 1116 hilog.info(0x0000, 'failed', ''); 1117 } 1118 } 1119 }) 1120 } 1121 } 1122 }).margin({top:100}) 1123 } 1124 .width('100%') 1125 .height('100%') 1126 } 1127} 1128 ``` 1129  1130 1131## DragStartRequestStatus<sup>18+</sup> 1132 1133Enumerates the states defining whether an application can initiate a drag operation. 1134 1135**Atomic service API**: This API can be used in atomic services since API version 18. 1136 1137**System capability**: SystemCapability.ArkUI.ArkUI.Full 1138 1139| Name | Value| Description | 1140| -------- | -- | ------------------------------------------------------------ | 1141| WAITING | 0 | The application is preparing data and cannot initiate a drag operation yet.| 1142| READY | 1 | The application has completed data preparation and is ready to initiate a drag operation.| 1143 1144## DragSpringLoadingState<sup>20+</sup> 1145 1146Enumerates hover detection states during drag operations. 1147 1148**Atomic service API**: This API can be used in atomic services since API version 20. 1149 1150**System capability**: SystemCapability.ArkUI.ArkUI.Full 1151 1152 1153| Name| Value|Description | 1154| ------ | --------------------- |--------------------------------------- | 1155| BEGIN | - |Initial state when a dragged item enters the component boundary and remains stationary for the specified duration. | 1156| UPDATE | - |Periodic notification state during sustained hover detection.| 1157| END | - |Final state indicating completion of the hover detection cycle, which is triggered when the dragged item remains stationary after the last update notification. Hover detection will only restart after the dragged item exits and re-enters the component boundary or enters a child component.| 1158| CANCEL | - |Interruption state of hover detection triggered by termination events, which include the following: finger or mouse release, window switching, screen off, exiting the component boundary, entering child components, or exceeding the movement threshold within the component.| 1159 1160## DragSpringLoadingConfiguration<sup>20+</sup> 1161 1162Defines the configuration parameters for drag hover detection. 1163 1164**Atomic service API**: This API can be used in atomic services since API version 20. 1165 1166**System capability**: SystemCapability.ArkUI.ArkUI.Full 1167 1168| Name | Type |Read-Only| Optional| Description | 1169| :--------------------- | ------ | ---- | --- | ---------------------------------------------------- | 1170| stillTimeLimit | number | No | Yes |Time (in ms) required to remain stationary to enter the BEGIN state of hover detection. Value range: integer from 0 to 2<sup>31</sup> - 1. Floating-point number inputs will be truncated to integers. Invalid values (negative numbers, **null**, **undefined**, **NaN**) are treated as the default value **500**.| 1171| updateInterval | number | No | Yes |Time interval (in ms) at which update notifications are sent after hover detection enters the UPDATE state. Value range: integer from 0 to 2<sup>31</sup> - 1. Floating-point number inputs will be truncated to integers. Invalid values (negative numbers, **null**, **undefined**, **NaN**) are treated as the default value **100**.| 1172| updateNotifyCount | number | No | Yes |Maximum number of update notifications after hover detection enters the UPDATE state. Value range: integer from 0 to 2<sup>31</sup> - 1. Floating-point number inputs will be truncated to integers. Invalid values (negative numbers, **null**, **undefined**, **NaN**) are treated as the default value **3**.| 1173| updateToFinishInterval | number | No | Yes |Maximum waiting time (in ms) from the UPDATE state to the END state. Value range: integer from 0 to 2<sup>31</sup> - 1. Floating-point number inputs will be truncated to integers. Invalid values (negative numbers, **null**, **undefined**, **NaN**) are treated as the default value **100**.| 1174 1175## SpringLoadingDragInfos<sup>20+</sup> 1176 1177Defines the drag event information when hover detection is triggered. 1178 1179**Atomic service API**: This API can be used in atomic services since API version 20. 1180 1181**System capability**: SystemCapability.ArkUI.ArkUI.Full 1182 1183| Name | Type | Mandatory| Description | 1184| :-------- | ------- | ---- |--------------------------------------------- | 1185| dataSummary | [unifiedDataChannel.Summary](../apis-arkdata/js-apis-data-unifiedDataChannel.md#summary) |No | Summary of the dragged data. The default value is null.| 1186| extraInfos | string |No | Additional information about the drag event. The default value is an empty string. | 1187 1188## SpringLoadingContext<sup>20+</sup> 1189 1190Defines the callback context information, which is passed to the application in the hover detection callback to allow the application to access the drag status. 1191 1192### Properties 1193 1194**Atomic service API**: This API can be used in atomic services since API version 20. 1195 1196**System capability**: SystemCapability.ArkUI.ArkUI.Full 1197 1198| Name | Type | Read-only |Optional | Description | 1199| :----- | -------- | ---- | ---- | ---------------------------------------- | 1200| state | [DragSpringLoadingState](#dragspringloadingstate20) |No |No | Current state of hover detection. | 1201| currentNotifySequence | number |No |No |Callback notification sequence number in the current hover detection cycle. The value is zero-based.| 1202| dragInfos | [SpringLoadingDragInfos](#springloadingdraginfos20) |No |Yes | Drag information. If the value provided is **undefined**, the default value of [SpringLoadingDragInfos](#springloadingdraginfos20) is used. | 1203| currentConfig | [DragSpringLoadingConfiguration](#dragspringloadingconfiguration20) |No |Yes | Configuration information in the current callback. If the value provided is **undefined**, the default value of [DragSpringLoadingConfiguration](#dragspringloadingconfiguration20) is used. | 1204 1205### abort<sup>20+</sup> 1206 1207abort(): void 1208 1209Terminates subsequent hover detection. 1210 1211**Atomic service API**: This API can be used in atomic services since API version 20. 1212 1213**System capability**: SystemCapability.ArkUI.ArkUI.Full 1214 1215### updateConfiguration<sup>20+</sup> 1216 1217updateConfiguration(config: DragSpringLoadingConfiguration): void 1218 1219Updates the configuration for subsequent hover detection. 1220 1221**Atomic service API**: This API can be used in atomic services since API version 20. 1222 1223**System capability**: SystemCapability.ArkUI.ArkUI.Full 1224 1225**Parameters** 1226 1227| Name | Type | Mandatory | Description | 1228| :----- | -------- | ---- | --------------------------------------------- | 1229| config | [DragSpringLoadingConfiguration](#dragspringloadingconfiguration20) |Yes | New configuration for hover detection. | 1230
