@capacitor/clipboard

本项目基于 @capacitor/[email protected] 开发。

简介

@capacitor/clipboard 是 capacitor 生态系统中的核心插件，用于向系统剪贴板复制和粘贴内容，为跨平台应用开发提供设备差异化适配能力，兼容 capacitor 的 Android、iOS 等主流移动平台及浏览器环境，本文档主要说明在 OpenHarmony 系统中的使用。

该插件提供了向系统剪贴板复制文本、图片、URL，以及从剪贴板读取内容的能力，满足移动应用中常见的内容复制、分享、粘贴等场景需求。

支持平台

• OpenHarmony：5.0+

下载安装

通过命令行或手动引入即可快速安装插件，支持从npm仓库获取。

命令行安装（推荐）

安装hionic CLI：

npm install -g hionic

以下两种方式中任选其一即可，无需重复操作：

npm安装：

# 安装插件
npm install @capacitor/clipboard

# 同步插件
hionic sync

hionic CLI安装：

hionic plugin add @capacitor/clipboard

手动引入安装

根据插件源码中 plugin.xml 配置在项目中引入插件：

1. 添加插件配置

根据 plugin.xml 的 config-json 项，通过 target 字段找到 entry 模块中 capacitor.plugins.json 文件，并根据 param 标签添加配置如下：

{
    "pkg": "@capacitor/clipboard",
    "classpath": "Clipboard"
}

2. 修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，通过 modules-name 字段找到模块 capacitor，路径为 target 字段的 CMakeLists.txt 文件，并根据 param 标签添加 add_subdirectory 和 target_link_libraries 如下：

#START_ADD_SUBDIRECTORY
// ...
add_subdirectory(Clipboard)
// ...
#END_ADD_SUBDIRECTORY

// ...

target_link_libraries(capacitor PUBLIC
  "-Wl,--whole-archive"
  // ...
  Clipboard
  // ...
  "-Wl,--no-whole-archive"
)

3. 复制源码文件

根据 plugin.xml 的 source-file 项，根据 src 字段找到需要复制的文件，并根据 modules-name 字段和 target-dir 字段找到文件复制的具体模块和目录：

将源码中 src/main/cpp/Clipboard 目录下的 Clipboard.cpp、Clipboard.h、CMakeLists.txt 文件引入到 capacitor 模块中 src/main/cpp/Clipboard 目录下。

卸载

# 卸载 clipboard 插件
hionic plugin remove @capacitor/clipboard

约束与限制

兼容性

在以下版本中已测试通过：

1. SDK: 5.0.5(17); IDE: DevEco Studio: 6.0.0; ROM: 5.1.0.150;

权限要求

OpenHarmony 需要申请读取剪贴板权限，在主工程的 module.json5 的 requestPermissions 添加 ohos.permission.READ_PASTEBOARD 权限，示例如下：

{
  "name" : "ohos.permission.READ_PASTEBOARD",
  "reason": "$string:pasteboard",
  "usedScene": {
    "abilities": [
      "EntryAbility"
    ],
    "when": "always"
  }
}

更多权限说明参考：申请应用权限。

使用示例

基础示例：写入剪切板并读取

import { Clipboard } from '@capacitor/clipboard';

const writeToClipboard = async () => {
  await Clipboard.write({
    string: "Hello World!"
  });
};

const checkClipboard = async () => {
  const { type, value } = await Clipboard.read();

  console.log(`Got ${type} from clipboard: ${value}`);
};

使用说明

接口方法

| 方法名 | 返回类型 | 描述 | | ---- | ---- | ---- | | write(options: WriteOptions) | Promise<void> | 将值写入剪贴板 | | read() | Promise<ReadResult> | 从剪贴板读取值 |

数据结构

WriteOptions

要写入剪贴板的数据：

| 属性名 | 类型 | 描述 | 备注 | | ------------ | ------ | ------------------------------------------------------------ | ------------ | | string | string | 要复制的文本值 | | | image | string | 图片 数据 URL 复制格式 | | | url | string | 要复制的 URL 字符串 | | | label | string | 用户可见标签，用于标记复制的数据 | 仅限 Android |

ReadResult

从剪贴板读取的数据：

| 属性名 | 类型 | 描述 | | ----------- | ------ | ------------------- | | value | string | 从剪贴板读取数据 | | type | string | 剪贴板中的数据类型 |

目录结构

|---- 项目根目录
|     |---- src
|           |---- main
|                 |---- cpp
|                       |---- Clipboard   # 插件核心 C++ 实现
|                             |---- Clipboard.cpp
|                             |---- Clipboard.h
|                             |---- CMakeLists.txt
|     |---- README.md          # 说明文档
|     |---- package.json       # npm 配置文件
|     |---- plugin.xml         # capacitor 插件配置
|     |---- LICENSE            # 许可证文件

贡献代码

使用过程中发现任何问题都可以提 Issue，当然，也非常欢迎发 PR 共建。

许可证

本插件基于 MIT License 开源，详见 LICENSE 文件。