@ohos.pasteboard (Pasteboard)

The pasteboard module provides the copy and paste support for the system pasteboard. You can use the APIs of this module to operate pasteboard content of the plain text, HTML, URI, Want, pixel map, and other types.

NOTE

The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import pasteboard from '@ohos.pasteboard';

Constants

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Value Description
MAX_RECORD_NUM7+ number - Maximum number of records in a PasteData object. In versions earlier than API version 10, the value is 512, indicating that no more records can be added once the number of records reaches 512.
Since API version 10, no limit is placed on the number of records in a PasteData object.
MIMETYPE_TEXT_HTML7+ string 'text/html' MIME type of the HTML content.
MIMETYPE_TEXT_WANT7+ string 'text/want' MIME type of the Want content.
MIMETYPE_TEXT_PLAIN7+ string 'text/plain' MIME type of the plain text content.
MIMETYPE_TEXT_URI7+ string 'text/uri' MIME type of the URI content.
MIMETYPE_PIXELMAP9+ string 'pixelMap' MIME type of the pixel map.

ValueType9+

Enumerates the value types.

System capability: SystemCapability.MiscServices.Pasteboard

Type Description
string The value is a string.
image.PixelMap The value is of the image.PixelMap type.
Want The value is of the Want type.
ArrayBuffer The value is of the ArrayBuffer type.

pasteboard.createData9+

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

Creates a PasteData object of a custom type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
mimeType string Yes MIME type of custom data. The value can a predefined MIME type listed in Constants, including HTML, WANT, plain text, URI, and pixel map, or a custom MIME type.
value ValueType Yes Content of custom data.

Return value

Type Description
PasteData PasteData object.

Example 1

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

Example 2

let dataText = 'hello';
let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, dataText);

pasteboard.createRecord9+

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

Creates a PasteDataRecord object of the custom type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
mimeType string Yes MIME type of custom data. The value can a predefined MIME type listed in Constants, including HTML, WANT, plain text, URI, and pixel map, or a custom MIME type.
value ValueType Yes Content of custom data.

Return value

Type Description
PasteDataRecord New PasteDataRecord object of the custom type.

Example 1

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

Example 2

let dataUri = 'dataability:///com.example.myapplication1/user.txt';
let record: pasteboard.PasteDataRecord = pasteboard.createRecord(pasteboard.MIMETYPE_TEXT_URI, dataUri);

pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

Obtains this SystemPasteboard object.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
SystemPasteboard SystemPasteboard object.

Example

let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();

ShareOption9+

Enumerates the paste options of data.

System capability: SystemCapability.MiscServices.Pasteboard

Name Value Description
INAPP 0 Only intra-application pasting is allowed.
LOCALDEVICE 1 Paste is allowed in any application on the local device.
CROSSDEVICE 2 Paste is allowed in any application across devices.

pasteboard.createHtmlData(deprecated)

createHtmlData(htmlText: string): PasteData

Creates a PasteData object of the HTML type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML content.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createWantData(deprecated)

createWantData(want: Want): PasteData

Creates a PasteData object of the Want type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want content.

Return value

Type Description
PasteData PasteData object.

Example

import Want from '@ohos.app.ability.Want';

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

pasteboard.createPlainTextData(deprecated)

createPlainTextData(text: string): PasteData

Creates a PasteData object of the plain text type.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use pasteboard.createData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createUriData(deprecated)

createUriData(uri: string): PasteData

Creates a PasteData object of the URI type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI content.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createHtmlTextRecord(deprecated)

createHtmlTextRecord(htmlText: string): PasteDataRecord

Creates a PasteDataRecord object of the HTML text type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML content.

Return value

Type Description
PasteDataRecord PasteDataRecord object of the HTML text type.

Example

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

pasteboard.createWantRecord(deprecated)

createWantRecord(want: Want): PasteDataRecord

Creates a PasteDataRecord object of the Want type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want content.

Return value

Type Description
PasteDataRecord New PasteDataRecord object of the Want type.

Example

import Want from '@ohos.app.ability.Want';

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

pasteboard.createPlainTextRecord(deprecated)

createPlainTextRecord(text: string): PasteDataRecord

Creates a PasteDataRecord object of the plain text type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Return value

Type Description
PasteDataRecord New PasteDataRecord object of the plain text type.

Example

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

pasteboard.createUriRecord(deprecated)

createUriRecord(uri: string): PasteDataRecord

Creates a PasteDataRecord object of the URI type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.createRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI content.

Return value

Type Description
PasteDataRecord New PasteDataRecord object of the URI type.

Example

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

PasteDataProperty7+

Defines the properties of all data records on the pasteboard, including the timestamp, data type, and additional data. The defined properties can be applied to the pasteboard only with the setProperty API.

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Readable Writable Description
additions7+ {[key:string]:object} Yes Yes Additional data. It does not allow for dynamic adding of attributes. Attributes can be added only by re-assigning values. For details, see the example of setProperty.
mimeTypes7+ Array<string> Yes No Non-repeating data types of the data records on the pasteboard.
tag7+ string Yes Yes Custom tag.
timestamp7+ number Yes No Timestamp when data is written to the pasteboard (unit: ms).
localOnly7+ boolean Yes Yes Whether the pasteboard content is for local access only. The default value is false. The value will be overwritten by the value of the shareOption attribute. You are advised to use the shareOption attribute instead. ShareOption.INAPP and ShareOption.LOCALDEVICE set localOnly to true, and ShareOption.CROSSDEVICE sets localOnly to false.
- true: The pasteboard content is set for local access only.
- false: The pasteboard content can be shared between devices.
shareOption9+ ShareOption Yes Yes Where the pasteboard content can be pasted. If this attribute is set incorrectly or not set, the default value CROSSDEVICE is used.

PasteDataRecord7+

Provides PasteDataRecord APIs. A PasteDataRecord is an abstract definition of the content on the pasteboard. The pasteboard content consists of one or more plain text, HTML, URI, or Want records.

Attributes

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Readable Writable Description
htmlText7+ string Yes No HTML content.
want7+ Want Yes No Want content.
mimeType7+ string Yes No Data type.
plainText7+ string Yes No Plain text.
uri7+ string Yes No URI content.
pixelMap9+ image.PixelMap Yes No Pixel map.
data9+ {[mimeType: string]: ArrayBuffer} Yes No Content of custom data.

toPlainText9+

toPlainText(): string

Forcibly converts the content in a PasteData object to text.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string Plain text.

Example

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

convertToText(deprecated)

convertToText(callback: AsyncCallback<string>): void

Forcibly converts the content in a PasteData object to text. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use toPlainText.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<string> Yes Callback used to return the result. If the operation is successful, err is undefined and data is the text obtained from the conversion. Otherwise, err is error information.

Example

import { BusinessError } from '@ohos.base';

let record: pasteboard.PasteDataRecord = pasteboard.createUriRecord('dataability:///com.example.myapplication1/user.txt');
record.convertToText((err: BusinessError, data: string) => {
    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>

Forcibly converts the content in a PasteData object to text. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use toPlainText.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<string> Promise used to return the text obtained from the conversion.

Example

import { BusinessError } from '@ohos.base';

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

PasteData

Implements a PasteData object. Paste data contains one or more data records (PasteDataRecord) and property description objects (PasteDataProperty).

Before calling any API in PasteData, you must use createData() or getData() to create a PasteData object.

System capability: SystemCapability.MiscServices.Pasteboard

getPrimaryText

getPrimaryText(): string

Obtains the plain text of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string Plain text.

Example

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

getPrimaryHtml7+

getPrimaryHtml(): string

Obtains the HTML content of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string HTML content.

Example

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

getPrimaryWant7+

getPrimaryWant(): Want

Obtains the Want object of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Want Want object.

Example

import Want from '@ohos.app.ability.Want';

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

getPrimaryUri7+

getPrimaryUri(): string

Obtains the URI of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string URI content.

Example

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

getPrimaryPixelMap9+

getPrimaryPixelMap(): image.PixelMap

Obtains the pixel map of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
image.PixelMap Pixel map.

Example

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

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

addRecord7+

addRecord(record: PasteDataRecord): void

Adds a data record to this pasteboard, and adds its type to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
record PasteDataRecord Yes Record to add.

Example

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

addRecord9+

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

Adds a custom-type record to this pasteboard, and adds the custom type to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
mimeType string Yes MIME type of custom data.
value ValueType Yes Content of custom data.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900002 The number of record exceeds the maximum limit.

Example

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

getMimeTypes7+

getMimeTypes(): Array<string>

Obtains a list of mimeTypes objects in PasteDataProperty from this pasteboard. If the pasteboard is empty, the returned list is also empty.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Array<string> Non-repeating data types of the data records on the pasteboard.

Example

let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
let types: string[] = pasteData.getMimeTypes();

getPrimaryMimeType7+

getPrimaryMimeType(): string

Obtains the data type of the primary record in this pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string Data type of the primary record.

Example

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

getProperty7+

getProperty(): PasteDataProperty

Obtains the property of the pasteboard data.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
PasteDataProperty Property of the pasteboard data.

Example

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

setProperty9+

setProperty(property: PasteDataProperty): void

Sets a PasteDataProperty object.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
property PasteDataProperty Yes Property of the pasteboard data.

Example

type AdditionType = Record<string, Record<string, Object>>;

let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_HTML, 'application/xml');
let prop: pasteboard.PasteDataProperty = pasteData.getProperty();
prop.shareOption = pasteboard.ShareOption.INAPP;
// Note that attributes cannot be added to additions. Attributes can be added only by re-assigning values.
prop.additions = { 'TestOne': { 'Test': 123 }, 'TestTwo': { 'Test': 'additions' } } as AdditionType;
prop.tag = 'TestTag';
pasteData.setProperty(prop);

The localOnly and shareOption attributes of PasteDataProperty are mutually exclusive. The shareOption attribute is prioritized, and its value affects the value of localOnly.

(async () => {
    let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'hello');
    let prop: pasteboard.PasteDataProperty = pasteData.getProperty();
    prop.shareOption = pasteboard.ShareOption.INAPP;
    prop.localOnly = false;
    pasteData.setProperty(prop);
    let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();

    await systemPasteboard.setData(pasteData).then(async () => {
        console.info('Succeeded in setting PasteData.');
        await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => {
            let prop: pasteboard.PasteDataProperty = pasteData.getProperty();
            prop.localOnly; // true
        });
    });

    prop.shareOption = pasteboard.ShareOption.LOCALDEVICE;
    prop.localOnly = false;
    pasteData.setProperty(prop);

    await systemPasteboard.setData(pasteData).then(async () => {
        console.info('Succeeded in setting PasteData.');
        await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => {
            let prop: pasteboard.PasteDataProperty = pasteData.getProperty();
            prop.localOnly; // true
        });
    });

    prop.shareOption = pasteboard.ShareOption.CROSSDEVICE;
    prop.localOnly = true;
    pasteData.setProperty(prop);

    await systemPasteboard.setData(pasteData).then(async () => {
        console.info('Succeeded in setting PasteData.');
        await systemPasteboard.getData().then((pasteData: pasteboard.PasteData) => {
            let prop: pasteboard.PasteDataProperty = pasteData.getProperty();
            prop.localOnly; // false
        });
    });
})()

getRecord9+

getRecord(index: number): PasteDataRecord

Obtains the specified record in the pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Index of the target record.

Return value

Type Description
PasteDataRecord Record with the specified index.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900001 The index is out of the record.

Example

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

getRecordCount7+

getRecordCount(): number

Obtains the number of records in the pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
number Number of records.

Example

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

getTag7+

getTag(): string

Obtains the custom tag from the pasteboard. If no custom tag is set, null is returned.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string Custom tag. If no custom tag is set, null is returned.

Example

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

hasType9+

hasType(mimeType: string): boolean

Checks whether the pasteboard contains data of the specified type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
mimeType string Yes Type of the data to query.

Return value

Type Description
boolean Returns true if the specified data type exists; returns false otherwise.

Example

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

removeRecord9+

removeRecord(index: number): void

Removes the record with the specified index from the pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Specified index.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900001 The index is out of the record.

Example

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

replaceRecord9+

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

Replaces the record with the specified index in the pasteboard with a new record.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Specified index.
record PasteDataRecord Yes New record.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900001 The index is out of the record.

Example

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

addHtmlRecord(deprecated)

addHtmlRecord(htmlText: string): void

Adds an HTML record to this pasteboard, and adds MIMETYPE_TEXT_HTML to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use addRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML content.

Example

let pasteData: pasteboard.PasteData = pasteboard.createPlainTextData('hello');
let html: string = "<!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

Adds a Want record to this pasteboard, and adds MIMETYPE_TEXT_WANT to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use addRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want object.

Example

import Want from '@ohos.app.ability.Want';

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

addTextRecord(deprecated)

addTextRecord(text: string): void

Adds a plain text record to this pasteboard, and adds MIME_TEXT_PLAIN to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use addRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Example

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

addUriRecord(deprecated)

addUriRecord(uri: string): void

Adds a URI record to this pasteboard, and adds MIMETYPE_TEXT_URI to mimeTypes in PasteDataProperty. The parameters cannot be empty. Otherwise, the operation fails.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use addRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI content.

Example

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

getRecordAt(deprecated)

getRecordAt(index: number): PasteDataRecord

Obtains the specified record in the pasteboard.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use getRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Index of the target record.

Return value

Type Description
PasteDataRecord Record with the specified index.

Example

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

hasMimeType(deprecated)

hasMimeType(mimeType: string): boolean

Checks whether the pasteboard contains data of the specified type.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use hasType.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
mimeType string Yes Type of the data to query.

Return value

Type Description
boolean Returns true if the specified data type exists; returns false otherwise.

Example

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

removeRecordAt(deprecated)

removeRecordAt(index: number): boolean

Removes the record with the specified index from the pasteboard.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use removeRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Specified index.

Return value

Type Description
boolean Returns true if the operation is successful; returns false otherwise.

Example

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

replaceRecordAt(deprecated)

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

Replaces the record with the specified index in the pasteboard with a new record.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use replaceRecord.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Specified index.
record PasteDataRecord Yes New record.

Return value

Type Description
boolean Returns true if the operation is successful; returns false otherwise.

Example

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

SystemPasteboard

Provides SystemPasteboard APIs.

Before calling any SystemPasteboard API, you must obtain a SystemPasteboard object using getSystemPasteboard.

let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();

on('update')7+

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

Subscribes to the content change event of the system pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
type string Yes Event type. The value 'update' indicates changes in the pasteboard content.
callback function Yes Callback invoked when the pasteboard content changes.

Example

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

off('update')7+

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

Unsubscribes from the system pasteboard content change event.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
type string Yes Event type. The value 'update' indicates changes in the pasteboard content.
callback function No Callback invoked when the pasteboard content changes. If this parameter is not specified, listening will be disabled for all callbacks registered by the current application.

Example

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

clearData9+

clearData(callback: AsyncCallback<void>): void

Clears the system pasteboard. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

let systemPasteboard: pasteboard.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.');
});

clearData9+

clearData(): Promise<void>

Clears the system pasteboard. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@ohos.base';

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

setData9+

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

Writes a PasteData object to the pasteboard. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
data PasteData Yes PasteData object.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900003 Another copy or paste is in progress.
12900004 Replication is prohibited.

Example

let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content');
let systemPasteboard: pasteboard.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.');
});

setData9+

setData(data: PasteData): Promise<void>

Writes a PasteData object to the pasteboard. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
data PasteData Yes PasteData object.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900003 Another copy or paste is in progress.
12900004 Replication is prohibited.

Example

import { BusinessError } from '@ohos.base';

let pasteData: pasteboard.PasteData = pasteboard.createData(pasteboard.MIMETYPE_TEXT_PLAIN, 'content');
let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.setData(pasteData).then((data: void) => {
    console.info('Succeeded in setting PasteData.');
}).catch((err: BusinessError) => {
    console.error('Failed to set PasteData. Cause: ' + err.message);
});

getData9+

getData( callback: AsyncCallback<PasteData>): void

Obtains a PasteData object from the pasteboard. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<PasteData> Yes Callback used to return the result. If the operation is successful, err is undefined and data is the system pasteboard data. Otherwise, err is an error object.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900003 Another copy or paste is in progress.

Example

import { BusinessError } from '@ohos.base';

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

getData9+

getData(): Promise<PasteData>

Obtains a PasteData object from the pasteboard. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<PasteData> Promise used to return the system pasteboard data.

Error codes

For details about the error codes, see Pasteboard Error Codes.

Error Code ID Error Message
12900003 Another copy or paste is in progress.

Example

import { BusinessError } from '@ohos.base';

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

hasData9+

hasData(callback: AsyncCallback<boolean>): void

Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result. Returns true if the system pasteboard contains data; returns false otherwise.

Example

import { BusinessError } from '@ohos.base';

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

hasData9+

hasData(): Promise<boolean>

Checks whether the system pasteboard contains data. This API uses a promise to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<boolean> Promise used to return the result. Returns true if the system pasteboard contains data; returns false otherwise.

Example

import { BusinessError } from '@ohos.base';

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

clear(deprecated)

clear(callback: AsyncCallback<void>): void

Clears the system pasteboard. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.clearData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
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>

Clears the system pasteboard. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use pasteboard.clearData.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@ohos.base';

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

getPasteData(deprecated)

getPasteData( callback: AsyncCallback<PasteData>): void

Obtains a PasteData object from the pasteboard. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use getData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<PasteData> Yes Callback used to return the result. If the operation is successful, err is undefined and data is the system pasteboard data. Otherwise, err is an error object.

Example

import { BusinessError } from '@ohos.base';

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

getPasteData(deprecated)

getPasteData(): Promise<PasteData>

Obtains a PasteData object from the pasteboard. This API uses a promise to return the result.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use getData.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<PasteData> Promise used to return the system pasteboard data.

Example

import { BusinessError } from '@ohos.base';

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

hasPasteData(deprecated)

hasPasteData(callback: AsyncCallback<boolean>): void

Checks whether the system pasteboard contains data. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use hasData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Callback used to return the result. Returns true if the system pasteboard contains data; returns false otherwise.

Example

import { BusinessError } from '@ohos.base';

let systemPasteboard: pasteboard.SystemPasteboard = pasteboard.getSystemPasteboard();
systemPasteboard.hasPasteData((err: BusinessError, data: boolean) => {
    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>

Checks whether the system pasteboard contains data. This API uses a promise to return the result.

NOTE

This API is supported since API version 7 and deprecated since API version 9. You are advised to use hasData.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<boolean> Promise used to return the result. Returns true if the system pasteboard contains data; returns false otherwise.

Example

import { BusinessError } from '@ohos.base';

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

setPasteData(deprecated)

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

Writes a PasteData object to the pasteboard. This API uses an asynchronous callback to return the result.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use setData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
data PasteData Yes PasteData object.
callback AsyncCallback<void> Yes Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Example

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

Writes a PasteData object to the pasteboard. This API uses a promise to return the result.

NOTE

This API is supported since API version 6 and deprecated since API version 9. You are advised to use setData.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
data PasteData Yes PasteData object.

Return value

Type Description
Promise<void> Promise that returns no value.

Example

import { BusinessError } from '@ohos.base';

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