useDraggable

分类

元素

导出大小

1.37 kB

上次更改

8 个月前

使元素可拖动。

演示

源代码演示 (beta)

禁用拖放

检查浮动框

👋 拖动我！

我在 48, 80

无渲染组件

位置持久化到 sessionStorage

51, 150

👋 拖动到这里！

触发拖动事件的句柄

我在 56, 240

不使用捕获元素

在这里拖动将不起作用

61, 330

用法

vue

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

const el
 = useTemplateRef
<HTMLElement>('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>

设置 preventDefault: true 可以覆盖浏览器中某些元素的默认拖放行为。

const { x
, y
, style
 } = useDraggable
(el, {
  preventDefault
: true,
  // with `preventDefault: true`
  // you can disable the native behavior (e.g., for img)
  // and control the drag-and-drop, preventing the browser interference.
})

组件用法

此函数还通过 @vueuse/components 包提供了一个无渲染组件版本。了解更多用法。

vue

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

对于组件用法，可以向组件传递额外的 props storageKey 和 storageType，以实现元素位置的持久化。

vue

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

类型声明

显示类型声明

export interface UseDraggableOptions {
  /**
   * Only start the dragging when click on the element directly
   *
   * @default false
   */
  exact
?: MaybeRefOrGetter
<boolean>
  /**
   * Prevent events defaults
   *
   * @default false
   */
  preventDefault
?: MaybeRefOrGetter
<boolean>
  /**
   * Prevent events propagation
   *
   * @default false
   */
  stopPropagation
?: MaybeRefOrGetter
<boolean>
  /**
   * Whether dispatch events in capturing phase
   *
   * @default true
   */
  capture
?: boolean
  /**
   * Element to attach `pointermove` and `pointerup` events to.
   *
   * @default window
   */
  draggingElement
?: MaybeRefOrGetter
<
    HTMLElement | SVGElement | Window | Document | null | undefined
  >
  /**
   * Element for calculating bounds (If not set, it will use the event's target).
   *
   * @default undefined
   */
  containerElement
?: MaybeRefOrGetter
<
    HTMLElement | SVGElement | null | undefined
  >
  /**
   * Handle that triggers the drag event
   *
   * @default target
   */
  handle
?: MaybeRefOrGetter
<HTMLElement | SVGElement | null | undefined>
  /**
   * Pointer types that listen to.
   *
   * @default ['mouse', 'touch', 'pen']
   */
  pointerTypes
?: PointerType
[]
  /**
   * Initial position of the element.
   *
   * @default { x: 0, y: 0 }
   */
  initialValue
?: MaybeRefOrGetter
<Position
>
  /**
   * Callback when the dragging starts. Return `false` to prevent dragging.
   */
  onStart
?: (position
: Position
, event
: PointerEvent) => void | false
  /**
   * Callback during dragging.
   */
  onMove
?: (position
: Position
, event
: PointerEvent) => void
  /**
   * Callback when dragging end.
   */
  onEnd
?: (position
: Position
, event
: PointerEvent) => void
  /**
   * Axis to drag on.
   *
   * @default 'both'
   */
  axis
?: "x" | "y" | "both"
  /**
   * Disabled drag and drop.
   *
   * @default false
   */
  disabled
?: MaybeRefOrGetter
<boolean>
  /**
   * Mouse buttons that are allowed to trigger drag events.
   *
   * - `0`: Main button, usually the left button or the un-initialized state
   * - `1`: Auxiliary button, usually the wheel button or the middle button (if present)
   * - `2`: Secondary button, usually the right button
   * - `3`: Fourth button, typically the Browser Back button
   * - `4`: Fifth button, typically the Browser Forward button
   *
   * @see https://mdn.org.cn/en-US/docs/Web/API/MouseEvent/button#value
   * @default [0]
   */
  buttons
?: MaybeRefOrGetter
<number[]>
}
/**
 * Make elements draggable.
 *
 * @see https://vueuse.org.cn/useDraggable
 * @param target
 * @param options
 */
export declare function useDraggable
(
  target
: MaybeRefOrGetter
<HTMLElement | SVGElement | null | undefined>,
  options
?: UseDraggableOptions,
):
  | {
      position
: Ref
<
        {
          x
: number
          y
: number
        },
        | Position

        | {
            x
: number
            y
: number
          }
      >
      isDragging
: ComputedRef
<boolean>
      style
: ComputedRef
<string>
      x
: Ref
<number, number>
      y
: Ref
<number, number>
    }
  | {
      position
: Ref
<
        {
          x
: number
          y
: number
        },
        | Position

        | {
            x
: number
            y
: number
          }
      >
      isDragging
: ComputedRef
<boolean>
      style
: ComputedRef
<string>
      x
: Ref
<number, number>
      y
: Ref
<number, number>
    }
export type UseDraggableReturn
 = ReturnType
<typeof useDraggable
>