Draggable 拖拽

avue-draggable 以绝对定位包装内容，支持移动、缩放、范围限制和键盘微调。父容器需要 position: relative 和明确尺寸。

效果预览可直接操作下方示例

拖动蓝色卡片，选中后拖动边缘调整大小；方向键微调，Shift + 方向键移动 10 倍步长，Escape 取消选中。

正在加载示例…

<template>
  <div ref="canvas" class="draggable-demo" @pointerdown.self="draggable?.setActive(false)">
    <avue-draggable ref="draggable" index="card" :width="160" :height="100"
                    :left="24" :top="40" :step="5" :grid="5"
                    :bounds="{ left: 0, top: 0, width: canvasWidth, height: 260 }"
                    @change="state = $event">
      <div class="draggable-demo__card">拖动卡片或边缘控制点</div>
    </avue-draggable>
  </div>
  <el-alert :title="state ? `位置 (${state.left}, ${state.top})，尺寸 ${state.width} × ${state.height}` : '点击卡片后可使用方向键微调'"
            type="info" :closable="false" />
</template>

<script setup>
import { onBeforeUnmount, onMounted, ref } from 'vue'
const canvas = ref(null)
const draggable = ref(null)
const canvasWidth = ref(280)
const state = ref(null)
let observer
onMounted(() => {
  const measure = () => { canvasWidth.value = canvas.value?.clientWidth || 280 }
  measure()
  observer = new ResizeObserver(measure)
  observer.observe(canvas.value)
})
onBeforeUnmount(() => observer?.disconnect())
</script>

<style scoped>
.draggable-demo { position: relative; height: 260px; margin-bottom: 16px; border: 1px solid var(--el-border-color); border-radius: 8px; }
.draggable-demo__card { display: grid; place-items: center; padding: 12px; box-sizing: border-box; color: #fff; background: var(--el-color-primary); border-radius: 6px; text-align: center; user-select: none; }
</style>

Props

参数	说明	类型	默认值
index	业务标识，在事件载荷中返回	string / number	—
left / top	相对父容器的横向 / 纵向坐标	number / 数字字符串	0
width / height	宽高，不传时读取第一个内容元素的尺寸	number / 数字字符串	—
zIndex	常规图层，选中时内部提升到 9999	number / string	1
disabled / readonly / lock	禁用 / 只读 / 锁定；都阻止移动与缩放	boolean	false
resize	是否启用缩放控制点与同步子元素尺寸	boolean	true
mask	使用遮罩捕获拖动；需要直接操作内容控件时可关闭	boolean	true
scale	父画布缩放倍率，用于换算指针位移	number	1
step	指针位移倍率，同时是键盘移动步长	number	1
grid	网格吸附间距，0 不吸附	number	0
minWidth / minHeight	最小尺寸	number	20
maxWidth / maxHeight	最大尺寸	number	—
bounds	允许移动的边界，支持 { left, top, right, bottom } 或 { left, top, width, height }	object	—
handle	允许开始拖动的 CSS 选择器	string	—
ignore	无 handle 时跳过的 CSS 选择器	string	输入框、按钮、链接及 [data-avue-draggable-ignore]

坐标和尺寸通过 Number() 转换，推荐传数字，不要传 '100px'。组件不自动向父级回写位置；需要保存时监听 change 的实际状态。

Events

state 为 { index, left, top, width, height }，其中坐标是当前绝对位置。

事件	参数	说明
move	{ index, left, top }	位移量；指针拖动为相对本次按下位置的变化，键盘为本次变化
resize	{ ...state, deltaX, deltaY }	缩放后的状态与指针位移
change	{ type: 'move' 或 'resize', ...state }	适合持久化的当前状态
focus	{ type, ...state }	开始拖动或缩放
blur	state	指针释放或取消
over / out	state	指针进入 / 离开

这里的 focus / blur 是拖动生命周期事件，不等同于原生 DOM 聚焦和失焦事件。

Methods 与 Slots

方法	说明
setActive(boolean)	设置选中状态，选中时聚焦根元素
setOverActive(boolean)	设置悬浮状态
setLeft(left) / setTop(top)	修改坐标并按边界约束
setSize(width, height)	设置尺寸并应用最小、最大与边界约束
getState()	返回当前状态对象

default 放置内容，menu 自定义悬浮操作区，参数为 { index, zIndex }。通过实例方法更新状态不会自动等同于用户拖动事件。