useDraggable

类别

Elements

导出大小

1.33 kB

最近修改

2 days ago

使元素可拖动。

🌐 Make elements draggable.

示例

源代码在线运行

Disabled drag and drop

Check the floating boxes

👋 Drag me!

I am at 48, 80

Renderless component

Position persisted in sessionStorage

51, 150

👋 Drag here!

Handle that triggers the drag event

I am at 56, 240

Not Use Captured Element

Dragging here will not work

61, 330

用法

🌐 Usage

<script setup lang="ts">
import { useDraggable } from '@vueuse/core'
import { useTemplateRef } from 'vue'

const el = useTemplateRef('el')

// `style` will be a helper computed for `left: ?px; top: ?px;`
const { x, y, style } = useDraggable(el, {
  initialValue: { x: 40, y: 40 },
})
</script>

<template>
  <div ref="el" :style="style" style="position: fixed">
    Drag me! I am at {{ x }}, {{ y }}
  </div>
</template>

返回值

🌐 Return Values

属性	类型	描述
x	Ref<number>	当前 x 坐标
y	Ref<number>	当前 y 坐标
position	Ref<{x, y}>	当前位置信息对象
isDragging	ComputedRef<boolean>	是否正在拖拽
style	ComputedRef<string>	CSS 样式字符串 left: ?px; top: ?px;

选项

🌐 Options

useDraggable(el, {
  // Initial position (default: { x: 0, y: 0 })
  initialValue: { x: 40, y: 40 },
  // Restrict dragging to specific axis: 'x', 'y', or 'both' (default)
  axis: 'both',
  // Only trigger when clicking directly on the element (default: false)
  exact: false,
  // Prevent default browser behavior (default: false)
  preventDefault: true,
  // Stop event propagation (default: false)
  stopPropagation: false,
  // Use capture phase for events (default: true)
  capture: true,
  // Disable dragging (default: false)
  disabled: false,
  // Mouse buttons that trigger drag (default: [0] - left button)
  buttons: [0],
  // Pointer types to listen to (default: ['mouse', 'touch', 'pen'])
  pointerTypes: ['mouse', 'touch', 'pen'],
  // Custom drag handle element (default: target element)
  handle: handleRef,
  // Container element for bounds (default: none)
  containerElement: containerRef,
  // Element to attach pointermove/pointerup events (default: window)
  draggingElement: window,
  // Callbacks
  onStart: (position, event) => {
    // Return false to prevent dragging
  },
  onMove: (position, event) => {},
  onEnd: (position, event) => {},
})

阻止默认

🌐 Prevent Default

设置 preventDefault: true 以覆盖浏览器中某些元素（例如图片）的默认拖放行为。

🌐 Set preventDefault: true to override the default drag-and-drop behavior of certain elements in the browser (e.g., images).

import { useDraggable } from '@vueuse/core'

const { x, y, style } = useDraggable(el, {
  preventDefault: true,
})

容器边界

🌐 Container Bounds

使用 containerElement 将拖动限制在容器内。

🌐 Use containerElement to constrain dragging within a container.

import { useDraggable } from '@vueuse/core'

const { x, y } = useDraggable(el, {
  containerElement: containerRef,
})

将 autoScroll: true 设置为在拖动靠近边缘时启用自动滚动。

🌐 Set autoScroll: true to enable auto-scroll when dragging near the edges.

const { x, y, style } = useDraggable(el, {
  autoScroll: {
    speed: 2, // Control the speed of auto-scroll.
    margin: 30, // Set the margin from the edge that triggers auto-scroll.
    direction: 'both' // Determine the direction of auto-scroll.
  },
})

组件用法

🌐 Component Usage

<template>
  <UseDraggable v-slot="{ x, y }" :initial-value="{ x: 10, y: 10 }">
    Drag me! I am at {{ x }}, {{ y }}
  </UseDraggable>
</template>

对于组件使用，可以向组件传递额外的属性 storageKey 和 storageType，以启用元素位置的持久化。

🌐 For component usage, additional props storageKey and storageType can be passed to the component and enable the persistence of the element position.

<template>
  <UseDraggable storage-key="vueuse-draggable" storage-type="session">
    Refresh the page and I am still in the same position!
  </UseDraggable>
</template>