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