• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.arkui.dragController (DragController)
2
3本模块提供发起主动拖拽的能力，当应用接收到点击或长按等事件时可以主动发起拖拽的动作，并在其中携带拖拽信息。
4
5> **说明：**
6>
7> 本模块首批接口从 API version 10 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 示例效果请以真机运行为准，当前 IDE 预览器不支持。
10>
11> 当前不支持同时配置excuteDrag和[onDragStart](../arkui-ts/ts-universal-events-drag-drop.md#事件)。
12
13
14## 导入模块
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
24主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过回调返回结果。
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说明) | 是   | 拖拽发起后跟手效果所拖拽的对象。 |
33| dragInfo | [DragInfo](#draginfo)                                        | 是   | 拖拽信息。                       |
34| callback | [AsyncCallback](./js-apis-base.md#asynccallback)<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent说明), extraParams: string}> | 是   | 拖拽结束返回结果的回调。         |
35
36**示例：**
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:DragEvent|undefined = undefined
70                extraParams:string = ''
71              }
72              let eve:tmp = new tmp()
73              dragController.executeDrag(()=>{this.DraggingBuilder()}, dragInfo, (err, eve) => {
74                if(eve.event){
75                  if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
76                  // ...
77                  } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
78                  // ...
79                  }
80                }
81              })
82            }
83          }
84        })
85    }
86  }
87}
88```
89
90## dragController.executeDrag
91
92executeDrag(custom: CustomBuilder | DragItemInfo, dragInfo: DragInfo): Promise<{event: DragEvent, extraParams: string}>
93
94主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过Promise返回结果。
95
96**系统能力：** SystemCapability.ArkUI.ArkUI.Full
97
98**参数：**
99
100| 参数名   | 类型                                                         | 必填 | 说明                             |
101| -------- | ------------------------------------------------------------ | ---- | -------------------------------- |
102| custom   | [CustomBuilder](../arkui-ts/ts-types.md#custombuilder8) \| [DragItemInfo](../arkui-ts/ts-universal-events-drag-drop.md#dragiteminfo说明) | 是   | 拖拽发起后跟手效果所拖拽的对象。 |
103| dragInfo | [DragInfo](#draginfo)                                        | 是   | 拖拽信息。                       |
104
105**返回值：**
106
107| 类型                                                   | 说明               |
108| ------------------------------------------------------ | ------------------ |
109| Promise<{event: [DragEvent](../arkui-ts/ts-universal-events-drag-drop.md#dragevent说明), extraParams: string}> | 拖拽结束返回的结果。 |
110
111**示例：**
112
113```ts
114import dragController from "@ohos.arkui.dragController"
115import componentSnapshot from '@ohos.arkui.componentSnapshot';
116import image from '@ohos.multimedia.image';
117import UDMF from '@ohos.data.UDMF';
118
119@Entry
120@Component
121struct DragControllerPage {
122  @State pixmap: image.PixelMap|null = null
123
124  @Builder DraggingBuilder() {
125    Column() {
126      Text("DraggingBuilder")
127    }
128    .width(100)
129    .height(100)
130    .backgroundColor(Color.Blue)
131  }
132
133  @Builder PixmapBuilder() {
134    Column() {
135      Text("PixmapBuilder")
136    }
137    .width(100)
138    .height(100)
139    .backgroundColor(Color.Blue)
140  }
141
142  build() {
143    Column() {
144      Button('touch to execute drag')
145        .onTouch((event?:TouchEvent) => {
146          if(event){
147            if (event.type == TouchType.Down) {
148              let text = new UDMF.Text()
149              let unifiedData = new UDMF.UnifiedData(text)
150
151              let dragInfo: dragController.DragInfo = {
152                pointerId: 0,
153                data: unifiedData,
154                extraParams: ''
155              }
156              let pb:CustomBuilder =()=>{():void=>{this.PixmapBuilder()}}
157              componentSnapshot.createFromBuilder(pb).then((pix: image.PixelMap) => {
158                this.pixmap = pix;
159                let dragItemInfo: DragItemInfo = {
160                  pixelMap: this.pixmap,
161                  builder: ()=>{this.DraggingBuilder()},
162                  extraInfo: "DragItemInfoTest"
163                }
164
165                class tmp{
166                  event:DragResult|undefined = undefined
167                  extraParams:string = ''
168                }
169                let eve:tmp = new tmp()
170                dragController.executeDrag(dragItemInfo, dragInfo)
171                  .then((eve) => {
172                    if (eve.event.getResult() == DragResult.DRAG_SUCCESSFUL) {
173                      // ...
174                    } else if (eve.event.getResult() == DragResult.DRAG_FAILED) {
175                      // ...
176                    }
177                  })
178                  .catch((err:Error) => {
179                  })
180              })
181            }
182          }
183        })
184    }
185    .width('100%')
186    .height('100%')
187  }
188}
189```
190
191## DragInfo
192
193**系统能力：** SystemCapability.ArkUI.ArkUI.Full
194
195发起拖拽所需要的属性和拖拽时携带的信息。
196
197| 名称        | 类型                                                   | 必填 | 说明                                     |
198| ----------- | ------------------------------------------------------ | ---- | ---------------------------------------- |
199| pointerId   | number                                                 | 是   | 设置启动拖拽时屏幕上触摸点的Id。         |
200| data        | [unifiedDataChannel.UnifiedData](js-apis-data-unifiedDataChannel.md#unifieddata) | 否   | 设置拖拽过程中携带的数据。               |
201| extraParams | string                                                 | 否   | 设置拖拽事件额外信息，具体功能暂未实现。 |
202
203