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) | 否 | 配置跟手点坐标。不配置时，左右居中，顶部向下偏移20%。 | 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 if (event && event.type == TouchType.Down) { 510 let customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 511 customBuilders.push(()=>{}); 512 let text = new unifiedDataChannel.Text() 513 let unifiedData = new unifiedDataChannel.UnifiedData(text) 514 let dragInfo: dragController.DragInfo = { 515 pointerId: 0, 516 data: unifiedData, 517 extraParams: '' 518 } 519 try{ 520 let dragAction: dragController.DragAction | null = dragController.createDragAction(customBuilders, dragInfo); // 建议使用 this.getUIContext().getDragController().createDragAction()接口 521 if(!dragAction){ 522 console.info("listener dragAction is null"); 523 return 524 } 525 dragAction.on('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 526 console.info("Register to listen on drag status", JSON.stringify(dragAndDropInfo)); 527 }) 528 }catch(err) { 529 console.info("create dragAction Error:" + err.message); 530 } 531 } 532 }) 533 } 534 } 535} 536``` 537 538### off('statusChange')<sup>11+</sup> 539 540 off(type: 'statusChange', callback?: Callback<[DragAndDropInfo](#draganddropinfo11)>): void 541 542取消注册监听拖拽状态改变事件。 543 544**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 545 546**系统能力：** SystemCapability.ArkUI.ArkUI.Full 547 548**参数：** 549| 参数名 | 类型 | 必填 | 说明 | 550| ------ | ------ | ------- | ---------------- | 551| type | string | 是 | 监听事件，固定为'statusChange'，即取消监听拖拽状态改变事件。| 552| callback | Callback<[DragAndDropInfo](#draganddropinfo11)> | 否 | 回调函数，取消注册了该回调函数的事件， 不设置取消所有监听。| 553 554**示例：** 555 556> **说明：** 557> 558> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 559 560```ts 561import { dragController } from "@kit.ArkUI" 562import { unifiedDataChannel } from '@kit.ArkData'; 563 564@Entry 565@Component 566struct DragControllerPage { 567 build() { 568 Column() { 569 Button('touch to execute drag') 570 .onTouch((event?:TouchEvent) => { 571 if (event && event.type == TouchType.Down) { 572 let customBuilders:Array<CustomBuilder | DragItemInfo> = new Array<CustomBuilder | DragItemInfo>(); 573 customBuilders.push(()=>{}); 574 let text = new unifiedDataChannel.Text() 575 let unifiedData = new unifiedDataChannel.UnifiedData(text) 576 let dragInfo: dragController.DragInfo = { 577 pointerId: 0, 578 data: unifiedData, 579 extraParams: '' 580 } 581 try{ 582 let dragAction: dragController.DragAction | null = dragController.createDragAction(customBuilders, dragInfo); // 建议使用 this.getUIContext().getDragController().createDragAction()接口 583 if(!dragAction){ 584 console.info("listener dragAction is null"); 585 return 586 } 587 dragAction.off('statusChange', (dragAndDropInfo: dragController.DragAndDropInfo)=>{ 588 console.info("Cancel listening on drag status", JSON.stringify(dragAndDropInfo)); 589 }) 590 }catch(err) { 591 console.info("create dragAction Error:" + err.message); 592 } 593 } 594 }) 595 } 596 } 597} 598``` 599 600## DragAndDropInfo<sup>11+</sup> 601 602**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 603 604**系统能力：** SystemCapability.ArkUI.ArkUI.Full 605 606拖拽过程中监听到status改变时上报的数据。 607 608| 名称 | 类型 | 必填 | 说明 | 609| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 610| status | [DragStatus](#dragstatus11) | 是 | 当前拖拽状态（启动和结束）。 | 611| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent) | 是 | 当前状态所对应的拖拽事件。通过dragController发起的dragEvent仅支持获取result和behavior，且用于拖拽结束状态。 | 612| extraParams| string | 否 | 设置拖拽事件额外信息，具体功能暂未实现。 | 613 614## DragStatus<sup>11+</sup> 615 616**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 617 618**系统能力：** SystemCapability.ArkUI.ArkUI.Full 619 620拖拽开始和结束状态。 621 622| 名称 | 值 | 说明 | 623| ----------- | ------------------------------------------------------| ---------------------------------------- | 624| STARTED | 0 | 拖拽已成功发起。 | 625| ENDED | 1 | 拖拽结束。 | 626 627## AnimationOptions<sup>11+</sup> 628 629**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 630 631**系统能力：** SystemCapability.ArkUI.ArkUI.Full 632 633发起拖拽所需要的属性和拖拽时携带的信息。 634 635| 名称 | 类型 | 必填 | 说明 | 636| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 637| duration | number | 否 | 动画持续时间，单位为毫秒。<br/>默认值：1000<br/>**说明：**<br/>- 设置小于0的值时按0处理。<br/>- 设置浮点型类型的值时，向下取整。例如，设置值为1.2，按照1处理。| 638| curve | [Curve](arkui-ts/ts-appendix-enums.md#curve) \| [ICurve](js-apis-curve.md#icurve) | 否 | 设置动画曲线。<br/>默认值：Curve.EaseInOut| | 639 640## DragEventParam<sup>12+</sup> 641 642**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 643 644**系统能力：** SystemCapability.ArkUI.ArkUI.Full 645 646拖拽结束返回结果的回调。 647 648| 名称 | 类型 | 必填 | 说明 | 649| ----------- | ------------------------------------------------------------ | ---- | ------------------------------ | 650| event | [DragEvent](arkui-ts/ts-universal-events-drag-drop.md#dragevent) | 是 | 拖拽事件信息，仅包括拖拽结果。 | 651| extraParams | string | 是 | 拖拽事件额外信息。 | 652 653## dragController.getDragPreview<sup>11+</sup> 654 655getDragPreview(): DragPreview 656 657返回一个代表拖拽背板的对象。 658 659**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 660 661**系统能力：** SystemCapability.ArkUI.ArkUI.Full 662 663**返回值：** 664 665| 类型 | 说明 | 666| ------------| ------------------------------------------------| 667| [DragPreview](#dragpreview11) | 一个代表拖拽背板的对象，提供背板样式设置的接口，在OnDrop和OnDragEnd回调中使用不生效。 | 668 669**示例：** 670 671请参考[animate](#animate11) 672 673## DragPreview<sup>11+</sup> 674 675拖拽背板的对象，在OnDrop和OnDragEnd回调中使用不生效。 676 677**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 678 679**系统能力：** SystemCapability.ArkUI.ArkUI.Full 680 681### setForegroundColor<sup>11+</sup> 682 683setForegroundColor(color: ResourceColor): void 684 685设置背板蒙版颜色，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](js-apis-arkui-UIContext.md#getdragpreview11) 方法获取到的对象上使用。 686 687**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 688 689**系统能力：** SystemCapability.ArkUI.ArkUI.Full 690 691**参数：** 692 693| 参数名 | 类型 | 必填 | 说明 | 694| -------- | -------------------------------- | ---- | ------------------------ | 695| color | [ResourceColor](arkui-ts/ts-types.md#resourcecolor) | 是 | 背板蒙版颜色。 | 696 697**示例：** 698 699请参考[animate](#animate11) 700 701 ### animate<sup>11+</sup> 702 703animate(options: AnimationOptions, handler: () => void): void 704 705设置背板蒙版颜色变化动效，在OnDrop和OnDragEnd回调中使用不生效，仅支持通过 [getDragPreview()](js-apis-arkui-UIContext.md#getdragpreview11) 方法获取到的对象上使用。 706 707**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 708 709**系统能力：** SystemCapability.ArkUI.ArkUI.Full 710 711**参数：** 712 713| 参数名 | 类型 | 必填 | 说明 | 714| -------- | -------------------------------- | ---- | -----------------------------------| 715| options | [AnimationOptions](#animationoptions11) | 是 | 动效参数。 | 716| handler | () => void | 是 | 用于修改背板蒙版颜色等属性的回调方法。 | 717 718**示例：** 719 720> **说明：** 721> 722> 推荐通过使用[UIContext](js-apis-arkui-UIContext.md#uicontext)中的[getDragController](js-apis-arkui-UIContext.md#getdragcontroller11)方法获取当前UI上下文关联的DragController对象。 723 7241.在EntryAbility.ets中获取UI上下文并保存至LocalStorage中。 725 ```ts 726import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'; 727import { hilog } from '@kit.PerformanceAnalysisKit'; 728import { window, UIContext } from '@kit.ArkUI'; 729 730let uiContext: UIContext; 731let localStorage: LocalStorage = new LocalStorage('uiContext'); 732 733export default class EntryAbility extends UIAbility { 734 storage: LocalStorage = localStorage; 735 736 onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { 737 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate'); 738 } 739 740 onDestroy(): void { 741 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy'); 742 } 743 744 onWindowStageCreate(windowStage: window.WindowStage): void { 745 hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate'); 746 747 windowStage.loadContent('pages/Index', (err, data) => { 748 if (err.code) { 749 hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? ''); 750 return; 751 } 752 hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? ''); 753 windowStage.getMainWindow((err, data) => { 754 if (err.code) { 755 hilog.error(0x0000, 'Failed to abtain the main window. Cause:' + err.message, ''); 756 return; 757 } 758 let windowClass: window.Window = data; 759 uiContext = windowClass.getUIContext(); 760 this.storage.setOrCreate<UIContext>('uiContext', uiContext); 761 }) 762 }); 763 } 764} 765 ``` 7662.在Index.ets中通过LocalStorage.getShared()获取UI上下文，进而获取DragController对象实施后续操作。 767 ```ts 768 769import { unifiedDataChannel } from '@kit.ArkData'; 770import { hilog } from '@kit.PerformanceAnalysisKit'; 771import { dragController, curves, promptAction, UIContext } from "@kit.ArkUI"; 772import { image } from '@kit.ImageKit'; 773import { BusinessError } from '@kit.BasicServicesKit'; 774 775let storages = LocalStorage.getShared(); 776 777@Entry(storages) 778@Component 779struct DragControllerPage { 780 @State pixmap: image.PixelMap|null = null 781 782 @Builder DraggingBuilder() { 783 Column() { 784 Text("DraggingBuilder") 785 .fontColor(Color.White) 786 .fontSize(12) 787 } 788 .width(100) 789 .height(100) 790 .backgroundColor(Color.Blue) 791 } 792 793 @Builder PixmapBuilder() { 794 Column() { 795 Text("PixmapBuilder") 796 } 797 .width(100) 798 .height(100) 799 .backgroundColor(Color.Blue) 800 } 801 802 build() { 803 Column() { 804 Button('拖拽至此处') 805 .margin(10) 806 .onDragEnter(() => { 807 try { 808 let uiContext: UIContext = storages.get<UIContext>('uiContext') as UIContext; 809 let previewObj: dragController.DragPreview = uiContext.getDragController().getDragPreview(); 810 let foregroundColor: ResourceColor = Color.Green; 811 812 let previewAnimation: dragController.AnimationOptions = { 813 curve: curves.cubicBezierCurve(0.2,0,0,1), 814 } 815 previewObj.animate(previewAnimation, () => { 816 previewObj.setForegroundColor(foregroundColor); 817 }); 818 } catch (error) { 819 let msg = (error as BusinessError).message; 820 let code = (error as BusinessError).code; 821 hilog.error(0x0000, `show error code is ${code}, message is ${msg}`, ''); 822 } 823 }) 824 .onDrop(() => { 825 promptAction.showToast({duration: 100, message: 'Drag Success', bottom: 400}) 826 }) 827 Button('拖起').onTouch((event?:TouchEvent) => { 828 if(event){ 829 if (event.type == TouchType.Down) { 830 let text = new unifiedDataChannel.Text() 831 let unifiedData = new unifiedDataChannel.UnifiedData(text) 832 let dragInfo: dragController.DragInfo = { 833 pointerId: 0, 834 data: unifiedData, 835 extraParams: '' 836 } 837 class tmp{ 838 event:DragEvent|undefined = undefined 839 extraParams:string = '' 840 } 841 let eve:tmp = new tmp() 842 dragController.executeDrag(() => { // 建议使用 this.getUIContext().getDragController().executeDrag()接口 843 this.DraggingBuilder() 844 }, dragInfo, (err , eve) => { 845 hilog.info(0x0000, `ljx ${JSON.stringify(err)}`, '') 846 if (eve && eve.event) { 847 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 848 hilog.info(0x0000, 'success', ''); 849 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 850 hilog.info(0x0000, 'failed', ''); 851 } 852 } 853 }) 854 } 855 } 856 }).margin({top:100}) 857 } 858 .width('100%') 859 .height('100%') 860 } 861} 862 ``` 863 
