1# @ohos.deviceStatus.dragInteraction（拖拽)(系统接口)
2
3拖拽功能模块，提供注册和取消拖拽状态监听的能力。
4
5> **说明：**
6>
7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> - 本模块接口均为系统接口。
10
11## 导入模块
12
13```js
14import { dragInteraction } from '@kit.ArkUI'
15```
16
17## DragState
18
19拖拽状态。
20
21**系统接口：** 此接口为系统接口。
22
23**系统能力：** SystemCapability.Msdp.DeviceStatus.Drag
24
25| 名称                  | 值   | 说明           |
26| --------------------- | ---- | -------------- |
27| MSG_DRAG_STATE_START  | 1    | 表示开始拖拽。 |
28| MSG_DRAG_STATE_STOP   | 2    | 表示结束拖拽。 |
29| MSG_DRAG_STATE_CANCEL | 3    | 表示取消拖拽。 |
30
31## Summary<sup>11+</sup>
32
33拖拽对象的数据摘要。
34
35**系统接口：** 此接口为系统接口。
36
37**系统能力：** SystemCapability.Msdp.DeviceStatus.Drag
38
39| 名称       | 类型     | 必填 | 说明               |
40| ---------- | -------- | ---- | ------------------ |
41| dataType   | string   | 是   | 拖拽对象类型。     |
42| dataSize   | number   | 是   | 拖拽对象数据长度。 |
43
44## dragInteraction.on('drag')
45
46on(type: 'drag', callback: Callback\<DragState>): void
47
48注册监听拖拽状态。
49
50**系统接口：** 此接口为系统接口。
51
52**系统能力：** SystemCapability.Msdp.DeviceStatus.Drag
53
54**参数：**
55
56| 参数名   | 类型                               | 必填 | 说明                             |
57| -------- | ---------------------------------- | ---- | -------------------------------- |
58| type     | string                             | 是   | 监听类型，固定取值为 'drag'。    |
59| callback | Callback\<[DragState](#dragstate)> | 是   | 回调函数，异步返回拖拽状态消息。 |
60
61**错误码：**
62
63以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
64
65| 错误码ID | 错误信息          |
66| -------- | ----------------- |
67| 202 | Not system application. |
68| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. |
69
70**示例：**
71
72```ts
73try {
74  dragInteraction.on('drag', (data: dragInteraction.DragState) => {
75    console.log(`Drag interaction event: ${JSON.stringify(data)}`);
76  });
77} catch (error) {
78  console.log(`Register failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
79}
80```
81
82## dragInteraction.off('drag')
83
84off(type: 'drag', callback?: Callback\<DragState>): void
85
86取消监听拖拽状态。
87
88**系统接口：** 此接口为系统接口。
89
90**系统能力：** SystemCapability.Msdp.DeviceStatus.Drag
91
92**参数：**
93
94| 参数名   | 类型                               | 必填 | 说明                                                                   |
95| -------- | ---------------------------------- | ---- | ---------------------------------------------------------------------- |
96| type     | string                             | 是   | 监听类型，固定取值为 'drag'。                                          |
97| callback | Callback\<[DragState](#dragstate)> | 否   | 需要取消注册的回调函数，若无此参数，则取消当前应用注册的所有回调函数。 |
98
99**错误码：**
100
101以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
102
103| 错误码ID | 错误信息          |
104| -------- | ----------------- |
105| 202 | Not system application. |
106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified.2.Incorrect parameter types.3.Parameter verification failed. |
107
108**示例：**
109
110```ts
111// 取消注册单个回调函数
112function single_callback(event: dragInteraction.DragState) {
113  console.log(`Drag interaction event: ${JSON.stringify(event)}`);
114  return false;
115}
116try {
117  dragInteraction.on('drag', single_callback);
118  dragInteraction.off("drag", single_callback);
119} catch (error) {
120  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
121}
122```
123
124```ts
125// 取消注册所有回调函数
126function all_callback(event: dragInteraction.DragState) {
127  console.log(`Drag interaction event: ${JSON.stringify(event)}`);
128  return false;
129}
130try {
131  dragInteraction.on('drag', all_callback);
132  dragInteraction.off("drag");
133} catch (error) {
134  console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`);
135}
136```
137
138## dragInteraction.getDataSummary<sup>11+</sup>
139
140getDataSummary(): Array\<Summary>
141
142获取所有拖拽对象的摘要。
143
144**系统接口：** 此接口为系统接口。
145
146**系统能力：** SystemCapability.Msdp.DeviceStatus.Drag
147
148**返回值：**
149
150| 类型                          | 说明                                                 |
151| ----------------------------- | ---------------------------------------------------- |
152| Array\<[Summary](#summary11)> | 所有拖拽对象的数据摘要，包含拖拽对象的类型和数据长度。 |
153
154**错误码：**
155
156以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
157
158| 错误码ID | 错误信息          |
159| -------- | ----------------- |
160| 202 | Not system application. |
161
162**示例：**
163
164```ts
165let summarys: Array<dragInteraction.Summary> = dragInteraction.getDataSummary();
166console.log(`Drag interaction summarys: ${JSON.stringify(summarys)}`);
167```