# distributeddatamgr_pasteboard **Repository Path**: this-is-a-net-name/distributeddatamgr_pasteboard ## Basic Information - **Project Name**: distributeddatamgr_pasteboard - **Description**: Pasteboard System Ability | 剪贴板服务 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 298 - **Created**: 2025-02-24 - **Last Updated**: 2025-02-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 剪贴板服务 ## 简介 剪贴板服务作为杂散子系统的功能组件，提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪切板支持包文本、超本文、URIs等内容操作。 **图 1** 子系统架构图 ![](figures/subsystem_architecture_zh.png "子系统架构图") 剪贴板服务，提供支撑应用开发者方便、高效的使用剪贴板相关业务的功能。其主要组件包括剪贴板管理客户端和剪贴板服务。剪贴板管理客户端负责剪贴板接口管理，提供剪贴板北向JS API给应用；在应用框架侧创建剪贴板数据、请求剪贴板SA执行剪贴板的新建、删除、查询、转换文本、配置等。剪贴板服务负责剪贴板事件管理，管理剪贴板SA的生命周期（启动、销毁、多用户等）；执行应用请求，通知剪贴板数据管理，并将结果返回给剪贴板管理客户端。 ## 目录 ``` /foundation/distributeddatamgr/pasteboard ├── etc # 组件包含的进程的配置文件 ├── figures # 构架图 ├── framework # innerKit接口 ├── interfaces # 组件对外提供的接口代码 │ └── kits # 对应用提供的接口 ├── profile # 组件包含的系统服务的配置文件 ├── services # 剪贴板服务实现 │ └── core # 核心代码实现 │ └── test # native测试代码 │ └── zidl # 跨进程通信代码实现 ├── utils # 测试或服务使用mock的数据 └──README_zh.md # 使用说明 ``` ## 说明 ### 接口说明 **表 1** PasteBoard开放的主要方法

接口名

描述

createData(mimeType: string, value: ValueType): PasteData;

用MIME类型和值创建一个PasteData 对象

createRecord(mimeType: string, value: ValueType): PasteDataRecord;

用MIME类型和值创建一个PasteDataRecord对象

createHtmlData(htmlText: string): PasteData;

为HTML类型的数据创建一个MIMETYPE_TEXT_HTML类型的PasteData 对象

createWantData(want: Want): PasteData;

为want类型的数据创建一个MIMETYPE_TEXT_WANT类型的PasteData对象

createPlainTextData(text: string): PasteData;

为纯文本类型的数据创建一个MIMETYPE_TEXT_PLAIN类型的PasteData 对象

createUriData(uri: string): PasteData;

为URI类型的数据创建一个MIMETYPE_TEXT_URI类型的PasteData 对象

createHtmlTextRecord(htmlText: string): PasteDataRecord;

为超文本类型的数据创建一个RecordMIMETYPE_TEXT_HTML类型的PasteDataRecord对象

createWantRecord(want: Want): PasteDataRecord;

为want类型的数据创建一个MIMETYPE_TEXT_WANT类型的PasteDataRecord对象

createPlainTextRecord(text: string): PasteDataRecord;

为纯文本类型的数据创建一个MIMETYPE_TEXT_PLAIN类型的PasteDataRecord对象

createUriRecord(uri: string): PasteDataRecord;

为URI类型的数据创建一个MIMETYPE_TEXT_URI类型的PasteDataRecord对象

getSystemPasteboard(): SystemPasteboard;

获取系统剪贴板
**表 2** SystemPasteboard开放的主要方法

接口名

描述

clearData(callback: AsyncCallback<void>): void;

清除剪贴板

clearData(): Promise<void>;

清除剪贴板

getData(callback: AsyncCallback<PasteData>): void;

从系统剪贴板获取pastedata对象

getData(): Promise<PasteData>;

从系统剪贴板获取pastedata对象

hasData(callback: AsyncCallback<boolean>): void;

判断系统剪贴板中的内容

hasData(): Promise<boolean>;

判断系统剪贴板中的内容

setData(data: PasteData, callback: AsyncCallback<void>): void;

向系统剪贴板写入PasteData

setData(data: PasteData): Promise<void>;

向系统剪贴板写入PasteData

on(type:'update', callback: () => void): void;

打开粘贴板内容更改时调用的回调

off(type: 'update', callback?: () => void): void;

关闭粘贴板内容更改时调用的回调

clear(callback: AsyncCallback<void>): void;

清除剪贴板

clear(): Promise<void>;

清除剪贴板

getPasteData(callback: AsyncCallback<PasteData>): void;

获取系统剪贴板数据对象

getPasteData():Promise<PasteData>;

获取系统剪贴板数据对象

hasPasteData(callback: AsyncCallback<boolean>:void;

检查粘贴板中是否有内容

hasPasteData(): Promise<boolean>;

检查粘贴板中是否有内容

setPasteData(data: PasteData, callback: AsyncCallback<void>:void;

将 PasteData 写入粘贴板

setPasteData(data: PasteData): Promise<void>;

将 PasteData 写入粘贴板
**表 3** PasteData开放的主要方法

接口名

描述

addRecord(mimeType: string, value: ValueType): void;

将mimeType和对应值添加到 PasteData 对象中

getRecord(index: number): PasteDataRecord;

使用PasteData对象中的次序获取PasteDataRecord记录

hasType(mimeType: string): boolean;

判断DataProperty中是否有指定MIME类型的值

removeRecord(index: number): void;

基于PasteData中值的次序删除一条记录

replaceRecord(index: number, record: PasteDataRecord): void;

用PasteDataRecord记录替换PasteData中指定次序的记录

addHtmlRecord(htmlText: string): void;

将 HTML 文本记录添加到 PasteData 对象，并将 MIME 类型更新为 DataProperty 中的 PasteData#MIMETYPE_TEXT_HTML。

addWantRecord(want: Want): void;

将want记录添加到 PasteData 对象，并将 MIME 类型更新为 DataProperty 中的 PasteData#MIMETYPE_TEXT_WANT

addRecord(record: PasteDataRecord): void;

将 PasteRecord 添加到粘贴数据对象并更新数据属性中的 MIME 类型

addTextRecord(text: string): void;

将纯文本记录添加到 PasteData 对象，并将 MIME 类型更新为 DataProperty 中的 PasteData#MIMETYPE_TEXT_PLAIN

addUriRecord(uri: string): void;

将 URI 记录添加到 PasteData 对象，并将 MIME 类型更新为 DataProperty 中的 PasteData#MIMETYPE_TEXT_URI

getMimeTypes(): Array<string>;

粘贴板上所有内容的 MIME 类型

getPrimaryHtml(): string;

PasteData 对象中主要记录的 HTML 文本

getPrimaryWant(): Want;

PasteData 对象中的主记录的want

getPrimaryMimeType(): string;

PasteData 对象中主记录的 MIME 类型。

getPrimaryUri(): string;

PasteData 对象中主记录的 URI

getPrimaryPixelMap(): image.PixelMap;

PasteData 对象中主记录的 PixelMap。

getProperty(): PasteDataProperty;

获取剪贴板数据对象的属性

setProperty(property: PasteDataProperty): void;

设置属性描述对象，当前仅支持设置shareOption属性。

getRecordAt(index: number): PasteDataRecord;

基于指定索引的记录

getRecordCount(): number;

PasteData 对象中的记录数

hasMimeType(mimeType: string): boolean;

检查 DataProperty 中是否存在指定的 MIME 类型的数据

removeRecordAt(index: number): boolean;

根据指定索引删除记录

replaceRecordAt(index: number, record: PasteDataRecord): boolean;

用新记录替换指定记录
**表 4** PasteDataRecord开放的主要方法

接口名

描述

convertToTextV9(callback: AsyncCallback<string>): void;

将 PasteData中的数据 转换为文本格式

convertToTextV9(): Promise<string>;

将 PasteData中的数据 转换为文本格式

convertToText(callback: AsyncCallback<string>): void;

将 PasteData 转换为文本内容的内容

convertToText(): Promise<void>;

将 PasteData 转换为文本内容的内容
**表 5** PasteDataProperty参数说明

名称

类型

说明

additions{[key:string]}

object

附加属性数据键值对

mimeTypes

Array

PasteData 中所有记录的非重复 MIME 类型

tag

string

PasteData 对象的用户定义标签

timestamp

number

时间戳，指示何时将数据写入系统粘贴板。

localOnly

boolean

检查 PasteData 是否设置为仅用于本地访问。

shareOption

[ShareOption](https://gitee.com/openharmony/docs/blob/a4ead7d2fe7ac381133ba47c70c9df8cdfa95325/zh-cn/application-dev/reference/apis/js-apis-pasteboard.md#shareoption9)

指示剪贴板数据可以粘贴到的范围 。
**表 6** pasteboard主要属性说明

名称

类型

说明

MAX_RECORD_NUM

number

单个PasteData中所能包含的Record的数量上限。

MIMETYPE_TEXT_HTML

string

HTML text文本的MIME类型定义。

MIMETYPE_TEXT_WANT

string

Want的MIME类型定义。

MIMETYPE_TEXT_PLAIN

string

Plain text文本的MIME类型定义。

MIMETYPE_TEXT_URI

string

URI文本的MIME类型定义。

MIMETYPE_PIXELMAP

string

PixelMap的MIME类型定义 。

ValueType

string | image.PixelMap | Want | ArrayBuffer

value值的类型定义。

**表 7** PasteDataRecord主要属性说明

名称

类型

说明

htmlText

string

HTML文本内容。

want

[Want](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis/js-apis-application-want.md)

Want文本内容。

mimeType

string

数据类型。

plainText

string

文本内容。

uri

string

URI内容。

pixelMap

[image.PixelMap](https://gitee.com/openharmony/docs/blob/a4ead7d2fe7ac381133ba47c70c9df8cdfa95325/zh-cn/application-dev/reference/apis/js-apis-image.md#pixelmap7)

PixelMap内容。

**表 8** ShareOption枚举类型说明

名称

说明

InApp

InApp表示仅允许同应用内粘贴。

LocalDevice

LocalDevice表示仅允许在此设备中粘贴。
### 使用说明 剪贴板模块使用示例： ``` // 导入模块 import pasteboard from '@ohos.pasteboard' //文本拷贝 console.log('Get SystemPasteboard') var systemPasteboard = pasteboard.getSystemPasteboard() systemPasteboard.clear() var textData = 'Hello World!' console.log('createPlainTextData = ' + textData) var pasteData = pasteboard.createPlainTextData(textData) console.log('Writes PasteData to the pasteboard') systemPasteboard.setPasteData(pasteData) console.log('Checks there is content in the pasteboard') assert.equal(systemPasteboard.hasPasteData(), true) console.log('Checks the number of records') pasteData = systemPasteboard.getPasteData() assert.equal(pasteData.getRecordCount(), 1) console.log('Checks the pasteboard content') assert.equal(pasteData.getPrimaryText(), textData) console.log('Checks there is a MIMETYPE_TEXT_PLAIN MIME type of data') assert.equal(pasteData.hasMimeType(MIMETYPE_TEXT_PLAIN), true) assert.equal(pasteData.getPrimaryMimeType(), MIMETYPE_TEXT_PLAIN) //剪贴板变化监听 console.log('Off the content changes') var systemPasteboard = pasteboard.getSystemPasteboard() systemPasteboard.off(contentChanges) systemPasteboard.clear() var textData = 'Hello World!' console.log('createUriData = ' + textData) var pasteData = pasteboard.createUriData(textData) console.log('Writes PasteData to the pasteboard') systemPasteboard.setPasteData(pasteData) console.log('Checks there is content in the pasteboard') assert.equal(systemPasteboard.hasPasteData(), true) console.log('Checks the number of records') pasteData = systemPasteboard.getPasteData() assert.equal(pasteData.getRecordCount(), 1) console.log('On the content changes') systemPasteboard.on(contentChanges) console.log('Removes the Record') assert.equal(pasteData.removeRecordAt(0), true) console.log('Writes PasteData to the pasteboard') systemPasteboard.setPasteData(pasteData) console.log('Checks the number of records') pasteData = systemPasteboard.getPasteData() assert.equal(pasteData.getRecordCount(), 0) console.log('Checks there is no content in the pasteboard') assert.equal(systemPasteboard.hasPasteData(), false) var textDataNew = 'Hello World!-New' console.log('createUriData = ' + textDataNew) var pasteData = pasteboard.createUriData(textDataNew) console.log('Writes PasteData to the pasteboard') systemPasteboard.setPasteData(pasteData) console.log('Checks there is content in the pasteboard') assert.equal(systemPasteboard.hasPasteData(), true) console.log('Checks the number of records') pasteData = systemPasteboard.getPasteData() assert.equal(pasteData.getRecordCount(), 1) console.log('Checks the pasteboard content') assert.equal(pasteData.getRecordAt(0).plainText, textDataNew) //构建一个自定义类型的剪贴板内容对象 var dataXml = new ArrayBuffer(256); var pasteData = pasteboard.createData('app/xml', dataXml); //创建一条自定义数据内容条目 var dataXml = new ArrayBuffer(256); var pasteDataRecord = pasteboard.createRecord('app/xml', dataXml); //将一个PasteData中的内容强制转换为文本内容，使用callback异步回调 var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); record.convertToTextV9((err, data) => { if (err) { console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); return; } console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); }); //将一个PasteData中的内容强制转换为文本内容，使用Promise异步回调 var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); record.convertToTextV9().then((data) => { console.info('Succeeded in converting to text. Data: ' + JSON.stringify(data)); }).catch((err) => { console.error('Failed to convert to text. Cause: ' + JSON.stringify(err)); }); //向当前剪贴板内容中添加一条自定义数据内容条目 var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1/user.txt"); var dataXml = new ArrayBuffer(256); pasteData.addRecord('app/xml', dataXml); //获取剪贴板内容中指定下标的条目 var pasteData = pasteboard.createPlainTextData("hello"); var record = pasteData.getRecord(0); //检查剪贴板内容中是否有指定的MIME数据类型 var pasteData = pasteboard.createPlainTextData("hello"); var hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN); //移除剪贴板内容中指定下标的条目 var pasteData = pasteboard.createPlainTextData("hello"); pasteData.removeRecord(0); //替换剪贴板内容中指定下标的条目 var pasteData = pasteboard.createPlainTextData("hello"); var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1/user.txt"); pasteData.replaceRecord(0, record); //清空系统剪贴板内容，使用callback异步回调 systemPasteboard.clearData((err, data) => { if (err) { console.error('Failed to clear the pasteboard. Cause: ' + JSON.stringify(err)); return; } console.info('Succeeded in clearing the pasteboard.'); }); //清空系统剪贴板内容，使用Promise异步回调 systemPasteboard.clearData().then((data) => { console.info('Succeeded in clearing the pasteboard.'); }).catch((err) => { console.error('Failed to clear the pasteboard. Cause: ' + JSON.stringify(err)); }); //读取系统剪贴板内容，使用callback异步回调 var systemPasteboard = pasteboard.getSystemPasteboard(); systemPasteboard.getData((err, pasteData) => { if (err) { console.error('Failed to get PasteData. Cause: ' + err.message); return; } var text = pasteData.getPrimaryText(); }); //读取系统剪贴板内容，使用Promise异步回调 var systemPasteboard = pasteboard.getSystemPasteboard(); systemPasteboard.getData().then((pasteData) => { var text = pasteData.getPrimaryText(); }).catch((err) => { console.error('Failed to get PasteData. Cause: ' + err.message); }) //判断系统剪贴板中是否有内容，使用callback异步回调 systemPasteboard.hasData((err, data) => { if (err) { console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); return; } console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); }); //判断系统剪贴板中是否有内容，使用Promise异步回调 systemPasteboard.hasData().then((data) => { console.info('Succeeded in checking the PasteData. Data: ' + JSON.stringify(data)); }).catch((err) => { console.error('Failed to check the PasteData. Cause: ' + JSON.stringify(err)); }); //将数据写入系统剪贴板，使用callback异步回调 var pasteData = pasteboard.createPlainTextData("content"); var systemPasteboard = pasteboard.getSystemPasteboard(); systemPasteboard.setData(pasteData, (err, data) => { if (err) { console.error('Failed to set PasteData. Cause: ' + err.message); return; } console.info('Succeeded in setting PasteData.'); }); //将数据写入系统剪贴板，使用Promise异步回调 var pasteData = pasteboard.createPlainTextData("content"); var systemPasteboard = pasteboard.getSystemPasteboard(); systemPasteboard.setData(pasteData).then((data) => { console.info('Succeeded in setting PasteData.'); }).catch((err) => { console.error('Failed to set PasteData. Cause: ' + err.message); }); ``` ## 相关仓 **分布式数据管理子系统** [distributeddatamgr\_pasteboard](https://gitee.com/openharmony/distributeddatamgr_pasteboard)