---
title: "writeText"
description: "把文本写入系统剪贴板。"
---


> 把文本写入系统剪贴板。

## 签名

```ts
KSM.clipboard.writeText(text: string): Promise<{ written: boolean }>
```

## 平台与权限

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

## 参数

|参数 |类型 |必填 |说明 |
| --- | --- | --- | --- |
| `text` | `string` |是 |要写入的 UTF-8 文本 |

参数是位置字符串，不是对象。

## 返回值

|字段 |类型 |说明 |
| --- | --- | --- |
| `written` | `boolean` |系统是否接受写入 |

## 行为

- Windows 先清空剪贴板，再写入 `CF_UNICODETEXT`。
- Android 使用纯文本 `ClipData`，标签固定为 `Kasumi`。
- 写入系统拒绝时返回 `{ written: false }`，不是稳定错误码。
- 不提供富文本、HTML 或文件剪贴板格式。

## 示例

```ts
const { written } = await KSM.clipboard.writeText('Kasumi');

if (!written) {
  console.info('系统拒绝写入剪贴板');
}
```

## 错误

|错误 |场景 |
| --- | --- |
|普通 `TypeError` | `text` 不是字符串 |
| `PERMISSION_DENIED` | `clipboard.write` 不可用 |
| `NOT_SUPPORTED` |宿主没有配置剪贴板服务 |
| `TIMEOUT` |宿主未在默认时间内响应 |

## 相关

- [readText](/docs/kasumi/api/clipboard/read-text)
- [permission.request](/docs/kasumi/api/permission/request)