@teddyzhu/clipboard 0.0.2 → 0.0.4

package/README.md

@@ -1,35 +1,474 @@
-# `@teddyzhu/clipboard`
+# @teddyzhu/clipboard
 
-![https://github.com/Teddy-Zhu/node-clipboard-rs/actions](https://github.com/Teddy-Zhu/node-clipboard-rs/workflows/CI/badge.svg)
+![CI](https://github.com/Teddy-Zhu/node-clipboard-rs/workflows/CI/badge.svg)
+[![npm version](https://badge.fury.io/js/@teddyzhu%2Fclipboard.svg)](https://www.npmjs.com/package/@teddyzhu/clipboard)
 
-> it's a node package with napi-rs wrapper clipboard-rs
+基于 clipboard-rs 和 napi-rs 的高性能 Node.js 剪贴板操作库，提供跨平台的剪贴板读写和监听功能。
 
-# Usage
+## ✨ 特性
+
+- 🚀 **高性能**: 基于 Rust 原生实现，性能优越
+- 🔄 **实时监听**: 支持剪贴板变化监听，自动检测内容更新
+- 🌐 **跨平台**: 支持 Windows、macOS 和 Linux（包括 Wayland(实验)）
+- 📝 **多格式**: 支持文本、HTML、RTF、图片、文件等多种数据格式
+- ⚡ **异步支持**: 提供同步和异步 API
+- 🖼️ **图片处理**: 完整的图片剪贴板支持，包含尺寸和格式信息
+- 🔧 **自定义格式**: 支持自定义数据格式的读写
+
+## 📦 安装
 
 ```bash
 npm install @teddyzhu/clipboard
 ```
 
+## 🚀 快速开始
+
+### 基本使用
+
 ```javascript
 const { ClipboardManager } = require('@teddyzhu/clipboard')
 
 const clipboard = new ClipboardManager()
 
+// 设置和获取文本
 clipboard.setText('Hello World!')
-console.log(clipboard.getText())
+console.log(clipboard.getText()) // "Hello World!"
+
+// 设置和获取 HTML
+clipboard.setHtml('<h1>Hello HTML</h1>')
+console.log(clipboard.getHtml())
+
+// 检查格式是否可用
+if (clipboard.hasFormat('text')) {
+  console.log('剪贴板包含文本内容')
+}
 ```
 
-listen
+### 图片操作
+
+```javascript
+const { ClipboardManager } = require('@teddyzhu/clipboard')
+
+const clipboard = new ClipboardManager()
+
+// 检查是否有图片
+if (clipboard.hasFormat('image')) {
+  // 获取图片详细信息
+  const imageData = clipboard.getImageData()
+  console.log('图片信息:', {
+    width: imageData.width,
+    height: imageData.height,
+    size: imageData.size,
+    format: 'PNG (base64)'
+  })
+  
+  // 保存图片到文件
+  const fs = require('fs')
+  const imageBuffer = Buffer.from(imageData.base64Data, 'base64')
+  fs.writeFileSync('clipboard-image.png', imageBuffer)
+}
+
+// 从文件设置图片到剪贴板
+const fs = require('fs')
+const imageBuffer = fs.readFileSync('my-image.png')
+const base64Data = imageBuffer.toString('base64')
+clipboard.setImageBase64(base64Data)
+```
+
+### 剪贴板监听
 
 ```javascript
 const { ClipboardListener } = require('@teddyzhu/clipboard')
 
 const listener = new ClipboardListener()
 
-listener.watch((text) => {
-  console.log('剪贴板内容变化:', text)
+listener.watch((data) => {
+  console.log('剪贴板内容变化:')
+  console.log('可用格式:', data.available_formats)
+
+  // 处理文本内容
+  if (data.text) {
+    console.log('📝 文本:', data.text)
+  }
+
+  // 处理 HTML 内容
+  if (data.html) {
+    console.log('🌐 HTML:', data.html)
+  }
+
+  // 处理富文本内容
+  if (data.rtf) {
+    console.log('📄 RTF:', data.rtf)
+  }
+
+  // 处理图片内容
+  if (data.image) {
+    console.log('🖼️  图片信息:')
+    console.log(`   尺寸: ${data.image.width}x${data.image.height}px`)
+    console.log(`   大小: ${data.image.size} bytes`)
+    console.log(`   数据长度: ${data.image.base64_data.length} 字符`)
+  }
+
+  // 处理文件列表
+  if (data.files) {
+    console.log('📁 文件列表:', data.files)
+  }
 })
 
-// stop listen
-listener.stop()
+// 检查监听状态
+console.log('监听器类型:', listener.getListenerType()) // "wayland" 或 "generic"
+console.log('正在监听:', listener.isWatching())
+
+// 停止监听
+// listener.stop()
+```
+
+### 异步操作
+
+```javascript
+const { ClipboardManager } = require('@teddyzhu/clipboard')
+
+const clipboard = new ClipboardManager()
+
+async function asyncClipboardDemo() {
+  try {
+    // 异步设置文本
+    await clipboard.setTextAsync('异步设置的文本')
+    
+    // 异步获取文本
+    const text = await clipboard.getTextAsync()
+    console.log('异步获取的文本:', text)
+    
+    // 异步获取图片
+    if (clipboard.hasFormat('image')) {
+      const imageData = await clipboard.getImageDataAsync()
+      console.log('异步获取的图片信息:', {
+        width: imageData.width,
+        height: imageData.height,
+        size: imageData.size
+      })
+    }
+  } catch (error) {
+    console.error('异步操作失败:', error)
+  }
+}
+
+asyncClipboardDemo()
+```
+
+### 便利函数
+
+```javascript
+const {
+  getClipboardText,
+  setClipboardText,
+  getClipboardHtml,
+  setClipboardHtml,
+  getClipboardImageData,
+  setClipboardImage,
+  getClipboardFiles,
+  setClipboardFiles,
+  getFullClipboardData,
+  clearClipboard,
+  isWaylandClipboardAvailable
+} = require('@teddyzhu/clipboard')
+
+// 快速文本操作
+setClipboardText('快速设置文本')
+console.log(getClipboardText())
+
+// 快速获取完整数据
+const fullData = getFullClipboardData()
+console.log('完整剪贴板数据:', fullData)
+
+// 检查 Wayland 支持
+if (isWaylandClipboardAvailable()) {
+  console.log('当前环境支持 Wayland 剪贴板')
+}
+
+// 清空剪贴板
+clearClipboard()
 ```
+
+### 复合内容操作
+
+```javascript
+const { ClipboardManager } = require('@teddyzhu/clipboard')
+
+const clipboard = new ClipboardManager()
+
+// 同时设置多种格式的内容
+const complexData = {
+  text: '这是纯文本内容',
+  html: '<h1>这是 HTML 内容</h1><p>支持丰富的格式</p>',
+  rtf: '{\\rtf1\\ansi 这是 RTF 格式}',
+  files: ['/path/to/file1.txt', '/path/to/file2.jpg']
+}
+
+clipboard.setContents(complexData)
+
+// 或使用便利函数
+const { setClipboardContents } = require('@teddyzhu/clipboard')
+setClipboardContents(complexData)
+```
+
+## 📖 API 文档
+
+### ClipboardManager 类
+
+用于管理剪贴板操作的主要类。
+
+#### 构造函数
+
+```typescript
+new ClipboardManager(): ClipboardManager
+```
+
+#### 文本操作
+
+```typescript
+getText(): string                    // 获取纯文本
+setText(text: string): void          // 设置纯文本
+getTextAsync(): Promise<string>      // 异步获取纯文本
+setTextAsync(text: string): Promise<void> // 异步设置纯文本
+```
+
+#### HTML 操作
+
+```typescript
+getHtml(): string                    // 获取 HTML 内容
+setHtml(html: string): void          // 设置 HTML 内容
+```
+
+#### 富文本操作
+
+```typescript
+getRichText(): string                // 获取 RTF 富文本
+setRichText(rtf: string): void       // 设置 RTF 富文本
+```
+
+#### 图片操作
+
+```typescript
+getImageBase64(): string             // 获取图片 base64 数据
+getImageData(): ImageData            // 获取图片详细信息
+getImageDataAsync(): Promise<ImageData> // 异步获取图片信息
+setImageBase64(base64: string): void // 设置图片（base64）
+```
+
+#### 文件操作
+
+```typescript
+getFiles(): string[]                 // 获取文件路径列表
+setFiles(files: string[]): void      // 设置文件路径列表
+```
+
+#### 自定义格式操作
+
+```typescript
+getBuffer(format: string): Uint8Array    // 获取自定义格式数据
+setBuffer(format: string, data: Uint8Array): void // 设置自定义格式数据
+```
+
+#### 复合操作
+
+```typescript
+setContents(data: ClipboardData): void   // 设置复合内容
+```
+
+#### 工具方法
+
+```typescript
+hasFormat(format: string): boolean       // 检查格式是否可用
+getAvailableFormats(): string[]          // 获取所有可用格式
+clear(): void                           // 清空剪贴板
+```
+
+### ClipboardListener 类
+
+用于监听剪贴板变化的类。
+
+#### 构造函数
+
+```typescript
+new ClipboardListener(): ClipboardListener
+```
+
+#### 监听控制
+
+```typescript
+watch(callback: (data: ClipboardData) => void): void  // 开始监听
+stop(): void                                          // 停止监听
+isWatching(): boolean                                 // 检查监听状态
+getListenerType(): string                            // 获取监听器类型
+```
+
+### 数据类型
+
+#### ClipboardData
+
+```typescript
+interface ClipboardData {
+  available_formats: string[]     // 可用格式列表
+  text?: string                   // 纯文本内容
+  rtf?: string                    // RTF 富文本内容
+  html?: string                   // HTML 内容
+  image?: ImageData               // 图片数据
+  files?: string[]                // 文件路径列表
+}
+```
+
+#### ImageData
+
+```typescript
+interface ImageData {
+  width: number           // 图片宽度（像素）
+  height: number          // 图片高度（像素）
+  size: number            // 数据大小（字节）
+  base64_data: string     // base64 编码的图片数据
+}
+```
+
+### 便利函数
+
+```typescript
+// 文本操作
+getClipboardText(): string
+setClipboardText(text: string): void
+
+// HTML 操作
+getClipboardHtml(): string
+setClipboardHtml(html: string): void
+
+// 图片操作
+getClipboardImage(): string                    // 获取 base64
+getClipboardImageData(): ImageData             // 获取详细信息
+setClipboardImage(base64: string): void
+
+// 文件操作
+getClipboardFiles(): string[]
+setClipboardFiles(files: string[]): void
+
+// 自定义格式操作
+getClipboardBuffer(format: string): Uint8Array
+setClipboardBuffer(format: string, data: Uint8Array): void
+
+// 复合操作
+getFullClipboardData(): ClipboardData
+setClipboardContents(data: ClipboardData): void
+
+// 工具函数
+clearClipboard(): void
+isWaylandClipboardAvailable(): boolean
+```
+
+## 🌟 特殊功能
+
+### Wayland 支持
+
+本库自动检测运行环境，在 Wayland 桌面环境下会使用专门优化的监听器：
+
+```javascript
+const { isWaylandClipboardAvailable, ClipboardListener } = require('@teddyzhu/clipboard')
+
+if (isWaylandClipboardAvailable()) {
+  console.log('使用 Wayland 优化的剪贴板监听器')
+} else {
+  console.log('使用通用剪贴板监听器')
+}
+
+const listener = new ClipboardListener()
+console.log('监听器类型:', listener.getListenerType())
+```
+
+### 环境检测
+
+```javascript
+// 检测当前环境是否支持 Wayland 剪贴板
+if (isWaylandClipboardAvailable()) {
+  // Wayland 环境下的特殊处理
+}
+```
+
+## 🛠️ 开发环境要求
+
+- **Node.js**: >= 12.0.0
+- **操作系统**: Windows 7+, macOS 10.9+, Linux
+- **Linux 额外要求**:
+  - X11: `libxcb`, `libxcb-shape`, `libxcb-xfixes`
+  - Wayland: `wl-clipboard` 工具
+
+### Linux 依赖安装
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install libxcb1-dev libxcb-shape0-dev libxcb-xfixes0-dev wl-clipboard
+```
+
+**CentOS/RHEL:**
+```bash
+sudo yum install libxcb-devel wl-clipboard
+```
+
+**Arch Linux:**
+```bash
+sudo pacman -S libxcb wl-clipboard
+```
+
+## 🔧 故障排除
+
+### 常见问题
+
+1. **Linux 环境下无法访问剪贴板**
+   - 确保安装了必要的系统依赖
+   - 检查桌面环境是否支持剪贴板操作
+
+2. **Wayland 环境下监听不工作**
+   - 确保安装了 `wl-clipboard` 工具
+   - 检查环境变量 `WAYLAND_DISPLAY` 是否正确设置
+
+3. **图片格式不支持**
+   - 目前支持 PNG、JPEG、GIF、BMP 格式
+   - 图片数据统一转换为 PNG 格式输出
+
+4. **权限问题**
+   - 某些 Linux 发行版可能需要额外的权限配置
+   - 确保应用程序有访问剪贴板的权限
+
+### 调试模式
+
+```javascript
+const { ClipboardManager } = require('@teddyzhu/clipboard')
+
+const clipboard = new ClipboardManager()
+
+try {
+  // 检查可用格式
+  const formats = clipboard.getAvailableFormats()
+  console.log('可用格式:', formats)
+  
+  // 逐一测试各种格式
+  if (clipboard.hasFormat('text')) {
+    console.log('文本内容:', clipboard.getText())
+  }
+  
+  if (clipboard.hasFormat('image')) {
+    const imageData = clipboard.getImageData()
+    console.log('图片信息:', imageData.width, 'x', imageData.height)
+  }
+} catch (error) {
+  console.error('剪贴板操作失败:', error.message)
+}
+```
+
+## 📄 许可证
+
+MIT License - 详见 [LICENSE](LICENSE) 文件。
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📞 支持
+
+如遇问题，请在 [GitHub Issues](https://github.com/Teddy-Zhu/node-clipboard-rs/issues) 中报告。

package/index.d.ts

@@ -2,6 +2,7 @@
 /* eslint-disable */
 /**
  * 剪贴板监听器实例，用于监听剪贴板变化并支持停止
+ * 支持自动检测环境：在 Wayland 环境下使用 Wayland 专用监听器，否则使用通用监听器
  * 使用方法：
  * ```javascript
  * const { ClipboardListener } = require('./index.node');
@@ -21,17 +22,23 @@
  * ```
  */
 export declare class ClipboardListener {
-  /** 创建新的剪贴板监听器实例 */
+  /**
+   * 创建新的剪贴板监听器实例
+   * 自动检测当前环境类型（Wayland 或其他）
+   */
   constructor()
   /**
    * 开始监听剪贴板变化
    * callback: 当剪贴板变化时调用的回调函数，参数为包含所有格式数据的复杂对象
+   * 自动根据当前环境选择合适的监听方式（Wayland 或通用）
    */
   watch(callback: (arg: ClipboardData) => void): void
   /** 停止监听剪贴板变化 */
   stop(): void
   /** 检查是否正在监听 */
   isWatching(): boolean
+  /** 获取当前使用的监听器类型 */
+  getListenerType(): string
 }
 
 /** 剪贴板管理器，提供跨平台的剪贴板操作功能 */
@@ -52,12 +59,20 @@ export declare class ClipboardManager {
   setRichText(text: string): void
   /** 获取剪贴板中的图片数据（以 base64 编码返回） */
   getImageBase64(): string
+  /** 获取剪贴板中的图片详细信息（包含宽度、高度、大小和 base64 数据） */
+  getImageData(): ImageData
   /** 从 base64 编码的图片数据设置剪贴板图片 */
   setImageBase64(base64Data: string): void
   /** 获取剪贴板中的文件列表 */
   getFiles(): Array<string>
   /** 设置剪贴板中的文件列表 */
   setFiles(files: Array<string>): void
+  /** 设置剪贴板中的自定义格式数据 */
+  setBuffer(format: string, buffer: Array<number>): void
+  /** 获取剪贴板中的自定义格式数据 */
+  getBuffer(format: string): Array<number>
+  /** 设置剪贴板中的复合内容（可同时设置多种格式） */
+  setContents(contents: ClipboardData): void
   /** 检查剪贴板是否包含指定格式的内容 */
   hasFormat(format: string): boolean
   /** 获取剪贴板中所有可用的格式 */
@@ -70,6 +85,8 @@ export declare class ClipboardManager {
   setTextAsync(text: string): Promise<void>
   /** 异步获取剪贴板图片数据（以 base64 编码返回） */
   getImageBase64Async(): Promise<string>
+  /** 异步获取剪贴板图片详细信息（包含宽度、高度、大小和 base64 数据） */
+  getImageDataAsync(): Promise<ImageData>
 }
 
 /** 快速清空剪贴板 */
@@ -85,21 +102,61 @@ export interface ClipboardData {
   rtf?: string
   /** HTML 内容 */
   html?: string
-  /** 图片数据（base64 编码） */
-  image?: string
+  /** 图片数据 */
+  image?: ImageData
   /** 文件列表 */
   files?: Array<string>
 }
 
+/** 快速获取剪贴板自定义格式数据 */
+export declare function getClipboardBuffer(format: string): Array<number>
+
+/** 快速获取剪贴板文件列表 */
+export declare function getClipboardFiles(): Array<string>
+
 /** 快速获取剪贴板 HTML 内容 */
 export declare function getClipboardHtml(): string
 
 /** 快速获取剪贴板图片（base64 编码） */
 export declare function getClipboardImage(): string
 
+/** 快速获取剪贴板图片详细信息（包含宽度、高度、大小和 base64 数据） */
+export declare function getClipboardImageData(): ImageData
+
 /** 快速获取剪贴板文本内容 */
 export declare function getClipboardText(): string
 
+/** 快速获取完整的剪贴板数据 */
+export declare function getFullClipboardData(): ClipboardData
+
+/** 图片数据结构，包含图片的详细信息 */
+export interface ImageData {
+  /** 图片宽度（像素） */
+  width: number
+  /** 图片高度（像素） */
+  height: number
+  /** 图片数据大小（字节） */
+  size: number
+  /** 图片数据（base64 编码） */
+  base64Data: string
+}
+
+/**
+ * 检测 Wayland 剪贴板监听是否可用
+ *
+ * 返回 true 表示当前环境支持 Wayland 剪贴板监听
+ */
+export declare function isWaylandClipboardAvailable(): boolean
+
+/** 快速设置剪贴板自定义格式数据 */
+export declare function setClipboardBuffer(format: string, buffer: Array<number>): void
+
+/** 快速设置剪贴板复合内容（可同时设置多种格式） */
+export declare function setClipboardContents(contents: ClipboardData): void
+
+/** 快速设置剪贴板文件列表 */
+export declare function setClipboardFiles(files: Array<string>): void
+
 /** 快速设置剪贴板 HTML 内容 */
 export declare function setClipboardHtml(html: string): void
 

package/index.js

@@ -396,9 +396,17 @@ module.exports = nativeBinding
 module.exports.ClipboardListener = nativeBinding.ClipboardListener
 module.exports.ClipboardManager = nativeBinding.ClipboardManager
 module.exports.clearClipboard = nativeBinding.clearClipboard
+module.exports.getClipboardBuffer = nativeBinding.getClipboardBuffer
+module.exports.getClipboardFiles = nativeBinding.getClipboardFiles
 module.exports.getClipboardHtml = nativeBinding.getClipboardHtml
 module.exports.getClipboardImage = nativeBinding.getClipboardImage
+module.exports.getClipboardImageData = nativeBinding.getClipboardImageData
 module.exports.getClipboardText = nativeBinding.getClipboardText
+module.exports.getFullClipboardData = nativeBinding.getFullClipboardData
+module.exports.isWaylandClipboardAvailable = nativeBinding.isWaylandClipboardAvailable
+module.exports.setClipboardBuffer = nativeBinding.setClipboardBuffer
+module.exports.setClipboardContents = nativeBinding.setClipboardContents
+module.exports.setClipboardFiles = nativeBinding.setClipboardFiles
 module.exports.setClipboardHtml = nativeBinding.setClipboardHtml
 module.exports.setClipboardImage = nativeBinding.setClipboardImage
 module.exports.setClipboardText = nativeBinding.setClipboardText

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teddyzhu/clipboard",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "it's a node package with napi-rs wrapper clipboard-rs",
   "main": "index.js",
   "repository": "git@github.com:Teddy-Zhu/node-clipboard-rs.git",
@@ -101,11 +101,11 @@
   },
   "packageManager": "yarn@4.9.2",
   "optionalDependencies": {
-    "@teddyzhu/clipboard-win32-x64-msvc": "0.0.2",
-    "@teddyzhu/clipboard-darwin-x64": "0.0.2",
-    "@teddyzhu/clipboard-linux-x64-gnu": "0.0.2",
-    "@teddyzhu/clipboard-linux-arm64-gnu": "0.0.2",
-    "@teddyzhu/clipboard-darwin-arm64": "0.0.2",
-    "@teddyzhu/clipboard-win32-arm64-msvc": "0.0.2"
+    "@teddyzhu/clipboard-win32-x64-msvc": "0.0.4",
+    "@teddyzhu/clipboard-darwin-x64": "0.0.4",
+    "@teddyzhu/clipboard-linux-x64-gnu": "0.0.4",
+    "@teddyzhu/clipboard-linux-arm64-gnu": "0.0.4",
+    "@teddyzhu/clipboard-darwin-arm64": "0.0.4",
+    "@teddyzhu/clipboard-win32-arm64-msvc": "0.0.4"
   }
 }