Package Exports

dragable-js
dragable-js/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (dragable-js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Dragable.js 使用文档 - v1.1.0

简介

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

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

安装与引入

直接引入 CDN

<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 安装

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/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