@ionic-native/clipboard

本项目基于 @ionic-native/[email protected]开发。

简介

@ionic-native/clipboard 是 OpenHarmony Cordova生态系统中的核心插件，提供剪贴板复制与粘贴功能，为跨平台应用开发提供设备差异化适配能力。兼容 Android、iOS 和OpenHarmony平台，为跨平台应用开发提供统一的剪贴板操作能力。本文档主要说明在OpenHarmony系统中的应用。

@ionic-native/clipboard API提供剪贴板复制、粘贴和清除功能。

支持平台

• OpenHarmony：5.0+

下载安装

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

命令行安装（推荐）

安装 hionic CLI：

npm install -g hionic

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

npm 安装：

# 安装插件
npm install @ionic-native/clipboard

# 同步插件
hionic sync

hionic CLI 安装：

hionic plugin add @ionic-native/clipboard

手动引入安装

1.添加插件配置

根据 plugin.xml 的 config-json 项，找到 entry 模块中 config.xml 文件，并根据 param 标签添加配置

<feature name="Clipboard">
  <param name="harmony-package" value="Clipboard" />
</feature>

2.修改 CMake 配置

根据 plugin.xml 的 CMakeLists 项，找到 cordova 模块，路径为 target 字段的文件 CMakeLists.txt，添加 add_library

add_library(cordova SHARED
  // ...
  Clipboard/Clipboard.cpp
  // ...
)

3.复制源码文件

根据 plugin.xml 的 source-file 项，将 src 字段的路径代码复制到 cordova 模块中 target-dir 字段的目录中：

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

将源码中 src/main/ets/components/PluginAction 目录下的 ClipboardAction.ets 文件引入到 cordova 模块中 src/main/ets/components/PluginAction 目录下。

4.添加 ArkTS 配置

在 cordova 模块的 build-profile.json5 文件中，buildOption/arkOptions/runtimeOnly/sources 配置项数组中加入步骤 3 中拷贝的 ets 文件路径:

"buildOption":{
  "arkOptions": {
    "runtimeOnly": {
      "sources": [
        // ...
        "./src/main/ets/components/PluginAction/ClipboardAction.ets"
        // ...
      ]
    }
  }
}

卸载

# hionic CLI 卸载
hionic plugin remove @ionic-native/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"
  }
}

使用示例

示例1：文本复制粘贴清除

实现文本框内容复制到剪贴板、从剪贴板粘贴到文本框，以及清除剪贴板内容的功能。

import { Clipboard } from '@ionic-native/clipboard';

const res1 = await Clipboard.copy(txt);
const text = await Clipboard.paste();
const res2 = await Clipboard.clear();

使用说明

接口方法

| 方法名 | 请求参数 | 返回类型 | 描述 | 备注 | |-------|---------|---------|------|------| | copy(...) | copy(text: string) | Promise<string> | 复制文本到剪贴板 | | | paste(...) | paste(successCallback: (text: string) => void, errorCallback: (error: any) => void) | Promise<string> | 从剪贴板粘贴文本 | | | clear() | clear() | Promise<string> | 清除剪贴板内容 | |

方法参数说明

1. 复制文本到剪贴板

Clipboard.copy(
  text: string, // 需要复制的纯文本内容
): Promise<string>;

2. 从剪贴板粘贴文本

Clipboard.paste(
  successCallback: (text: string) => void, // 成功回调，参数为剪贴板中的文本内容
  errorCallback: (error: any) => void // 失败回调，参数为错误对象（含message属性）
): Promise<string>;

3. 清除剪贴板内容

Clipboard.clear(): Promise<string>;

目录结构

|---- 目录
|     |---- src/main  # 插件的实现代码
|           |---- cpp  # C++ 代码
|           |---- ets  # ArkTS 代码
|     |---- www    # Web 侧代码
|     |---- README.md          # 说明文档
|     |---- package.json       # 配置文件
|     |---- plugin.xml         # 插件配置文件

贡献代码

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

许可证

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