Files
vue-desktop/src/core/utils/Draggable.ts
T

328 lines
9.6 KiB
TypeScript
Raw Normal View History

2025-09-01 16:31:47 +08:00
type TDragStartCallback = (x: number, y: number) => void;
type TDragMoveCallback = (x: number, y: number) => void;
type TDragEndCallback = (x: number, y: number) => void;
/**
* 拖拽参数
*/
interface IDraggableOptions {
/** 用来触发拖拽的元素、句柄 */
handle: HTMLElement;
/** 真正移动的元素 */
target: HTMLElement;
/** 拖拽模式 */
mode?: 'transform' | 'position';
/** 拖拽的边界或容器元素 */
2025-09-02 11:14:38 +08:00
boundary?: IBoundaryRect | HTMLElement;
/** 移动步进(网格吸附) */
snapGrid?: number;
/** 关键点吸附(边界/中心等) */
snapThreshold?: number;
/** 是否开启吸附动画(拖拽结束时) */
snapAnimation?: boolean;
/** 拖拽结束时吸附动画时长(ms,默认 200) */
snapAnimationDuration?: number;
/** 是否允许拖拽超出容器范围 */
allowOverflow?: boolean;
2025-09-01 16:31:47 +08:00
/** 拖拽开始回调 */
onStart?: TDragStartCallback;
/** 拖拽移动中回调 */
onMove?: TDragMoveCallback;
/** 拖拽结束回调 */
onEnd?: TDragEndCallback;
}
/** 拖拽的范围边界 */
2025-09-02 11:14:38 +08:00
interface IBoundaryRect {
2025-09-01 16:31:47 +08:00
/** 最小 X 坐标 */
minX?: number;
/** 最大 X 坐标 */
maxX?: number;
/** 最小 Y 坐标 */
minY?: number;
/** 最大 Y 坐标 */
maxY?: number;
}
/**
* 拖拽功能通用类
*/
export class Draggable {
private handle: HTMLElement;
private target: HTMLElement;
2025-09-02 11:14:38 +08:00
private boundary?: HTMLElement | IBoundaryRect;
private mode: "transform" | "position";
private snapGrid: number;
private snapThreshold: number;
2025-09-01 16:31:47 +08:00
private onStart?: TDragStartCallback;
private onMove?: TDragMoveCallback;
private onEnd?: TDragEndCallback;
2025-09-02 11:14:38 +08:00
private snapAnimation: boolean;
private snapAnimationDuration: number;
private allowOverflow: boolean;
2025-09-01 16:31:47 +08:00
2025-09-02 11:14:38 +08:00
private isDragging = false;
private startX = 0;
private startY = 0;
private offsetX = 0;
private offsetY = 0;
private currentX = 0;
private currentY = 0;
private containerRect?: DOMRect;
2025-09-01 16:31:47 +08:00
private resizeObserver?: ResizeObserver;
2025-09-02 11:14:38 +08:00
private mutationObserver: MutationObserver;
/** 动画控制 */
private animationFrame?: number;
2025-09-01 16:31:47 +08:00
constructor(options: IDraggableOptions) {
this.handle = options.handle;
this.target = options.target;
2025-09-02 11:14:38 +08:00
this.boundary = options.boundary;
this.mode = options.mode ?? "transform";
this.snapGrid = options.snapGrid ?? 1;
this.snapThreshold = options.snapThreshold ?? 0;
this.snapAnimation = options.snapAnimation ?? false;
this.snapAnimationDuration = options.snapAnimationDuration ?? 200;
this.allowOverflow = options.allowOverflow ?? true;
2025-09-01 16:31:47 +08:00
this.onStart = options.onStart;
this.onMove = options.onMove;
this.onEnd = options.onEnd;
2025-09-02 11:14:38 +08:00
// 自动监听 DOM 移除
this.mutationObserver = new MutationObserver(() => {
if (!document.body.contains(this.target)) {
this.destroy();
2025-09-01 16:31:47 +08:00
}
});
2025-09-02 11:14:38 +08:00
this.mutationObserver.observe(document.body, { childList: true, subtree: true });
2025-09-01 16:31:47 +08:00
2025-09-02 11:14:38 +08:00
this.init();
2025-09-01 16:31:47 +08:00
}
2025-09-02 11:14:38 +08:00
/** 初始化事件 */
private init() {
this.handle.addEventListener("mousedown", this.onMouseDown);
if (this.boundary instanceof HTMLElement) {
this.observeResize(this.boundary);
2025-09-01 16:31:47 +08:00
}
}
2025-09-02 11:14:38 +08:00
/** 销毁 */
public destroy() {
this.handle.removeEventListener("mousedown", this.onMouseDown);
document.removeEventListener("mousemove", this.onMouseMove);
document.removeEventListener("mouseup", this.onMouseUp);
this.resizeObserver?.disconnect();
if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
this.mutationObserver.disconnect();
}
/** 开始拖拽 */
2025-09-01 16:31:47 +08:00
private onMouseDown = (e: MouseEvent) => {
e.preventDefault();
2025-09-02 11:14:38 +08:00
this.isDragging = true;
2025-09-01 16:31:47 +08:00
this.startX = e.clientX;
this.startY = e.clientY;
2025-09-02 11:14:38 +08:00
if (this.mode === "position") {
const rect = this.target.getBoundingClientRect();
this.offsetX = rect.left;
this.offsetY = rect.top;
2025-09-01 16:31:47 +08:00
} else {
2025-09-02 11:14:38 +08:00
this.offsetX = this.currentX;
this.offsetY = this.currentY;
2025-09-01 16:31:47 +08:00
}
2025-09-02 11:14:38 +08:00
document.addEventListener("mousemove", this.onMouseMove);
document.addEventListener("mouseup", this.onMouseUp);
2025-09-01 16:31:47 +08:00
2025-09-02 11:14:38 +08:00
this.onStart?.(this.offsetX, this.offsetY);
2025-09-01 16:31:47 +08:00
};
2025-09-02 11:14:38 +08:00
/** 拖拽中(实时移动,不做吸附) */
private onMouseMove = (e: MouseEvent) => {
if (!this.isDragging) return;
const dx = e.clientX - this.startX;
const dy = e.clientY - this.startY;
let newX = this.offsetX + dx;
let newY = this.offsetY + dy;
if (this.snapGrid > 1) {
newX = Math.round(newX / this.snapGrid) * this.snapGrid;
newY = Math.round(newY / this.snapGrid) * this.snapGrid;
}
this.applyPosition(newX, newY, false);
this.onMove?.(newX, newY);
};
/** 拖拽结束(此时再执行吸附动画) */
2025-09-01 16:31:47 +08:00
private onMouseUp = () => {
2025-09-02 11:14:38 +08:00
if (!this.isDragging) return;
this.isDragging = false;
2025-09-01 16:31:47 +08:00
2025-09-02 11:14:38 +08:00
const snapped = this.applySnapping(this.currentX, this.currentY);
2025-09-01 16:31:47 +08:00
2025-09-02 11:14:38 +08:00
if (this.snapAnimation) {
// 使用动画过渡到吸附点
this.animateTo(snapped.x, snapped.y, this.snapAnimationDuration, () => {
this.onEnd?.(snapped.x, snapped.y);
});
} else {
this.applyPosition(snapped.x, snapped.y, true);
this.onEnd?.(snapped.x, snapped.y);
}
document.removeEventListener("mousemove", this.onMouseMove);
document.removeEventListener("mouseup", this.onMouseUp);
2025-09-01 16:31:47 +08:00
};
2025-09-02 11:14:38 +08:00
/** 应用位置 */
private applyPosition(x: number, y: number, isFinal: boolean) {
this.currentX = x;
this.currentY = y;
if (this.mode === "position") {
this.target.style.left = `${x}px`;
this.target.style.top = `${y}px`;
} else {
this.target.style.transform = `translate(${x}px, ${y}px)`;
}
if (isFinal) {
this.applyBoundary();
}
}
/** 平滑动画移动到目标位置 */
private animateTo(targetX: number, targetY: number, duration: number, onComplete?: () => void) {
if (this.animationFrame) cancelAnimationFrame(this.animationFrame);
const startX = this.currentX;
const startY = this.currentY;
const deltaX = targetX - startX;
const deltaY = targetY - startY;
const startTime = performance.now();
const step = (now: number) => {
const elapsed = now - startTime;
const progress = Math.min(elapsed / duration, 1);
// 缓动函数(easeOutCubic)
const ease = 1 - Math.pow(1 - progress, 3);
const x = startX + deltaX * ease;
const y = startY + deltaY * ease;
this.applyPosition(x, y, false);
this.onMove?.(x, y);
if (progress < 1) {
this.animationFrame = requestAnimationFrame(step);
} else {
this.applyPosition(targetX, targetY, true);
this.onMove?.(targetX, targetY);
onComplete?.();
}
};
this.animationFrame = requestAnimationFrame(step);
}
/** 应用边界限制 */
private applyBoundary() {
if (!this.boundary || this.allowOverflow) return;
let { x, y } = { x: this.currentX, y: this.currentY };
if (this.boundary instanceof HTMLElement && this.containerRect) {
const rect = this.target.getBoundingClientRect();
const minX = 0;
const minY = 0;
const maxX = this.containerRect.width - rect.width;
const maxY = this.containerRect.height - rect.height;
x = Math.min(Math.max(x, minX), maxX);
y = Math.min(Math.max(y, minY), maxY);
} else if (!(this.boundary instanceof HTMLElement)) {
if (this.boundary.minX !== undefined) x = Math.max(x, this.boundary.minX);
if (this.boundary.maxX !== undefined) x = Math.min(x, this.boundary.maxX);
if (this.boundary.minY !== undefined) y = Math.max(y, this.boundary.minY);
if (this.boundary.maxY !== undefined) y = Math.min(y, this.boundary.maxY);
}
this.currentX = x;
this.currentY = y;
this.applyPosition(x, y, false);
}
/** 计算吸附点 */
private applySnapping(x: number, y: number): { x: number; y: number } {
const snapPoints = this.getSnapPoints();
let snappedX = x;
let snappedY = y;
if (this.snapThreshold > 0) {
for (const sx of snapPoints.x) {
if (Math.abs(x - sx) <= this.snapThreshold) {
snappedX = sx;
break;
}
}
for (const sy of snapPoints.y) {
if (Math.abs(y - sy) <= this.snapThreshold) {
snappedY = sy;
break;
}
}
}
return { x: snappedX, y: snappedY };
}
/** 获取吸附点 */
private getSnapPoints(): { x: number[]; y: number[] } {
const snapX: number[] = [];
const snapY: number[] = [];
if (this.boundary instanceof HTMLElement && this.containerRect) {
const containerRect = this.containerRect;
const targetRect = this.target.getBoundingClientRect();
// 左右边界
snapX.push(0);
snapX.push(containerRect.width - targetRect.width);
// 上下边界
snapY.push(0);
snapY.push(containerRect.height - targetRect.height);
// 中心点
// snapX.push(containerRect.width / 2 - targetRect.width / 2);
// snapY.push(containerRect.height / 2 - targetRect.height / 2);
} else if (!(this.boundary instanceof HTMLElement)) {
if (this.boundary?.minX !== undefined) snapX.push(this.boundary.minX);
if (this.boundary?.maxX !== undefined) snapX.push(this.boundary.maxX);
if (this.boundary?.minY !== undefined) snapY.push(this.boundary.minY);
if (this.boundary?.maxY !== undefined) snapY.push(this.boundary.maxY);
}
return { x: snapX, y: snapY };
}
/** 监听 boundary 尺寸变化 */
private observeResize(element: HTMLElement) {
this.resizeObserver = new ResizeObserver(() => {
this.containerRect = element.getBoundingClientRect();
});
this.resizeObserver.observe(element);
this.containerRect = element.getBoundingClientRect();
2025-09-01 16:31:47 +08:00
}
}