鸿蒙开发系统基础能力：ohos.pasteboard 剪贴板

剪贴板

说明： 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 开发前请熟悉鸿蒙开发指导文档 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

导入模块

import pasteboard from '@ohos.pasteboard';

属性

系统能力 : 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。

名称	参数类型	可读	可写	说明
MAX_RECORD_NUM7+	number	是	否	单个PasteData中所能包含的Record的数量上限。
MIMETYPE_TEXT_HTML7+	string	是	否	HTML text文本的MIME类型定义。
MIMETYPE_TEXT_WANT7+	string	是	否	Want的MIME类型定义。
MIMETYPE_TEXT_PLAIN7+	string	是	否	Plain text文本的MIME类型定义。
MIMETYPE_TEXT_URI7+	string	是	否	URI文本的MIME类型定义。

pasteboard.createPlainTextData

createPlainTextData(text:string): PasteData

构建一个纯文本剪贴板内容对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
text	string	是	纯文本数据。

返回值

类型	说明
[PasteData]	包含此内容的剪贴板内容对象。

示例

var pasteData = pasteboard.createPlainTextData("content");

pasteboard.createHtmlData7+

createHtmlData(htmlText:string): PasteData

构建一个html文本剪贴板内容对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
htmlText	string	是	待保存的HTML文本内容。

返回值

类型	说明
[PasteData]	包含此内容的剪贴板内容对象。

示例

var html = "< !DOCTYPE html >n" + "< html >n" + "< head >n" + "< meta charset="utf-8" >n" + "< title >HTML-PASTEBOARD_HTML< /title >n" + "< /head >n" + "< body >n" + "    < h1 >HEAD< /h1 >n" + "    < p >< /p >n" + "< /body >n" + "< /html >";
var pasteData = pasteboard.createHtmlData(html);

pasteboard.createWantData7+

createWantData(want:Want): PasteData

构建一个want剪贴板内容对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
want	[Want]	是	待保存的Want内容。

返回值

类型	说明
[PasteData]	包含此内容的剪贴板内容对象。

示例

var object = {
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);

pasteboard.createUriData7+

createUriData(uri:string): PasteData

构建一个URI剪贴板内容对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
uri	string	是	待保存的URI内容。

返回值

类型	说明
[PasteData]	包含此内容的剪贴板内容对象。

示例

var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");

pasteboard.createPlainTextRecord7+

createPlainTextRecord(text:string): PasteDataRecord

创建一条文本类型的内容条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
text	string	是	纯文本内容。

返回值

类型	说明
[PasteDataRecord]	一条新建的纯文本内容条目。

示例

var record = pasteboard.createPlainTextRecord("hello");

pasteboard.createHtmlTextRecord7+

createHtmlTextRecord(htmlText:string): PasteDataRecord

创建一条HTML内容的条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
htmlText	string	是	HTML内容。

返回值

类型	说明
[PasteDataRecord]	一条新建的HTML内容条目。

示例

var html = "< !DOCTYPE html >n" + "< html >n" + "< head >n" + "< meta charset="utf-8" >n" + "< title >HTML-PASTEBOARD_HTML< /title >n" + "< /head >n" + "< body >n" + "    < h1 >HEAD< /h1 >n" + "    < p >< /p >n" + "< /body >n" + "< /html >";
var record = pasteboard.createHtmlTextRecord(html);

pasteboard.createWantRecord7+

createWantRecord(want:Want): PasteDataRecord

创建一条Want内容条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
want	[Want]	是	Want类型数据。

返回值

类型	说明
[PasteDataRecord]	一条新建的Want内容条目

示例

var object = {
    bundleName: "com.example.aafwk.test",
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var record = pasteboard.createWantRecord(object);

pasteboard.createUriRecord7+

createUriRecord(uri:string): PasteDataRecord

创建一条URI内容的条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
uri	string	是	URI内容。

返回值

类型	说明
[PasteDataRecord]	一条新建的URI内容条目。

示例

var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");

PasteDataProperty7+

定义了剪贴板中所有内容条目的属性，包含时间戳、数据类型以及一些附加数据等。

系统能力 : 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。

名称	参数类型	可读	可写	说明
additions	{[key: string]: object}	是	是	设置的其他附加属性数据。
mimeTypes	Array	是	否	剪贴板内容条目的数据类型, 非重复的类型列表。
tag	string	是	是	用户自定义标签。
timestamp	number	是	否	剪贴板数据的写入时间戳（毫秒）。
localOnly	boolean	是	是	配置剪贴板内容的“仅在本地”标志位。 - 默认情况为true。 - 配置为true时，表示内容仅在本地，不会在设备之间传递。 - 配置为false时，表示内容将在设备间传递。

PasteDataRecord7+

对于剪贴板中内容记录的抽象定义，称之为条目。剪贴板内容部分由一个或者多个条目构成，例如一条文本内容、一份HTML、一个URI或者一个Want。

属性

系统能力 : 以下各项对应的系统能力均为SystemCapability.MiscServices.Pasteboard。

名称	参数类型	可读	可写	说明
htmlText7+	string	是	否	HTML文本内容。
want7+	[Want]	是	否	Want文本内容。
mimeType7+	string	是	否	数据类型。
plainText7+	string	是	否	文本内容。
uri7+	string	是	否	URI内容。

convertToText7+

convertToText(): Promise

实例方法，将一个PasteData中的内容强制转换为文本内容，并使用Promise异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
Promise	异步回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。

示例

var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText().then((data) = > {
    console.info('convertToText success data : ' + JSON.stringify(data));
}).catch((error) = > { 
    console.error('convertToText failed because ' + JSON.stringify(error));
});

convertToText7+

convertToText(callback: AsyncCallback): void

实例方法，将一个PasteData中的内容强制转换为文本内容，并使用callback方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
callback	AsyncCallback	是	回调函数，调用成功则返回强制转换的文本内容，调用失败则返回error信息。

示例

var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
record.convertToText((err, data) = > {    
    if (err) {        
        console.error('convertToText failed because ' + JSON.stringify(err));        
        return;   
      }
    console.info('convertToText success data : ' + JSON.stringify(data));
});

PasteData

在调用PasteData的接口前，需要先获取一个PasteData对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

getPrimaryText

getPrimaryText(): string

获取首个条目的纯文本内容。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
string	纯文本内容。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var plainText = pasteData.getPrimaryText();

getPrimaryHtml7+

getPrimaryHtml(): string

获取首个条目的HTML文本内容。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
string	HTML文本数据。

示例

var html = "< !DOCTYPE html >n" + "< html >n" + "< head >n" + "< meta charset="utf-8" >n" + "< title >HTML-PASTEBOARD_HTML< /title >n" + "< /head >n" + "< body >n" + "    < h1 >HEAD< /h1 >n" + "    < p >< /p >n" + "< /body >n" + "< /html >";
var pasteData = pasteboard.createHtmlData(html);
var htmlText = pasteData.getPrimaryHtml();

getPrimaryWant7+

getPrimaryWant(): Want

获取首个条目的Want对象内容。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
[Want]	Want对象内容。

示例

var object = { 
    bundleName: "com.example.aafwk.test",    
    abilityName: "com.example.aafwk.test.TwoAbility"
};
var pasteData = pasteboard.createWantData(object);
var want = pasteData.getPrimaryWant();

getPrimaryUri7+

getPrimaryUri(): string

获取首个条目的URI文本内容。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
string	URI文本内容。

示例

var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var uri = pasteData.getPrimaryUri();

addTextRecord7+

addTextRecord(text: string): void

向当前剪贴板内容中添加一条纯文本条目，并将MIME_TEXT_PLAIN添加到[PasteDataProperty]的mimeTypes中。入参均不能为空，否则添加失败。

剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
text	string	是	纯文本内容。

示例

var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addTextRecord("good");

addHtmlRecord7+

addHtmlRecord(htmlText: string): void

向当前剪贴板内容中添加一条HTML文本条目，并将MIMETYPE_TEXT_HTML添加到[PasteDataProperty]的mimeTypes中。入参均不能为空，否则添加失败。

剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
htmlText	string	是	HTML格式的文本内容。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var html = "< !DOCTYPE html >n" + "< html >n" + "< head >n" + "< meta charset="utf-8" >n" + "< title >HTML-PASTEBOARD_HTML< /title >n" + "< /head >n" + "< body >n" + "    < h1 >HEAD< /h1 >n" + "    < p >< /p >n" + "< /body >n" + "< /html >";
pasteData.addHtmlRecord(html);

addWantRecord7+

addWantRecord(want: Want): void

向当前剪贴板内容中添加一条Want条目，并将MIMETYPE_TEXT_WANT添加到[PasteDataProperty]的mimeTypes中。入参均不能为空，否则添加失败。

剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
want	[Want]	是	Want对象内容。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var object = { 
    bundleName: "com.example.aafwk.test",    
    abilityName: "com.example.aafwk.test.TwoAbility"
};
pasteData.addWantRecord(object);

addUriRecord7+

addUriRecord(uri: string): void

向当前剪贴板内容中添加一条URI条目，并将MIMETYPE_TEXT_URI添加到[PasteDataProperty]的mimeTypes中。入参均不能为空，否则添加失败。

剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
uri	string	是	URI文本内容。

示例

var pasteData = pasteboard.createPlainTextData("hello");
pasteData.addUriRecord("dataability:///com.example.myapplication1?user.txt");

addRecord7+

addRecord(record: PasteDataRecord): void

向当前剪贴板内容中添加一条条目，同时也会将条目类型添加到PasteDataProperty的mimeTypes中。入参均不能为空，否则添加失败。

剪贴板内容中添加的条目达到数量上限128后，后续的添加操作无效。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
record	[PasteDataRecord]	是	待添加的条目。

示例

var pasteData = pasteboard.createUriData("dataability:///com.example.myapplication1?user.txt");
var textRecord = pasteboard.createPlainTextRecord("hello");
var html = "< !DOCTYPE html >n" + "< html >n" + "< head >n" + "< meta charset="utf-8" >n" + "< title >HTML-PASTEBOARD_HTML< /title >n" + "< /head >n" + "n" + "    < h1 >HEAD< /h1 >n" + "    < p >< /p >n" + "< /body >n" + "< /html >";
var htmlRecord = pasteboard.createHtmlTextRecord(html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);

getMimeTypes7+

getMimeTypes(): Array

获取剪贴板中[PasteDataProperty]的mimeTypes列表，当剪贴板内容为空时，返回列表为空。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
Array	非重复的类型列表。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var types = pasteData.getMimeTypes();

getPrimaryMimeType7+

getPrimaryMimeType(): string

获取首个条目的数据类型。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
string	首个条目的数据类型。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var type = pasteData.getPrimaryMimeType();

getProperty7+

getProperty(): PasteDataProperty

获取属性描述对象。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
[PasteDataProperty]	属性描述对象。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var property = pasteData.getProperty();

getRecordAt7+

getRecordAt(index: number): PasteDataRecord

获取指定下标的条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
index	number	是	指定条目的下标。

返回值

类型	说明
[PasteDataRecord]	指定下标的条目。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(0);

getRecordCount7+

getRecordCount(): number

获取剪贴板中条目的个数。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
number	条目的个数。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var count = pasteData.getRecordCount();

getTag7+

getTag(): string

获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
string	获取用户自定义的标签内容，如果没有设置用户自定义的标签内容将返回空。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var tag = pasteData.getTag();

hasMimeType7+

hasMimeType(mimeType: string): boolean

检查内容中是否有指定的数据类型。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
mimeType	string	是	待查询的数据类型。

返回值

类型	说明
boolean	有指定的数据类型返回true，否则返回false。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);

removeRecordAt7+

removeRecordAt(index: number): boolean

移除指定下标的条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
index	number	是	指定的下标。

返回值

类型	说明
boolean	成功移除返回true，失败返回false。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var isRemove = pasteData.removeRecordAt(0);

replaceRecordAt7+

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

替换指定下标的条目。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
index	number	是	指定的下标。
record	[PasteDataRecord]	是	替换后的条目。

返回值

类型	说明
boolean	成功替换返回true，失败返回false。

示例

var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteboard.createUriRecord("dataability:///com.example.myapplication1?user.txt");
var isReplace = pasteData.replaceRecordAt(0, record);

pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

获取系统剪切板。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
[SystemPasteboard]	系统剪切板对象。

示例

var systemPasteboard = pasteboard.getSystemPasteboard();

SystemPasteboard

在调用SystemPasteboard的接口前，需要先通过getSystemPasteboard获取系统剪切板。

var systemPasteboard = pasteboard.getSystemPasteboard();

setPasteData

setPasteData(data:PasteData, callback:AsyncCallback): void

将数据写入系统剪切板，并使用callback方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
data	[PasteData]	是	PasteData对象。
callback	AsyncCallback	是	回调函数，表示是否成功将数据写入系统剪切板。

示例

var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (error, data) = > { 
    if (error) {
        console.error('Failed to setPasteData. Cause: ' + error.message);
        return;
    }
    console.info('setPasteData successfully.');
});

setPasteData

setPasteData(data:PasteData): Promise

将数据写入系统剪切板，并使用Promise异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	说明
data	[PasteData]	PasteData对象。

返回值

类型	说明
Promise	异步回调函数，表示是否成功将数据写入系统剪切板。

示例

var pasteData = pasteboard.createPlainTextData("content");
var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) = > {
    console.info('setPasteData success.');
}).catch((error) = > {
    console.error('Failed to setPasteData. Cause: ' + error.message);
});

getPasteData

getPasteData( callback:AsyncCallback): void

读取系统剪切板内容，并使用callback方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
callback	AsyncCallback<[PasteData]>	是	回调函数，返回系统剪切板数据。

示例

var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData((error, pasteData) = > {  
    if (error) {
        console.error('Failed to getPasteData. Cause: ' + error.message);
        return;
    }
    var text = pasteData.getPrimaryText();
});

getPasteData

getPasteData(): Promise

读取系统剪切板内容，并使用Promise异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
Promise<[PasteData]>	异步回调函数，调返回系统剪切板数据。

示例

var systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getPasteData().then((pasteData) = > { 
    var text = pasteData.getPrimaryText();
}).catch((error) = > {
    console.error('Failed to getPasteData. Cause: ' + error.message);
})

on('update')7+

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

订阅系统剪贴板内容变化事件，当系统剪贴板中内容变化时触发用户程序的回调。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
type	string	是	取值为'update'，表示系统剪贴板内容变化事件。
callback	function	是	剪贴板中内容变化时触发的用户程序的回调。

示例

var systemPasteboard = pasteboard.getSystemPasteboard();
var listener = () = > {
    console.info('The system pasteboard has changed');
};
systemPasteboard.on('update', listener);

off('update')7+

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

取消订阅系统剪贴板内容变化事件。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
type	string	是	取值为'update'，表示系统剪贴板内容变化事件。
callback	function	否	剪贴板中内容变化时触发的用户程序的回调。

示例

let listener = () = > {
    console.info('The system pasteboard has changed');
};
systemPasteboard.off('update', listener);

hasPasteData7+

hasPasteData(callback: AsyncCallback): void

判断系统剪切板中是否有内容，并使用callback异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
callback	AsyncCallback	是	返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。

示例

systemPasteboard.hasPasteData((err, data) = > {
    if (err) {
        console.error('failed to hasPasteData because ' + JSON.stringify(err));
        return;
    }
    console.info('success hasPasteData : ' + JSON.stringify(data));
});

hasPasteData7+

hasPasteData(): Promise

判断系统剪切板中是否有内容，并使用Promise异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
Promise	返回为true表示系统剪切板中有内容，返回false表示系统剪切板中没有内容。

示例

systemPasteboard.hasPasteData().then((data) = > { 
    console.info('success hasPasteData : ' + JSON.stringify(data));
}).catch((error) = > {
    console.error('failed to hasPasteData because ' + JSON.stringify(error));
});

clear7+

clear(callback: AsyncCallback): void

清空系统剪切板内容，并使用callback异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

参数

参数名	类型	必填	说明
callback	AsyncCallback	是	回调函数，表示是否成功清空系统剪切板内容。

示例

systemPasteboard.clear((err, data) = > { 
    if (err) {        
        console.error('failed to clear because ' + JSON.stringify(err));        
        return;    
    }
    console.info('success clear');
});

clear7+

clear(): Promise

清空系统剪切板内容，并使用Promise异步方式返回结果。

系统能力 : SystemCapability.MiscServices.Pasteboard

返回值

类型	说明
Promise	异步回调函数，表示是否成功清空系统剪切板内容。HarmonyOS与OpenHarmony鸿蒙文档籽料：mau123789是v直接拿

示例

systemPasteboard.clear().then((data) = > { 
    console.info('success clear');
}).catch((error) = > {    
    console.error('failed to clear because ' + JSON.stringify(error));
});

审核编辑 黄宇