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';

Attributes

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Readable Writable Description
MAX_RECORD_NUM7+ number Yes No Maximum number of records in a PasteData object.
MIMETYPE_TEXT_HTML7+ string Yes No MIME type of the HTML content.
MIMETYPE_TEXT_WANT7+ string Yes No MIME type of the Want content.
MIMETYPE_TEXT_PLAIN7+ string Yes No MIME type of the plain text content.
MIMETYPE_TEXT_URI7+ string Yes No MIME type of the URI content.

pasteboard.createPlainTextData

createPlainTextData(text: string): PasteData

Creates a PasteData object of the plain text type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createHtmlData7+

createHtmlData(htmlText: string): PasteData

Creates a PasteData object of the HTML type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML content.

Return value

Type Description
PasteData PasteData object.

Example

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

Creates a PasteData object of the Want type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want content.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createUriData7+

createUriData(uri: string): PasteData

Creates a PasteData object of the URI type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI content.

Return value

Type Description
PasteData PasteData object.

Example

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

pasteboard.createPlainTextRecord7+

createPlainTextRecord(text: string): PasteDataRecord

Creates a PasteDataRecord object of the plain text type.

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

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

pasteboard.createHtmlTextRecord7+

createHtmlTextRecord(htmlText: string): PasteDataRecord

Creates a PasteDataRecord object of the HTML text type.

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

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

Creates a PasteDataRecord object of the Want type.

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

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

pasteboard.createUriRecord7+

createUriRecord(uri: string): PasteDataRecord

Creates a PasteDataRecord object of the URI type.

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

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

pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

Obtains this SystemPasteboard object.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
SystemPasteboard SystemPasteboard object.

Example

var systemPasteboard = pasteboard.getSystemPasteboard();

PasteDataProperty7+

Defines the properties of all data records on the pasteboard, including the timestamp, data type, and additional data.

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Readable Writable Description
additions {[key:string]:object} Yes Yes Additional data.
mimeTypes Array<string> Yes No Non-repeating data types of the data records on the pasteboard.
tag string Yes Yes Custom tag.
timestamp number Yes No Timestamp when data is written to the pasteboard (unit: ms).
localOnly boolean Yes Yes Whether the pasteboard content is set for local access only. The default value is true.
- true: The pasteboard content is set for local access only.
- false: The pasteboard content can be shared between devices.

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.

convertToText7+

convertToText(): Promise<string>

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

System capability: SystemCapability.MiscServices.Pasteboard

Return value

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

Example

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

convertToText7+

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.

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

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

PasteData

Provides PasteData APIs.

Before calling any PasteData API, you must obtain 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

var pasteData = pasteboard.createPlainTextData("hello");
var plainText = 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

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

Obtains the Want object of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Want Want object.

Example

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

Obtains the URI of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string URI content.

Example

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

addTextRecord7+

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.

The pasteboard supports a maximum number of 128 data records.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Example

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

addHtmlRecord7+

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.

The pasteboard supports a maximum number of 128 data records.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML content.

Example

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

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.

The pasteboard supports a maximum number of 128 data records.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want object.

Example

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

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.

The pasteboard supports a maximum number of 128 data records.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI content.

Example

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

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.

The pasteboard supports a maximum number of 128 data records.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
record PasteDataRecord Yes Record to add.

Example

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" + "<body>\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<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

var pasteData = pasteboard.createPlainTextData("hello");
var types = 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

var pasteData = pasteboard.createPlainTextData("hello");
var type = 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

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

getRecordAt7+

getRecordAt(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.

Example

var pasteData = pasteboard.createPlainTextData("hello");
var record = pasteData.getRecordAt(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

var pasteData = pasteboard.createPlainTextData("hello");
var count = 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

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

hasMimeType7+

hasMimeType(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

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

removeRecordAt7+

removeRecordAt(index: number): boolean

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.

Return value

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

Example

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

replaceRecordAt7+

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

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.

Return value

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

Example

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

SystemPasteboard

Provides SystemPasteboard APIs.

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

var systemPasteboard = pasteboard.getSystemPasteboard();

setPasteData

setPasteData(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.

Example

var pasteData = pasteboard.createPlainTextData("content");
var 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

setPasteData(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 Description
data PasteData PasteData object.

Return value

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

Example

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

getPasteData

getPasteData( 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.

Example

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

getPasteData

getPasteData(): 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.

Example

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

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

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

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.

Example

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

hasPasteData7+

hasPasteData(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

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

hasPasteData7+

hasPasteData(): 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

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

clear7+

clear(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

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

clear7+

clear(): 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

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