1# @ohos.arkui.dragController (DragController) 2<!--Kit: ArkUI--> 3<!--Subsystem: ArkUI--> 4<!--Owner: @jiangtao92--> 5<!--Designer: @piggyguy--> 6<!--Tester: @songyanhong--> 7<!--Adviser: @HelloCrease--> 8 9本模块提供发起主动拖拽的能力，当应用接收到触摸或长按等事件时可以主动发起拖拽的动作，并在其中携带拖拽信息。 10 11> **说明：** 12> 13> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 本模块功能依赖UI的执行上下文，不可在[UI上下文不明确](../../ui/arkts-global-interface.md#ui上下文不明确)的地方使用，参见[UIContext](arkts-apis-uicontext-uicontext.md)说明。 15> 示例效果请以真机运行为准，当前 DevEco Studio预览器不支持。 16 17## 导入模块 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 27主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。使用callback异步回调。 28 29> **说明：** 30> 31> 从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)获取[DragController](arkts-apis-uicontext-dragcontroller.md)实例，再通过此实例调用替代方法[executeDrag](arkts-apis-uicontext-dragcontroller.md#executedrag11)。 32> 33> 从API version 11开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的[DragController](arkts-apis-uicontext-dragcontroller.md)对象。 34 35**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 36 37**系统能力：** SystemCapability.ArkUI.ArkUI.Full 38 39**参数：** 40 41| 参数名 | 类型 | 必填 | 说明 | 42| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 43| custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | 是 | 拖拽发起后跟手效果所拖拽的对象。<br/>**说明：** <br/>不支持全局builder。如果builder中使用了[Image](arkui-ts/ts-basic-components-image.md)组件，应尽量开启同步加载，即配置Image的[syncLoad](arkui-ts/ts-basic-components-image.md#syncload8)为true。该builder只用于生成当次拖拽中显示的图片。builder的根组件宽高为0时，无法生成拖拽显示的图片导致拖拽失败。builder的修改不会同步到当前正在拖拽的图片，对builder的修改需要在下一次拖拽时生效。 | 44| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 45| callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<[DragEventParam](#drageventparam12)> | 是 | 回调函数。当拖拽成功结束，err为undefined，data为获取到的DragEventParam；否则为错误对象。 | 46 47**错误码：** 48 49以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 50 51| 错误码ID | 错误信息 | 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**示例：** 57 58> **说明：** 59> 60> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 61 62```ts 63import { dragController } from '@kit.ArkUI'; 64import { unifiedDataChannel } from '@kit.ArkData'; 65 66class Tmp{ 67 event:DragEvent|undefined = undefined 68 extraParams:string = '' 69} 70 71@Entry 72@Component 73struct DragControllerPage { 74 @State text: string = '' 75 76 @Builder DraggingBuilder() { 77 Column() { 78 Text("DraggingBuilder") 79 .fontColor(Color.White) 80 .fontSize(12) 81 } 82 .width(100) 83 .height(100) 84 .backgroundColor(Color.Blue) 85 } 86 87 build() { 88 Column() { 89 Button('touch to execute drag') 90 .margin(10) 91 .onTouch((event?:TouchEvent) => { 92 if(event){ 93 if (event.type == TouchType.Down) { 94 let text = new unifiedDataChannel.PlainText() 95 text.textContent = 'drag text' 96 text.abstract = 'abstract' 97 let unifiedData = new unifiedDataChannel.UnifiedData(text) 98 99 let dragInfo: dragController.DragInfo = { 100 pointerId: 0, 101 data: unifiedData, 102 extraParams: '' 103 } 104 let eve:tmp = new tmp() 105 this.getUIContext().getDragController().executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口 106 if(eve.event){ 107 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 108 // ... 109 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 110 // ... 111 } 112 } 113 }) 114 } 115 } 116 }) 117 Text(this.text) 118 .height(100) 119 .width(150) 120 .margin({top:20}) 121 .border({color:Color.Black,width:1}) 122 .onDrop((dragEvent?:DragEvent)=>{ 123 if(dragEvent){ 124 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 125 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 126 this.text = plainText.textContent; 127 } 128 }) 129 } 130 .width('100%') 131 .height('100%') 132 } 133} 134``` 135  136## dragController.executeDrag<sup>(deprecated)</sup> 137 138executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise\<DragEventParam> 139 140主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。使用Promise异步回调。 141 142> **说明：** 143> 144> 从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)获取[DragController](arkts-apis-uicontext-dragcontroller.md)实例，再通过此实例调用替代方法[executeDrag](arkts-apis-uicontext-dragcontroller.md#executedrag11-1)。 145> 146> 从API version 11开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的[DragController](arkts-apis-uicontext-dragcontroller.md)对象。 147 148**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 149 150**系统能力：** SystemCapability.ArkUI.ArkUI.Full 151 152**参数：** 153 154| 参数名 | 类型 | 必填 | 说明 | 155| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 156| custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | 是 | 拖拽发起后跟手效果所拖拽的对象。 | 157| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 158 159**返回值：** 160 161| 类型 | 说明 | 162| -------------------------------------------------- | ------------------------ | 163| Promise<[DragEventParam](#drageventparam12)> | Promise对象，拖拽结束返回结果的回调。 | 164 165**错误码：** 166以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 167| 错误码ID | 错误信息 | 168| -------- | ------------- | 169| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 170| 100001 | Internal handling failed. | 171 172**示例：** 173 174> **说明：** 175> 176> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 177 178```ts 179import { dragController } from '@kit.ArkUI'; 180import { image } from '@kit.ImageKit'; 181import { unifiedDataChannel } from '@kit.ArkData'; 182 183class Tmp{ 184 event:DragResult|undefined = undefined 185 extraParams:string = '' 186} 187 188@Entry 189@Component 190struct DragControllerPage { 191 @State pixmap: image.PixelMap|undefined = undefined 192 @State text: string = '' 193 194 @Builder DraggingBuilder() { 195 Column() { 196 Text("DraggingBuilder") 197 .fontColor(Color.White) 198 } 199 .width(100) 200 .height(100) 201 .backgroundColor(Color.Blue) 202 } 203 204 @Builder PixmapBuilder() { 205 Column() { 206 Text("PixmapBuilder") 207 .fontColor(Color.White) 208 .fontSize(15) 209 } 210 .width(100) 211 .height(100) 212 .backgroundColor(Color.Blue) 213 } 214 215 aboutToAppear() { 216 let pb: CustomBuilder = (): void => { 217 this.PixmapBuilder() 218 } 219 this.getUIContext().getComponentSnapshot().createFromBuilder(pb).then((pix: image.PixelMap) => { 220 this.pixmap = pix; 221 }) 222 } 223 224 build() { 225 Column() { 226 Button('touch to execute drag') 227 .margin(10) 228 .onTouch((event?:TouchEvent) => { 229 if(event){ 230 if (event.type == TouchType.Down) { 231 let text = new unifiedDataChannel.PlainText() 232 text.textContent = 'drag text' 233 text.abstract = 'abstract' 234 let unifiedData = new unifiedDataChannel.UnifiedData(text) 235 236 let dragInfo: dragController.DragInfo = { 237 pointerId: 0, 238 data: unifiedData, 239 extraParams: '' 240 } 241 let dragItemInfo: DragItemInfo = { 242 pixelMap: this.pixmap, 243 builder: ()=>{this.DraggingBuilder()}, 244 extraInfo: "DragItemInfoTest" 245 } 246 let eve:tmp = new tmp() 247 this.getUIContext().getDragController().executeDrag(dragItemInfo, dragInfo) // 建议使用 this.getUIContext().getDragController().executeDrag()接口 248 .then((eve) => { 249 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 250 // ... 251 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 252 // ... 253 } 254 }) 255 .catch((err:Error) => { 256 }) 257 } 258 } 259 }) 260 Text(this.text) 261 .height(100) 262 .width(150) 263 .margin({top:20}) 264 .border({color:Color.Black,width:1}) 265 .onDrop((dragEvent?:DragEvent)=>{ 266 if(dragEvent){ 267 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 268 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 269 this.text = plainText.textContent; 270 } 271 }) 272 } 273 .width('100%') 274 .height('100%') 275 } 276} 277``` 278  279## DragInfo 280 281发起拖拽所需要的属性和拖拽时携带的信息。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285| 名称 | 类型 | 只读 | 可选 | 说明 | 286| ----------- | ----------------------------------------------------- | ---- | ---- | --------------------------------------- | 287| pointerId | number | 否 | 否 | 设置启动拖拽时屏幕上触摸点的Id。取值范围为[0, 9]的整数。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 288| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | 否 | 是 | 设置拖拽过程中携带的数据。 <br/>默认值：空<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 289| extraParams | string | 否 | 是 | 设置拖拽事件额外信息，具体功能暂未实现。<br/>默认值：空<br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 290| touchPoint<sup>11+</sup> | [TouchPoint](arkui-ts/ts-types.md#touchpoint11) | 否 | 是 | 配置跟手点坐标。不配置时，左右居中，顶部向下偏移20%。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 | 291| previewOptions<sup>11+</sup>| [DragPreviewOptions](arkui-ts/ts-universal-attributes-drag-drop.md#dragpreviewoptions11) | 否 | 是 | 设置拖拽过程中背板图处理模式及数量角标的显示。 <br/>**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。| 292| dataLoadParams<sup>20+</sup>| [unifiedDataChannel.DataLoadParams](../apis-arkdata/js-apis-data-unifiedDataChannel.md#dataloadparams20) | 否 | 是 | 设置拖起方延迟提供数据。调用此方法向系统提供数据加载参数，而非直接传入完整的数据对象。当用户将数据拖拽至目标应用程序并释放时，系统将使用此参数从起拖方请求实际数据。与data同时设置时，dataLoadParams生效。<br/>默认值：空<br/>**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| 293 294## dragController.createDragAction<sup>(deprecated)</sup> 295 296createDragAction(customArray: Array<CustomBuilder \| DragItemInfo>, dragInfo: DragInfo): DragAction 297 298创建拖拽的Action对象，需要显式指定拖拽背板图(可多个)，以及拖拽的数据，跟手点等信息；当通过一个已创建的 Action 对象发起的拖拽未结束时，无法再次创建新的 Action 对象，接口会抛出异常；当Action对象的生命周期结束后，注册在该对象上的回调函数会失效，因此需要在一个尽量长的作用域下持有该对象，并在每次发起拖拽前通过createDragAction返回新的对象覆盖旧值。 299 300> **说明：** 301> 302> 从API version 11开始支持，从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)获取[DragController](arkts-apis-uicontext-dragcontroller.md)实例，再通过此实例调用替代方法[createDragAction](arkts-apis-uicontext-dragcontroller.md#createdragaction11)。 303> 304> 从API version 11开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的[DragController](arkts-apis-uicontext-dragcontroller.md)对象。 305> 306> 建议控制传递的拖拽背板数量，传递过多容易导致拖起的效率问题。 307 308**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 309 310**系统能力：** SystemCapability.ArkUI.ArkUI.Full 311 312**参数：** 313 314| 参数名 | 类型 | 必填 | 说明 | 315| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 316| customArray | Array<[CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo)> | 是 | 拖拽发起后跟手效果所拖拽的对象。 | 317| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 318 319**返回值：** 320 321| 类型 | 说明 | 322| ------------------------------------------------------ | ------------------ | 323| [DragAction](#dragaction11)| 创建拖拽Action对象，主要用于后面实现注册监听拖拽状态改变事件和启动拖拽服务。 | 324 325**错误码：** 326 327以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 328| 错误码ID | 错误信息 | 329| -------- | ------------- | 330| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 331| 100001 | Internal handling failed. | 332 333**示例：** 334 335> **说明：** 336> 337> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 338 339```ts 340import { dragController } from '@kit.ArkUI'; 341import { image } from '@kit.ImageKit'; 342import { unifiedDataChannel } from '@kit.ArkData'; 343 344@Entry 345@Component 346struct DragControllerPage { 347 @State pixmap: image.PixelMap | null = null 348 @State text: string = '' 349 private dragAction: dragController.DragAction | null = null; 350 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 351 @Builder DraggingBuilder() { 352 Column() { 353 Text("DraggingBuilder") 354 .fontColor(Color.White) 355 .fontSize(12) 356 } 357 .width(100) 358 .height(100) 359 .backgroundColor(Color.Blue) 360 } 361 362 build() { 363 Column() { 364 365 Column() { 366 Text(this.text) 367 .width('100%') 368 .height('100%') 369 .fontColor(Color.White) 370 .fontSize(18) 371 .onDrop((dragEvent?:DragEvent)=>{ 372 if(dragEvent){ 373 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 374 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 375 this.text = plainText.textContent; 376 } 377 }) 378 } 379 .width(100) 380 .height(100) 381 .backgroundColor(Color.Red) 382 .margin(10) 383 384 Button('多对象dragAction customBuilder拖拽').onTouch((event?:TouchEvent) => { 385 if(event){ 386 if (event.type == TouchType.Down) { 387 console.info("multi drag Down by listener"); 388 this.customBuilders.splice(0, this.customBuilders.length); 389 this.customBuilders.push(()=>{this.DraggingBuilder()}); 390 this.customBuilders.push(()=>{this.DraggingBuilder()}); 391 this.customBuilders.push(()=>{this.DraggingBuilder()}); 392 let text = new unifiedDataChannel.PlainText() 393 text.textContent = 'drag text' 394 let unifiedData = new unifiedDataChannel.UnifiedData(text) 395 let dragInfo: dragController.DragInfo = { 396 pointerId: 0, 397 data: unifiedData, 398 extraParams: '' 399 } 400 try{ 401 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口 402 if(!this.dragAction){ 403 console.info("listener dragAction is null"); 404 return 405 } 406 this.dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 407 if (dragAndDropInfo.status == dragController.DragStatus.STARTED) { 408 console.info("drag has start"); 409 } else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){ 410 console.info("drag has end"); 411 if (!this.dragAction) { 412 return 413 } 414 this.dragAction.off('statusChange') 415 } 416 }) 417 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 418 console.error("start drag Error:" + err.message); 419 }) 420 } catch(err) { 421 console.error("create dragAction Error:" + err.message); 422 } 423 } 424 } 425 }).margin({top:20}) 426 } 427 } 428} 429``` 430  431## DragAction<sup>11+</sup> 432 433监听状态改变，启动拖拽服务的对象。 434 435**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 436 437**系统能力：** SystemCapability.ArkUI.ArkUI.Full 438 439### startDrag<sup>11+</sup> 440 441startDrag(): Promise<void> 442 443启动拖拽服务。使用Promise异步回调。 444 445**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 446 447**系统能力：** SystemCapability.ArkUI.ArkUI.Full 448 449**返回值：** 450 451| 类型 | 说明 | 452| -------- | -------- | 453| Promise<void> | Promise对象，无返回结果。 | 454 455**错误码：** 456 457| 错误码ID | 错误信息 | 458| -------- | ------------- | 459| 100001 | Internal handling failed. | 460 461**示例1：** 462 463> **说明：** 464> 465> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 466 467```ts 468import { dragController } from '@kit.ArkUI'; 469import { unifiedDataChannel } from '@kit.ArkData'; 470 471@Entry 472@Component 473struct DragControllerPage { 474 private dragAction: dragController.DragAction | null = null; 475 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 476 @Builder DraggingBuilder() { 477 Column() { 478 Text("DraggingBuilder") 479 .fontColor(Color.White) 480 .fontSize(12) 481 } 482 .width(100) 483 .height(100) 484 .backgroundColor(Color.Blue) 485 } 486 487 build() { 488 Column() { 489 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 490 if(event){ 491 if (event.type == TouchType.Down) { 492 this.customBuilders.splice(0, this.customBuilders.length); 493 this.customBuilders.push(()=>{this.DraggingBuilder()}); 494 let text = new unifiedDataChannel.PlainText() 495 text.textContent = 'drag text' 496 let unifiedData = new unifiedDataChannel.UnifiedData(text) 497 let dragInfo: dragController.DragInfo = { 498 pointerId: 0, 499 data: unifiedData, 500 extraParams: '' 501 } 502 try{ 503 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口 504 if(!this.dragAction){ 505 console.info("listener dragAction is null"); 506 return; 507 } 508 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 509 console.error(`start drag Error: ${err.message}`); 510 }) 511 } catch(err) { 512 console.error(`create dragAction Error: ${err.message}`); 513 } 514 } 515 } 516 }).margin({top:20}) 517 } 518 } 519} 520``` 521 522**示例2：** 523 524在[DragInfo](#draginfo)中配置dataLoadParams，设置拖起方延迟提供数据。 525 526```ts 527import { unifiedDataChannel, uniformTypeDescriptor, uniformDataStruct } from '@kit.ArkData'; 528import { fileUri, fileIo as fs } from '@kit.CoreFileKit'; 529import { common } from '@kit.AbilityKit'; 530import { dragController } from '@kit.ArkUI'; 531 532@Entry 533@Component 534struct ImageExample { 535 private dragAction: dragController.DragAction | null = null; 536 customBuilders: Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 537 @State uri: string = ""; 538 @State blockArr: string[] = []; 539 uiContext = this.getUIContext(); 540 udKey: string = ''; 541 542 @Builder 543 DraggingBuilder() { 544 Video({ src: $rawfile('test1.mp4'), controller: new VideoController() }) 545 .width(100) 546 .height(100) 547 } 548 549 build() { 550 Column() { 551 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center, justifyContent: FlexAlign.SpaceAround }) { 552 Button('touch to execute drag') 553 .margin(10) 554 .onTouch((event?: TouchEvent) => { 555 if (event) { 556 if (event.type == TouchType.Down) { 557 this.customBuilders.splice(0, this.customBuilders.length); 558 this.customBuilders.push(() => { 559 this.DraggingBuilder() 560 }); 561 const context: Context | undefined = this.uiContext.getHostContext(); 562 if (context) { 563 let loadHandler: unifiedDataChannel.DataLoadHandler = () => { 564 let data = 565 context.resourceManager.getRawFdSync('test1.mp4'); 566 let filePath = context.filesDir + '/test1.mp4'; 567 let file = fs.openSync(filePath, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE); 568 let bufferSize = data.length as number; 569 let buf = new ArrayBuffer(bufferSize); 570 fs.readSync(data.fd, buf, { offset: data.offset, length: bufferSize }); 571 fs.writeSync(file.fd, buf, { offset: 0, length: bufferSize }); 572 fs.closeSync(file.fd); 573 context.resourceManager.closeRawFdSync('test1.mp4') 574 this.uri = fileUri.getUriFromPath(filePath); 575 let videoMp: uniformDataStruct.FileUri = { 576 uniformDataType: 'general.file-uri', 577 oriUri: this.uri, 578 fileType: 'general.video', 579 } 580 let unifiedRecord = new unifiedDataChannel.UnifiedRecord(); 581 let unifiedData = new unifiedDataChannel.UnifiedData(); 582 unifiedRecord.addEntry(uniformTypeDescriptor.UniformDataType.FILE_URI, videoMp); 583 unifiedData.addRecord(unifiedRecord); 584 return unifiedData; 585 } 586 587 let dragInfo: dragController.DragInfo = { 588 pointerId: 0, 589 extraParams: '', 590 dataLoadParams: { 591 loadHandler: loadHandler, 592 dataLoadInfo: { types: new Set([uniformTypeDescriptor.UniformDataType.VIDEO]), recordCount: 1 } 593 } 594 } 595 596 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 597 console.info(`ndq Register to listen on drag status ${JSON.stringify(dragAndDropInfo)}`); 598 } 599 try { 600 this.dragAction = this.getUIContext() 601 .getDragController() 602 .createDragAction(this.customBuilders, 603 dragInfo) 604 if (!this.dragAction) { 605 console.info("listener dragAction is null"); 606 return; 607 } 608 this.dragAction.on('statusChange', func); 609 this.dragAction.startDrag().then(() => { 610 }).catch((err: Error) => { 611 console.error(`start drag Error: ${err.message}`); 612 }) 613 } catch (err) { 614 console.error(`create dragAction Error: ${err.message}`); 615 } 616 } 617 } 618 } 619 }) 620 } 621 .margin({ bottom: 20 }) 622 623 Row() { 624 Column() { 625 Text('可释放区域') 626 .fontSize('15dp') 627 .height('10%') 628 List() { 629 ForEach(this.blockArr, (item: string, index) => { 630 ListItem() { 631 Video({ src: item, controller: new VideoController() }) 632 .width(100) 633 .height(100) 634 .border({ width: 1 }) 635 } 636 .margin({ left: 30, top: 30 }) 637 }, (item: string) => item) 638 } 639 .border({ width: 1 }) 640 .height('90%') 641 .width('100%') 642 .allowDrop([uniformTypeDescriptor.UniformDataType.VIDEO]) 643 .onDrop((event?: DragEvent, extraParams?: string) => { 644 let context = this.uiContext.getHostContext() as common.UIAbilityContext; 645 let pathDir: string = context.distributedFilesDir; 646 let destUri = fileUri.getUriFromPath(pathDir); 647 let progressListener: unifiedDataChannel.DataProgressListener = 648 (progress: unifiedDataChannel.ProgressInfo, dragData: UnifiedData | null) => { 649 if (dragData != null) { 650 let arr: Array<unifiedDataChannel.UnifiedRecord> = dragData.getRecords(); 651 if (arr.length > 0) { 652 if (arr[0].getType() === uniformTypeDescriptor.UniformDataType.VIDEO) { 653 this.blockArr.splice(JSON.parse(extraParams as string).insertIndex, 0, this.uri); 654 } 655 } else { 656 console.info('dragData arr is null'); 657 } 658 } else { 659 console.info('dragData is undefined'); 660 } 661 console.info(`percentage: ${progress.progress}`); 662 }; 663 let options: DataSyncOptions = { 664 destUri: destUri, 665 fileConflictOptions: unifiedDataChannel.FileConflictOptions.OVERWRITE, 666 progressIndicator: unifiedDataChannel.ProgressIndicator.DEFAULT, 667 dataProgressListener: progressListener, 668 } 669 try { 670 this.udKey = (event as DragEvent).startDataLoading(options); 671 console.info('udKey: ', this.udKey); 672 } catch (e) { 673 console.error(`startDataLoading errorCode: ${e.code}, errorMessage: ${e.message}`); 674 } 675 }, { disableDataPrefetch: true }) 676 } 677 .height("50%") 678 .width("90%") 679 .border({ width: 1 }) 680 } 681 682 Button('取消数据传输') 683 .onClick(() => { 684 try { 685 this.getUIContext().getDragController().cancelDataLoading(this.udKey); 686 } catch (e) { 687 console.error(`cancelDataLoading errorCode: ${e.code}, errorMessage: ${e.message}`); 688 } 689 }) 690 .margin({ top: 10 }) 691 }.width('100%') 692 } 693} 694``` 695 696 697### on('statusChange')<sup>11+</sup> 698 699on(type: 'statusChange', callback: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 700 701注册监听拖拽状态改变事件。 702 703**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 704 705**系统能力：** SystemCapability.ArkUI.ArkUI.Full 706 707**参数：** 708| 参数名 | 类型 | 必填 | 说明 | 709| ------ | ------ | ------- | ---------------- | 710| type | string | 是 | 监听事件，固定为'statusChange'，即注册监听拖拽状态改变事件。| 711| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | 是 | 回调函数，返回当前的[DragAndDropInfo](#draganddropinfo11)组件状态。| 712 713**示例：** 714 715> **说明：** 716> 717> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 718 719```ts 720import { dragController } from '@kit.ArkUI'; 721import { unifiedDataChannel } from '@kit.ArkData'; 722 723@Entry 724@Component 725struct DragControllerPage { 726 private dragAction: dragController.DragAction | null = null; 727 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 728 @Builder DraggingBuilder() { 729 Column() { 730 Text("DraggingBuilder") 731 .fontColor(Color.White) 732 .fontSize(12) 733 } 734 .width(100) 735 .height(100) 736 .backgroundColor(Color.Blue) 737 } 738 739 build() { 740 Column() { 741 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 742 if(event){ 743 if (event.type == TouchType.Down) { 744 this.customBuilders.splice(0, this.customBuilders.length); 745 this.customBuilders.push(()=>{this.DraggingBuilder()}); 746 let text = new unifiedDataChannel.PlainText() 747 text.textContent = 'drag text' 748 let unifiedData = new unifiedDataChannel.UnifiedData(text) 749 let dragInfo: dragController.DragInfo = { 750 pointerId: 0, 751 data: unifiedData, 752 extraParams: '' 753 } 754 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 755 console.info(`Register to listen on drag status ${JSON.stringify(dragAndDropInfo)}`); 756 } 757 try{ 758 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口 759 if(!this.dragAction){ 760 console.info("listener dragAction is null"); 761 return; 762 } 763 // 监听状态改变，触发后打印func中的日志 764 this.dragAction.on('statusChange', func); 765 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 766 console.error(`start drag Error: ${err.message}`); 767 }) 768 } catch(err) { 769 console.error(`create dragAction Error: ${err.message}`); 770 } 771 } 772 } 773 }).margin({top:20}) 774 } 775 } 776} 777``` 778 779### off('statusChange')<sup>11+</sup> 780 781 off(type: 'statusChange', callback?: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 782 783取消注册监听拖拽状态改变事件。 784 785**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 786 787**系统能力：** SystemCapability.ArkUI.ArkUI.Full 788 789**参数：** 790| 参数名 | 类型 | 必填 | 说明 | 791| ------ | ------ | ------- | ---------------- | 792| type | string | 是 | 监听事件，固定为'statusChange'，即取消监听拖拽状态改变事件。| 793| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | 否 | 回调函数，返回当前的[DragAndDropInfo](#draganddropinfo11)组件状态。| 794 795**示例：** 796 797> **说明：** 798> 799> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 800 801```ts 802import { dragController } from '@kit.ArkUI'; 803import { unifiedDataChannel } from '@kit.ArkData'; 804 805@Entry 806@Component 807struct DragControllerPage { 808 private dragAction: dragController.DragAction | null = null; 809 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 810 @Builder DraggingBuilder() { 811 Column() { 812 Text("DraggingBuilder") 813 .fontColor(Color.White) 814 .fontSize(12) 815 } 816 .width(100) 817 .height(100) 818 .backgroundColor(Color.Blue) 819 } 820 821 build() { 822 Column() { 823 Button('touch to execute drag').onTouch((event?:TouchEvent) => { 824 if(event){ 825 if (event.type == TouchType.Down) { 826 this.customBuilders.splice(0, this.customBuilders.length); 827 this.customBuilders.push(()=>{this.DraggingBuilder()}); 828 let text = new unifiedDataChannel.PlainText() 829 text.textContent = 'drag text' 830 let unifiedData = new unifiedDataChannel.UnifiedData(text) 831 let dragInfo: dragController.DragInfo = { 832 pointerId: 0, 833 data: unifiedData, 834 extraParams: '' 835 } 836 let func = (dragAndDropInfo: dragController.DragAndDropInfo) => { 837 console.info(`Register to listen on drag status ${JSON.stringify(dragAndDropInfo)}`); 838 } 839 this.dragAction = this.getUIContext().getDragController().createDragAction(this.customBuilders, dragInfo) // 建议使用 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 // 取消监听，发起拖拽后不会打印func中的日志 846 this.dragAction.off('statusChange', func); 847 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 848 console.error(`start drag Error: ${err.message}`); 849 }) 850 } 851 } 852 }).margin({top:20}) 853 } 854 } 855} 856``` 857 858## DragAndDropInfo<sup>11+</sup> 859 860拖拽过程中监听到status改变时上报的数据。 861 862**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 863 864**系统能力：** SystemCapability.ArkUI.ArkUI.Full 865 866| 名称 | 类型 | 必填 | 说明 | 867| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 868| status | [DragStatus](#dragstatus11) | 是 | 当前拖拽状态（启动和结束）。 | 869| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent7) | 是 | 当前状态所对应的拖拽事件。通过dragController发起的dragEvent仅支持获取result和behavior，且用于拖拽结束状态。 | 870| extraParams| string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。默认值为空。 | 871 872## DragStatus<sup>11+</sup> 873 874拖拽开始和结束状态。 875 876**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 877 878**系统能力：** SystemCapability.ArkUI.ArkUI.Full 879 880| 名称 | 值 | 说明 | 881| ----------- | ------------------------------------------------------| ---------------------------------------- | 882| STARTED | 0 | 拖拽已成功发起。 | 883| ENDED | 1 | 拖拽结束。 | 884 885## AnimationOptions<sup>11+</sup> 886 887拖拽相关的动效参数。 888 889**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 890 891**系统能力：** SystemCapability.ArkUI.ArkUI.Full 892 893| 名称 | 类型 | 必填 | 说明 | 894| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 895| duration | number | 否 | 动画持续时间，单位为毫秒。<br/>默认值：1000<br/>**说明：**<br/>- 设置小于0的值时按0处理。<br/>- 设置浮点型类型的值时，向下取整。例如，设置值为1.2，按照1处理。| 896| curve | [Curve](arkui-ts/ts-appendix-enums.md#curve) \| [ICurve](js-apis-curve.md#icurve9) | 否 | 设置动画曲线。<br/>默认值：Curve.EaseInOut| | 897 898## DragEventParam<sup>12+</sup> 899 900拖拽结束返回结果的回调。 901 902**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 903 904**系统能力：** SystemCapability.ArkUI.ArkUI.Full 905 906| 名称 | 类型 | 必填 | 说明 | 907| ----------- | ------------------------------------------------------------ | ---- | ------------------------------ | 908| event<sup>10+</sup> | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent7) | 是 | 拖拽事件信息，仅包括拖拽结果。 | 909| extraParams<sup>10+</sup> | string | 是 | 拖拽事件额外信息。 | 910 911## dragController.getDragPreview<sup>(deprecated)</sup> 912 913getDragPreview(): DragPreview 914 915返回一个代表拖拽背板的对象。 916 917> **说明：** 918> 919> 从API version 11开始支持，从API version 18开始废弃，建议使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)获取[DragController](arkts-apis-uicontext-dragcontroller.md)实例，再通过此实例调用替代方法[getDragPreview](arkts-apis-uicontext-dragcontroller.md#getdragpreview11)。 920> 921> 从API version 11开始，可以通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的[DragController](arkts-apis-uicontext-dragcontroller.md)对象。 922 923**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 924 925**系统能力：** SystemCapability.ArkUI.ArkUI.Full 926 927**返回值：** 928 929| 类型 | 说明 | 930| ------------| ------------------------------------------------| 931| [DragPreview](#dragpreview11) | 一个代表拖拽背板的对象，提供背板样式设置的接口，在OnDrop和OnDragEnd回调中使用不生效。 | 932 933**示例：** 934 935请参考[animate](#animate11) 936 937## DragPreview<sup>11+</sup> 938 939拖拽背板的对象，在OnDrop和OnDragEnd回调中使用不生效。 940 941**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 942 943**系统能力：** SystemCapability.ArkUI.ArkUI.Full 944 945### setForegroundColor<sup>11+</sup> 946 947setForegroundColor(color: ResourceColor): void 948 949设置背板蒙版颜色，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](arkts-apis-uicontext-dragcontroller.md#getdragpreview11) 方法获取到的对象上使用。 950 951**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 952 953**系统能力：** SystemCapability.ArkUI.ArkUI.Full 954 955**参数：** 956 957| 参数名 | 类型 | 必填 | 说明 | 958| -------- | -------------------------------- | ---- | ------------------------ | 959| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 是 | 背板蒙版颜色。 | 960 961**示例：** 962 963请参考[animate](#animate11) 964 965### animate<sup>11+</sup> 966 967animate(options: AnimationOptions, handler: () => void): void 968 969设置背板蒙版颜色变化动效，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](arkts-apis-uicontext-dragcontroller.md#getdragpreview11) 方法获取到的对象上使用。 970 971**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 972 973**系统能力：** SystemCapability.ArkUI.ArkUI.Full 974 975**参数：** 976 977| 参数名 | 类型 | 必填 | 说明 | 978| -------- | -------------------------------- | ---- | -----------------------------------| 979| options | [AnimationOptions](#animationoptions11) | 是 | 动效参数。 | 980| handler | () => void | 是 | 用于修改背板蒙版颜色等属性的回调方法。 | 981 982**示例：** 983 984> **说明：** 985> 986> 推荐通过使用[UIContext](arkts-apis-uicontext-uicontext.md)中的[getDragController](arkts-apis-uicontext-uicontext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 987 9881.在EntryAbility.ets中获取UI上下文并保存至LocalStorage中。 989 ```ts 990import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 991import { hilog } from '@kit.PerformanceAnalysisKit'; 992import { window, UIContext } from '@kit.ArkUI'; 993 994let uiContext: UIContext; 995let localStorage: LocalStorage = new LocalStorage('uiContext'); 996 997export default class EntryAbility extends UIAbility { 998 storage: LocalStorage = localStorage; 999 1000 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 1001 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 1002 } 1003 1004 onDestroy(): void { 1005 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 1006 } 1007 1008 onWindowStageCreate(windowStage: window.WindowStage): void { 1009 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 1010 1011 windowStage.loadContent('pages/Index', this.storage, (err, data) => { 1012 if (err.code) { 1013 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', `Code is ${err.code}, message is ${err.message}`); 1014 return; 1015 } 1016 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', `Code is ${err.code}, message is ${err.message}`); 1017 windowStage.getMainWindow((err, data) => { 1018 if (err.code) { 1019 hilog.error(0x0000, `Failed to abtain the main window. Cause: ${err.message}`, ''); 1020 return; 1021 } 1022 uiContext = data.getUIContext(); 1023 this.storage.setOrCreate<UIContext>('uiContext', uiContext); 1024 }) 1025 }); 1026 } 1027} 1028 ``` 10292.在Index.ets中通过this.getUIContext().getSharedLocalStorage()获取UI上下文，进而获取DragController对象实施后续操作。 1030 ```ts 1031 1032import { unifiedDataChannel } from '@kit.ArkData'; 1033import { hilog } from '@kit.PerformanceAnalysisKit'; 1034import { dragController, curves, promptAction, UIContext } from '@kit.ArkUI'; 1035import { image } from '@kit.ImageKit'; 1036import { BusinessError } from '@kit.BasicServicesKit'; 1037 1038class Tmp{ 1039 event:DragEvent|undefined = undefined 1040 extraParams:string = '' 1041} 1042 1043@Entry() 1044@Component 1045struct DragControllerPage { 1046 @State pixmap: image.PixelMap|null = null; 1047 storages = this.getUIContext().getSharedLocalStorage(); 1048 1049 @Builder DraggingBuilder() { 1050 Column() { 1051 Text("DraggingBuilder") 1052 .fontColor(Color.White) 1053 .fontSize(12) 1054 } 1055 .width(100) 1056 .height(100) 1057 .backgroundColor(Color.Blue) 1058 } 1059 1060 @Builder PixmapBuilder() { 1061 Column() { 1062 Text("PixmapBuilder") 1063 } 1064 .width(100) 1065 .height(100) 1066 .backgroundColor(Color.Blue) 1067 } 1068 1069 build() { 1070 Column() { 1071 Button('拖拽至此处') 1072 .margin(10) 1073 .onDragEnter(() => { 1074 try { 1075 let uiContext: UIContext = this.storages?.get<UIContext>('uiContext') as UIContext; 1076 let previewObj: dragController.DragPreview = uiContext.getDragController().getDragPreview(); 1077 let foregroundColor: ResourceColor = Color.Green; 1078 1079 let previewAnimation: dragController.AnimationOptions = { 1080 curve: curves.cubicBezierCurve(0.2,0,0,1), 1081 } 1082 previewObj.animate(previewAnimation, () => { 1083 previewObj.setForegroundColor(foregroundColor); 1084 }); 1085 } catch (error) { 1086 let msg = (error as BusinessError).message; 1087 let code = (error as BusinessError).code; 1088 hilog.error(0x0000, `show error code is ${code}, message is ${msg}`, ''); 1089 } 1090 }) 1091 .onDrop(() => { 1092 this.getUIContext().getPromptAction().showToast({duration: 100, message: 'Drag Success', bottom: 400}) 1093 }) 1094 Button('拖起').onTouch((event?:TouchEvent) => { 1095 if(event){ 1096 if (event.type == TouchType.Down) { 1097 let text = new unifiedDataChannel.Text() 1098 let unifiedData = new unifiedDataChannel.UnifiedData(text) 1099 let dragInfo: dragController.DragInfo = { 1100 pointerId: 0, 1101 data: unifiedData, 1102 extraParams: '' 1103 } 1104 let eve:tmp = new tmp() 1105 this.getUIContext().getDragController().executeDrag(() => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口 1106 this.DraggingBuilder() 1107 }, dragInfo, (err , eve) => { 1108 hilog.info(0x0000, `${JSON.stringify(err)}`, '') 1109 if (eve && eve.event) { 1110 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 1111 hilog.info(0x0000, 'success', ''); 1112 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 1113 hilog.info(0x0000, 'failed', ''); 1114 } 1115 } 1116 }) 1117 } 1118 } 1119 }).margin({top:100}) 1120 } 1121 .width('100%') 1122 .height('100%') 1123 } 1124} 1125 ``` 1126  1127 1128## DragStartRequestStatus<sup>18+</sup> 1129 1130定义应用是否可以发起拖拽的枚举类型。 1131 1132**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1133 1134**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1135 1136| 名称 | 值 | 说明 | 1137| -------- | -- | ------------------------------------------------------------ | 1138| WAITING | 0 | 应用准备数据中，无法发起拖拽。 | 1139| READY | 1 | 应用数据准备完成，可以发起拖拽。 | 1140 1141## DragSpringLoadingState<sup>20+</sup> 1142 1143定义拖拽的悬停检测状态的枚举类型。 1144 1145**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1146 1147**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1148 1149 1150| 名称 | 值|说明 | 1151| ------ | --------------------- |--------------------------------------- | 1152| BEGIN | - |拖拽进入组件范围静止一段时间，被识别被悬停状态。 | 1153| UPDATE | - |拖拽已处于悬停状态，如果继续静止会定期触发UPDATE通知，以检查悬停状态。 | 1154| END | - |如果最后一次UPDATE通知后拖拽继续静止会进入END，整个悬停检测结束。进入END后拖拽需要移出组件范围后再次进入组件或移入组件内子组件才会重新开始悬停检测。 | 1155| CANCEL | - |拖拽进入BEGIN后，在手指/鼠标抬起、切换窗口、息屏、移出组件范围、移入组件内子组件或组件内移动超过检测阈值等场景会触发CANCEL通知，悬停检测中断。 | 1156 1157## DragSpringLoadingConfiguration<sup>20+</sup> 1158 1159定义拖拽的悬停检测配置参数的接口。 1160 1161**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1162 1163**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1164 1165| 名称 | 类型 |只读| 可选 | 说明 | 1166| --------------------- | ------ | ---- | --- | ---------------------------------------------------- | 1167| stillTimeLimit | number | 否 | 是 |进入悬停检测BEGIN状态所需保持静止的时间（ms）。取值范围为[0, 2<sup>31</sup>-1]的整数。输入浮点数时只取整数部分。输入非法值（负数、null、undefined、NaN）时取默认值500。 | 1168| updateInterval | number | 否 | 是 |进入悬停检测UPDATE状态后，更新通知的时间间隔（ms）。取值范围为[0, 2<sup>31</sup>-1]的整数。输入浮点数时只取整数部分。输入非法值（负数、null、undefined、NaN）时取默认值100。| 1169| updateNotifyCount | number | 否 | 是 |进入悬停检测UPDATE状态后，更新通知的最大次数。取值范围为[0, 2<sup>31</sup>-1]的整数。输入浮点数时只取整数部分。输入非法值（负数、null、undefined、NaN）时取默认值3。| 1170| updateToFinishInterval | number | 否 | 是 |从UPDATE状态到END状态的最长等待时间（ms）。取值范围为[0, 2<sup>31</sup>-1]的整数。输入浮点数时只取整数部分。输入非法值（负数、null、undefined、NaN）时取默认值100。 | 1171 1172## SpringLoadingDragInfos<sup>20+</sup> 1173 1174定义触发悬停检测时拖拽事件信息的接口。 1175 1176**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1177 1178**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1179 1180| 名称 | 类型 | 必填 | 说明 | 1181| :-------- | ------- | ---- |--------------------------------------------- | 1182| dataSummary | [unifiedDataChannel.Summary](../apis-arkdata/js-apis-data-unifiedDataChannel.md#summary) |否 | 拖拽数据的摘要，默认为null。 | 1183| extraInfos | string |否 | 拖拽事件额外信息，默认为空字符串。 | 1184 1185## SpringLoadingContext<sup>20+</sup> 1186 1187定义回调上下文信息的类，用于在悬停检测回调中传递给应用程序，使其能访问拖拽状态。 1188 1189### 属性 1190 1191**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1192 1193**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1194 1195| 名称 | 类型 | 只读 |可选 | 说明 | 1196| :----- | -------- | ---- | ---- | ---------------------------------------- | 1197| state | [DragSpringLoadingState](#dragspringloadingstate20) |否 |否 | 当前悬停检测的状态。 | 1198| currentNotifySequence | number |否 |否 |在一次悬停检测流转中的回调通知次数，从0开始。 | 1199| dragInfos | [SpringLoadingDragInfos](#springloadingdraginfos20) |否 |是 | 拖拽信息，为undefined时取[SpringLoadingDragInfos](#springloadingdraginfos20)默认值。 | 1200| currentConfig | [DragSpringLoadingConfiguration](#dragspringloadingconfiguration20) |否 |是 | 当前回调中的配置信息，为undefined时取[DragSpringLoadingConfiguration](#dragspringloadingconfiguration20)默认值。 | 1201 1202### abort<sup>20+</sup> 1203 1204abort(): void 1205 1206终止后续的悬停检测。 1207 1208**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1209 1210**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1211 1212### updateConfiguration<sup>20+</sup> 1213 1214updateConfiguration(config: DragSpringLoadingConfiguration): void 1215 1216更新后续的悬停检测配置。 1217 1218**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 1219 1220**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1221 1222**参数：** 1223 1224| 参数名 | 类型 | 必填 | 说明 | 1225| :----- | -------- | ---- | --------------------------------------------- | 1226| config | [DragSpringLoadingConfiguration](#dragspringloadingconfiguration20) |是 | 悬停检测配置。 |
