"鸿蒙OS开发文档"的目录
鸿蒙OS开发文档 鸿蒙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() | 当系统剪贴板数据发生变化时的回调接口。 |
开发步骤
- 应用A获取系统剪贴板服务。
SystemPasteboard pasteboard = SystemPasteboard.getSystemPasteboard(appContext);
- 应用A向系统剪贴板中写入一条纯文本数据。
if (pasteboard != null) {
pasteboard.setPasteData(PasteData.creatPlainTextData("Hello, world!"));
} - 应用 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;
}
}
}
- 应用 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);