跳到主要内容

useDraggable

分类
导出大小
1.37 kB
上次更改
8 个月前

使元素可拖动。

演示

检查浮动框

👋 拖动我!
我在 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 可以覆盖浏览器中某些元素的默认拖放行为。

ts
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 storageKeystorageType,以实现元素位置的持久化。

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

类型声明

显示类型声明
ts
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
>

来源

源代码演示文档

贡献者

Anthony Fu
huiliangShen
Anthony Fu
IlyaL
IlyaL
丶远方
webfansplz
Shigma
SerKo
wgh970312
Robin
Fernando Fernández
Alex Peshkov
Joona Tiinanen
GU Yiling
wangliangxin
Kazim Duran
Jessé Correia Lins
faga
vaakian X
Akiho Nagao
stefnotch
btea
guolao
vaakian X
Jelf
donotloveshampo
Julian Meinking
Jukka Raimovaara
wheat

更新日志

8c521 - feat(components)!: 重构组件并使其保持一致 (#4912)
v13.6.0
547f8 - 修复:为组件添加捕获属性 (#4911)
v12.8.0
7432f - feat(types): 废弃 MaybeRefMaybeRefOrGetter,转而使用 Vue 的原生类型 (#4636)
v12.4.0
dd316 - feat: 尽可能在所有地方使用被动事件处理程序 (#4477)
v12.3.0
59f75 - feat(toValue): 废弃 @vueuse/shared 中的 toValue,转而使用 Vue 的原生函数
0a9ed - feat!: 放弃对 Vue 2 的支持,优化打包并清理 (#4349)
v11.1.0
7f25b - 修复:可拖动组件与容器不兼容 (#4192)
e9938 - 特性:添加 buttons 选项 (#4084)
9f10a - 修复:应忽略右键点击 (#3850)
v10.8.0
dee9a - 特性:添加 disabled 参数 (#3613)
55b94 - 修复:避免移出容器 (#3768)
v10.7.2
bdd79 - 修复:当父元素可滚动时无法正常工作 (#3692)
v10.6.0
08246 - 修复:元素无法相对父元素移动 (#3531)
v10.4.0
c08e5 - 特性:允许对固定元素进行边界计算 (#3335)
v10.2.0
6b670 - 特性:改进组件 props (#3075)

根据 MIT 许可证发布。