剪贴板服务

简介

剪贴板服务作为杂散子系统的功能组件，提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪切板支持包文本、超本文、URIs等内容操作。

图 1 子系统架构图

剪贴板服务，提供支撑应用开发者方便、高效的使用剪贴板相关业务的功能。其主要组件包括剪贴板管理客户端和剪贴板服务。剪贴板管理客户端负责剪贴板接口管理，提供剪贴板北向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);
});

guochao / distributeddatamgr_pasteboard

剪贴板服务

简介

目录

说明

接口说明

使用说明

相关仓

简介

发行版

贡献者

近期动态

guochao / distributeddatamgr_pasteboard .gitee-modal { width: 500px !important; }

剪贴板服务

简介

目录

说明

接口说明

使用说明

相关仓

简介

发行版

贡献者

近期动态

搜索帮助

guochao / distributeddatamgr_pasteboard