Package Exports

@teddyzhu/clipboard
@teddyzhu/clipboard/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 (@teddyzhu/clipboard) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

`@teddyzhu/clipboard`

基于 napi-rs 包装 clipboard-rs/wl-clipboard-rs 的 Node.js 剪贴板库，提供跨平台剪贴板操作功能

特性

🚀 跨平台支持（Windows、macOS、Linux）
📝 支持多种数据格式：文本、HTML、 RTF、图片、文件列表
🖼️ 完整的图片处理支持（PNG、JPEG、GIF、BMP）
👂 剪贴板实时监听功能
🐧 Linux Wayland 环境原生支持
⚡ 同步和异步 API
🎯 TypeScript 类型定义

安装

npm install @teddyzhu/clipboard

基本使用

剪贴板管理器

const { ClipboardManager } = require('@teddyzhu/clipboard')

const clipboard = new ClipboardManager()

// 文本操作
clipboard.setText('Hello World!')
console.log(clipboard.getText()) // "Hello World!"

// HTML 操作
clipboard.setHtml('<h1>Hello HTML</h1>')
console.log(clipboard.getHtml())

// 富文本（RTF）操作
clipboard.setRichText('Hello RTF')
console.log(clipboard.getRichText())

// 检查格式支持
console.log(clipboard.hasFormat('text')) // true
console.log(clipboard.getAvailableFormats()) // ['text', 'html', ...]

// 清空剪贴板
clipboard.clear()

快速操作函数

const {
  getClipboardText,
  setClipboardText,
  getClipboardHtml,
  setClipboardHtml,
  clearClipboard,
  getFullClipboardData,
} = require('@teddyzhu/clipboard')

// 快速文本操作
setClipboardText('Hello World!')
console.log(getClipboardText())

// 快速 HTML 操作
setClipboardHtml('<p>Hello HTML</p>')
console.log(getClipboardHtml())

// 获取完整剪贴板数据
const data = getFullClipboardData()
console.log('可用格式:', data.availableFormats)
console.log('文本内容:', data.text)
console.log('HTML内容:', data.html)

// 清空剪贴板
clearClipboard()

图片操作

基本图片操作

const { ClipboardManager, getClipboardImageData } = require('@teddyzhu/clipboard')
const fs = require('fs')

const clipboard = new ClipboardManager()

// 检查是否有图片
if (clipboard.hasFormat('image')) {
  // 获取图片详细信息
  const imageData = clipboard.getImageData()
  console.log('图片宽度:', imageData.width + 'px')
  console.log('图片高度:', imageData.height + 'px')
  console.log('图片大小:', imageData.size + ' bytes')

  // 保存图片到文件
  fs.writeFileSync('clipboard_image.png', imageData.data)

  // 获取 base64 编码
  const base64 = clipboard.getImageBase64()
  console.log('Base64 长度:', base64.length)
}

// 从文件设置图片
const imageBuffer = fs.readFileSync('image.png')
clipboard.setImageRaw(imageBuffer)

// 从 base64 设置图片
const base64Data = fs.readFileSync('image.png', 'base64')
clipboard.setImageBase64(base64Data)

// 快速图片操作
const quickImageData = getClipboardImageData()

异步图片操作

const clipboard = new ClipboardManager()

// 异步获取图片
try {
  const imageData = await clipboard.getImageDataAsync()
  console.log('异步获取图片:', imageData.width + 'x' + imageData.height)

  const base64 = await clipboard.getImageBase64Async()
  console.log('异步获取 Base64 长度:', base64.length)
} catch (error) {
  console.error('获取图片失败:', error.message)
}

// 异步文本操作
await clipboard.setTextAsync('Hello Async!')
const text = await clipboard.getTextAsync()
console.log('异步文本:', text)

文件操作

const { ClipboardManager, getClipboardFiles, setClipboardFiles } = require('@teddyzhu/clipboard')

const clipboard = new ClipboardManager()

// 设置文件列表
const files = ['/path/to/file1.txt', '/path/to/file2.pdf']
clipboard.setFiles(files)

// 获取文件列表
if (clipboard.hasFormat('files')) {
  const clipboardFiles = clipboard.getFiles()
  console.log('剪贴板中的文件:', clipboardFiles)
}

// 快速文件操作
setClipboardFiles(['/path/to/document.pdf'])
const quickFiles = getClipboardFiles()
console.log('快速获取文件:', quickFiles)

自定义格式数据

const clipboard = new ClipboardManager()

// 设置自定义格式数据
const customData = Buffer.from('custom binary data')
clipboard.setBuffer('application/custom', customData)

// 获取自定义格式数据
try {
  const data = clipboard.getBuffer('application/custom')
  console.log('自定义数据:', data.toString())
} catch (error) {
  console.error('自定义格式不存在')
}

复合内容操作

const { ClipboardManager, setClipboardContents } = require('@teddyzhu/clipboard')

const clipboard = new ClipboardManager()

// 同时设置多种格式
const contents = {
  text: 'Hello World!',
  html: '<h1>Hello HTML</h1>',
  rtf: 'Hello RTF',
  // 可选：图片数据
  // image: { width: 100, height: 100, size: 1000, data: imageBuffer },
  // 可选：文件列表
  // files: ['/path/to/file.txt']
}

clipboard.setContents(contents)

// 快速设置复合内容
setClipboardContents({
  text: 'Multi-format content',
  html: '<p>Multi-format <strong>content</strong></p>',
})

剪贴板监听

基本监听

const { ClipboardListener } = require('@teddyzhu/clipboard')

const listener = new ClipboardListener()

listener.watch((data) => {
  console.log('剪贴板数据变化:', data)
  console.log('可用格式:', data.availableFormats)

  if (data.text) {
    console.log('文本:', data.text)
  }

  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')
    // 注意：图片数据在 data.image.data (Buffer) 中，不是 base64Data
    console.log('  数据类型:', Buffer.isBuffer(data.image.data) ? 'Buffer' : typeof data.image.data)
  }

  if (data.files) {
    console.log('文件:', data.files)
  }
})

// 检查监听状态
console.log('是否正在监听:', listener.isWatching())
console.log('监听器类型:', listener.getListenerType()) // 'wayland' 或 'generic'

// 停止监听
setTimeout(() => {
  listener.stop()
  console.log('已停止监听')
}, 10000)

Wayland 支持

本库对 Linux Wayland 环境提供原生支持：

const { isWaylandClipboardAvailable, ClipboardListener } = require('@teddyzhu/clipboard')

// 检查 Wayland 剪贴板是否可用
if (isWaylandClipboardAvailable()) {
  console.log('Wayland 剪贴板监听可用')

  const listener = new ClipboardListener()
  console.log('当前监听器类型:', listener.getListenerType()) // 在 Wayland 下会显示 'wayland'

  // Wayland 监听器会自动处理不同的 MIME 类型
  listener.watch((data) => {
    console.log('Wayland 剪贴板变化:', data)
  })
} else {
  console.log('使用通用剪贴板监听器')
}

API 参考

ClipboardManager 类

方法	描述
`getText()`	获取纯文本内容
`setText(text)`	设置纯文本内容
`getHtml()`	获取 HTML 内容
`setHtml(html)`	设置 HTML 内容
`getRichText()`	获取 RTF 富文本内容
`setRichText(text)`	设置 RTF 富文本内容
`getImageBase64()`	获取图片的 base64 编码
`getImageData()`	获取图片详细信息（包含尺寸和原始数据）
`setImageBase64(base64Data)`	从 base64 设置图片
`setImageRaw(buffer)`	从 Buffer 设置图片
`getImageRaw()`	获取图片原始数据（Buffer）
`getFiles()`	获取文件列表
`setFiles(files)`	设置文件列表
`setBuffer(format, buffer)`	设置自定义格式数据
`getBuffer(format)`	获取自定义格式数据
`setContents(contents)`	设置复合内容
`hasFormat(format)`	检查是否包含指定格式
`getAvailableFormats()`	获取所有可用格式
`clear()`	清空剪贴板

异步方法

方法	描述
`getTextAsync()`	异步获取文本内容
`setTextAsync(text)`	异步设置文本内容
`getImageBase64Async()`	异步获取图片 base64
`getImageDataAsync()`	异步获取图片详细信息

ClipboardListener 类

方法	描述
`watch(callback)`	开始监听剪贴板变化
`stop()`	停止监听
`isWatching()`	检查是否正在监听
`getListenerType()`	获取监听器类型（'wayland' 或 'generic'）

快速操作函数

函数	描述
`getClipboardText()`	快速获取文本
`setClipboardText(text)`	快速设置文本
`getClipboardHtml()`	快速获取 HTML
`setClipboardHtml(html)`	快速设置 HTML
`getClipboardImage()`	快速获取图片（base64）
`getClipboardImageData()`	快速获取图片详细信息
`setClipboardImage(base64Data)`	快速设置图片（base64）
`setClipboardImageRaw(buffer)`	快速设置图片（Buffer）
`getClipboardImageRaw()`	快速获取图片原始数据
`getClipboardFiles()`	快速获取文件列表
`setClipboardFiles(files)`	快速设置文件列表
`getClipboardBuffer(format)`	快速获取自定义格式数据
`setClipboardBuffer(format, buffer)`	快速设置自定义格式数据
`setClipboardContents(contents)`	快速设置复合内容
`getFullClipboardData()`	快速获取完整剪贴板数据
`clearClipboard()`	快速清空剪贴板
`isWaylandClipboardAvailable()`	检查 Wayland 剪贴板是否可用

数据结构

ClipboardData

interface ClipboardData {
  availableFormats: string[] // 可用的格式列表
  text?: string // 纯文本内容
  rtf?: string // RTF 富文本内容
  html?: string // HTML 内容
  image?: ImageData // 图片数据
  files?: string[] // 文件列表
}

ImageData

interface ImageData {
  width: number // 图片宽度（像素）
  height: number // 图片高度（像素）
  size: number // 图片数据大小（字节）
  data: Buffer // 图片原始数据（Buffer）
}

注意事项

图片格式：所有图片都会转换为 PNG 格式存储
文件路径：文件路径需要是绝对路径
自定义格式：自定义格式的 MIME 类型需要遵循标准
Wayland 支持：在 Wayland 环境下会自动使用专用监听器以获得更好的性能
异步操作：对于可能耗时的操作，推荐使用异步版本
错误处理：所有方法都可能抛出异常，请适当处理错误

许可证

MIT