{"_id":"@aggbond/draggable-window","_rev":"2-868551d5b6dfd516df86089bf71e6c1f","name":"@aggbond/draggable-window","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@aggbond/draggable-window","version":"1.0.1","keywords":["draggable","window","float","drag","touch","mobile","vanilla-js","ui","dom","javascript","悬浮窗口","拖拽","前端组件"],"author":{"name":"aGG-Bond"},"license":"MIT","_id":"@aggbond/draggable-window@1.0.1","maintainers":[{"name":"gg_bond","email":"775986968@qq.com"}],"homepage":"https://github.com/aGG-Bond/draggableWindow#readme","bugs":{"url":"https://github.com/aGG-Bond/draggableWindow/issues"},"dist":{"shasum":"98dea474ab3c037c3f61df644f789e69b7e53172","tarball":"https://registry.npmjs.org/@aggbond/draggable-window/-/draggable-window-1.0.1.tgz","fileCount":17,"integrity":"sha512-4VXpJyqRuDbilm1rcBegVYh+Bwi0QcrF6XCctLFMk7Wjit1xl0Mu+NK6ZqzyHKDlTr64/2N+3UpIgAtnynrnBQ==","signatures":[{"sig":"MEUCIQC5c+roNBVXjzkZ1FfiEjojg4DCxcBFut8A4DPF/rF2dQIgPKODCRgXLDeDeaxyB7H0uO3Prhge/R/ByGMXumtuF1o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":125588},"main":"dist/DraggableWindow.common.js","types":"dist/DraggableWindow.d.ts","unpkg":"dist/DraggableWindow.min.js","module":"dist/DraggableWindow.esm.js","browser":"dist/DraggableWindow.min.js","engines":{"node":">=14.0.0"},"gitHead":"c633ce375b08eef209647f5024d67dabd4d2ee8b","scripts":{"test":"echo \"No tests specified\" && exit 0","build":"rollup -c","build:watch":"rollup -c --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"gg_bond","email":"775986968@qq.com"},"jsdelivr":"dist/DraggableWindow.min.js","repository":{"url":"git+https://github.com/aGG-Bond/draggableWindow.git","type":"git"},"_npmVersion":"10.9.2","description":"一个轻量级的 JavaScript 可拖拽浮动窗口插件，支持移动端触摸和 PC 端鼠标操作，具有容器内拖拽和边界约束功能","directories":{},"_nodeVersion":"22.17.1","publishConfig":{"access":"public","provenance":false},"_hasShrinkwrap":false,"devDependencies":{"rollup":"^3.29.0","@rollup/plugin-terser":"^0.4.0","@rollup/plugin-replace":"^5.0.0","@rollup/plugin-commonjs":"^25.0.0","@rollup/plugin-node-resolve":"^15.0.0"},"_npmOperationalInternal":{"tmp":"tmp/draggable-window_1.0.1_1772695105367_0.5320495458443921","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aggbond/draggable-window","version":"1.0.2","description":"一个轻量级的 JavaScript 可拖拽浮动窗口插件，支持移动端触摸和 PC 端鼠标操作，具有容器内拖拽和边界约束功能","publishConfig":{"provenance":false,"access":"public"},"main":"dist/DraggableWindow.common.js","module":"dist/DraggableWindow.esm.js","unpkg":"dist/DraggableWindow.min.js","jsdelivr":"dist/DraggableWindow.min.js","browser":"dist/DraggableWindow.min.js","types":"dist/DraggableWindow.d.ts","scripts":{"build":"rollup -c","build:watch":"rollup -c --watch","prepublishOnly":"npm run build","test":"echo \"No tests specified\" && exit 0"},"repository":{"type":"git","url":"git+https://github.com/aGG-Bond/draggableWindow.git"},"keywords":["draggable","window","float","drag","touch","mobile","vanilla-js","ui","dom","javascript","悬浮窗口","拖拽","前端组件"],"author":{"name":"aGG-Bond"},"license":"MIT","bugs":{"url":"https://github.com/aGG-Bond/draggableWindow/issues"},"homepage":"https://github.com/aGG-Bond/draggableWindow#readme","engines":{"node":">=14.0.0"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.0","@rollup/plugin-node-resolve":"^15.0.0","@rollup/plugin-replace":"^5.0.0","@rollup/plugin-terser":"^0.4.0","rollup":"^3.29.0"},"_id":"@aggbond/draggable-window@1.0.2","gitHead":"06aaa99b5ae0e4e4e068008e5f6011351f9db45b","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-HszrlzmhHLUqEcsbfWSPBAQMKo9hMeNMabYrIwg93MKdeJ0uyc4TqbzVSXonBBLsA6C41cUMdLYYGZfjF4z9NQ==","shasum":"1c2ebb3359919a5229583c0ae64290f91ebed537","tarball":"https://registry.npmjs.org/@aggbond/draggable-window/-/draggable-window-1.0.2.tgz","fileCount":17,"unpackedSize":124158,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBzY45qF2hj6qEmTBnEKaKljCJIZNyhppFLeAMP+QbAsAiAvhb21etAkzFfaTScgU/PX5u0vJ0ZVVBVRAhznXVMJlg=="}]},"_npmUser":{"name":"gg_bond","email":"775986968@qq.com"},"directories":{},"maintainers":[{"name":"gg_bond","email":"775986968@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/draggable-window_1.0.2_1772698513442_0.8143266003720797"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-05T07:18:25.293Z","modified":"2026-03-05T08:15:13.691Z","1.0.1":"2026-03-05T07:18:25.508Z","1.0.2":"2026-03-05T08:15:13.574Z"},"bugs":{"url":"https://github.com/aGG-Bond/draggableWindow/issues"},"author":{"name":"aGG-Bond"},"license":"MIT","homepage":"https://github.com/aGG-Bond/draggableWindow#readme","keywords":["draggable","window","float","drag","touch","mobile","vanilla-js","ui","dom","javascript","悬浮窗口","拖拽","前端组件"],"repository":{"type":"git","url":"git+https://github.com/aGG-Bond/draggableWindow.git"},"description":"一个轻量级的 JavaScript 可拖拽浮动窗口插件，支持移动端触摸和 PC 端鼠标操作，具有容器内拖拽和边界约束功能","maintainers":[{"name":"gg_bond","email":"775986968@qq.com"}],"readme":"# DraggableWindow 可拖拽浮动窗口插件\n\n## 简介\n\nDraggableWindow 是一个轻量级的 JavaScript 插件，用于创建可拖拽的浮动窗口。该插件支持移动端触摸操作和 PC 端鼠标操作，具有智能的拖拽检测、边界约束和容器内拖拽功能。\n\n## 功能特性\n\n- ✅ **全平台兼容**：同时支持移动端触摸和 PC 端鼠标操作\n- ✅ 支持触摸设备的拖拽操作\n- ✅ 支持鼠标拖拽操作（PC 端）\n- ✅ 自动边界检测，防止窗口移出屏幕\n- ✅ 智能区分拖拽和点击操作\n- ✅ 点击时可跳转到指定链接\n- ✅ **支持容器内拖拽**：可限制在特定区域内移动\n- ✅ **可配置边界内边距**：与容器边缘保持指定距离\n- ✅ 轻量级，无依赖\n- ✅ 易于集成和自定义\n\n## 安装和引入\n\n### NPM 安装（推荐）\n```bash\nnpm install @aggbond/draggable-window\n```\n\n### CDN 引入\n```html\n<!-- unpkg -->\n<script src=\"https://unpkg.com/@aggbond/draggable-window/dist/DraggableWindow.min.js\"></script>\n\n<!-- jsDelivr -->\n<script src=\"https://cdn.jsdelivr.net/npm/@aggbond/draggable-window/dist/DraggableWindow.min.js\"></script>\n```\n\n### 直接引入\n```html\n<script src=\"DraggableWindow.js\"></script>\n```\n\n## 跨平台支持\n\n### 移动端（触摸设备）\n- 使用 `touchstart`、`touchmove`、`touchend` 事件\n- 支持多点触控检测\n- 优化的触摸体验\n\n### PC端（鼠标设备）\n- 使用 `mousedown`、`mousemove`、`mouseup` 事件\n- 自动禁用文本选择防止干扰\n- 平滑的鼠标拖拽体验\n\n### 自动检测\n插件会自动检测设备类型并使用相应的事件系统：\n```javascript\n// 内部检测逻辑\nconst isTouchDevice = 'ontouchstart' in window || navigator.maxTouchPoints > 0;\n```\n\n## 使用方式\n\n#### 1. HTML 结构\n```html\n<!-- 基本用法 -->\n<!-- data-url为点击跳转的链接 非必填 -->\n<div id=\"myFloatWindow\" data-url=\"https://www.example.com\">\n    点击我跳转\n</div>\n\n<!-- 或者动态创建 -->\n<div class=\"float-window\">无需点击跳转</div>\n```\n\n#### 2. JavaScript 初始化\n```javascript\n// 初始化单个窗口\nconst floatWindow = document.getElementById('myFloatWindow');\nnew DraggableWindow(floatWindow);\n\n// 批量初始化多个窗口\ndocument.querySelectorAll('.float-window').forEach(element => {\n    new DraggableWindow(element);\n});\n```\n\n#### 3. 高级用法 - 容器内拖拽\n```javascript\n// 限制在特定容器内拖拽 *指定容器需要有相对定位/绝对定位*\nconst container = document.getElementById('myContainer');\nconst floatWindow = document.getElementById('myFloatWindow');\n\nnew DraggableWindow(floatWindow, {\n    container: container  // 指定容器\n});\n\n// 带边界内边距的配置\nnew DraggableWindow(floatWindow, {\n    container: container,\n    padding: 20  // 距离容器边界保持 20px 距离\n});\n```\n\n## API 文档\n\n### 构造函数\n```javascript\nnew DraggableWindow(element, options = {})\n```\n\n**参数：** \n- `element` (HTMLElement): 要转换为可拖拽窗口的 DOM 元素 required\n- `options` (Object): 配置选项对象（可选）\n  - `container` (HTMLElement): 拖拽容器，限制窗口移动范围\n  - `padding` (Number): 距离容器边界的内边距（像素），默认 0\n\n### 配置选项\n\n通过构造函数 options 参数进行配置：\n\n| 选项 | 类型 | 默认值 | 描述 | 适用模式 |\n|------|------|--------|------|----------|\n| `container` | HTMLElement | document.body | 拖拽容器，限制窗口移动范围 | 容器模式 |\n| `padding` | Number | 0 | 距离容器边界的内边距（像素） | 仅容器模式 |\n\n通过元素的 `data-*` 属性进行配置：\n\n| 属性 | 类型 | 默认值 | 描述 |\n|------|------|--------|------|\n| `data-url` | String | '' | 点击时跳转的目标 URL/非必填 |\n\n### 实例方法\n\n该插件主要通过事件监听自动工作，无需手动调用方法。\n\n## 使用示例\n\n### 基础示例\n```\n<!DOCTYPE html>\n<html>\n<head>\n    <title>基础示例</title>\n</head>\n<body>\n    <div id=\"floatBtn\" data-url=\"https://github.com\">GitHub</div>\n    \n    <script src=\"DraggableWindow.js\"></script>\n    <script>\n        // 初始化\n        new DraggableWindow(document.getElementById('floatBtn'));\n    </script>\n</body>\n</html>\n```\n\n### 容器内拖拽示例\n```html\n<div id=\"container\" style=\"width: 400px; height: 400px; position: relative; border: 2px solid #ccc;\">\n    <div id=\"floatWindow\" data-url=\"https://example.com\" \n         style=\"width: 60px; height: 60px; background: #007bff; position: absolute;\">\n        拖动我\n    </div>\n</div>\n\n<script src=\"DraggableWindow.js\"></script>\n<script>\n    const container = document.getElementById('container');\n    const floatWindow = document.getElementById('floatWindow');\n    \n    // 限制在容器内拖拽，距离边界 20px\n    new DraggableWindow(floatWindow, {\n        container: container,\n        padding: 20\n    });\n</script>\n```\n\n### 容器内拖拽的样式要求\n```css\n/* 容器必须设置相对定位 */\n.drag-container {\n    position: relative; /* 关键：作为子元素绝对定位的参照物 */\n    overflow: hidden;   /* 可选：隐藏超出容器的内容 */\n}\n```\n\n## 技术细节\n\n### 拖拽检测机制\n- 使用 10px 的拖动阈值来区分点击和拖拽操作\n- 触摸开始时记录初始位置\n- 移动过程中计算位移距离\n- 超过阈值标记为拖拽状态\n\n### 智能定位切换\n```\n// 根据是否指定容器决定定位方式\nconst isContainerSpecified = options.container && options.container !== document.body;\nelement.style.position = isContainerSpecified ? 'absolute' : 'fixed';\n```\n\n**定位策略说明：**\n- **全局模式**（未指定 container）：使用 `position: fixed`，相对于视口定位\n- **容器模式**（指定 container）：使用 `position: absolute`，相对于容器定位\n  - 页面滚动时，元素保持在容器内的固定位置\n  - 不会随页面滚动而移动\n\n### 边界约束\n\n#### 全局模式（默认）\n- 自动检测视口尺寸\n- 防止窗口移出屏幕边界\n- 保持窗口完全可见\n- 使用 `position: fixed` 定位\n\n#### 容器模式\n- 限制在指定容器内移动\n- 支持可配置的边界内边距（padding）\n- 四个方向统一应用 padding 值\n- 使用 `position: absolute` 相对于容器定位\n- 页面滚动时，元素保持在容器内的固定位置\n\n### 定位策略\n```javascript\n// 根据是否指定容器决定定位方式\nconst isContainerSpecified = options.container && options.container !== document.body;\nelement.style.position = isContainerSpecified ? 'absolute' : 'fixed';\n```\n\n### 事件处理\n- `touchstart` / `mousedown`: 开始拖拽检测\n- `touchmove` / `mousemove`: 更新窗口位置\n- `touchend` / `mouseup`: 结束拖拽并处理点击\n\n## 浏览器兼容性\n\n- ✅ Chrome (移动端/桌面端)\n- ✅ Safari (移动端/桌面端)\n- ✅ Firefox\n- ✅ Edge\n- ✅ Android Browser\n- ✅ iOS Safari\n\n## 注意事项\n\n1. **引入文件**：确保正确引入 `DraggableWindow.js` 文件\n2. 确保目标元素具有明确的定位属性 (`position: fixed` 或 `position: absolute`)\n3. 建议设置合适的 `z-index` 值以确保窗口显示在其他内容之上\n4. 移动端使用时建议添加 `user-select: none` 防止文本选择\n5. 可以通过 CSS 自定义窗口的外观和动画效果\n6. **容器内拖拽时**：\n   - 容器必须设置 `position: relative`（或其他非 static 定位）\n   - 子元素会自动使用 `position: absolute`\n   - padding 配置仅在容器模式下生效\n7. **推荐使用 demo.html 查看完整演示**\n8. **推荐使用 demo1.html 查看区域拖拽演示**\n\n## 许可证\n\nMIT License\n\n## 更新日志\n\n详细的更新记录请查看 [CHANGELOG.md](CHANGELOG.md)。\n\n### v1.0.0 (2026-03-04) - 正式发布 🎉\n\n#### ✨ 核心功能\n- ✅ 全平台拖拽支持（PC 端鼠标 + 移动端触摸）\n- ✅ 智能拖拽检测（基于 10px 阈值区分点击和拖拽）\n- ✅ 边界约束系统（全局模式 + 容器模式）\n- ✅ 定位策略自动切换（fixed/absolute）\n- ✅ 点击跳转功能（data-url 属性）\n\n#### 📦 工程化特性\n- ✅ 多格式打包输出（UMD/ESM/CommonJS）\n- ✅ 生产环境压缩版仅 ~3KB\n- ✅ TypeScript 类型定义支持\n- ✅ NPM 包发布支持\n- ✅ CDN 支持（unpkg/jsDelivr）\n\n#### 📝 完整文档\n- ✅ 详细使用文档和 API 说明\n- ✅ 多个示例页面\n- ✅ 快速开始指南\n- ✅ 发布检查清单\n\n#### 🔧 技术特点\n- ✅ 零依赖，纯原生 JavaScript\n- ✅ 轻量高效，核心代码 205 行\n- ✅ 向后兼容 ES5+\n- ✅ 支持现代主流浏览器\n\n---\n\n**版本**: v1.0.0  \n**最后更新**: 2026-03-04  \n**项目主页**: https://github.com/aGG-Bond/draggableWindow\n","readmeFilename":"README.md"}