Pasteboard

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 allowed in a PasteData object.
MIMETYPE_TEXT_HTML7+ string Yes No MIME type of the HTML text.
MIMETYPE_TEXT_WANT7+ string Yes No MIME type of the Want text.
MIMETYPE_TEXT_PLAIN7+ string Yes No MIME type of the plain text.
MIMETYPE_TEXT_URI7+ string Yes No MIME type of the URI text.

pasteboard.createPlainTextData

createPlainTextData(text:string): PasteData

Creates a PasteData object for plain text.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
text string Yes Plain text.

Return value

Type Description
PasteData PasteData object with the specified content.

Example

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

pasteboard.createHtmlData7+

createHtmlData(htmlText:string): PasteData

Creates a PasteData object for HTML text.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
htmlText string Yes HTML text.

Return value

Type Description
PasteData PasteData object with the specified 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);

pasteboard.createWantData7+

createWantData(want:Want): PasteData

Creates a PasteData object for Want text.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want text.

Return value

Type Description
PasteData PasteData object with the specified content.

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 for URI text.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI text.

Return value

Type Description
PasteData PasteData object with the specified content.

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 plain text record.

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 text.

Return value

Type Description
PasteDataRecord New HTML record.

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 text type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
want Want Yes Want text.

Return value

Type Description
PasteDataRecord New Want record.

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 text type.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
uri string Yes URI text.

Return value

Type Description
PasteDataRecord New URI record.

Example

var record = 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.

System capability: SystemCapability.MiscServices.Pasteboard

Name Type Readable Writable Description
additions {[key: string]: object} Yes Yes Additional property data.
mimeTypes Array<string> Yes No Non-repeating data types of the data records on the pasteboard.
tag string Yes Yes User-defined tag.
timestamp number Yes No Timestamp at which the data is written to the pasteboard, in milliseconds.
localOnly boolean Yes Yes Whether local access only is set for the pasteboard.
- The default value is true.
- true: The PasteData is set for local access only.
- false: The PasteData can be shared between devices.

PasteDataRecord7+

A data record 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 text.
want7+ Want Yes No Want text.
mimeType7+ string Yes No Data type.
plainText7+ string Yes No Plain text.
uri7+ string Yes No URI text.

convertToText7+

convertToText(): Promise<string>

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

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<void> Promise used to return the result. If the operation is successful, the plain text content after conversion is returned. Otherwise, error information is returned.

Example

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

convertToText7+

convertToText(callback: AsyncCallback<string>): void

Forcibly converts the content in this PasteData object to the plain 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 this callback is successful, the plain text content after conversion is returned. Otherwise, error information is returned.

Example

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

PasteData

Before calling any PasteData method, 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 text of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string HTML text.

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 text of the primary record.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string URI text.

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 text 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 text.

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 text 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 text 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 text.

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 mimeTypes 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> List of non-duplicate MIME types.

Example

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

getPrimaryMimeType7+

getPrimaryMimeType(): string

Obtains the data type of the primary record.

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 description object.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
PasteDataProperty Property description object.

Example

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

getRecordAt7+

getRecordAt(index: number): PasteDataRecord

Obtains the record with the specified index.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
index number Yes Index of the specified 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 data records in this 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 user-defined tag content. If the tag content is not set, null is returned.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
string User-defined tag content if obtained and null if no tag is set.

Example

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

hasMimeType7+

hasMimeType(mimeType: string): boolean

Checks whether the content of this pasteboard contains the specified data 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 data record with a specified index from this 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 data record with a specified index in this pasteboard.

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

pasteboard.getSystemPasteboard

getSystemPasteboard(): SystemPasteboard

Obtains the system pasteboard.

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
SystemPasteboard System pasteboard.

Example

var systemPasteboard = pasteboard.getSystemPasteboard();

SystemPasteboard

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

var systemPasteboard = pasteboard.getSystemPasteboard();

setPasteData

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

Writes data to a 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 data write result.

Example

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

setPasteData

setPasteData(data:PasteData): Promise<void>

Writes data to a 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 used to return the data write result.

Example

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

getPasteData

getPasteData( callback:AsyncCallback<PasteData>): void

Reads the system pasteboard content. 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 system pasteboard data.

Example

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

getPasteData

getPasteData(): Promise<PasteData>

Reads the system pasteboard content. 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((error) => {
    console.error('Failed to getPasteData. Cause: ' + error.message);
})

on('update')7+

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

Subscribes to the content change event of the system pasteboard. If the pasteboard content changes, the callback is triggered.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
type string Yes Data type. The value update indicates the pasteboard content has changed.
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 Data type. The value update indicates the pasteboard content has changed.
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 content. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.MiscServices.Pasteboard

Parameters

Name Type Mandatory Description
callback AsyncCallback<boolean> Yes Returns true if the pasteboard contains content; returns false otherwise.

Example

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

hasPasteData7+

hasPasteData(): Promise<boolean>

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

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<boolean> Returns true if the pasteboard contains content; returns false otherwise.

Example

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

clear7+

clear(callback: AsyncCallback<void>): void

Clears the system pasteboard content. 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.

Example

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

clear7+

clear(): Promise<void>

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

System capability: SystemCapability.MiscServices.Pasteboard

Return value

Type Description
Promise<void> Promise used to return the result.

Example

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