dragable-js
v1.1.0
Published
一个简单易用的js拖动库
Readme
Dragable.js 使用文档 - v1.1.0
简介
Dragable.js 是一个轻量级、易用的 JavaScript 拖动库，支持移动端和 PC 端，提供元素拖动和边缘停靠功能。本库通过扩展 HTMLElement 原型提供简单易用的 API。
安装与引入
直接引入 CDN
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<!-- 或 -->
<script src="https://unpkg.com/[email protected]"></script>NPM 安装
npm install dragable-js然后通过模块系统引入:
import 'dragable-js';基本用法
启用拖动
const element = document.getElementById('myElement');
element.enableDrag();禁用拖动
element.disableDrag();配置选项
enableDrag() 方法接受一个配置对象:
element.enableDrag({
dockable: true, // 是否启用停靠功能，默认true
dockDistance: 20, // 停靠触发距离(px)，默认20
dockAnimationDuration: 300, // 停靠动画时长(ms)，默认300
dockAreas: ['top', 'right', 'bottom', 'left'] // 可停靠区域，默认全部
});选项说明
| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| dockable | boolean | true | 是否启用停靠功能 |
| dockDistance | number | 20 | 距离屏幕边缘多少像素时触发停靠 |
| dockAnimationDuration | number | 300 | 停靠动画时长(毫秒) |
| dockAreas | Array | ['top', 'right', 'bottom', 'left'] | 允许停靠的区域，可设置为部分区域 |
事件系统
Dragable.js 提供了多个自定义事件供监听:
可用事件
dragstart- 拖动开始时触发dragmove- 拖动过程中持续触发dragend- 拖动结束时触发dock- 元素停靠到边缘时触发
事件对象详情
每个事件都包含 detail 属性，提供相关数据:
dragstart 事件
{
x: number, // 鼠标/触摸点的X坐标
y: number // 鼠标/触摸点的Y坐标
}dragmove 事件
{
x: number, // 当前鼠标/触摸点的X坐标
y: number, // 当前鼠标/触摸点的Y坐标
left: number, // 元素当前的left位置
top: number, // 元素当前的top位置
docked: boolean, // 是否已停靠
dockArea: string|null // 停靠区域(null表示未停靠)
}dock 事件
{
area: string, // 停靠区域('top', 'right', 'bottom', 'left'或组合如'top-left')
left: number, // 停靠后的left位置
top: number // 停靠后的top位置
}事件监听示例
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 注意事项
定位要求: 元素需要有
position属性设置为relative、absolute或fixed。如果元素没有设置，库会自动设置为absolute。拖动时类名: 拖动过程中会添加
dragging类名，可用于自定义拖动样式。
.dragging {
/* 拖动时的自定义样式 */
opacity: 0.8;
box-shadow: 0 0 10px rgba(0,0,0,0.5);
}- 停靠动画: 停靠时使用 CSS transition 实现平滑动画，可通过配置修改时长。
完整示例
<!DOCTYPE html>
<html>
<head>
<title>Dragable.js 示例</title>
<style>
#draggable {
width: 100px;
height: 100px;
background-color: #3498db;
color: white;
display: flex;
align-items: center;
justify-content: center;
cursor: move;
user-select: none;
position: absolute;
top: 50px;
left: 50px;
transition: left 0.3s ease-out, top 0.3s ease-out;
}
#draggable.dragging {
opacity: 0.8;
box-shadow: 0 0 10px rgba(0,0,0,0.5);
}
</style>
</head>
<body>
<div id="draggable">拖动我</div>
<script src="https://cdn.jsdelivr.net/npm/[email protected]"></script>
<script>
const draggable = document.getElementById('draggable');
// 启用拖动并配置
draggable.enableDrag({
dockable: true,
dockDistance: 30,
dockAnimationDuration: 200,
dockAreas: ['top', 'left', 'right'] // 不启用底部停靠
});
// 监听事件
draggable.addEventListener('dragstart', (e) => {
console.log('开始拖动', e.detail);
});
draggable.addEventListener('dragmove', (e) => {
console.log('拖动中', e.detail);
});
draggable.addEventListener('dragend', () => {
console.log('拖动结束');
});
draggable.addEventListener('dock', (e) => {
console.log('停靠在', e.detail.area);
});
</script>
</body>
</html>浏览器兼容性
Dragable.js 兼容所有现代浏览器，包括:
- Chrome
- Firefox
- Safari
- Edge
- iOS Safari
- Android Browser
更新日志
v1.1.0
- 新增边缘停靠功能
- 添加配置选项系统
- 新增
dock事件 - 改进边界处理
- 添加停靠动画支持
v1.0.0
- 初始版本
- 基础拖动功能
- 支持移动端和PC端
- 简单的事件系统
许可证
MIT License
Copyright (c) 2025 王小玗