harmony 鸿蒙drag_and_drop.h

2025-06-12
浏览 (6)

drag_and_drop.h

概述

提供NativeDrag相关接口定义。

库： libace_ndk.z.so

引用文件：

系统能力： SystemCapability.ArkUI.ArkUI.Full

起始版本： 12

相关模块：ArkUI_NativeModule

汇总

类型定义

名称	描述
typedef struct ArkUI_NodeEvent ArkUI_NodeEvent	组件事件的通用结构类型。
typedef struct ArkUI_Context ArkUI_Context	native UI的上下文实例对象。
typedef struct ArkUI_Context * ArkUI_ContextHandle	native UI的上下文实例对象指针定义。
typedef struct ArkUI_DragEvent ArkUI_DragEvent	拖拽事件。
typedef struct ArkUI_DragPreviewOption ArkUI_DragPreviewOption	设置拖拽跟手图的相关自定义参数。
typedef struct ArkUI_DragAction ArkUI_DragAction	拖拽行为，用于主动发起拖拽。
typedef struct ArkUI_DragAndDropInfo ArkUI_DragAndDropInfo	主动发起拖拽后，通过拖拽状态监听返回的系统拖拽相关数据。
typedef struct OH_UdmfData OH_UdmfData	UDMF 统一数据定义。
typedef struct OH_PixelmapNative OH_PixelmapNative	Pixelmap结构体类型，用于执行Pixelmap相关操作。
typedef struct OH_UdmfGetDataParams OH_UdmfGetDataParams	从UDMF获取数据时的参数。

枚举

名称	描述
ArkUI_DragResult { ARKUI_DRAG_RESULT_SUCCESSFUL, ARKUI_DRAG_RESULT_FAILED, ARKUI_DRAG_RESULT_CANCELED }	拖拽结果定义，由数据接收方设置，并由系统传递给数据拖出方，拖出方可感知接收方对数据的处理结果。
ArkUI_DropOperation { ARKUI_DROP_OPERATION_COPY, ARKUI_DROP_OPERATION_MOVE }	定义拖拽释放时的数据处理方式，可影响角标的显示。
ArkUI_PreDragStatus { ARKUI_PRE_DRAG_STATUS_UNKNOWN = -1, ARKUI_PRE_DRAG_STATUS_ACTION_DETECTING, ARKUI_PRE_DRAG_STATUS_READY_TO_TRIGGER_DRAG, ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_STARTED, ARKUI_PRE_DRAG_STATUS_PREVIEW_LIFT_FINISHED, ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_STARTED, ARKUI_PRE_DRAG_STATUS_PREVIEW_LANDING_FINISHED, ARKUI_PRE_DRAG_STATUS_CANCELED_BEFORE_DRAG }	定义拖拽发起前的长按交互阶段的变化状态。
ArkUI_DragPreviewScaleMode { ARKUI_DRAG_PREVIEW_SCALE_AUTO, ARKUI_DRAG_PREVIEW_SCALE_DISABLED }	拖拽预览缩放模式。
ArkUI_DragStatus { ArkUI_DRAG_STATUS_UNKNOWN, ArkUI_DRAG_STATUS_STARTED, ArkUI_DRAG_STATUS_ENDED }	拖拽状态。

函数

名称	描述
ArkUI_DragEvent * OH_ArkUI_NodeEvent_GetDragEvent (ArkUI_NodeEvent *nodeEvent)	从 NodeEvent 中获取DragEvent。
ArkUI_PreDragStatus OH_ArkUI_NodeEvent_GetPreDragStatus (ArkUI_NodeEvent *nodeEvent)	获取预览拖拽事件状态。
int32_t OH_ArkUI_DragEvent_DisableDefaultDropAnimation (ArkUI_DragEvent *event, bool disable)	设置是否禁用松手时的系统默认动效，默认不禁用，通常在应用需要自定义落位动效时配置。
int32_t OH_ArkUI_DragEvent_SetSuggestedDropOperation (ArkUI_DragEvent *event, ArkUI_DropOperation dropOperation)	设置数据处理方式。
int32_t OH_ArkUI_DragEvent_SetDragResult (ArkUI_DragEvent *event, ArkUI_DragResult result)	设置拖拽事件的结果。
int32_t OH_ArkUI_DragEvent_SetData (ArkUI_DragEvent event, OH_UdmfData data)	向ArkUI_DragEvent中设置拖拽数据。
int32_t OH_ArkUI_DragEvent_GetUdmfData (ArkUI_DragEvent event, OH_UdmfData data)	从ArkUI_DragEvent中获取拖拽默认相关数据。
int32_t OH_ArkUI_DragEvent_GetDataTypeCount (ArkUI_DragEvent event, int32_t count)	从ArkUI_DragEvent中获取所拖拽的数据类型种类个数。
int32_t OH_ArkUI_DragEvent_GetDataTypes (ArkUI_DragEvent event, char eventTypeArray[], int32_t length， int32_t maxStrLen)	从ArkUI_DragEvent中获取拖拽数据的类型列表。
int32_t OH_ArkUI_DragEvent_GetDragResult (ArkUI_DragEvent event, ArkUI_DragResult result)	从ArkUI_DragEvent中获取拖拽结果。
int32_t OH_ArkUI_DragEvent_GetDropOperation (ArkUI_DragEvent event, ArkUI_DropOperation operation)	从ArkUI_DragEvent中获取数据处理方式。
float OH_ArkUI_DragEvent_GetPreviewTouchPointX (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取预览图跟手点的x轴坐标。
float OH_ArkUI_DragEvent_GetPreviewTouchPointY (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取预览图跟手点的y轴坐标。
float OH_ArkUI_DragEvent_GetPreviewRectWidth (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取预览图的宽。
float OH_ArkUI_DragEvent_GetPreviewRectHeight (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取预览图的高。
float OH_ArkUI_DragEvent_GetTouchPointXToWindow (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取跟手点相对于window的x轴坐标。
float OH_ArkUI_DragEvent_GetTouchPointYToWindow (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取跟手点相对于window的y轴坐标。
float OH_ArkUI_DragEvent_GetTouchPointXToDisplay (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取跟手点相对于当前Display的x轴坐标。
float OH_ArkUI_DragEvent_GetTouchPointYToDisplay (ArkUI_DragEvent *event)	从ArkUI_DragEvent中获取跟手点相对于当前Display的y轴坐标。
float OH_ArkUI_DragEvent_GetVelocityX (ArkUI_DragEvent *event)	获取当前拖拽的x轴方向拖动速度。
float OH_ArkUI_DragEvent_GetVelocityY (ArkUI_DragEvent *event)	获取当前拖拽的y轴方向拖动速度。
float OH_ArkUI_DragEvent_GetVelocity (ArkUI_DragEvent *event)	获取当前拖拽的主方向拖动速度。
int32_t OH_ArkUI_DragEvent_GetModifierKeyStates (ArkUI_DragEvent event, uint64_t keys)	获取功能键按压状态。
ArkUI_ErrorCode OH_ArkUI_DragEvent_GetDragSource (ArkUI_DragEvent event, char bundleName, int32_t length)	获取拖起方包名。
ArkUI_ErrorCode OH_ArkUI_DragEvent_IsRemote (ArkUI_DragEvent event, bool isRemote)	获取是否是跨设备拖拽，跨设备拖拽时为true。
ArkUI_ErrorCode OH_ArkUI_DragEvent_GetDisplayId (ArkUI_DragEvent event, int32_t displayId)	获取当前拖拽事件发生时所在的屏幕ID，不支持当eventType为NODE_ON_DRAG_END时获取。起始版本： 20
int32_t OH_ArkUI_SetDragEventStrictReportWithNode (ArkUI_NodeHandle node, bool enabled)	控制是否使能严格dragEvent上报，建议开启；默认是不开启的；当不开启时，从父组件拖移进子组件时，父组件并不会收到leave的通知；而开启之后，只要前后两个组件发生变化，上一个组件就会收到 leave，新的组件收到enter通知；该配置与具体的UI实例相关，需要通过传入一个当前UI实例上的一个具体的组件节点来关联。
int32_t OH_ArkUI_SetDragEventStrictReportWithContext (ArkUI_ContextHandle uiContext, bool enabled)	控制是否使能严格dragEvent上报，建议开启；默认是不开启的; 当不开启时，从父组件拖移进子组件时，父组件并不会收到leave的通知；而开启之后，只要前后两个组件发生变化，上一个组件就会收到 leave，新的组件收到enter通知；该配置与具体的UI实例相关，可通过传入一个UI实例进行关联。
int32_t OH_ArkUI_SetNodeAllowedDropDataTypes (ArkUI_NodeHandle node, const char *typesArray[], int32_t count)	配置组件允许接受落入的数据类型，该接口会重置通过 OH_ArkUI_DisallowNodeAnyDropDataTypes 或 OH_ArkUI_AllowNodeAllDropDataTypes进行的配置。
int32_t OH_ArkUI_DisallowNodeAnyDropDataTypes (ArkUI_NodeHandle node)	配置组件不允许接受任何数据类型，该接口会重置通过OH_ArkUI_SetNodeAllowedDropDataTypes配置的数据类型。
int32_t OH_ArkUI_AllowNodeAllDropDataTypes (ArkUI_NodeHandle node)	配置组件允许接受任意数据类型，该接口会重置通过OH_ArkUI_SetNodeAllowedDropDataTypes配置的数据类型。
int32_t OH_ArkUI_SetNodeDraggable (ArkUI_NodeHandle node, bool enabled)	设置该组件是否允许进行拖拽。
int32_t OH_ArkUI_SetNodeDragPreview (ArkUI_NodeHandle node, OH_PixelmapNative *preview)	设置组件在被拖拽时的自定义跟手图。
ArkUI_DragPreviewOption * OH_ArkUI_CreateDragPreviewOption (void)	构建一个ArkUI_DragPreviewOption对象。
void OH_ArkUI_DragPreviewOption_Dispose (ArkUI_DragPreviewOption *option)	销毁跟手图自定义参数对象实例。
int32_t OH_ArkUI_DragPreviewOption_SetScaleMode (ArkUI_DragPreviewOption *option, ArkUI_DragPreviewScaleMode scaleMode)	设置拖拽跟手图是否根据系统定义自动进行缩放。
int32_t OH_ArkUI_DragPreviewOption_SetDefaultShadowEnabled (ArkUI_DragPreviewOption *option, bool enabled)	设置跟手图背板默认的投影效果，默认使能。
int32_t OH_ArkUI_DragPreviewOption_SetDefaultRadiusEnabled (ArkUI_DragPreviewOption *option, bool enabled)	设置跟手图背板默认的圆角效果，默认使能。
int32_t OH_ArkUI_DragPreviewOption_SetNumberBadgeEnabled (ArkUI_DragPreviewOption *option, bool enabled)	设置跟手图背板是否显示角标,默认使能,开启后,系统会根据拖拽数量自动进行角标显示。
int32_t OH_ArkUI_DragPreviewOption_SetBadgeNumber (ArkUI_DragPreviewOption *option, uint32_t forcedNumber)	强制显示角标的数量,覆盖SetDragPreviewNumberBadgeEnabled设置的值。
int32_t OH_ArkUI_DragPreviewOption_SetDefaultAnimationBeforeLiftingEnabled (ArkUI_DragPreviewOption *option, bool enabled)	配置是否开启点按时的默认动画。
int32_t OH_ArkUI_SetNodeDragPreviewOption (ArkUI_NodeHandle node, ArkUI_DragPreviewOption *option)	将构造的ArkUI_DragPreviewOption设置给组件。
ArkUI_DragAction * OH_ArkUI_CreateDragActionWithNode (ArkUI_NodeHandle node)	创建一个拖拽操作对象，该对象需与一个UI实例相关联，可通过传入一个当前UI实例的某个组件节点来指定。
ArkUI_DragAction * OH_ArkUI_CreateDragActionWithContext (ArkUI_ContextHandle uiContext)	创建一个拖拽操作对象，该对象需与一个UI实例相关联，可通过传入一个UI实例指针来关联。
void OH_ArkUI_DragAction_Dispose (ArkUI_DragAction *dragAction)	销毁创建的 ArkUI_DragAction 对象。
int32_t OH_ArkUI_DragAction_SetPointerId (ArkUI_DragAction *dragAction, int32_t pointer)	设置手指ID，当屏幕上仅有一只手指在操作时，pointer ID 为 0；一般情况下，配置 0 即可。
int32_t OH_ArkUI_DragAction_SetPixelMaps (ArkUI_DragAction dragAction, OH_PixelmapNative pixelmapArray[], int32_t size)	设置拖拽跟手图，只能使用 pixelmap 格式对象。
int32_t OH_ArkUI_DragAction_SetTouchPointX (ArkUI_DragAction *dragAction, float x)	设置跟手点，相对于设置的第一个pixelmap的左上角。
int32_t OH_ArkUI_DragAction_SetTouchPointY (ArkUI_DragAction *dragAction, float y)	设置跟手点,相对于设置的第一个pixelmap的左上角。
int32_t OH_ArkUI_DragAction_SetData (ArkUI_DragAction dragAction, OH_UdmfData data)	设置拖拽数据。
int32_t OH_ArkUI_DragAction_SetDragPreviewOption (ArkUI_DragAction dragAction, ArkUI_DragPreviewOption option)	将构造的ArkUI_DragPreviewOption设置给ArkUI_DragAction。
int32_t OH_ArkUI_DragAction_RegisterStatusListener (ArkUI_DragAction dragAction, void userData, void(listener)(ArkUI_DragAndDropInfo dragAndDropInfo, void *userData))	注册拖拽状态监听回调,该回调可感知到拖拽已经发起或用户松手结束的状态, 可通过该监听获取到落入方对数据的接收处理是否成功。
void OH_ArkUI_DragAction_UnregisterStatusListener (ArkUI_DragAction *dragAction)	解注册拖拽状态监听回调。
ArkUI_DragStatus OH_ArkUI_DragAndDropInfo_GetDragStatus (ArkUI_DragAndDropInfo *dragAndDropInfo)	获取dragaction发起拖拽的状态，获取异常时返回 ArkUI_DRAG_STATUS_UNKNOWN。
ArkUI_DragEvent * OH_ArkUI_DragAndDropInfo_GetDragEvent (ArkUI_DragAndDropInfo *dragAndDropInfo)	通过dragAndDropInfo获取到DragEvent，可通过DragEvent获取释放结果等。
int32_t OH_ArkUI_StartDrag (ArkUI_DragAction *dragAction)	通过构造的DragAction对象发起拖拽。
int32_t OH_ArkUI_DragEvent_StartDataLoading (ArkUI_DragEvent* event, OH_UdmfGetDataParams* options, char* key, unsigned int keyLen)	异步获取拖拽数据。
int32_t OH_ArkUI_CancelDataLoading (ArkUI_Context uiContext, const char* key)	取消异步获取拖拽数据。
int32_t OH_ArkUI_DisableDropDataPrefetchOnNode (ArkUI_NodeHandle node, bool disable)	设置拖拽是否提前获取数据。true为不提前获取数据，默认值为false。
int32_t OH_ArkUI_DragEvent_RequestDragEndPending(ArkUI_DragEvent* event, int32_t* requestIdentify)	请求延迟执行拖拽结束。
int32_t OH_ArkUI_NotifyDragResult(int32_t requestIdentify, ArkUI_DragResult * result)	通知拖拽结果。
int32_t OH_ArkUI_NotifyDragEndPendingDone(int32_t requestIdentify)	通知拖拽延迟执行结束。
int32_t OH_ArkUI_EnableDropDisallowedBadge (ArkUI_ContextHandle uiContext, bool enabled)	设置是否可以显示禁用角标。起始版本： 20