鸿蒙OS 剪贴板开发指导

场景介绍

同一设备的应用程序 A、B 之间可以借助系统剪贴板服务完成简单数据的传递，即应用程序 A 向剪贴板服务写入数据后，应用程序 B 可以从中读取出数据。在满足分布式剪贴板服务的使用条件时，应用程序 A、B 也可以来自组网内的不同设备。

图1 剪贴板服务示意图

在使用剪贴板服务时，需要注意以下几点：

• 只有在前台获取到焦点的应用才有读取系统剪贴板的权限（系统默认输入法应用除外）。
• 写入到剪贴板服务中的剪贴板数据不会随应用程序结束而销毁。
• 对同一用户而言，写入剪贴板服务的数据会被下一次写入的剪贴板数据所覆盖。
• 如果设备满足分布式组网条件，且进行复制操作的设备打开了剪贴板分布式开关，未配置“仅在本地”标志位的剪贴板数据里的 MIME 类型为纯文本和 HTML 的内容可以被组网内其他打开了剪贴板分布式开关的设备粘贴出来。
• 在同一设备内，剪贴板单次传递内容不应超过 800KB。在分布式场景下多设备间传递时，每次传递内容不应超过 64KB。

接口说明

SystemPasteboard 提供系统剪贴板操作的相关接口，比如复制、粘贴、配置回调等。PasteData 是剪贴板服务操作的数据对象，一个 PasteData 由若干个内容节点（PasteData.Record）和一个属性集合对象（PasteData.DataProperty）组成。Record 是存放剪贴板数据内容信息的最小单位，每个 Record 都有其特定的 MIME 类型，如纯文本、HTML、URI、Intent。剪贴板数据的属性信息存在放 DataProperty 中，包括标签、时间戳、“仅在本地”标记位等。

SystemPasteboard

SystemPasteboard 提供系统剪贴板服务的操作接口，比如复制、粘贴、配置回调等。

接口名	描述
getSystemPasteboard(Context context)	获取系统剪切板服务的对象实例。
getPasteData()	读取当前系统剪贴板中的数据。
hasPasteData()	判断当前系统剪贴板中是否有内容。
setPasteData(PasteData data)	将剪贴板数据写入到系统剪贴板。
clear()	清空系统剪贴板数据。
addPasteDataChangedListener(IPasteDataChangedListener listener)	用户程序添加系统剪贴板数据变化的回调，当系统剪贴板数据发生变化时，会触发用户程序的回调实现。
removePasteDataChangedListener(IPasteDataChangedListener listener)	用户程序移除系统剪贴板数据变化的回调。

PasteData

PasteData 是剪贴板服务操作的数据对象，其中内容节点定义为 PasteData.Record，属性集合定义为 PasteData.DataProperty。

接口名	描述
PasteData()	构造器，创建一个空内容数据对象。
createPlainTextData(CharSequence text)	构建一个包含纯文本内容节点的数据对象。
creatHtmlData(String htmlText)	构建一个包含 HTML 内容节点的数据对象。
creatUriData(Uri uri)	构建一个包含 URI 内容节点的数据对象。
creatIntentData(Intent intent)	构建一个包含 Intent 内容节点的数据对象。
getPrimaryMimeType()	获取数据对象中首个内容节点的 MIME 类型，如果没有查询到内容，将返回一个空字符串。
getPrimaryText()	获取数据对象中首个内容节点的纯文本内容，如果没有查询到内容，将返回一个空对象。
addTextRecord(CharSequence text)	向数据对象中添加一个纯文本内容节点，该方法会自动更新数据属性中的MIME类型集合，最多只能添加 128 个内容节点。
addRecord(Record record)	向数据对象中添加一个内容节点，该方法会自动更新数据属性中的 MIME 类型集合，最多只能添加 128 个内容节点。
getRecordCount()	获取数据对象中内容节点的数量。
getRecordAt(int index)	获取数据对象在指定下标处的内容节点，如果操作失败会返回空对象。
removeRecordAt(int index)	移除数据对象在指定下标处的内容节点，如果操作成功会返回 true，操作失败会返回 false。
getMimeTypes()	获取数据对象中上所有内容节点的MIME类型列表，当内容节点为空时，返回列表为空对象。
getProperty()	获取该数据对象的属性集合成员。

常量名	描述
MIMETYPE_TEXT_PLAIN= "text/plain"	纯文本的 MIME 类型定义。
MIMETYPE_TEXT_HTML= "text/html"	HTML的 MIM E类型定义。
MIMETYPE_TEXT_URI= "text/uri"	URI的 MIME 类型定义。
MIMETYPE_TEXT_INTENT= "text/ohos.intent"	Intent的 MIME 类型定义。
MAX_RECORD_NUM=128	单个 PasteData 中所能包含的 Record 的数量上限。

PasteData.Record

一个 PasteData 中包含若干个特定MIME类型的 PasteData.Record，每个 Record 是存放剪贴板数据内容信息的最小单位。

接口名	描述
createPlainTextRecord(CharSequence text)	构造一个 MIME 类型为纯文本的内容节点。
createHtmlTextRecord(String htmlText)	构造一个 MIME 类型为HTML的内容节点。
createUriRecord(Uri uri)	构造一个 MIME 类型为URI的内容节点。
createIntentRecord(Intent intent)	构造一个 MIME 类型为Intent的内容节点。
getPlainText()	获取该内容节点中的文本内容，如果没有内容将返回空对象。
getHtmlText()	获取该内容节点中的 HTML 内容，如果没有内容将返回空对象。
getUri()	获取该内容节点中的 URI 内容，如果没有内容将返回空对象。
getIntent()	获取该内容节点中的 Intent 内容，如果没有内容将返回空对象。
getMimeType()	获取该内容节点的 MIME 类型。
convertToText(Context context)	将该内容节点的内容转为文本形式。

PasteData.DataProperty

每个 PasteData 中都有一个 PasteData.DataProperty 成员，其中存放着该数据对象的属性集合，例如自定义标签、MIME 类型集合列表，“仅在本地”标记位等。

接口名	描述
getMimeTypes()	获取所属数据对象的 MIME 类型集合列表，当内容节点为空时，返回列表为空对象。
hasMimeType(String mimeType)	判断所属数据对象中是否包含特定 MIME类型的内容。
getTimestamp()	获取所属数据对象被写入系统剪贴板时的时间戳，如果该数据对象尚未被写入，则返回0。
setTag(CharSequence tag)	设置自定义标签。
getTag()	获取自定义标签。
setAdditions(PacMap extraProps)	设置一些附加键值对信息。
getAdditions()	获取附加键值对信息。
setLocalOnly(boolean isLocalonly)	配置“仅在本地”标志位，默认配置为false，表示此数据对象能在分布式剪贴板场景下跨设备传递，否则只在本地设备使用。
isLocalOnly()	查询“仅在本地”标志位。

IPasteDataChangedListener

IPasteDataChangedListener 是定义剪贴板数据变化回调的接口类，开发者需要实现此接口来编码触发回调时的处理逻辑。

接口名	描述
onChanged()	当系统剪贴板数据发生变化时的回调接口。

开发步骤

1. 应用A获取系统剪贴板服务。

   SystemPasteboard pasteboard = SystemPasteboard.getSystemPasteboard(appContext);

1. 应用A向系统剪贴板中写入一条纯文本数据。

   if (pasteboard != null) {
       pasteboard.setPasteData(PasteData.creatPlainTextData("Hello, world!"));
   }

1. 应用 B 从系统剪贴板读取数据，将数据对象中的首个文本类型（纯文本/HTML）内容信息在控件中显示，忽略其他类型内容。

   PasteData pasteData = pasteboard.getPasteData();
   if (pasteData == null) {
       return;
   }
   DataProperty dataProperty = pasteData.getProperty();
   boolean hasHtml = dataProperty.hasMimeType(PasteData.MIMETYPE_TEXT_HTML);
   boolean hasText = dataProperty.hasMimeType(PasteData.MIMETYPE_TEXT_PLAIN);
   if (hasHtml || hasText) {
       for (int i = 0; i < pasteData.getRecordCount(); i++) {
           Record record = pasteData.getRecordAt(i);
           String mimeType = record.getMimeType();
           if (mimeType.equals(PasteData.MIMETYPE_TEXT_HTML)) {
               text.setText(record.getHtmlText());
               break;
           } else if (mimeType.equals(PasteData.MIMETYPE_TEXT_PLAIN)) {
               text.setText(record.getPlainText().toString());
               break;
           }
       }
   }

1. 应用 C 注册添加系统剪贴板数据变化回调，当系统剪贴板数据发生变化时触发处理逻辑。

   IPasteDataChangedListener listener = new IPasteDataChangedListener() {
       @Override
       public void onChanged() {
           PasteData pasteData = pasteboard.getPasteData();
           if (pasteData == null) {
               return;
           }
           // Operations to handle data change on the system pasteboard
       }
   };
   pasteboard.addPasteDataChangedListener(listener);