@ohos.pasteboard (剪贴板)

本模块主要提供管理系统剪贴板的能力，为系统复制、粘贴功能提供支持。系统剪贴板支持对文本、HTML、URI、Want、PixelMap等内容的操作。

说明：

本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import pasteboard from '@ohos.pasteboard';

常量

系统能力： SystemCapability.MiscServices.Pasteboard

名称	类型	值	说明
MAX_RECORD_NUM⁷⁺	number	512	单个PasteData中所能包含的最大条目数。
MIMETYPE_TEXT_HTML⁷⁺	string	'text/html'	HTML内容的MIME类型定义。
MIMETYPE_TEXT_WANT⁷⁺	string	'text/want'	Want内容的MIME类型定义。
MIMETYPE_TEXT_PLAIN⁷⁺	string	'text/plain'	纯文本内容的MIME类型定义。
MIMETYPE_TEXT_URI⁷⁺	string	'text/uri'	URI内容的MIME类型定义。
MIMETYPE_PIXELMAP⁹⁺	string	'pixelMap'	PixelMap内容的MIME类型定义。

ValueType⁹⁺

用于表示允许的数据字段类型。

系统能力： SystemCapability.MiscServices.Pasteboard

类型	说明
string	表示string的类型。
image.PixelMap	表示image.PixelMap的类型。
Want	表示Want的类型。
ArrayBuffer	表示ArrayBuffer的类型。

pasteboard.createData⁹⁺

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

构建一个自定义类型的剪贴板内容对象。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
mimeType	string	是	自定义数据的MIME类型。
value	ValueType	是	自定义数据内容。

返回值：

类型	说明
PasteData	剪贴板内容对象。

示例：

let dataXml = new ArrayBuffer(256);
let pasteData = pasteboard.createData('app/xml', dataXml);

pasteboard.createRecord⁹⁺

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

创建一条自定义数据内容条目。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
mimeType	string	是	自定义数据的MIME类型。
value	ValueType	是	自定义数据内容。

返回值：

类型	说明
PasteDataRecord	一条新建的自定义数据内容条目。

示例：

let dataXml = new ArrayBuffer(256);
let pasteDataRecord = pasteboard.createRecord('app/xml', dataXml);

pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

获取系统剪贴板对象。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
SystemPasteboard	系统剪贴板对象。

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();

ShareOption⁹⁺

可粘贴数据的范围类型枚举。

系统能力： SystemCapability.MiscServices.Pasteboard

名称	值	说明
INAPP	0	表示仅允许同应用内粘贴。
LOCALDEVICE	1	表示允许在此设备中任何应用内粘贴。
CROSSDEVICE	2	表示允许跨设备在任何应用内粘贴。

pasteboard.createHtmlData^(deprecated)

createHtmlData(htmlText: string): PasteData

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

类型	说明
PasteData	剪贴板内容对象。

示例：

let 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>";
let pasteData = pasteboard.createHtmlData(html);

pasteboard.createWantData^(deprecated)

createWantData(want: Want): PasteData

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
want	Want	是	Want内容。

返回值：

类型	说明
PasteData	剪贴板内容对象。

示例：

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

pasteboard.createPlainTextData^(deprecated)

createPlainTextData(text: string): PasteData

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

类型	说明
PasteData	剪贴板内容对象。

示例：

let pasteData = pasteboard.createPlainTextData('content');

pasteboard.createUriData^(deprecated)

createUriData(uri: string): PasteData

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

类型	说明
PasteData	剪贴板内容对象。

示例：

let pasteData = pasteboard.createUriData('dataability:///com.example.myapplication1/user.txt');

pasteboard.createHtmlTextRecord^(deprecated)

createHtmlTextRecord(htmlText: string): PasteDataRecord

创建一条HTML内容的条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let 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>";
let record = pasteboard.createHtmlTextRecord(html);

pasteboard.createWantRecord^(deprecated)

createWantRecord(want: Want): PasteDataRecord

创建一条Want内容条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
want	Want	是	Want内容。

返回值：

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

示例：

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

pasteboard.createPlainTextRecord^(deprecated)

createPlainTextRecord(text: string): PasteDataRecord

创建一条纯文本内容条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let record = pasteboard.createPlainTextRecord('hello');

pasteboard.createUriRecord^(deprecated)

createUriRecord(uri: string): PasteDataRecord

创建一条URI内容的条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.createRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');

PasteDataProperty⁷⁺

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

系统能力： SystemCapability.MiscServices.Pasteboard

名称	类型	可读	可写	说明
additions⁷⁺	{[key:string]:object}	是	是	设置其他附加属性数据。
mimeTypes⁷⁺	Array<string>	是	否	剪贴板内容条目的数据类型，非重复的类型列表。
tag⁷⁺	string	是	是	用户自定义标签。
timestamp⁷⁺	number	是	否	剪贴板数据的写入时间戳（单位：ms）。
localOnly⁷⁺	boolean	是	是	配置剪贴板内容是否为“仅在本地”，默认值为false。暂不支持，推荐使用shareOption属性。 - 配置为true时，表示内容仅在本地，不会在设备之间传递。 - 配置为false时，表示内容将在设备间传递。
shareOption⁹⁺	ShareOption	是	是	指示剪贴板数据可以粘贴到的范围，如果未设置或设置不正确，则默认值为CROSSDEVICE。

PasteDataRecord⁷⁺

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

属性

系统能力： SystemCapability.MiscServices.Pasteboard

名称	类型	可读	可写	说明
htmlText⁷⁺	string	是	否	HTML内容。
want⁷⁺	Want	是	否	Want内容。
mimeType⁷⁺	string	是	否	数据类型。
plainText⁷⁺	string	是	否	纯文本内容。
uri⁷⁺	string	是	否	URI内容。
pixelMap⁹⁺	image.PixelMap	是	否	PixelMap内容。
data⁹⁺	{[mimeType: string]: ArrayBuffer}	是	否	自定义数据内容。

toPlainText⁹⁺

toPlainText(): string

将一个PasteData中的内容强制转换为文本内容。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
string	纯文本内容。

示例：

let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt');
let data = record.toPlainText();
console.info(`Succeeded in converting to text. Data: ${data}`);

convertToText^(deprecated)

convertToText(callback: AsyncCallback<string>): void

将一个PasteData中的内容强制转换为文本内容，使用callback异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用toPlainText替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
callback	AsyncCallback<string>	是	回调函数，当转换成功，err为undefined，data为强制转换的文本内容；否则返回错误信息。

示例：

let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
record.convertToText((err, data) => {
    if (err) {
        console.error(`Failed to convert to text. Cause: ${err.message}`);
        return;
    }
    console.info(`Succeeded in converting to text. Data: ${data}`);
});

convertToText^(deprecated)

convertToText(): Promise<string>

将一个PasteData中的内容强制转换为文本内容，使用Promise异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用toPlainText替代。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<string>	Promise对象，返回强制转换的文本内容。

示例：

let record = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
record.convertToText().then((data) => {
    console.info(`Succeeded in converting to text. Data: ${data}`);
}).catch((err) => {
    console.error(`Failed to convert to text. Cause: ${err.message}`);
});

PasteData

剪贴板内容对象。剪贴板内容包含一个或者多个内容条目（PasteDataRecord）以及属性描述对象（PasteDataProperty）。

在调用PasteData的接口前，需要先通过createData()或getData()获取一个PasteData对象。

系统能力： SystemCapability.MiscServices.Pasteboard

getPrimaryText

getPrimaryText(): string

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

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
string	纯文本内容。

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let plainText = pasteData.getPrimaryText();

getPrimaryHtml⁷⁺

getPrimaryHtml(): string

获取首个条目的HTML内容。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
string	HTML内容。

示例：

let 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>";
let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, html);
let htmlText = pasteData.getPrimaryHtml();

getPrimaryWant⁷⁺

getPrimaryWant(): Want

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

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Want	Want对象内容。

示例：

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

getPrimaryUri⁷⁺

getPrimaryUri(): string

获取首个条目的URI内容。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
string	URI内容。

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt');
let uri = pasteData.getPrimaryUri();

getPrimaryPixelMap⁹⁺

getPrimaryPixelMap(): image.PixelMap

获取首个条目的PixelMap内容。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
image.PixelMap	PixelMap内容。

示例：

import image from '@ohos.multimedia.image';

let buffer = new ArrayBuffer(128);
let opt = {
  size: { height: 3, width: 5 },
  pixelFormat: 3,
  editable: true,
  alphaType: 1,
  scaleMode: 1
};
image.createPixelMap(buffer, opt).then((pixelMap) => {
    let pasteData = pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP, pixelMap);
    let PixelMap = pasteData.getPrimaryPixelMap();
});

addRecord⁷⁺

addRecord(record: PasteDataRecord): void

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

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

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt');
let textRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let 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>";
let htmlRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_HTML, html);
pasteData.addRecord(textRecord);
pasteData.addRecord(htmlRecord);

addRecord⁹⁺

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

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

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

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
mimeType	string	是	自定义数据的MIME类型。
value	ValueType	是	自定义数据内容。

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900002	The number of record exceeds the maximum limit.

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt');
let dataXml = new ArrayBuffer(256);
pasteData.addRecord('app/xml', dataXml);

getMimeTypes⁷⁺

getMimeTypes(): Array<string>

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

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Array<string>	剪贴板内容条目的数据类型，非重复的类型列表。

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let types = pasteData.getMimeTypes();

getPrimaryMimeType⁷⁺

getPrimaryMimeType(): string

获取剪贴板内容中首个条目的数据类型。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

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

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let type = pasteData.getPrimaryMimeType();

getProperty⁷⁺

getProperty(): PasteDataProperty

获取剪贴板内容的属性描述对象。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

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

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let property = pasteData.getProperty();

setProperty⁹⁺

setProperty(property: PasteDataProperty): void

设置剪贴板内容的属性描述对象，当前仅支持设置shareOption属性。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
property	PasteDataProperty	是	属性描述对象。

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml');
let prop = pasteData.getProperty();
prop.shareOption = pasteboard.ShareOption.INAPP;
pasteData.setProperty(prop);

getRecord⁹⁺

getRecord(index: number): PasteDataRecord

获取剪贴板内容中指定下标的条目。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900001	The index is out of the record.

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let record = pasteData.getRecord(0);

getRecordCount⁷⁺

getRecordCount(): number

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

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
number	条目的个数。

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let count = pasteData.getRecordCount();

getTag⁷⁺

getTag(): string

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

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

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

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let tag = pasteData.getTag();

hasType⁹⁺

hasType(mimeType: string): boolean

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

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let hasType = pasteData.hasType(pasteboard.MIMETYPE_TEXT_PLAIN);

removeRecord⁹⁺

removeRecord(index: number): void

移除剪贴板内容中指定下标的条目。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900001	The index is out of the record.

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
pasteData.removeRecord(0);

replaceRecord⁹⁺

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

替换剪贴板内容中指定下标的条目。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900001	The index is out of the record.

示例：

let pasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let record = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, 'dataability:///com.example.myapplication1/user.txt');
pasteData.replaceRecord(0, record);

addHtmlRecord^(deprecated)

addHtmlRecord(htmlText: string): void

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

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用addRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
let 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);

addWantRecord^(deprecated)

addWantRecord(want: Want): void

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

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用addRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

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

addTextRecord^(deprecated)

addTextRecord(text: string): void

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

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用addRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
pasteData.addTextRecord('good');

addUriRecord^(deprecated)

addUriRecord(uri: string): void

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

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用addRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
pasteData.addUriRecord('dataability:///com.example.myapplication1/user.txt');

getRecordAt^(deprecated)

getRecordAt(index: number): PasteDataRecord

获取剪贴板内容中指定下标的条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用getRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
let record = pasteData.getRecordAt(0);

hasMimeType^(deprecated)

hasMimeType(mimeType: string): boolean

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

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用hasType替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
let hasType = pasteData.hasMimeType(pasteboard.MIMETYPE_TEXT_PLAIN);

removeRecordAt^(deprecated)

removeRecordAt(index: number): boolean

移除剪贴板内容中指定下标的条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用removeRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

let pasteData = pasteboard.createPlainTextData('hello');
let isRemove = pasteData.removeRecordAt(0);

replaceRecordAt^(deprecated)

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

替换剪贴板内容中指定下标的条目。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用replaceRecord替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

返回值：

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

示例：

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

SystemPasteboard

系统剪贴板对象。

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

let systemPasteboard = pasteboard.getSystemPasteboard();

on('update')⁷⁺

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

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

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

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

off('update')⁷⁺

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

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

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
type	string	是	取值为'update'，表示系统剪贴板内容变化事件。
callback	function	否	剪贴板中内容变化时触发的用户程序的回调。如果此参数未填，表明清除本应用的所有监听回调，否则表示清除指定监听回调。

示例：

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

clearData⁹⁺

clearData(callback: AsyncCallback<void>): void

清空系统剪贴板内容，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当成功清空时，err为undefined；否则为错误对象。

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.clearData((err, data) => {
    if (err) {
        console.error(`Failed to clear the pasteboard. Cause: ${err.message}`);
        return;
    }
    console.info('Succeeded in clearing the pasteboard.');
});

clearData⁹⁺

clearData(): Promise<void>

清空系统剪贴板内容，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.clearData().then((data) => {
    console.info('Succeeded in clearing the pasteboard.');
}).catch((err) => {
    console.error(`Failed to clear the pasteboard. Cause: ${err.message}`);
});

setData⁹⁺

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

将数据写入系统剪贴板，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
data	PasteData	是	PasteData对象。
callback	AsyncCallback<void>	是	回调函数。当写入成功，err为undefined，否则为错误对象。

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900003	Another copy or paste is in progress.
12900004	Replication is prohibited.

示例：

let pasteData = pasteboard.createPlainTextData('content');
let 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.');
});

setData⁹⁺

setData(data: PasteData): Promise<void>

将数据写入系统剪贴板，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
data	PasteData	是	PasteData对象。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900003	Another copy or paste is in progress.
12900004	Replication is prohibited.

示例：

let pasteData = pasteboard.createPlainTextData('content');
let 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);
});

getData⁹⁺

getData( callback: AsyncCallback<PasteData>): void

读取系统剪贴板内容，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
callback	AsyncCallback<PasteData>	是	回调函数。当读取成功，err为undefined，data为返回的系统剪贴板数据；否则返回错误对象。

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900003	Another copy or paste is in progress.

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getData((err, pasteData) => {
    if (err) {
        console.error('Failed to get PasteData. Cause: ' + err.message);
        return;
    }
    let text = pasteData.getPrimaryText();
});

getData⁹⁺

getData(): Promise<PasteData>

读取系统剪贴板内容，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<PasteData>	Promise对象，返回系统剪贴板数据。

错误码：

以下错误码的详细介绍请参见剪贴板错误码。

错误码ID	错误信息
12900003	Another copy or paste is in progress.

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.getData().then((pasteData) => {
    let text = pasteData.getPrimaryText();
}).catch((err) => {
    console.error('Failed to get PasteData. Cause: ' + err.message);
})

hasData⁹⁺

hasData(callback: AsyncCallback<boolean>): void

判断系统剪贴板中是否有内容，使用callback异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.hasData((err, data) => {
    if (err) {
        console.error(`Failed to check the PasteData. Cause: ${err.message}`);
        return;
    }
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
});

hasData⁹⁺

hasData(): Promise<boolean>

判断系统剪贴板中是否有内容，使用Promise异步回调。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<boolean>	返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。

示例：

let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.hasData().then((data) => {
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
}).catch((err) => {
    console.error(`Failed to check the PasteData. Cause: ${err.message}`);
});

clear^(deprecated)

clear(callback: AsyncCallback<void>): void

清空系统剪贴板内容，使用callback异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.clearData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
callback	AsyncCallback<void>	是	回调函数。当成功清空时，err为undefined；否则为错误对象。

示例：

systemPasteboard.clear((err, data) => {
    if (err) {
        console.error(`Failed to clear the PasteData. Cause: ${err.message}`);
        return;
    }
    console.info('Succeeded in clearing the PasteData.');
});

clear^(deprecated)

clear(): Promise<void>

清空系统剪贴板内容，使用Promise异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用pasteboard.clearData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

systemPasteboard.clear().then((data) => {
    console.info('Succeeded in clearing the PasteData.');
}).catch((err) => {
    console.error(`Failed to clear the PasteData. Cause: ${err.message}`);
});

getPasteData^(deprecated)

getPasteData( callback: AsyncCallback<PasteData>): void

读取系统剪贴板内容，使用callback异步回调。

说明：

从 API Version 6 开始支持，从 API Version 9 开始废弃，建议使用getData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
callback	AsyncCallback<PasteData>	是	回调函数。当读取成功，err为undefined，data为返回的系统剪贴板数据；否则返回错误对象。

示例：

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

getPasteData^(deprecated)

getPasteData(): Promise<PasteData>

读取系统剪贴板内容，使用Promise异步回调。

说明：

从 API Version 6 开始支持，从 API Version 9 开始废弃，建议使用getData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<PasteData>	Promise对象，返回系统剪贴板数据。

示例：

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

hasPasteData^(deprecated)

hasPasteData(callback: AsyncCallback<boolean>): void

判断系统剪贴板中是否有内容，使用callback异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用hasData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

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

示例：

systemPasteboard.hasPasteData((err, data) => {
    if (err) {
        console.error(`Failed to check the PasteData. Cause: ${err.message}`);
        return;
    }
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
});

hasPasteData^(deprecated)

hasPasteData(): Promise<boolean>

判断系统剪贴板中是否有内容，使用Promise异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用hasData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

返回值：

类型	说明
Promise<boolean>	返回true表示系统剪贴板中有内容，返回false表示系统剪贴板中没有内容。

示例：

systemPasteboard.hasPasteData().then((data) => {
    console.info(`Succeeded in checking the PasteData. Data: ${data}`);
}).catch((err) => {
    console.error(`Failed to check the PasteData. Cause: ${err.message}`);
});

setPasteData^(deprecated)

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

将数据写入系统剪贴板，使用callback异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用setData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
data	PasteData	是	PasteData对象。
callback	AsyncCallback<void>	是	回调函数。当写入成功，err为undefined，否则为错误对象。

示例：

let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData, (err, data) => {
    if (err) {
        console.error('Failed to set PasteData. Cause: ' + err.message);
        return;
    }
    console.info('Succeeded in setting PasteData.');
});

setPasteData^(deprecated)

setPasteData(data: PasteData): Promise<void>

将数据写入系统剪贴板，使用Promise异步回调。

说明：

从 API Version 7 开始支持，从 API Version 9 开始废弃，建议使用setData替代。

系统能力： SystemCapability.MiscServices.Pasteboard

参数：

参数名	类型	必填	说明
data	PasteData	是	PasteData对象。

返回值：

类型	说明
Promise<void>	无返回结果的Promise对象。

示例：

let pasteData = pasteboard.createPlainTextData('content');
let systemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setPasteData(pasteData).then((data) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
});

@ohos.pasteboard (剪贴板)

导入模块

常量

ValueType9+

pasteboard.createData9+

pasteboard.createRecord9+

pasteboard.getSystemPasteboard

ShareOption9+

pasteboard.createHtmlData(deprecated)

pasteboard.createWantData(deprecated)

pasteboard.createPlainTextData(deprecated)

pasteboard.createUriData(deprecated)

pasteboard.createHtmlTextRecord(deprecated)

pasteboard.createWantRecord(deprecated)

pasteboard.createPlainTextRecord(deprecated)

pasteboard.createUriRecord(deprecated)

PasteDataProperty7+

PasteDataRecord7+

属性

toPlainText9+

convertToText(deprecated)

convertToText(deprecated)

PasteData

getPrimaryText

getPrimaryHtml7+

getPrimaryWant7+

getPrimaryUri7+

getPrimaryPixelMap9+

addRecord7+

addRecord9+

getMimeTypes7+

getPrimaryMimeType7+

getProperty7+

setProperty9+

getRecord9+

getRecordCount7+

getTag7+

hasType9+

removeRecord9+

replaceRecord9+

addHtmlRecord(deprecated)

addWantRecord(deprecated)

addTextRecord(deprecated)

addUriRecord(deprecated)

getRecordAt(deprecated)

hasMimeType(deprecated)

removeRecordAt(deprecated)

replaceRecordAt(deprecated)

SystemPasteboard

on('update')7+

off('update')7+

clearData9+

clearData9+

setData9+

setData9+

getData9+

getData9+

hasData9+

hasData9+

clear(deprecated)

clear(deprecated)

getPasteData(deprecated)

getPasteData(deprecated)

hasPasteData(deprecated)

hasPasteData(deprecated)

setPasteData(deprecated)

setPasteData(deprecated)

ValueType⁹⁺

pasteboard.createData⁹⁺

pasteboard.createRecord⁹⁺

ShareOption⁹⁺

pasteboard.createHtmlData^(deprecated)

pasteboard.createWantData^(deprecated)

pasteboard.createPlainTextData^(deprecated)

pasteboard.createUriData^(deprecated)

pasteboard.createHtmlTextRecord^(deprecated)

pasteboard.createWantRecord^(deprecated)

pasteboard.createPlainTextRecord^(deprecated)

pasteboard.createUriRecord^(deprecated)

PasteDataProperty⁷⁺

PasteDataRecord⁷⁺

toPlainText⁹⁺

convertToText^(deprecated)

convertToText^(deprecated)

getPrimaryHtml⁷⁺

getPrimaryWant⁷⁺

getPrimaryUri⁷⁺

getPrimaryPixelMap⁹⁺

addRecord⁷⁺

addRecord⁹⁺

getMimeTypes⁷⁺

getPrimaryMimeType⁷⁺

getProperty⁷⁺

setProperty⁹⁺

getRecord⁹⁺

getRecordCount⁷⁺

getTag⁷⁺

hasType⁹⁺

removeRecord⁹⁺

replaceRecord⁹⁺

addHtmlRecord^(deprecated)

addWantRecord^(deprecated)

addTextRecord^(deprecated)

addUriRecord^(deprecated)

getRecordAt^(deprecated)

hasMimeType^(deprecated)

removeRecordAt^(deprecated)

replaceRecordAt^(deprecated)

on('update')⁷⁺

off('update')⁷⁺

clearData⁹⁺

clearData⁹⁺

setData⁹⁺

setData⁹⁺

getData⁹⁺

getData⁹⁺

hasData⁹⁺

hasData⁹⁺

clear^(deprecated)

clear^(deprecated)

getPasteData^(deprecated)

getPasteData^(deprecated)

hasPasteData^(deprecated)

hasPasteData^(deprecated)

setPasteData^(deprecated)

setPasteData^(deprecated)