1# @ohos.arkui.dragController (DragController) 2 3本模块提供发起主动拖拽的能力，当应用接收到触摸或长按等事件时可以主动发起拖拽的动作，并在其中携带拖拽信息。 4 5> **说明：** 6> 7> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 本模块功能依赖UI的执行上下文，不可在UI上下文不明确的地方使用，参见[UIContext](js-apis-arkui-UIContext.md#uicontext)说明。 9> 从API version 11开始，可以通过使用UIContext中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 10> 示例效果请以真机运行为准，当前 IDE 预览器不支持。 11 12## 导入模块 13 14```ts 15import { dragController } from "@kit.ArkUI"; 16``` 17 18## dragController.executeDrag 19 20executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo,callback:AsyncCallback\<DragEventParam>): void 21 22主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过回调返回结果。 23 24**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 25 26**系统能力：** SystemCapability.ArkUI.ArkUI.Full 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 32| 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的修改不会同步到当前正在拖拽的图片，对builder的修改需要在下一次拖拽时生效。 | 33| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 34| callback | [AsyncCallback](../apis-basic-services-kit/js-apis-base.md#asynccallback)<[DragEventParam](#drageventparam12)> | 是 | 拖拽结束返回结果的回调。 | 35 36**错误码：** 37 38以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 39 40| 错误码ID | 错误信息 | 41| -------- | ------------- | 42| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 43| 100001 | Internal handling failed. | 44 45**示例：** 46 47> **说明：** 48> 49> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 50 51```ts 52import { dragController } from "@kit.ArkUI"; 53import { unifiedDataChannel } from '@kit.ArkData'; 54 55@Entry 56@Component 57struct DragControllerPage { 58 @State text: string = '' 59 60 @Builder DraggingBuilder() { 61 Column() { 62 Text("DraggingBuilder") 63 .fontColor(Color.White) 64 .fontSize(12) 65 } 66 .width(100) 67 .height(100) 68 .backgroundColor(Color.Blue) 69 } 70 71 build() { 72 Column() { 73 Button('touch to execute drag') 74 .margin(10) 75 .onTouch((event?:TouchEvent) => { 76 if(event){ 77 if (event.type == TouchType.Down) { 78 let text = new unifiedDataChannel.PlainText() 79 text.textContent = 'drag text' 80 text.abstract = 'abstract' 81 let unifiedData = new unifiedDataChannel.UnifiedData(text) 82 83 let dragInfo: dragController.DragInfo = { 84 pointerId: 0, 85 data: unifiedData, 86 extraParams: '' 87 } 88 class tmp{ 89 event:DragEvent|undefined = undefined 90 extraParams:string = '' 91 } 92 let eve:tmp = new tmp() 93 dragController.executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口 94 if(eve.event){ 95 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 96 // ... 97 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 98 // ... 99 } 100 } 101 }) 102 } 103 } 104 }) 105 Text(this.text) 106 .height(100) 107 .width(150) 108 .margin({top:20}) 109 .border({color:Color.Black,width:1}) 110 .onDrop((dragEvent?:DragEvent)=>{ 111 if(dragEvent){ 112 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 113 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 114 this.text = plainText.textContent; 115 } 116 }) 117 } 118 .width('100%') 119 .height('100%') 120 } 121} 122``` 123  124## dragController.executeDrag 125 126executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise\<DragEventParam> 127 128主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过Promise返回结果。 129 130**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 131 132**系统能力：** SystemCapability.ArkUI.ArkUI.Full 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 138| custom | [CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明) | 是 | 拖拽发起后跟手效果所拖拽的对象。 | 139| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 140 141**返回值：** 142 143| 类型 | 说明 | 144| -------------------------------------------------- | ------------------------ | 145| Promise<[DragEventParam](#drageventparam12)> | 拖拽结束返回结果的回调。 | 146 147**错误码：** 148以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 149| 错误码ID | 错误信息 | 150| -------- | ------------- | 151| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 152| 100001 | Internal handling failed. | 153 154**示例：** 155 156> **说明：** 157> 158> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 159 160```ts 161import { dragController, componentSnapshot } from "@kit.ArkUI" 162import { image } from '@kit.ImageKit'; 163import { unifiedDataChannel } from '@kit.ArkData'; 164 165@Entry 166@Component 167struct DragControllerPage { 168 @State pixmap: image.PixelMap|undefined = undefined 169 @State text: string = '' 170 171 @Builder DraggingBuilder() { 172 Column() { 173 Text("DraggingBuilder") 174 .fontColor(Color.White) 175 } 176 .width(100) 177 .height(100) 178 .backgroundColor(Color.Blue) 179 } 180 181 @Builder PixmapBuilder() { 182 Column() { 183 Text("PixmapBuilder") 184 .fontColor(Color.White) 185 .fontSize(15) 186 } 187 .width(100) 188 .height(100) 189 .backgroundColor(Color.Blue) 190 } 191 192 aboutToAppear() { 193 let pb: CustomBuilder = (): void => { 194 this.PixmapBuilder() 195 } 196 componentSnapshot.createFromBuilder(pb).then((pix: image.PixelMap) => { 197 this.pixmap = pix; 198 }) 199 } 200 201 build() { 202 Column() { 203 Button('touch to execute drag') 204 .margin(10) 205 .onTouch((event?:TouchEvent) => { 206 if(event){ 207 if (event.type == TouchType.Down) { 208 let text = new unifiedDataChannel.PlainText() 209 text.textContent = 'drag text' 210 text.abstract = 'abstract' 211 let unifiedData = new unifiedDataChannel.UnifiedData(text) 212 213 let dragInfo: dragController.DragInfo = { 214 pointerId: 0, 215 data: unifiedData, 216 extraParams: '' 217 } 218 let dragItemInfo: DragItemInfo = { 219 pixelMap: this.pixmap, 220 builder: ()=>{this.DraggingBuilder()}, 221 extraInfo: "DragItemInfoTest" 222 } 223 224 class tmp{ 225 event:DragResult|undefined = undefined 226 extraParams:string = '' 227 } 228 let eve:tmp = new tmp() 229 dragController.executeDrag(dragItemInfo, dragInfo) // 建议使用 this.getUIContext().getDragController().executeDrag()接口 230 .then((eve) => { 231 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 232 // ... 233 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 234 // ... 235 } 236 }) 237 .catch((err:Error) => { 238 }) 239 } 240 } 241 }) 242 Text(this.text) 243 .height(100) 244 .width(150) 245 .margin({top:20}) 246 .border({color:Color.Black,width:1}) 247 .onDrop((dragEvent?:DragEvent)=>{ 248 if(dragEvent){ 249 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 250 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 251 this.text = plainText.textContent; 252 } 253 }) 254 } 255 .width('100%') 256 .height('100%') 257 } 258} 259``` 260  261## DragInfo 262 263**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 264 265**系统能力：** SystemCapability.ArkUI.ArkUI.Full 266 267发起拖拽所需要的属性和拖拽时携带的信息。 268 269| 名称 | 类型 | 必填 | 说明 | 270| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 271| pointerId | number | 是 | 设置启动拖拽时屏幕上触摸点的Id。 | 272| data | [unifiedDataChannel.UnifiedData](../apis-arkdata/js-apis-data-unifiedDataChannel.md#unifieddata) | 否 | 设置拖拽过程中携带的数据。 | 273| extraParams | string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。 | 274| touchPoint<sup>11+</sup> | [TouchPoint](arkui-ts/ts-types.md#touchpoint11) | 否 | 配置跟手点坐标，不配置时，默认居中。 | 275| previewOptions<sup>11+</sup>| [DragPreviewOptions](arkui-ts/ts-universal-attributes-drag-drop.md#dragpreviewoptions11) | 否 | 拖拽背板自定义配置。 | 276 277## dragController.createDragAction<sup>11+</sup> 278 279createDragAction(customArray: Array<CustomBuilder \| DragItemInfo>, dragInfo: DragInfo): DragAction 280 281创建拖拽的Action对象，需要显式指定拖拽背板图(可多个)，以及拖拽的数据，跟手点等信息；当通过一个已创建的 Action 对象发起的拖拽未结束时，无法再次创建新的 Action 对象，接口会抛出异常；当Action对象的生命周期结束后，注册在该对象上的回调函数会失效，因此需要在一个尽量长的作用域下持有该对象，并在每次发起拖拽前通过createDragAction返回新的对象覆盖旧值。 282 283**说明：** 建议控制传递的拖拽背板数量，传递过多容易导致拖起的效率问题。 284 285**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 286 287**系统能力：** SystemCapability.ArkUI.ArkUI.Full 288 289**参数：** 290 291| 参数名 | 类型 | 必填 | 说明 | 292| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 293| customArray | Array<[CustomBuilder](arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明)> | 是 | 拖拽发起后跟手效果所拖拽的对象。 | 294| dragInfo | [DragInfo](#draginfo) | 是 | 拖拽信息。 | 295 296**返回值：** 297 298| 类型 | 说明 | 299| ------------------------------------------------------ | ------------------ | 300| [DragAction](#dragaction11)| 创建拖拽Action对象，主要用于后面实现注册监听拖拽状态改变事件和启动拖拽服务。 | 301 302**错误码：** 303 304以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)错误码。 305| 错误码ID | 错误信息 | 306| -------- | ------------- | 307| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 308| 100001 | Internal handling failed. | 309 310**示例：** 311 312> **说明：** 313> 314> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 315 316```ts 317import { dragController, componentSnapshot } from "@kit.ArkUI"; 318import { image } from '@kit.ImageKit'; 319import { unifiedDataChannel } from '@kit.ArkData'; 320 321@Entry 322@Component 323struct DragControllerPage { 324 @State pixmap: image.PixelMap | null = null 325 @State text: string = '' 326 private dragAction: dragController.DragAction | null = null; 327 customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 328 @Builder DraggingBuilder() { 329 Column() { 330 Text("DraggingBuilder") 331 .fontColor(Color.White) 332 .fontSize(12) 333 } 334 .width(100) 335 .height(100) 336 .backgroundColor(Color.Blue) 337 } 338 339 build() { 340 Column() { 341 342 Column() { 343 Text(this.text) 344 .width('100%') 345 .height('100%') 346 .fontColor(Color.White) 347 .fontSize(18) 348 .onDrop((dragEvent?:DragEvent)=>{ 349 if(dragEvent){ 350 let records: Array<unifiedDataChannel.UnifiedRecord> = dragEvent.getData().getRecords(); 351 let plainText: unifiedDataChannel.PlainText = records[0] as unifiedDataChannel.PlainText; 352 this.text = plainText.textContent; 353 } 354 }) 355 } 356 .width(100) 357 .height(100) 358 .backgroundColor(Color.Red) 359 .margin(10) 360 361 Button('多对象dragAction customBuilder拖拽').onTouch((event?:TouchEvent) => { 362 if(event){ 363 if (event.type == TouchType.Down) { 364 console.info("muti drag Down by listener"); 365 this.customBuilders.splice(0, this.customBuilders.length); 366 this.customBuilders.push(()=>{this.DraggingBuilder()}); 367 this.customBuilders.push(()=>{this.DraggingBuilder()}); 368 this.customBuilders.push(()=>{this.DraggingBuilder()}); 369 let text = new unifiedDataChannel.PlainText() 370 text.textContent = 'drag text' 371 let unifiedData = new unifiedDataChannel.UnifiedData(text) 372 let dragInfo: dragController.DragInfo = { 373 pointerId: 0, 374 data: unifiedData, 375 extraParams: '' 376 } 377 try{ 378 this.dragAction = dragController.createDragAction(this.customBuilders, dragInfo) // 建议使用 this.getUIContext().getDragController().createDragAction()接口 379 if(!this.dragAction){ 380 console.info("listener dragAction is null"); 381 return 382 } 383 this.dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 384 if (dragAndDropInfo.status == dragController.DragStatus.STARTED) { 385 console.info("drag has start"); 386 } else if (dragAndDropInfo.status == dragController.DragStatus.ENDED){ 387 console.info("drag has end"); 388 if (!this.dragAction) { 389 return 390 } 391 this.dragAction.off('statusChange') 392 } 393 }) 394 this.dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 395 console.info("start drag Error:" + err.message); 396 }) 397 } catch(err) { 398 console.info("create dragAction Error:" + err.message); 399 } 400 } 401 } 402 }).margin({top:20}) 403 } 404 } 405} 406``` 407  408## DragAction<sup>11+</sup> 409 410监听状态改变，启动拖拽服务的对象。 411 412**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 413 414**系统能力：** SystemCapability.ArkUI.ArkUI.Full 415 416### startDrag<sup>11+</sup> 417 418startDrag(): Promise<void> 419 420启动拖拽服务，返回Promise对象，回调启动成功和失败的结果。 421 422**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 423 424**系统能力：** SystemCapability.ArkUI.ArkUI.Full 425 426**错误码：** 427 428| 错误码ID | 错误信息 | 429| -------- | ------------- | 430| 100001 | Internal handling failed. | 431 432**示例：** 433 434> **说明：** 435> 436> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 437 438```ts 439import { dragController } from "@kit.ArkUI" 440import { unifiedDataChannel } from '@kit.ArkData'; 441 442@Entry 443@Component 444struct DragControllerPage { 445 build() { 446 Column() { 447 Button('touch to execute drag') 448 .onTouch((event?:TouchEvent) => { 449 let customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 450 let text = new unifiedDataChannel.Text() 451 let unifiedData = new unifiedDataChannel.UnifiedData(text) 452 let dragInfo: dragController.DragInfo = { 453 pointerId: 0, 454 data: unifiedData, 455 extraParams: '' 456 } 457 try { 458 let dragAction: dragController.DragAction | null = dragController.createDragAction(customBuilders, dragInfo); // 建议使用 this.getUIContext().getDragController().createDragAction()接口 459 if(!dragAction){ 460 console.info("listener dragAction is null"); 461 return 462 } 463 dragAction.startDrag().then(()=>{}).catch((err:Error)=>{ 464 console.info("start drag Error:" + err.message); 465 }) 466 } catch (err) { 467 console.info("create dragAction Error:" + err.message); 468 } 469 }) 470 } 471 } 472} 473 474``` 475 476### on('statusChange')<sup>11+</sup> 477 478on(type: 'statusChange', callback: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 479 480注册监听拖拽状态改变事件。 481 482**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 483 484**系统能力：** SystemCapability.ArkUI.ArkUI.Full 485 486**参数：** 487| 参数名 | 类型 | 必填 | 说明 | 488| ------ | ------ | ------- | ---------------- | 489| type | string | 是 | 监听事件，固定为'statusChange'，即注册监听拖拽状态改变事件。| 490| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | 是 | 回调函数，返回当前的[DragAndDropInfo](#draganddropinfo11)组件状态。| 491 492**示例：** 493 494> **说明：** 495> 496> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 497 498```ts 499import { dragController } from "@kit.ArkUI"; 500import { unifiedDataChannel } from '@kit.ArkData'; 501 502@Entry 503@Component 504struct DragControllerPage { 505 build() { 506 Column() { 507 Button('touch to execute drag') 508 .onTouch((event?:TouchEvent) => { 509 let customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 510 let text = new unifiedDataChannel.Text() 511 let unifiedData = new unifiedDataChannel.UnifiedData(text) 512 let dragInfo: dragController.DragInfo = { 513 pointerId: 0, 514 data: unifiedData, 515 extraParams: '' 516 } 517 try{ 518 let dragAction: dragController.DragAction | null = dragController.createDragAction(customBuilders, dragInfo); // 建议使用 this.getUIContext().getDragController().createDragAction()接口 519 if(!dragAction){ 520 console.info("listener dragAction is null"); 521 return 522 } 523 dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 524 console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo)); 525 }) 526 }catch(err) { 527 console.info("create dragAction Error:" + err.message); 528 } 529 }) 530 } 531 } 532} 533``` 534 535### off('statusChange')<sup>11+</sup> 536 537 off(type: 'statusChange', callback?: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 538 539取消注册监听拖拽状态改变事件。 540 541**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 542 543**系统能力：** SystemCapability.ArkUI.ArkUI.Full 544 545**参数：** 546| 参数名 | 类型 | 必填 | 说明 | 547| ------ | ------ | ------- | ---------------- | 548| type | string | 是 | 监听事件，固定为'statusChange'，即取消监听拖拽状态改变事件。| 549| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | 否 | 回调函数，返回当前的[DragAndDropInfo](#draganddropinfo11)组件状态， 不设置取消所有监听。| 550 551**示例：** 552 553> **说明：** 554> 555> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 556 557```ts 558import { dragController } from "@kit.ArkUI" 559import { unifiedDataChannel } from '@kit.ArkData'; 560 561@Entry 562@Component 563struct DragControllerPage { 564 build() { 565 Column() { 566 Button('touch to execute drag') 567 .onTouch((event?:TouchEvent) => { 568 let customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 569 let text = new unifiedDataChannel.Text() 570 let unifiedData = new unifiedDataChannel.UnifiedData(text) 571 let dragInfo: dragController.DragInfo = { 572 pointerId: 0, 573 data: unifiedData, 574 extraParams: '' 575 } 576 try{ 577 let dragAction: dragController.DragAction | null = dragController.createDragAction(customBuilders, dragInfo); // 建议使用 this.getUIContext().getDragController().createDragAction()接口 578 if(!dragAction){ 579 console.info("listener dragAction is null"); 580 return 581 } 582 dragAction.off('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 583 console.info("Cancel listening on drag status", JSON.stringify(dragAndDropInfo)); 584 }) 585 }catch(err) { 586 console.info("create dragAction Error:" + err.message); 587 } 588 }) 589 } 590 } 591} 592``` 593 594## DragAndDropInfo<sup>11+</sup> 595 596**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 597 598**系统能力：** SystemCapability.ArkUI.ArkUI.Full 599 600拖拽过程中监听到status改变时上报的数据。 601 602| 名称 | 类型 | 必填 | 说明 | 603| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 604| status | [DragStatus](#dragstatus11) | 是 | 当前拖拽状态（启动和结束）。 | 605| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent) | 是 | 当前状态所对应的拖拽事件。 | 606| extraParams| string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。 | 607 608## DragStatus<sup>11+</sup> 609 610**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 611 612**系统能力：** SystemCapability.ArkUI.ArkUI.Full 613 614拖拽开始和结束状态。 615 616| 名称 | 值 | 说明 | 617| ----------- | ------------------------------------------------------| ---------------------------------------- | 618| STARTED | 0 | 拖拽已成功发起。 | 619| ENDED | 1 | 拖拽结束。 | 620 621## AnimationOptions<sup>11+</sup> 622 623**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 624 625**系统能力：** SystemCapability.ArkUI.ArkUI.Full 626 627发起拖拽所需要的属性和拖拽时携带的信息。 628 629| 名称 | 类型 | 必填 | 说明 | 630| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 631| duration | number | 否 | 动画持续时间，单位为毫秒。<br/>默认值：1000<br/>**说明：**<br/>- 设置小于0的值时按0处理。<br/>- 设置浮点型类型的值时，向下取整。例如，设置值为1.2，按照1处理。| 632| curve | [Curve](arkui-ts/ts-appendix-enums.md#curve) \| [ICurve](js-apis-curve.md#icurve) | 否 | 设置动画曲线。<br/>默认值：Curve.EaseInOut| | 633 634## DragEventParam<sup>12+</sup> 635 636**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 637 638**系统能力：** SystemCapability.ArkUI.ArkUI.Full 639 640拖拽结束返回结果的回调。 641 642| 名称 | 类型 | 必填 | 说明 | 643| ----------- | ------------------------------------------------------------ | ---- | ------------------------------ | 644| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent) | 是 | 拖拽事件信息，仅包括拖拽结果。 | 645| extraParams | string | 是 | 拖拽事件额外信息。 | 646 647## dragController.getDragPreview<sup>11+</sup> 648 649getDragPreview(): DragPreview 650 651返回一个代表拖拽背板的对象。 652 653**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 654 655**系统能力：** SystemCapability.ArkUI.ArkUI.Full 656 657**返回值：** 658 659| 类型 | 说明 | 660| ------------| ------------------------------------------------| 661| [DragPreview](#dragpreview11) | 一个代表拖拽背板的对象，提供背板样式设置的接口，在OnDrop和OnDragEnd回调中使用不生效。 | 662 663**示例：** 664 665请参考[animate](#animate11) 666 667## DragPreview<sup>11+</sup> 668 669拖拽背板的对象，在OnDrop和OnDragEnd回调中使用不生效。 670 671**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 672 673**系统能力：** SystemCapability.ArkUI.ArkUI.Full 674 675### setForegroundColor<sup>11+</sup> 676 677setForegroundColor(color: ResourceColor): void 678 679设置背板蒙版颜色，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](js-apis-arkui-UIContext.md#getdragpreview11) 方法获取到的对象上使用。 680 681**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 682 683**系统能力：** SystemCapability.ArkUI.ArkUI.Full 684 685**参数：** 686 687| 参数名 | 类型 | 必填 | 说明 | 688| -------- | -------------------------------- | ---- | ------------------------ | 689| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 是 | 背板蒙版颜色。 | 690 691**示例：** 692 693请参考[animate](#animate11) 694 695 ### animate<sup>11+</sup> 696 697animate(options: AnimationOptions, handler: () => void): void 698 699设置背板蒙版颜色变化动效，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](js-apis-arkui-UIContext.md#getdragpreview11) 方法获取到的对象上使用。 700 701**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 702 703**系统能力：** SystemCapability.ArkUI.ArkUI.Full 704 705**参数：** 706 707| 参数名 | 类型 | 必填 | 说明 | 708| -------- | -------------------------------- | ---- | -----------------------------------| 709| options | [AnimationOptions](#animationoptions11) | 是 | 动效参数 | 710| handler | () => void | 是 | 用于修改背板蒙版颜色等属性的回调方法。 | 711 712**示例：** 713 714> **说明：** 715> 716> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 717 7181.在EntryAbility.ets中获取UI上下文并保存至LocalStorage中。 719 ```ts 720import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 721import { hilog } from '@kit.PerformanceAnalysisKit'; 722import { window, UIContext } from '@kit.ArkUI'; 723 724let uiContext: UIContext; 725let localStorage: LocalStorage = new LocalStorage('uiContext'); 726 727export default class EntryAbility extends UIAbility { 728 storage: LocalStorage = localStorage; 729 730 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 731 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 732 } 733 734 onDestroy(): void { 735 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 736 } 737 738 onWindowStageCreate(windowStage: window.WindowStage): void { 739 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 740 741 windowStage.loadContent('pages/Index', (err, data) => { 742 if (err.code) { 743 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 744 return; 745 } 746 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? ''); 747 windowStage.getMainWindow((err, data) => { 748 if (err.code) { 749 hilog.error(0x0000, 'Failed to abtain the main window. Cause:' + err.message, ''); 750 return; 751 } 752 let windowClass: window.Window = data; 753 uiContext = windowClass.getUIContext(); 754 this.storage.setOrCreate<UIContext>('uiContext', uiContext); 755 }) 756 }); 757 } 758} 759 ``` 7602.在Index.ets中通过LocalStorage.getShared()获取UI上下文，进而获取DragController对象实施后续操作。 761 ```ts 762 763import { unifiedDataChannel } from '@kit.ArkData'; 764import { hilog } from '@kit.PerformanceAnalysisKit'; 765import { dragController, curves, promptAction, UIContext } from "@kit.ArkUI"; 766import { image } from '@kit.ImageKit'; 767import { BusinessError } from '@kit.BasicServicesKit'; 768 769let storages = LocalStorage.getShared(); 770 771@Entry(storages) 772@Component 773struct DragControllerPage { 774 @State pixmap: image.PixelMap|null = null 775 776 @Builder DraggingBuilder() { 777 Column() { 778 Text("DraggingBuilder") 779 .fontColor(Color.White) 780 .fontSize(12) 781 } 782 .width(100) 783 .height(100) 784 .backgroundColor(Color.Blue) 785 } 786 787 @Builder PixmapBuilder() { 788 Column() { 789 Text("PixmapBuilder") 790 } 791 .width(100) 792 .height(100) 793 .backgroundColor(Color.Blue) 794 } 795 796 build() { 797 Column() { 798 Button('拖拽至此处') 799 .margin(10) 800 .onDragEnter(() => { 801 try { 802 let uiContext: UIContext = storages.get<UIContext>('uiContext') as UIContext; 803 let previewObj: dragController.DragPreview = uiContext.getDragController().getDragPreview(); 804 let foregroundColor: ResourceColor = Color.Green; 805 806 let previewAnimation: dragController.AnimationOptions = { 807 curve: curves.cubicBezierCurve(0.2,0,0,1), 808 } 809 previewObj.animate(previewAnimation, () => { 810 previewObj.setForegroundColor(foregroundColor); 811 }); 812 } catch (error) { 813 let msg = (error as BusinessError).message; 814 let code = (error as BusinessError).code; 815 hilog.error(0x0000, `show error code is ${code}, message is ${msg}`, ''); 816 } 817 }) 818 .onDrop(() => { 819 promptAction.showToast({duration: 100, message: 'Drag Success', bottom: 400}) 820 }) 821 Button('拖起').onTouch((event?:TouchEvent) => { 822 if(event){ 823 if (event.type == TouchType.Down) { 824 let text = new unifiedDataChannel.Text() 825 let unifiedData = new unifiedDataChannel.UnifiedData(text) 826 let dragInfo: dragController.DragInfo = { 827 pointerId: 0, 828 data: unifiedData, 829 extraParams: '' 830 } 831 class tmp{ 832 event:DragEvent|undefined = undefined 833 extraParams:string = '' 834 } 835 let eve:tmp = new tmp() 836 dragController.executeDrag(() => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口 837 this.DraggingBuilder() 838 }, dragInfo, (err , eve) => { 839 hilog.info(0x0000, `ljx ${JSON.stringify(err)}`, '') 840 if (eve && eve.event) { 841 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 842 hilog.info(0x0000, 'success', ''); 843 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 844 hilog.info(0x0000, 'failed', ''); 845 } 846 } 847 }) 848 } 849 } 850 }).margin({top:100}) 851 } 852 .width('100%') 853 .height('100%') 854 } 855} 856 ``` 857 
