# clipboard

**Repository Path**: xcode_xiao/clipboard

## Basic Information

- **Project Name**: clipboard
- **Description**: Java + Rust JNI 跨平台剪贴板库，用于在 Java 项目中统一读写系统剪贴板，并支持剪贴板变更监听。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# clipboard-jni-bridge

[![](https://www.jitpack.io/v/com.gitee.xcode_xiao/clipboard.svg)](https://www.jitpack.io/#com.gitee.xcode_xiao/clipboard)

基于 [clipboard-rs](https://github.com/ChurchTao/clipboard-rs) 的 Java + Rust JNI 跨平台剪贴板库。  
用于在 Java 项目中统一读写系统剪贴板，并支持剪贴板变更监听。

- Rust Native：`clipboard-rs`
- Java Bridge：`clipboard-bridge` 模块
- 支持平台：Windows / macOS / Linux（跟随 `clipboard-rs` 能力）

## 功能支持

- 纯文本（Plain Text）
- HTML
- RTF（Rich Text）
- 图片（PNG）
- 文件列表（File List）
- 监听剪贴板变化（Watch Changes）

## 平台支持对照

| 类型 | Windows | macOS | Linux(X11) |
| --- | --- | --- | --- |
| Plain Text | ✅ | ✅ | ✅ |
| HTML | ✅ | ✅ | ✅ |
| RTF | ✅ | ✅ | ✅ |
| Image(PNG) | ✅ | ✅ | ✅ |
| File List | ✅ | ✅ | ✅ |
| Watch Changes | ✅ | ✅ | ✅ |

说明：底层平台能力由 `clipboard-rs` 提供，本项目在其之上做 JNI 封装与 Java 类型建模。

## 项目结构

- `clipboard-bridge/`：JNI 桥接模块（Java API + Rust Native）
- `clipboard-bridge/rust/`：Rust 动态库源码
- `clipboard-bridge/src/main/java/me/xiaolei/clipboard/`：Java API 与模型
- `clipboard-bridge/src/main/resources/native/`：按平台分类的 native 产物

## 使用方式

### 1. 读取剪贴板

```java
import me.xiaolei.clipboard.NativeClipboard;
import me.xiaolei.clipboard.model.*;

ClipboardData data = NativeClipboard.getClipboardData();
switch (data.type()) {
    case TEXT -> System.out.println(((TextClipboardData) data).text());
    case HTML -> System.out.println(((HtmlClipboardData) data).html());
    case RTF -> System.out.println(((RtfClipboardData) data).rtf());
    case IMAGE -> {
        ImageClipboardData img = (ImageClipboardData) data;
        System.out.println("image=" + img.width() + "x" + img.height());
        System.out.println("pngBytes=" + img.pngBytes().length);
    }
    case FILE_LIST -> System.out.println(((FileListClipboardData) data).files());
    case EMPTY -> System.out.println("clipboard empty");
}
```

### 2. 写入剪贴板

```java
import me.xiaolei.clipboard.NativeClipboard;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;

NativeClipboard.setText("hello");
NativeClipboard.setHtml("<b>hello</b>");
NativeClipboard.setRtf("{\\rtf1\\ansi hello}");
NativeClipboard.setFiles(List.of("/tmp/a.txt", "/tmp/b.png"));
NativeClipboard.setImagePngBytes(Files.readAllBytes(Path.of("/tmp/test.png")));
```

### 3. 监听剪贴板变化

```java
import me.xiaolei.clipboard.NativeClipboard;

NativeClipboard.startListener(data -> {
    System.out.println("changed type=" + data.type());
});

Thread.sleep(10_000);
NativeClipboard.stopListener();
```

## 构建

### 构建整个项目

```bash
./gradlew build
```

### 仅构建 JNI 模块

```bash
./gradlew :clipboard-bridge:build
```

### 指定 Rust 目标平台构建

```bash
./gradlew :clipboard-bridge:build -PnativeTargets=x86_64-apple-darwin,aarch64-apple-darwin
```

构建过程会自动执行：

1. Rust 编译（`buildRustNative`）
2. 拷贝产物到资源目录（`copyRustNativeToResources`）
3. Java 资源处理与打包

## 设计说明

- 文本/HTML/RTF/文件列表：通过 JSON 跨 JNI 传输
- 图片：通过 JNI `byte[]` 二进制直传（避免 Base64 带来的内存与 CPU 开销）
- 监听：Rust 侧独立线程监听，回调 Java `ClipboardChangeListener`

## 参考

- [ChurchTao/clipboard-rs](https://github.com/ChurchTao/clipboard-rs)
- [clipboard-rs docs.rs](https://docs.rs/clipboard-rs/latest/clipboard_rs/)

## 许可证

本项目遵循 MIT License（可按你的项目实际许可证调整）。