---
title: "readText"
description: "读取系统剪贴板中的文本。"
---


> 读取系统剪贴板中的文本。

## 签名

```ts
KSM.clipboard.readText(): Promise<{ text: string }>
```

## 平台与权限

| Windows | Android |权限 |
| --- | --- | --- |
|支持 |支持 | `clipboard.read` |

## 参数

无。

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `text` | `string` |剪贴板文本；没有文本或读取失败时为空字符串 |

## 行为

- Windows 读取 `CF_UNICODETEXT`。
- Android 读取主剪贴板第一个 item 并调用 `coerceToText()`。
- 剪贴板为空、数据类型不可转换或底层读取失败时返回 `{ text: '' }`。
- 不区分“空剪贴板”和“读取失败”，需要区分时应调整宿主服务契约。

## 示例

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

if (text.length === 0) {
  console.info('剪贴板没有可用文本');
}
```

## 错误

|错误 |场景 |
| --- | --- |
| `PERMISSION_DENIED` | `clipboard.read` 不可用 |
| `NOT_SUPPORTED` |宿主没有配置剪贴板服务 |
| `TIMEOUT` |宿主未在默认时间内响应 |

读取失败通常不会抛错，而是返回空字符串。

## 相关

- [writeText](/docs/kasumi/api/clipboard/write-text)
- [clipboard 模块](/docs/kasumi/api/clipboard)