• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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> **excuteDrag** and [onDragStart](../arkui-ts/ts-universal-events-drag-drop.md# event) cannot be configured at the same time.
12
13
14## Modules to Import
15
16```ts
17import dragController from "@ohos.arkui.dragController";
18```
19
20## dragController.executeDrag
21
22executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo, callback: AsyncCallback<{event: DragEvent, extraParams: string}>): void
23
24Initiates 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.
25
26**System capability**: SystemCapability.ArkUI.ArkUI.Full
27
28**Parameters**
29
30| Name  | Type                                                        | Mandatory| Description                            |
31| -------- | ------------------------------------------------------------ | ---- | -------------------------------- |
32| custom   | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo) | Yes  | Object to be dragged.|
33| dragInfo | [DragInfo](#draginfo)                                        | Yes  | Drag information.                      |
34| 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.        |
35
36**Example**
37
38```ts
39import dragController from "@ohos.arkui.dragController"
40import UDMF from '@ohos.data.UDMF';
41
42@Entry
43@Component
44struct DragControllerPage {
45  @Builder DraggingBuilder() {
46    Column() {
47      Text("DraggingBuilder")
48    }
49    .width(100)
50    .height(100)
51    .backgroundColor(Color.Blue)
52  }
53
54  build() {
55    Column() {
56      Button('touch to execute drag')
57        .onTouch((event?:TouchEvent) => {
58          if(event){
59            if (event.type == TouchType.Down) {
60              let text = new UDMF.Text()
61              let unifiedData = new UDMF.UnifiedData(text)
62
63              let dragInfo: dragController.DragInfo = {
64                pointerId: 0,
65                data: unifiedData,
66                extraParams: ''
67              }
68              class tmp{
69                event:DragResult|undefined = undefined
70                extraParams:string = ''
71              }
72              let eve:tmp = new tmp()
73              dragController.executeDrag(this.DraggingBuilder(), dragInfo, (err, eve) => {
74                if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
75                // ...
76                } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
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.|
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 UDMF from '@ohos.data.UDMF';
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 UDMF.Text()
147              let unifiedData = new UDMF.UnifiedData(text)
148
149              let dragInfo: dragController.DragInfo = {
150                pointerId: 0,
151                data: unifiedData,
152                extraParams: ''
153              }
154              componentSnapshot.createFromBuilder(this.PixmapBuilder()).then((pix: image.PixelMap) => {
155                this.pixmap = pix;
156                let dragItemInfo: DragItemInfo = {
157                  pixelMap: this.pixmap,
158                  builder: this.DraggingBuilder(),
159                  extraInfo: "DragItemInfoTest"
160                }
161
162                class tmp{
163                  event:DragResult|undefined = undefined
164                  extraParams:string = ''
165                }
166                let eve:tmp = new tmp()
167                dragController.executeDrag(dragItemInfo, dragInfo)
168                  .then((eve) => {
169                    if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
170                      // ...
171                    } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
172                      // ...
173                    }
174                  })
175                  .catch((err:Error) => {
176                  })
177              })
178            }
179          }
180        })
181    }
182    .width('100%')
183    .height('100%')
184  }
185}
186```
187
188## DragInfo
189
190**System capability**: SystemCapability.ArkUI.ArkUI.Full
191
192Defines the attributes required for initiating a drag action and information carried in the dragging process.
193
194| Name       | Type                                                  | Mandatory| Description                                    |
195| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- |
196| pointerId   | number                                                 | Yes  | ID of the touch point on the screen when dragging is started.        |
197| data        | [unifiedDataChannel.UnifiedData](js-apis-data-unifiedDataChannel.md#unifieddata) | No  | Data carried in the dragging process.              |
198| extraParams | string                                                 | No  | Additional information about the drag action. Not supported currently.|
199