Dragable.js 使用文档 - v1.1.0

简介

> Dragable.js 是一个轻量级、易用的 JavaScript 拖动库，支持移动端和 PC 端，提供元素拖动和边缘停靠功能。本库通过扩展 HTMLElement 原型提供简单易用的 API。

- 版本: 1.1.0
- 许可证: MIT © 2025 王小玗
- CDN 地址:
- jsDelivr
- unpkg

安装与引入

$3

``html



`

$3

`bash
npm install dragable-js
`

然后通过模块系统引入:

`javascript
import 'dragable-js';
`

基本用法

$3

`javascript
const element = document.getElementById('myElement');
element.enableDrag();
`

$3

`javascript
element.disableDrag();
`

配置选项

enableDrag() 方法接受一个配置对象:

`javascript
element.enableDrag({
dockable: true, // 是否启用停靠功能，默认true
dockDistance: 20, // 停靠触发距离(px)，默认20
dockAnimationDuration: 300, // 停靠动画时长(ms)，默认300
dockAreas: ['top', 'right', 'bottom', 'left'] // 可停靠区域，默认全部
});
`

$3

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| dockable | boolean | true | 是否启用停靠功能 |
| dockDistance | number | 20 | 距离屏幕边缘多少像素时触发停靠 |
| dockAnimationDuration | number | 300 | 停靠动画时长(毫秒) |
| dockAreas | Array | ['top', 'right', 'bottom', 'left'] | 允许停靠的区域，可设置为部分区域 |

事件系统

Dragable.js 提供了多个自定义事件供监听:

$3

- dragstart - 拖动开始时触发
- dragmove - 拖动过程中持续触发
- dragend - 拖动结束时触发
- dock - 元素停靠到边缘时触发

$3

每个事件都包含 detail 属性，提供相关数据:

#### dragstart 事件

`javascript
{
x: number, // 鼠标/触摸点的X坐标
y: number // 鼠标/触摸点的Y坐标
}
`

#### dragmove 事件

`javascript
{
x: number, // 当前鼠标/触摸点的X坐标
y: number, // 当前鼠标/触摸点的Y坐标
left: number, // 元素当前的left位置
top: number, // 元素当前的top位置
docked: boolean, // 是否已停靠
dockArea: string|null // 停靠区域(null表示未停靠)
}
`

#### dock 事件

`javascript
{
area: string, // 停靠区域('top', 'right', 'bottom', 'left'或组合如'top-left')
left: number, // 停靠后的left位置
top: number // 停靠后的top位置
}
`

$3

`javascript
element.addEventListener('dragstart', (e) => {
console.log('开始拖动', e.detail);
});

element.addEventListener('dragmove', (e) => {
console.log('拖动中', e.detail);
});

element.addEventListener('dragend', () => {
console.log('拖动结束');
});

element.addEventListener('dock', (e) => {
console.log('停靠在', e.detail.area);
});
`

CSS 注意事项

1. 定位要求: 元素需要有 position 属性设置为 relative、absolute 或 fixed。如果元素没有设置，库会自动设置为 absolute。

2. 拖动时类名: 拖动过程中会添加 dragging 类名，可用于自定义拖动样式。

`css
.dragging {
/ 拖动时的自定义样式 /
opacity: 0.8;
box-shadow: 0 0 10px rgba(0,0,0,0.5);
}
`

3. 停靠动画: 停靠时使用 CSS transition 实现平滑动画，可通过配置修改时长。

完整示例

`html















`

浏览器兼容性

Dragable.js 兼容所有现代浏览器，包括:

- Chrome
- Firefox
- Safari
- Edge
- iOS Safari
- Android Browser

更新日志

$3

- 新增边缘停靠功能
- 添加配置选项系统
- 新增 dock` 事件
- 改进边界处理
- 添加停靠动画支持

$3

- 初始版本
- 基础拖动功能
- 支持移动端和PC端
- 简单的事件系统

许可证

MIT License

Copyright (c) 2025 王小玗