---
title: "clipboard"
description: "读取和写入系统文本剪贴板。"
---


> 读取和写入系统文本剪贴板。

## 模块边界

`clipboard` 只处理 UTF-8 文本，不提供图片、HTML、文件或自定义 MIME 类型。
实现入口是 `frontend/src/api/clipboard.ts`。

## 方法索引

|方法 |权限 |返回值 |
| --- | --- | --- |
| [readText](/docs/kasumi/api/clipboard/read-text) | `clipboard.read` | `{ text }` |
| [writeText](/docs/kasumi/api/clipboard/write-text) | `clipboard.write` | `{ written }` |

## 调用形式

`writeText` 接收位置参数，不是 `{ text }` 对象：

```ts
await KSM.clipboard.writeText('Kasumi');

const { text } = await KSM.clipboard.readText();
```

这与 `fs.writeText({ path, content })`、`notification.show({ title, body })`
的对象参数形式不同，迁移调用时不要机械统一。

## 平台差异

|项 | Windows | Android |
| --- | --- | --- |
|读取 | `CF_UNICODETEXT` |首个剪贴板 item 的 `coerceToText` |
|读取失败 |返回 `{ text: '' }` |返回 `{ text: '' }` |
|写入 |清空后写入 Unicode 文本 | `ClipData.newPlainText` |

## 相关

- [errors](/docs/kasumi/api/errors)
- [types](/docs/kasumi/api/types)