useDraggable

使元素可拖拽，支持指针类型、轴向约束、容器边界检测。

---

函数签名

function useDraggable(
  target: MaybeRefOrGetter<HTMLElement | SVGElement | null | undefined>,
  options?: UseDraggableOptions,
): {
  x: Ref<number>
  y: Ref<number>
  position: Ref<{ x: number; y: number }>
  isDragging: ComputedRef<boolean>
  style: ComputedRef<string>
}

基础用法

参数

参数	说明	类型	默认值
target	可拖拽的目标元素（ref / getter）	MaybeRefOrGetter<HTMLElement | SVGElement>	—
options	配置项	UseDraggableOptions	{}

UseDraggableOptions

参数	说明	类型	默认值
exact	仅在直接点击元素时开始拖拽	MaybeRefOrGetter<boolean>	false
preventDefault	阻止默认事件	MaybeRefOrGetter<boolean>	false
stopPropagation	阻止事件冒泡	MaybeRefOrGetter<boolean>	false
capture	是否在捕获阶段触发事件	boolean	true
draggingElement	pointermove/pointerup 绑定的元素	MaybeRefOrGetter<HTMLElement | Window | Document>	window
containerElement	拖拽边界计算容器	MaybeRefOrGetter<HTMLElement>	—
handle	触发拖拽的句柄元素	MaybeRefOrGetter<HTMLElement>	target
pointerTypes	监听的指针类型	('mouse' | 'touch' | 'pen')[]	['mouse', 'touch', 'pen']
initialValue	初始位置	MaybeRefOrGetter<{ x: number; y: number }>	{ x: 0, y: 0 }
axis	拖拽轴向	'x' | 'y' | 'both'	'both'
disabled	禁用拖拽	MaybeRefOrGetter<boolean>	false
onStart	拖拽开始回调，返回 false 可阻止	(position, event) => void | false	—
onMove	拖拽中回调	(position, event) => void	—
onEnd	拖拽结束回调	(position, event) => void	—

返回值

属性	说明	类型
x	水平位置	Ref<number>
y	垂直位置	Ref<number>
position	位置对象	Ref<{ x: number; y: number }>
isDragging	是否正在拖拽	ComputedRef<boolean>
style	可直接绑定到元素的 CSS 字符串（left:Xpx;top:Ypx;）	ComputedRef<string>

代码示例

import { ref } from 'vue'
import { useDraggable } from 'ljf-hooks'

const el = ref<HTMLElement>()
const { x, y, style, isDragging } = useDraggable(el, {
  initialValue: { x: 100, y: 100 },
  axis: 'x', // 仅水平拖拽
})