dragable-js
Version:
一个简单易用的js拖动库
254 lines (191 loc) • 5.96 kB
Markdown
# Dragable.js 使用文档 - v1.1.0
## 简介
> Dragable.js 是一个轻量级、易用的 JavaScript 拖动库，支持移动端和 PC 端，提供元素拖动和边缘停靠功能。本库通过扩展 HTMLElement 原型提供简单易用的 API。
- **版本**: 1.1.0
- **许可证**: MIT © 2025 王小玗
- **CDN 地址**:
- [jsDelivr](https://cdn.jsdelivr.net/npm/dragable-js@1.1.0/)
- [unpkg](https://unpkg.com/dragable-js@1.1.0/)
## 安装与引入
### 直接引入 CDN
```html
<script src="https://cdn.jsdelivr.net/npm/dragable-js@1.1.0"></script>
<!-- 或 -->
<script src="https://unpkg.com/dragable-js@1.1.0"></script>
```
### NPM 安装
```bash
npm install dragable-js
```
然后通过模块系统引入:
```javascript
import 'dragable-js';
```
## 基本用法
### 启用拖动
```javascript
const element = document.getElementById('myElement');
element.enableDrag();
```
### 禁用拖动
```javascript
element.disableDrag();
```
## 配置选项
`enableDrag()` 方法接受一个配置对象:
```javascript
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 事件
```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位置
}
```
### 事件监听示例
```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
<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/dragable-js@1.1.0"></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 王小玗