electron-drag-plus 1.0.0 → 1.0.2

package/README.md

@@ -1,378 +1,291 @@
-# electron-drag-plus
+# Electron Drag Plus
 
-增强版Electron窗口拖拽库，解决窗口抖动、不同分辨率/缩放导致的闪屏问题，并支持拖拽区域忽略鼠标事件。
+一个极简的 Electron 窗口拖拽增强库，通过简单的 API 实现自定义标题栏的窗口拖拽功能，并内置窗口防抖优化。
 
-## 功能特性
+## 特性
 
-- ✅ 解决Electron原生拖拽可能出现的窗口抖动问题
-- ✅ 修复不同分辨率和显示器缩放导致的拖拽闪屏问题
-- ✅ 智能识别并忽略拖拽区域内的交互元素（按钮、输入框等）
-- ✅ 支持自定义忽略元素选择器
-- ✅ 提供平滑拖拽体验
-- ✅ 支持高DPI显示器
-- ✅ 简单易用的API
-- ✅ TypeScript支持
+- **极简 API**：主进程仅需一个方法，渲染进程仅需两个方法
+- **窗口防抖**：内置窗口拖拽时的防抖优化，解决拖拽时窗口大小抖动问题
+- **自动处理**：自动识别并排除交互元素，避免交互冲突
+- **TypeScript 支持**：提供完整的类型定义
+- **安全可靠**：内置错误处理和延迟初始化，确保在各种环境下稳定运行
 
 ## 安装
 
 ```bash
+# 使用 npm
 npm install electron-drag-plus
-# 或
+
+# 使用 yarn
 yarn add electron-drag-plus
-# 或
+
+# 使用 pnpm
 pnpm add electron-drag-plus
 ```
 
-## 使用方法
-
-### 主进程使用
-
-```javascript
-// 在主进程中
-import { app, BrowserWindow } from 'electron';
-import { DragPlus } from 'electron-drag-plus';
-
-// 创建窗口时初始化拖拽增强
-function createWindow() {
-  const win = new BrowserWindow({
-    width: 800,
-    height: 600,
-    frame: false, // 无边框窗口
-    webPreferences: {
-      nodeIntegration: true,
-      contextIsolation: false
-    }
-  });
-
-  // 初始化拖拽增强
-  const dragPlus = new DragPlus(win, {
-    ignoreSelectors: ['.no-drag', '#close-button'],
-    enableHighDPI: true,
-    smoothDrag: true
-  });
+## API 文档
 
-  // 手动启用特定元素的拖拽
-  dragPlus.enableDrag('.title-bar');
-  
-  // 手动禁用特定元素的拖拽
-  dragPlus.disableDrag('.window-controls');
+### 主进程 API
 
-  win.loadFile('index.html');
-}
+#### `initializeDragPlus(window)`
 
-app.whenReady().then(createWindow);
-```
+初始化窗口拖拽功能。
 
-### 渲染进程使用
+**参数：**
+- `window: BrowserWindow` - Electron 窗口实例
 
-```javascript
-// 在渲染进程中
-import { initDragPlus, setupDraggableArea, enableDrag, disableDrag } from 'electron-drag-plus/dist/renderer';
-
-// 初始化拖拽功能
-initDragPlus({
-  ignoreSelectors: ['.no-drag', '.button'],
-  enableHighDPI: true,
-  smoothDrag: true
+**示例：**
+```typescript
+import { BrowserWindow } from 'electron';
+import { initializeDragPlus } from 'electron-drag-plus';
+
+// 创建窗口
+const mainWindow = new BrowserWindow({
+  width: 800,
+  height: 600,
+  frame: false, // 无边框窗口
+  webPreferences: {
+    contextIsolation: true,
+    nodeIntegration: false,
+    preload: path.join(__dirname, 'preload.js')
+  }
 });
 
-// 方法1: 设置整个区域为可拖拽，并自动忽略交互元素
-setupDraggableArea('.title-bar');
-
-// 方法2: 手动为元素启用拖拽
-const header = document.getElementById('app-header');
-enableDrag(header, { ignoreChildren: true });
-
-// 方法3: 手动为元素禁用拖拽
-const closeButton = document.getElementById('close-btn');
-disableDrag(closeButton);
+// 初始化拖拽功能 - 无需key参数
+initializeDragPlus(mainWindow);
 ```
 
-### 在现代框架中使用
-
-#### Vue 3 (Composition API)
-
-```vue
-<template>
-  <div class="app">
-    <div ref="titleBar" class="title-bar">
-      <h1>应用标题</h1>
-      <div class="window-controls">
-        <button @click="minimize">-</button>
-        <button @click="maximize">□</button>
-        <button @click="close">×</button>
-      </div>
-    </div>
-    <div class="content">
-      <!-- 应用内容 -->
-    </div>
-  </div>
-</template>
-
-<script setup>
-import { ref, onMounted } from 'vue';
-import { setupDraggableArea } from 'electron-drag-plus/dist/renderer';
-
-// 使用 ref 获取DOM元素
-const titleBar = ref(null);
+### 渲染进程 API
 
-// 窗口控制函数
-const minimize = () => {
-  window.electron.ipcRenderer.send('window:minimize');
-};
+#### `enableWindowDrag(element)`
 
-const maximize = () => {
-  window.electron.ipcRenderer.send('window:maximize');
-};
+启用指定元素的窗口拖拽功能。
 
-const close = () => {
-  window.electron.ipcRenderer.send('window:close');
-};
+**参数：**
+- `element: HTMLElement | string` - DOM 元素或 CSS 选择器
 
-// 组件挂载后设置拖拽区域
-onMounted(() => {
-  if (titleBar.value) {
-    setupDraggableArea(titleBar.value);
-  }
-});
-</script>
-
-<style scoped>
-.title-bar {
-  height: 40px;
-  background: #333;
-  color: white;
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  padding: 0 10px;
-  user-select: none;
-}
+**示例：**
+```typescript
+import { enableWindowDrag } from 'electron-drag-plus/renderer';
 
-.window-controls button {
-  width: 30px;
-  height: 30px;
-  background: none;
-  border: none;
-  color: white;
-  cursor: pointer;
-}
+// 使用 CSS 选择器
+enableWindowDrag('#title-bar');
 
-/* 确保按钮不会触发拖拽 */
-.window-controls button {
-  -webkit-app-region: no-drag;
+// 或使用 DOM 元素
+const titleBar = document.getElementById('title-bar');
+if (titleBar instanceof HTMLElement) {
+  enableWindowDrag(titleBar);
 }
-</style>
 ```
 
-#### Vue 3 组合式函数封装
+#### `disableWindowDrag(element)`
 
-```vue
-<script setup>
-import { ref, onMounted, onUnmounted } from 'vue';
-import { setupDraggableArea, destroyDragPlus } from 'electron-drag-plus/dist/renderer';
+禁用指定元素的窗口拖拽功能。
 
-// 创建可拖拽标题栏组件
-const titleBar = ref(null);
+**参数：**
+- `element: HTMLElement | string` - DOM 元素或 CSS 选择器
 
-// 组件挂载时初始化拖拽
-onMounted(() => {
-  if (titleBar.value) {
-    setupDraggableArea(titleBar.value);
-  }
-});
-
-// 组件卸载时清理
-onUnmounted(() => {
-  // 如果需要全局清理
-  // destroyDragPlus();
-});
-</script>
-```
-
-#### React
-
-```jsx
-import React, { useEffect, useRef } from 'react';
-import { setupDraggableArea } from 'electron-drag-plus/dist/renderer';
+**示例：**
+```typescript
+import { disableWindowDrag } from 'electron-drag-plus/renderer';
 
-function App() {
-  const titleBarRef = useRef(null);
-  
-  useEffect(() => {
-    // 设置标题栏为可拖拽区域
-    if (titleBarRef.current) {
-      setupDraggableArea(titleBarRef.current);
-    }
-  }, []);
-  
-  const minimize = () => {
-    window.electron.ipcRenderer.send('window:minimize');
-  };
-  
-  const maximize = () => {
-    window.electron.ipcRenderer.send('window:maximize');
-  };
-  
-  const close = () => {
-    window.electron.ipcRenderer.send('window:close');
-  };
-  
-  return (
-    <div className="app">
-      <div ref={titleBarRef} className="title-bar">
-        <h1>应用标题</h1>
-        <div className="window-controls">
-          <button onClick={minimize}>-</button>
-          <button onClick={maximize}>□</button>
-          <button onClick={close}>×</button>
-        </div>
-      </div>
-      <div className="content">
-        {/* 应用内容 */}
-      </div>
-    </div>
-  );
+// 禁用按钮的拖拽，使其可以正常点击
+const closeButton = document.getElementById('close-button');
+if (closeButton instanceof HTMLElement) {
+  disableWindowDrag(closeButton);
 }
-
-export default App;
 ```
 
-#### React 自定义Hook
+## 完整示例
+
+### 主进程示例 (main.js)
 
-```jsx
-import { useEffect } from 'react';
-import { setupDraggableArea } from 'electron-drag-plus/dist/renderer';
+```javascript
+const { app, BrowserWindow } = require('electron');
+const path = require('path');
+const { initializeDragPlus } = require('electron-drag-plus');
 
-// 创建一个自定义Hook来管理拖拽区域
-export function useDraggable(ref) {
-  useEffect(() => {
-    if (ref.current) {
-      setupDraggableArea(ref.current);
+function createWindow() {
+  const mainWindow = new BrowserWindow({
+    width: 800,
+    height: 600,
+    frame: false, // 无边框窗口
+    webPreferences: {
+      preload: path.join(__dirname, 'preload.js'),
+      contextIsolation: true,
+      nodeIntegration: false
     }
-  }, [ref]);
-}
+  });
 
-// 使用示例
-function DraggableTitleBar() {
-  const titleBarRef = useRef(null);
-  useDraggable(titleBarRef);
-  
-  return (
-    <div ref={titleBarRef} className="title-bar">
-      <h1>拖拽标题栏</h1>
-    </div>
-  );
+  // 初始化拖拽功能 - 简化版，无需key参数
+  initializeDragPlus(mainWindow);
+
+  // 加载页面
+  mainWindow.loadFile('index.html');
 }
 
-## API 参考
+app.whenReady().then(() => {
+  createWindow();
 
-### 主进程 API
-
-#### DragPlus 类
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow();
+  });
+});
 
-```typescript
-constructor(window: BrowserWindow, options?: DragPlusOptions);
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});
 ```
 
-**参数**:
-- `window`: Electron BrowserWindow 实例
-- `options`: 配置选项
-  - `ignoreSelectors`: 忽略的CSS选择器数组
-  - `enableHighDPI`: 是否启用高DPI支持
-  - `smoothDrag`: 是否启用平滑拖拽
-
-**方法**:
-
-- `enableDrag(elementSelector: string)`: 为指定选择器的元素启用拖拽
-- `disableDrag(elementSelector: string)`: 为指定选择器的元素禁用拖拽
-- `updateOptions(newOptions: Partial<DragPlusOptions>)`: 更新配置选项
-- `static getInstance(webContentsId: number)`: 获取特定webContents的DragPlus实例
+### 预加载脚本 (preload.js)
 
-### 渲染进程 API
-
-#### 初始化
+```javascript
+// 预加载脚本，用于暴露必要的API给渲染进程
+const { contextBridge, ipcRenderer } = require('electron');
 
-```typescript
-function initDragPlus(options?: RendererDragOptions): void;
+contextBridge.exposeInMainWorld('electron', {
+  // 这里可以暴露其他必要的API
+});
 ```
 
-**参数**:
-- `options`: 配置选项，与主进程相同
-
-#### 拖拽管理
+### 渲染进程示例 (renderer.js)
 
-```typescript
-// 设置可拖拽区域，自动忽略交互元素
-function setupDraggableArea(container: HTMLElement | string): void;
+```javascript
+import { enableWindowDrag, disableWindowDrag } from 'electron-drag-plus/renderer';
 
-// 为元素启用拖拽
-function enableDrag(element: HTMLElement | string, options?: { ignoreChildren?: boolean }): void;
+// 启用标题栏拖拽功能 - 简化版，无需key参数
+const titleBar = document.getElementById('title-bar');
+if (titleBar) {
+  enableWindowDrag(titleBar);
+}
 
-// 为元素禁用拖拽
-function disableDrag(element: HTMLElement | string): void;
+// 禁用控制按钮的拖拽
+const minimizeButton = document.getElementById('minimize-button');
+const maximizeButton = document.getElementById('maximize-button');
+const closeButton = document.getElementById('close-button');
 
-// 更新配置选项
-function updateDragPlusOptions(options: Partial<RendererDragOptions>): void;
+if (minimizeButton) disableWindowDrag(minimizeButton);
+if (maximizeButton) disableWindowDrag(maximizeButton);
+if (closeButton) disableWindowDrag(closeButton);
 
-// 销毁拖拽管理器
-function destroyDragPlus(): void;
+// 添加窗口控制功能
+closeButton?.addEventListener('click', () => {
+  window.close();
+});
 ```
 
-## 常见问题
-
-### 1. 拖拽区域内的按钮无法点击
-
-确保为按钮元素设置了`no-drag`样式：
-
-```css
-.button {
-  -webkit-app-region: no-drag;
-}
+### HTML 示例
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <title>Electron Drag Plus Example</title>
+  <style>
+    body {
+      margin: 0;
+      font-family: Arial, sans-serif;
+    }
+    
+    #title-bar {
+      height: 32px;
+      background-color: #252525;
+      color: white;
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0 8px;
+    }
+    
+    .title {
+      font-size: 14px;
+    }
+    
+    .controls {
+      display: flex;
+      gap: 8px;
+    }
+    
+    button {
+      width: 24px;
+      height: 24px;
+      border: none;
+      border-radius: 4px;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      cursor: pointer;
+    }
+    
+    #close-button {
+      background-color: #ff5f56;
+    }
+    
+    #minimize-button {
+      background-color: #ffbd2e;
+    }
+    
+    #maximize-button {
+      background-color: #27c93f;
+    }
+    
+    #content {
+      padding: 16px;
+    }
+  </style>
+</head>
+<body>
+  <div id="title-bar">
+    <div class="title">Electron Drag Plus Example</div>
+    <div class="controls">
+      <button id="minimize-button"></button>
+      <button id="maximize-button"></button>
+      <button id="close-button"></button>
+    </div>
+  </div>
+  <div id="content">
+    <h1>自定义标题栏示例</h1>
+    <p>拖动上方标题栏可以移动窗口</p>
+  </div>
+  
+  <script src="renderer.js"></script>
+</body>
+</html>
 ```
 
-或者使用`setupDraggableArea`函数，它会自动为交互元素添加`no-drag`。
+## 窗口防抖机制
 
-### 2. 在高DPI显示器上拖拽仍然有问题
+该库内置了窗口防抖优化，解决了 Electron 拖拽时窗口大小抖动的问题。实现方式包括：
 
-确保在创建`DragPlus`实例时启用了高DPI支持：
+1. **临时禁用窗口调整大小**：拖拽开始时保存窗口原始可调整大小状态，并临时禁用调整大小功能
+2. **强制写回窗口尺寸**：拖拽过程中强制保持窗口尺寸不变
+3. **恢复原始状态**：拖拽结束后恢复窗口原始的可调整大小状态
 
-```javascript
-const dragPlus = new DragPlus(win, {
-  enableHighDPI: true
-});
-```
+## 注意事项
 
-### 3. 窗口拖拽时仍然有抖动
+1. **初始化时机**：确保在窗口创建后、加载页面之前初始化拖拽功能
 
-尝试调整`smoothDrag`选项，或者检查是否有其他事件监听器干扰拖拽行为：
+2. **WebPreferences 配置**：在创建窗口时，需要正确配置 webPreferences：
+   - 建议启用 `contextIsolation: true` 和 `nodeIntegration: false` 以增强安全性
+   - 如需要在渲染进程中使用 Electron API，请通过预加载脚本暴露必要的功能
 
-```javascript
-const dragPlus = new DragPlus(win, {
-  smoothDrag: true
-});
-```
+3. **元素识别**：库会自动识别并排除常见的交互元素（如按钮、输入框等），避免交互冲突
 
-## 开发
+4. **错误处理**：库内置了基本的错误处理和日志警告，便于调试
 
-```bash
-# 安装依赖
-pnpm install
-
-# 开发模式
-pnpm run dev
+5. **DOM 就绪**：库会自动检测 DOM 就绪状态，确保在合适的时机初始化
 
-# 构建
-pnpm run build
+## 兼容性
 
-# 运行测试
-pnpm run test
-```
+- 支持 Electron 13.x 及以上版本
+- 支持 Windows、macOS 和 Linux 平台
+- 需要 TypeScript 4.0+（如果使用 TypeScript）
 
 ## 许可证
 
-[MIT](LICENSE)
+MIT License
 
 ## 贡献
 
-欢迎提交Issue和Pull Request！
+欢迎提交 Issues 和 Pull Requests！

package/dist/example.d.ts

@@ -1 +1,4 @@
+/**
+ * electron-drag-plus 简化版API使用示例
+ */
 export {};