# @capawesome/capacitor-clipboard 中文文档

规范地址：https://npmcn.com/package/%40capawesome/capacitor-clipboard/

版本：0\.1\.2
npm 元数据更新时间：2026-09-02T08:21:58.068Z
中文译文更新时间：2026-11-09T08:12:17.900Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capawesome/capacitor-clipboard
原文对照：https://npmcn.com/package/%40capawesome/capacitor-clipboard/?lang=original
项目主页：https://capawesome.io/docs/sdks/capacitor/clipboard/
源码仓库：https://github.com/capawesome-team/capacitor-plugins

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：108 kB，41 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2026-07-07T12:20:10.140Z
- 最新版本发布：2026-09-02T08:21:57.637Z
- 近 30 天下载量：3663（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

在Android,iOS,和Web上读取并写入系统剪贴板的电容插件.

## 安装

```sh
npm install @capawesome/capacitor-clipboard
```

也可以使用：`pnpm add @capawesome/capacitor-clipboard`、`yarn add @capawesome/capacitor-clipboard`、`bun add @capawesome/capacitor-clipboard`

## README

# 剪贴板插件

要从系统剪贴板读取并写入的电容插件 .

[![Deliver Live Updates to your Capacitor app with Capawesome Cloud](https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1)](https://cloud.capawesome.io/)

## 特征

-   📋 **读取和写入**: 从系统剪贴板读取并写入.
-   🖼️ **图像**:复制并粘贴真实的图像,而不仅仅是数据URL作为纯文本.
-   📝 **丰富文本**: 将 HTML 内容写入纯文本倒置后.
-   🔗 **URL( URL)**: 将 URL 复制为本地 URL 剪贴板项目 .
-   🌐 **跨平台**:在Android,iOS和网络上工作.
-   🔒 **App 存储安全**:只使用官方平台API.
-   🤝 **兼容性**: 与 [共享目标](https://capawesome.io/docs/sdks/capacitor/share-target/) 财务报告和审定财务报表 [文本交互](https://capawesome.io/docs/sdks/capacitor/text-interaction/) 插件 .
-   📦 **可可花和SPM**:支持CocoaPods和Swift软件包管理器用于iOS.
-   🔁 **最新数据**:总是支持最新的Capacitor版本.

缺少一个功能? 刚刚 [打开一个问题](https://github.com/capawesome-team/capacitor-plugins/issues) 我们看看!

## 使用大小写

通常在应用程序允许用户复制或粘贴内容时使用剪贴板插件,例如:

-   **复制到剪贴板按钮**:让用户复制优惠券代码,邀请链接,或一个自带的钱包地址.
-   **粘贴支持**: 将剪贴板上的文本、 URL 或图像读入您的应用程序, 例如, 读入窗体或编辑器 .
-   **共享图像**: 复制已生成的图像(例如QR代码或图表),这样用户就可以将它粘贴到其他应用程序中.
-   **丰富的文本工作流程**: 复制格式化的 HTML 内容,并带有无法处理 HTML 的应用程序的纯文本倒置.

## 兼容性

| 插件版本 | 电容版本 | 状态 |
| --- | --- | --- |
| 0.x.x (中文(简体) ) | \>=8.x.x | 积极支持 |

## 安装

你可以用我们的 **AI 辅助设置** 以安装插件. 添加数据 [超级技能](https://github.com/capawesome-team/skills) 至您的 AI 工具,使用以下命令:

```bash
npx skills add capawesome-team/skills --skill capacitor-plugins
```

然后使用下列提示:

```
 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-clipboard` plugin in my project.
```

如果你喜欢 **手动设置**,通过运行以下命令来安装插件,并遵循下面的平台特定指令:

```bash
npm install @capawesome/capacitor-clipboard
npx cap sync
```

### 机器人

此插件不需要额外的配置 .

### iOS系统

此插件不需要额外的配置 .

## 配置

此插件不需要配置 .

## 使用量

以下例子显示如何将文本,HTML,图像和URL写入剪贴板,以及如何读取其当前内容.

### 将文本写入剪贴板

将纯文本复制到系统剪贴板 :

```typescript
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeText = async () => {
  await Clipboard.write({ text: 'Hello World' });
};
```

### 用纯文本倒置写入 HTML

复制 HTML 内容并将其合并 `text` 为无法处理 HTML 内容的应用程序提供纯文本倒置:

```typescript
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeHtml = async () => {
  await Clipboard.write({
    html: '<b>Hello World</b>',
    text: 'Hello World',
  });
};
```

### 将图像写入剪贴板

通过一个 Base64 编码数据 URL 复制一个真实的图像(不仅仅是一个数据 URL 作为纯文本):

```typescript
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeImage = async () => {
  await Clipboard.write({
    image: 'data:image/png;base64,iVBORw0KGgo...',
  });
};
```

### 将 URL 写入剪贴板

作为本地 URL 剪贴板项目复制 :

```typescript
import { Clipboard } from '@capawesome/capacitor-clipboard';

const writeUrl = async () => {
  await Clipboard.write({ url: 'https://capawesome.io' });
};
```

### 读取剪贴板内容

读取系统剪贴板的当前内容 。 结果包含内容类型(文本,HTML,图像,或URL)和值. 请注意,在Android上,阅读剪贴板只有在应用程序处于前景时才可能,而在iOS上,显示一个系统粘贴通知:

```typescript
import { Clipboard } from '@capawesome/capacitor-clipboard';

const read = async () => {
  const { type, value } = await Clipboard.read();
  console.log('Type:', type, 'Value:', value);
};
```

## API 密码

-   [`read()`](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-read)
-   [`write(...)`](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-write)
-   [接口](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-interfaces)
-   [数字](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-enums)

### 改为( )

```typescript
read() => Promise<ReadResult>
```

读取系统剪贴板的当前内容 .

在Android上,阅读剪贴板只有在应用在 前观相.

在iOS上,读取剪贴板会显示一个系统粘贴通知. 这是 无法压制.

**回返情况:** `Promise<[ReadResult](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-readresult)>`

**自:** 0.1.0 (中文(简体) )

* * *

### 写入(...)

```typescript
write(options: WriteOptions) => Promise<void>
```

将内容写入系统剪贴板 .

就是其中一个 `text`, (中文(简体) ), `html`, (中文(简体) ), `image` 或者说 `url` 必须提供。 这个 `html` 财产还可以与 `text` 提供 简文倒回.

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[WriteOptions](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-writeoptions)` |

**自:** 0.1.0 (中文(简体) )

* * *

### 接口

#### 阅读结果

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`type`** | `[ClipboardContentType](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-clipboardcontenttype)` | 从剪贴板读取的内容类型 . | 0.1.0 (中文(简体) ) |
| **`value`** | `string` | 从剪贴板上读取的内容 。 图像作为 Base64 编码后的数据 URL 返回. | 0.1.0 (中文(简体) ) |

#### 写入选项

| Prop | 类型 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`html`** | `string` | 要写入剪贴板的 HTML 内容 。 把这个和 `text` 以提供无法处理 HTML 内容的应用程序的纯文本倒置. | 0.1.0 (中文(简体) ) |
| **`image`** | `string` | 要写入剪贴板的图像为 Base64- 编码后的数据 URL . | 0.1.0 (中文(简体) ) |
| **`label`** | `string` | 用于描述剪贴板内容的标签 。 只能从Android上找到. | 0.1.0 (中文(简体) ) |
| **`text`** | `string` | 要写入剪贴板的纯文本 . | 0.1.0 (中文(简体) ) |
| **`url`** | `string` | 要写入剪贴板的 URL . | 0.1.0 (中文(简体) ) |

### 数字

#### 剪贴板连接Type

| 成员 | 数值 | 说明 | 自兹 |
| --- | --- | --- | --- |
| **`Html`** | `'HTML'` | 内容为HTML. | 0.1.0 (中文(简体) ) |
| **`Image`** | `'IMAGE'` | 内容为图像,以 Base64 编码后的数据 URL 返回. | 0.1.0 (中文(简体) ) |
| **`Text`** | `'TEXT'` | 内容为正文. | 0.1.0 (中文(简体) ) |
| **`Url`** | `'URL'` | 内容为URL. | 0.1.0 (中文(简体) ) |

## 平台行为

### 机器人

-   在Android 10(API 第29关)上及后期,应用程序只能在处于前期时读取剪贴板并有输入焦点. 这个 `read(...)` 方法拒绝.
-   在Android 12(API level 31)上,当一个应用程序读取由另一个应用程序所写的剪贴板内容时,系统会显示一个敬酒信息. 这是预期的行为,不能压制.

### iOS系统

-   在iOS 14上,系统每次读取剪贴板时都会显示粘贴通知横幅. 这是预期的行为,不能压制.

## 从 `@capacitor/clipboard`

此插件是官方的下拉选项 [`@capacitor/clipboard`](https://github.com/ionic-team/capacitor-plugins/tree/main/clipboard) android 和 HTML 在所有平台上支持真实图像支持的插件. 适用下列差别:

| `@capacitor/clipboard` | `@capawesome/capacitor-clipboard` |
| --- | --- |
| `write({ string: 'Hello' })` | `write({ text: 'Hello' })` |
| `write({ image: dataUrl })` (只写在Android上) | `write({ image: dataUrl })` (所有平台上的真实图像) |
| —— 说 | `write({ html: '<b>Hello</b>', text: 'Hello' })` |
| `read() → { value, type: 'text/plain' }` | `read() → { value, type: 'TEXT' }` |

## 财务问题

### 此插件与其他类似插件有何不同?

它支持的远不止于纯文本——复制并粘贴图像,HTML带有纯文本倒置,以及本地的URL项目,在Android,iOS,和网络上都有可靠的真实图像处理. API完全被打入并针对最新的OS和框架版本积极维护,它只使用官方平台API,因此它对于App Store和Google Play的提交保持安全. 如果你只复制纯文本,一个简单的设置是完全好的;如果你需要丰富的内容和每个平台的一致行为,这个插件就是为此设计的.

### 为什么我的应用程序读取剪贴板时会显示通知?

在iOS 14上,系统每次读取剪贴板时都会显示粘贴通知横幅. 在Android 12(API关卡31)上,当一个应用程序读取由另一个应用程序所写的剪贴板内容时,系统会显示一个敬酒信息. 两者都是预期的平台行为,不能被压制.

### 为什么在Android上读取剪贴板失败?

在Android 10(API 第29关)上及后期,应用程序只能在处于前期时读取剪贴板并有输入焦点. 这个 `read()` 方法拒绝其他方法,所以在应用程序可见的同时,确保只针对用户交互调用.

### 我能同时写出多种内容类型吗?

不,就是其中一个 `text`, (中文(简体) ), `html`, (中文(简体) ), `image` 或者说 `url` 打电话时必须提供 `write(...)`。唯一的例外是 `html` 可能与 `text` 以提供无法处理 HTML 内容的应用程序的纯文本倒置.

### 此插件如何处理图像 ?

图像作为真实图像写入剪贴板,而不仅仅是数据URL作为纯文本,方法是将Base64编码数据URL传递到 `write(...)`。在读取时,图像也作为Base64编码数据URL返回。 见 [使用示例](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-write-an-image-to-the-clipboard) 见上文.

### 此插件与官方插件有何不同 `@capacitor/clipboard` 插件吗?

此插件是官方的下拉选项 `@capacitor/clipboard` android 和 HTML 在所有平台上支持真实图像支持的插件. 只有少数方法选项不同,参见 [移徙表](https://npmcn.com/package/%40capawesome/capacitor-clipboard/#readme-migrating-from-capacitorclipboard) 见上文.

### 我能用这个插件吗? 有Ionic、React、Vue或Angular?

是的,插件是框架不可知的。 它在任意网络框架的Capacitor app中工作,包括有Angular,React,或Vue的Ionic,以及平版JavaScript等项目.

## 相关插件

-   [共享目标](https://capawesome.io/docs/sdks/capacitor/share-target/): 从其他应用程序接收文本、链接和文件等内容.
-   [文本交互](https://capawesome.io/docs/sdks/capacitor/text-interaction/): 在应用的WebView中启用并禁用文本交互(选择,放大器,呼喊菜单).

## 通讯

随时更新有关卡帕韦索姆、Capacitor和Ionic生态系统的最新消息和最新消息,因为我们 [《卡帕索克通讯》](https://cloud.capawesome.io/newsletter/)。 。 。 .

## 更改日志

见 [变动情况](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/clipboard/CHANGELOG.md)。 。 。 .

## 许可证

见 [自由主义](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/clipboard/LICENSE)。 。 。 .

## 常见问题

### @capawesome/capacitor-clipboard 是什么？

在Android,iOS,和Web上读取并写入系统剪贴板的电容插件\.

### 如何安装 @capawesome/capacitor-clipboard？

在项目目录运行 npm install @capawesome/capacitor-clipboard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@capacitor/core（\>=8\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @capawesome/capacitor-clipboard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capawesome/capacitor-clipboard 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @capawesome/capacitor-clipboard 可以商用吗？

@capawesome/capacitor-clipboard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capawesome/capacitor-clipboard 的下载量有多少？

根据 npm 官方下载统计，@capawesome/capacitor-clipboard 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,663 次，日均约 122 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capawesome/capacitor-clipboard 还在维护吗？

最新版本 0\.1\.2 发布于 2026/09/02（2 个月前）；至今共发布 4 个版本，其中过去 12 个月发布了 4 个；首次发布于 2026/07/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。