HarmonyOS鸿蒙Next三方接入拖拽开发指导

1. API 使用指导

应用接入拖拽涉及ArkUI提供的OnDragStart、OnDrop等接口的使用，若应用需要自定义实现拖拽的触发逻辑，则应掌握DragController系接口的。为自定义处理各类拖拽数据，还应掌握 UDMF 相关接口的使用。针对一些资源在网络的场景，如在线Image，还应借助Http相关能力实现在线资源的下载落盘处理。

1.1 ArkUI Drag

ArkUI框架对以下组件实现了默认的拖拽能力，支持对数据的拖出或拖入响应，开发者只需要将这些组件的draggable属性设置为true，即可使用默认拖拽能力。其中，Text、TextInput、TextArea、Hyperlink、Image和RichEditor组件的draggable属性默认为true。默认支持拖出能力的组件（可从组件上拖出数据）：Search、TextInput、TextArea、RichEditor、Text、Image、Hyperlink默认支持拖入能力的组件（目标组件可响应拖入数据）：Search、TextInput、TextArea、Video开发者也可以通过实现通用拖拽事件来自定义拖拽响应。其他组件需要开发者将draggable属性设置为true，并在onDragStart等接口中实现数据传输相关内容，才能正确处理拖拽。

1.1.1 OnDragStart系列接口（框架能力）

draggable

设置当前组件是否可拖拽，系统默认可拖出的组件有Search、TextInput、TextArea、RichEditor、Text、Image、Hyperlink。

allowDrop

标识当前组件上支持拖拽落入的数据类型，该数据类型是UniformDataType定义标识的。

OnPreDrag

绑定该事件的组件，在触发拖拽前的不同阶段时，触发回调，可在该接口中实现一些在拖拽发起前需要完成的动作，如产生拖拽缩略图等。

DragItemInfo

该接口用于描述拖拽过程中缩略图的相关信息，可设置PixelMap或实现CustomBuilder来实现自定义拖拽背板图。若已设置过PixelMap，则CustomerBuilder将会被忽略, 使用CustomBuilder性能较差于使用PixelMap。

DragItemInfo中extraInfo标识一些系统侧需要处理的额外数据，三方应用一般不涉及。

DragEvent

拖拽事件，在拖拽起拖时可设置对应拖拽数据，在拖拽过程中可获取当前拖拽事件的坐标信息、拖拽数据类型、拖拽数据等信息。

OnDragStart

第一次拖拽此事件绑定的组件时，长按时间 >= 500ms，然后手指移动距离 >= 10vp，则触发回调。针对默认支持拖出能力的组件，如果开发者设置了onDragStart，优先执行开发者的onDragStart，并根据执行情况决定是否使用系统默认的拖出能力，具体为：如果开发者返回了自定义背板图，则不再使用系统默认的拖拽背板图；如果开发者设置了拖拽数据，则不再使用系统默认填充的拖拽数据。文本类组件Text、Search、TextInput、TextArea、RichEditor对选中的文本内容进行拖拽时，不支持背板图的自定义。当onDragStart与菜单预览一起使用或使用了默认支持拖出能力的组件时，预览及菜单项上的自定义内容不支持拖拽。

OnDrop

绑定此事件的组件可作为拖拽释放目标，当在本组件范围内停止拖拽行为时，触发回调。如果开发者没有在onDrop中主动调用event.setResult()设置拖拽接收的结果，则系统按照数据接收成功处理.通常在该事件回调中执行拖拽落位后的数据处理逻辑，如刷新UI、在线资源下载、落入数据发送、落盘等业务逻辑。该回调中不应该同步执行耗时操作，否则可能导致抬手操作后拖拽背板延迟消失的问题，应使用JS提供的异步处理机制避免此类问题。

OnDragEnter

拖拽进入组件范围内时，触发回调，当监听了onDrop事件时，此事件才有效。通常在该事件回调中实现一些动效以标识当前拖拽的响应。

OnDragMove

拖拽过程在该组件范围内移动时，触发该回调，但该事件只在监听OnDrop事件后才会被成功触发。

OnDragLeave

拖拽离开组件范围内时，触发回调，当监听了onDrop事件时，此事件才有效。注意：监听OnDragEnter、OnDragLeave事件时必须监听OnDrop事件，否则不能正常响应事件,且在拖拽过程中存在不能监听到OnDragLeave的情况；若要100%保证能够监听到OnDragLeave事件，则应该使用setDragEventStrictReportingEnabled方法严格触发onDragLeave事件。

DragController （自定义拖拽）

参考示例：

主动发起拖拽能力，传入拖拽发起后跟手效果所拖拽的对象以及携带拖拽信息。通过回调返回结果。

参考链接：getDragController，onPreDrag。

1.1.2 ArkUI涉及的参考文档

拖拽事件，拖拽控制，[@ohos.arkui.dragController (DragController)](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkui/js-apis-arkui-dragController.md)，通过NDK接口对接拖拽：拖拽事件NDK。

1.2 UDMF

UDMF提供标准化数据定义：提供HarmonyOS跨应用、跨设备的统一数据类型标准，包含标准化数据类型和标准化数据结构。

参考文档：[@ohos.data.unifiedDataChannel (标准化数据通路)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-data-unifieddatachannel)，[@ohos.data.commonType (数据通用类型)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-data-commontype)，[@ohos.data.uniformTypeDescriptor (标准化数据定义与描述)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-data-uniformtypedescriptor)，[@ohos.data.uniformDataStruct (标准化数据结构)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-data-uniformdatastruct)。

其它接口文档：addEntry，通过标准化数据通路实现数据共享。

1.3 网络 API

若拖拽的数据是在线资源时，则应由拖拽落入方实现在线资源的下载处理逻辑,可参考以下API使用实现对应功能。

参考文档：[@ohos.request (上传下载)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-request)，HTTP数据请求。