Clipboard
NPM Package: https://www.npmjs.com/package/@crosscopy/clipboard
GitHub: https://github.com/crosscopy/clipboard
跨平台原生剪贴板库，适用于 Node.js。支持读取、写入和监听系统剪贴板，兼容多种数据格式。
支持的格式
- 纯文本
- HTML
- 富文本 (RTF)
- 图片 (PNG 二进制 / base64)
- 文件
- 任意二进制数据 (自定义格式字符串)
安装
npm install @crosscopy/clipboard
# 或
pnpm add @crosscopy/clipboard
快速开始
import {
getText, setText,
hasText, hasImage,
getImageBase64,
startWatch,
} from '@crosscopy/clipboard'
// 读写文本
await setText('hello world')
console.log(await getText()) // "hello world"
// 检查剪贴板内容类型
console.log(hasText()) // true
console.log(hasImage()) // false
// 监听剪贴板变化
const watcher = startWatch(() => {
console.log('剪贴板内容已变化！')
})
// ... 之后停止监听
watcher.stop()
API
完整的类型声明请参阅 index.d.ts。
纯文本
| 函数 | 签名 | 说明 |
|---|---|---|
hasText | () => boolean | 检查剪贴板是否包含文本 |
getText | () => Promise<string> | 从剪贴板读取文本 |
setText | (text: string) => Promise<void> | 将文本写入剪贴板 |
import { hasText, getText, setText } from '@crosscopy/clipboard'
await setText('已复制！')
if (hasText()) {
console.log(await getText())
}
HTML
| 函数 | 签名 | 说明 |
|---|---|---|
hasHtml | () => boolean | 检查剪贴板是否包含 HTML |
getHtml | () => Promise<string> | 从剪贴板读取 HTML 字符串 |
setHtml | (html: string) => Promise<void> | 将 HTML 字符串写入剪贴板 |
import { setHtml, getHtml } from '@crosscopy/clipboard'
await setHtml('<b>粗体</b>')
console.log(await getHtml())
富文本 (RTF)
| 函数 | 签名 | 说明 |
|---|---|---|
hasRtf | () => boolean | 检查剪贴板是否包含 RTF |
getRtf | () => Promise<string> | 从剪贴板读取 RTF 字符串 |
setRtf | (rtf: string) => Promise<void> | 将 RTF 字符串写入剪贴板 |
图片
| 函数 | 签名 | 说明 |
|---|---|---|
hasImage | () => boolean | 检查剪贴板是否包含图片 |
getImageBinary | () => Promise<Array<number>> | 以 PNG 字节数组形式读取图片 |
getImageBase64 | () => Promise<string> | 以 base64 编码的 PNG 形式读取图片 |
setImageBinary | (imageBytes: Array<number>) => Promise<void> | 将 PNG 字节数组写入剪贴板 |
setImageBase64 | (base64Str: string) => Promise<void> | 将 base64 编码的 PNG 写入剪贴板 |
import { hasImage, getImageBase64, setImageBinary } from '@crosscopy/clipboard'
import { readFileSync } from 'fs'
// 将 PNG 文件写入剪贴板
const png = readFileSync('screenshot.png')
await setImageBinary(Array.from(png))
// 以 base64 形式读取
if (hasImage()) {
const b64 = await getImageBase64()
console.log(`data:image/png;base64,${b64}`)
}
文件
| 函数 | 签名 | 说明 |
|---|---|---|
hasFiles | () => boolean | 检查剪贴板是否包含文件引用 |
getFiles | () => Promise<Array<string>> | 从剪贴板读取文件路径列表 |
setFiles | (files: Array<string>) => Promise<void> | 将文件路径列表写入剪贴板 |
import { hasFiles, getFiles } from '@crosscopy/clipboard'
if (hasFiles()) {
const paths = await getFiles()
console.log(paths) // ["/Users/you/file.txt", ...]
}
Buffer (自定义格式)
| 函数 | 签名 | 说明 |
|---|---|---|
getBuffer | (format: string) => Promise<Array<number>> | 按指定格式读取原始字节 |
setBuffer | (format: string, buffer: Array<number>) => Promise<void> | 按指定格式写入原始字节 |
import { setBuffer, getBuffer } from '@crosscopy/clipboard'
await setBuffer('com.myapp.custom', [0x01, 0x02, 0x03])
const data = await getBuffer('com.myapp.custom')
工具函数
| 函数 | 签名 | 说明 |
|---|---|---|
availableFormats | () => Array<string> | 列出剪贴板中当前所有的数据格式 |
clear | () => Promise<void> | 清空剪贴板 |
剪贴板监听
使用操作系统原生通知机制监听剪贴板变化。
| 函数 / 方法 | 签名 | 说明 |
|---|---|---|
startWatch | (callback: () => void) => ClipboardWatcherJs | 开始监听，返回监听句柄 |
watcher.stop() | () => void | 停止监听 |
watcher.isRunning | boolean (getter) | 监听器是否正在运行 |
import { startWatch, getText } from '@crosscopy/clipboard'
const watcher = startWatch(async () => {
console.log('剪贴板已变化:', await getText())
})
console.log(watcher.isRunning) // true
// 不再需要时停止监听
watcher.stop()
console.log(watcher.isRunning) // false
监听器在后台线程中运行，使用操作系统原生的剪贴板变化事件，JavaScript 侧无需轮询。使用完毕后调用 stop() 释放资源。
平台支持
| 平台 | 架构 |
|---|---|
| macOS | x64, arm64 (Apple Silicon), universal |
| Windows | x64, arm64 |
| Linux | x64 (glibc) |
致谢
- ChurchTao/clipboard-rs 提供了跨 Linux、Windows 和 macOS 的原生剪贴板支持。
- napi.rs 将 Rust 实现桥接到 Node.js。
发布
所有构建和发布流程由 GitHub Actions 完成。
执行 npm version patch 升级版本号，然后 git push --follow-tags 推送到 GitHub，GitHub Actions 会自动构建并发布。