1# @ohos.arkui.dragController (DragController) 2 3The **dragController** module provides APIs for initiating drag actions. When receiving a gesture event, such as a click or long-press event, an application can initiate a drag action and carry drag information therein. 4 5> **NOTE** 6> 7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> You can preview how this component looks on a real device. The preview is not yet available in the DevEco Studio Previewer. 10 11 12## Modules to Import 13 14```ts 15import dragController from "@ohos.arkui.dragController"; 16``` 17 18## dragController.executeDrag 19 20executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo, callback: AsyncCallback<{event: DragEvent, extraParams: string}>): void 21 22Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses an asynchronous callback to return the result. 23 24**System capability**: SystemCapability.ArkUI.ArkUI.Full 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 30| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.<br>**NOTE**<br>The global builder is not supported. If the [\<Image>](../arkui-ts/ts-basic-components-image.md) component is used in the builder, enable synchronous loading, that is, set the [syncLoad](../arkui-ts/ts-basic-components-image.md#attributes) attribute of the component to **true**. The builder is used only to generate the image displayed during the current dragging. Changes to the builder, if any, apply to the next dragging, but not to the current dragging.| 31| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | 32| callback | [AsyncCallback](./js-apis-base.md#asynccallback)<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Yes | Callback used to return the result.<br>- **event**: drag event information that includes only the drag result.<br>- **extraParams**: extra information about the drag event. | 33 34**Example** 35 36```ts 37import dragController from "@ohos.arkui.dragController" 38import UDC from '@ohos.data.unifiedDataChannel'; 39 40@Entry 41@Component 42struct DragControllerPage { 43 @Builder DraggingBuilder() { 44 Column() { 45 Text("DraggingBuilder") 46 } 47 .width(100) 48 .height(100) 49 .backgroundColor(Color.Blue) 50 } 51 52 build() { 53 Column() { 54 Button('touch to execute drag') 55 .onTouch((event?:TouchEvent) => { 56 if(event){ 57 if (event.type == TouchType.Down) { 58 let text = new UDC.Text() 59 let unifiedData = new UDC.UnifiedData(text) 60 61 let dragInfo: dragController.DragInfo = { 62 pointerId: 0, 63 data: unifiedData, 64 extraParams: '' 65 } 66 class tmp{ 67 event:DragEvent|undefined = undefined 68 extraParams:string = '' 69 } 70 let eve:tmp = new tmp() 71 dragController.executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => { 72 if(eve.event){ 73 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 74 // ... 75 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 76 // ... 77 } 78 } 79 }) 80 } 81 } 82 }) 83 } 84 } 85} 86``` 87 88## dragController.executeDrag 89 90executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<{event: DragEvent, extraParams: string}> 91 92Initiates a drag action, with the object to be dragged and the drag information passed in. This API uses a promise to return the result. 93 94**System capability**: SystemCapability.ArkUI.ArkUI.Full 95 96**Parameters** 97 98| Name | Type | Mandatory| Description | 99| -------- | ------------------------------------------------------------ | ---- | -------------------------------- | 100| custom | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes | Object to be dragged.| 101| dragInfo | [DragInfo](#draginfo) | Yes | Drag information. | 102 103**Return value** 104 105| Type | Description | 106| ------------------------------------------------------ | ------------------ | 107| Promise<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent), extraParams: string}> | Promise used to return the result.<br>- **event**: drag event information that includes only the drag result.<br>- **extraParams**: extra information about the drag event.| 108 109**Example** 110 111```ts 112import dragController from "@ohos.arkui.dragController" 113import componentSnapshot from '@ohos.arkui.componentSnapshot'; 114import image from '@ohos.multimedia.image'; 115import UDC from '@ohos.data.unifiedDataChannel'; 116 117@Entry 118@Component 119struct DragControllerPage { 120 @State pixmap: image.PixelMap|null = null 121 122 @Builder DraggingBuilder() { 123 Column() { 124 Text("DraggingBuilder") 125 } 126 .width(100) 127 .height(100) 128 .backgroundColor(Color.Blue) 129 } 130 131 @Builder PixmapBuilder() { 132 Column() { 133 Text("PixmapBuilder") 134 } 135 .width(100) 136 .height(100) 137 .backgroundColor(Color.Blue) 138 } 139 140 build() { 141 Column() { 142 Button('touch to execute drag') 143 .onTouch((event?:TouchEvent) => { 144 if(event){ 145 if (event.type == TouchType.Down) { 146 let text = new UDC.Text() 147 let unifiedData = new UDC.UnifiedData(text) 148 149 let dragInfo: dragController.DragInfo = { 150 pointerId: 0, 151 data: unifiedData, 152 extraParams: '' 153 } 154 let pb:CustomBuilder =()=>{():void=>{this.PixmapBuilder()}} 155 componentSnapshot.createFromBuilder(pb).then((pix: image.PixelMap) => { 156 this.pixmap = pix; 157 let dragItemInfo: DragItemInfo = { 158 pixelMap: this.pixmap, 159 builder: ()=>{this.DraggingBuilder()}, 160 extraInfo: "DragItemInfoTest" 161 } 162 163 class tmp{ 164 event:DragResult|undefined = undefined 165 extraParams:string = '' 166 } 167 let eve:tmp = new tmp() 168 dragController.executeDrag(dragItemInfo, dragInfo) 169 .then((eve) => { 170 if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) { 171 // ... 172 } else if (eve.event.getResult() == DragResult.DRAG_FAILED) { 173 // ... 174 } 175 }) 176 .catch((err:Error) => { 177 }) 178 }) 179 } 180 } 181 }) 182 } 183 .width('100%') 184 .height('100%') 185 } 186} 187``` 188 189## DragInfo 190 191**System capability**: SystemCapability.ArkUI.ArkUI.Full 192 193Defines the attributes required for initiating a drag action and information carried in the dragging process. 194 195| Name | Type | Mandatory| Description | 196| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- | 197| pointerId | number | Yes | ID of the touch point on the screen when dragging is started. | 198| data | [unifiedDataChannel.UnifiedData](js-apis-data-unifiedDataChannel.md#unifieddata) | No | Data carried in the dragging process. | 199| extraParams | string | No | Additional information about the drag action. Not supported currently.| 200