@ohos.print (Print)

The print module provides APIs for basic print operations.

NOTE

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

Modules to Import

import print from '@ohos.print';

PrintTask

Implements event listeners for print tasks.

on

on(type: 'block', callback: Callback<void>): void

Registers a listener for the print task blocking event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'block', indicating blocking of the print task.
callback Callback<void> Yes Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.on('block', () => {
        console.log('print state is block');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

on

on(type: 'succeed', callback: Callback<void>): void

Registers a listener for the print task success event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'succeed', indicating success of the print task.
callback Callback<void> Yes Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.on('succeed', () => {
        console.log('print state is succeed');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

on

on(type: 'fail', callback: Callback<void>): void

Registers a listener for the print task failure event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'fail', indicating failure of the print task.
callback Callback<void> Yes Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.on('fail', () => {
        console.log('print state is fail');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

on

on(type: 'cancel', callback: Callback<void>): void

Registers a listener for the print task cancel event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'cancel', indicating canceling of the print task.
callback Callback<void> Yes Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.on('cancel', () => {
        console.log('print state is cancel');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

off

off(type: 'block', callback?: Callback<void>): void

Unregisters the listener for the print task blocking event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'block', indicating blocking of the print task.
callback Callback<void> No Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.off('block', () => {
        console.log('unregister state block');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

off

off(type: 'succeed', callback?: Callback<void>): void

Unregisters the listener for the print task success event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'succeed', indicating success of the print task.
callback Callback<void> No Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.off('succeed', () => {
        console.log('unregister state succeed');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

off

off(type: 'fail', callback?: Callback<void>): void

Unregisters the listener for the print task failure event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'fail', indicating failure of the print task.
callback Callback<void> No Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.off('fail', () => {
        console.log('unregister state fail');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

off

off(type: 'cancel', callback?: Callback<void>): void

Unregisters the listener for the print task cancel event. This API uses a callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
type string Yes Listening type.
The value is fixed at 'cancel', indicating canceling of the print task.
callback Callback<void> No Callback used to return the result.

Example

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

let file = ['file://data/print/a.png', 'file://data/print/b.png'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.off('cancel', () => {
        console.log('unregister state cancel');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

PrintDocumentAdapter11+

Provides information about the document to print. This API must be implemented by a third-party application.

onStartLayoutWrite

onStartLayoutWrite(jobId: string, oldAttrs: PrintAttributes, newAttrs: PrintAttributes, fd: number, writeResultCallback: (jobId: string, writeResult: PrintFileCreationState) => void): void

Updates the file to be printed. This API uses writeResultCallback as the callback.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
jobId string Yes ID of the print job.
oldAttrs PrintAttributes Yes Old print attributes.
newAttrs PrintAttributes Yes New print attributes.
fd number Yes File descriptor.
writeResultCallback (jobId: string, writeResult: PrintFileCreationState) Yes Callback used to return the result.

Example

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

class MyPrintDocumentAdapter implements print.PrintDocumentAdapter {
    onStartLayoutWrite(jobId: string, oldAttrs: print.PrintAttributes, newAttrs: print.PrintAttributes, fd: number,
        writeResultCallback: (jobId: string, writeResult: print.PrintFileCreationState) => void) {
        writeResultCallback(jobId, print.PrintFileCreationState.PRINT_FILE_CREATED);
    };
    onJobStateChanged(jobId: string, state: print.PrintDocumentAdapterState) {
        if (state == print.PrintDocumentAdapterState.PREVIEW_DESTROY) {
            console.log('PREVIEW_DESTROY');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_SUCCEED) {
            console.log('PRINT_TASK_SUCCEED');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_FAIL) {
            console.log('PRINT_TASK_FAIL');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_CANCEL) {
            console.log('PRINT_TASK_CANCEL');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_BLOCK) {
            console.log('PRINT_TASK_BLOCK');
        }
    }
}

onJobStateChanged

onJobStateChanged(jobId: string, state: PrintDocumentAdapterState): void

Registers a listener for print job state changes.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
jobId string Yes ID of the print job.
state PrintDocumentAdapterState Yes New state of the print job.

Example

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

class MyPrintDocumentAdapter implements print.PrintDocumentAdapter {
    onStartLayoutWrite(jobId: string, oldAttrs: print.PrintAttributes, newAttrs: print.PrintAttributes, fd: number,
        writeResultCallback: (jobId: string, writeResult: print.PrintFileCreationState) => void) {
        writeResultCallback(jobId, print.PrintFileCreationState.PRINT_FILE_CREATED);
    };
    onJobStateChanged(jobId: string, state: print.PrintDocumentAdapterState) {
        if (state == print.PrintDocumentAdapterState.PREVIEW_DESTROY) {
            console.log('PREVIEW_DESTROY');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_SUCCEED) {
            console.log('PRINT_TASK_SUCCEED');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_FAIL) {
            console.log('PRINT_TASK_FAIL');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_CANCEL) {
            console.log('PRINT_TASK_CANCEL');
        } else if (state == print.PrintDocumentAdapterState.PRINT_TASK_BLOCK) {
            console.log('PRINT_TASK_BLOCK');
        }
    }
}

print

print(files: Array<string>, callback: AsyncCallback<PrintTask>): void

Prints files. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
file Array<string> Yes List of files to print. Images in .jpg, .png, .gif, .bmp, or .webp format are supported.
callback AsyncCallback<PrintTask> Yes Callback used to return the result.

Example

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

// Pass in the URIs of the files.
let file = ['file://data/print/a.png', 'file://data/print/b.png'];
// Alternatively, pass in the file IDs.
//let file = ['fd://1', 'fd://2'];
print.print(file, (err: BusinessError, printTask: print.PrintTask) => {
    if (err) {
        console.log('print err ' + JSON.stringify(err));
    } else {
        printTask.on('succeed', () => {
            console.log('print state is succeed');
        })
        // ...
    }
})

print(files: Array<string>): Promise<PrintTask>

Prints files. This API uses a promise to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
file Array<string> Yes List of files to print. Images in .jpg, .png, .gif, .bmp, or .webp format are supported.

Return value

Type Description
Promise<PrintTask> Print result.

Example

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

// Pass in the URIs of the files.
let file = ['file://data/print/a.png', 'file://data/print/b.png'];
// Alternatively, pass in the file IDs.
//let file = ['fd://1', 'fd://2'];
print.print(file).then((printTask: print.PrintTask) => {
    printTask.on('succeed', () => {
        console.log('print state is succeed');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

print11+

print(files: Array<string>, context: Context, callback: AsyncCallback<PrintTask>): void

Prints files. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
file Array<string> Yes List of files to print. Images in .jpg, .png, .gif, .bmp, or .webp format are supported.
context Context Yes UIAbility context used to start printing.
callback AsyncCallback<PrintTask> Yes Callback used to return the result.

Example

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

// Pass in the URIs of the files.
let file = ['file://data/print/a.png', 'file://data/print/b.png'];
// Alternatively, pass in the file IDs.
//let file = ['fd://1', 'fd://2'];
let context = getContext(this);
print.print(file, context, (err: BusinessError, printTask: print.PrintTask) => {
    if (err) {
        console.log('print err ' + JSON.stringify(err));
    } else {
        printTask.on('succeed', () => {
            console.log('print state is succeed');
        })
        // ...
    }
})

print11+

print(files: Array<string>, context: Context): Promise<PrintTask>

Prints files. This API uses a promise to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
file Array<string> Yes List of files to print. Images in .jpg, .png, .gif, .bmp, or .webp format are supported.
context Context Yes UIAbility context used to start printing.

Return value

Type Description
Promise<PrintTask> Print result.

Example

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

// Pass in the URIs of the files.
let file = ['file://data/print/a.png', 'file://data/print/b.png'];
// Alternatively, pass in the file IDs.
//let file = ['fd://1', 'fd://2'];
let context = getContext(this);
print.print(file, context).then((printTask: print.PrintTask) => {
    printTask.on('succeed', () => {
        console.log('print state is succeed');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

print11+

print(jobName: string, printAdapter: PrintDocumentAdapter, printAttributes: PrintAttributes, context: Context): Promise<PrintTask>

Prints a file. This API uses a promise to return the result.

Required permissions: ohos.permission.PRINT

System capability: SystemCapability.Print.PrintFramework

Parameters

Name Type Mandatory Description
jobName string Yes Name of the file to print.
printAdapter PrintDocumentAdapter Yes Feature implemented by a third-party application.
printAttributes PrintAttributes Yes Print attributes.
context Context Yes UIAbility context used to start printing.

Return value

Type Description
Promise<PrintTask> Print result.

Example

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

let jobName : string = "jobName";
let printAdapter : print.PrintDocumentAdapter | null = null;
let printAttributes : print.PrintAttributes = {
    copyNumber: 1,
    pageRange: {
        startPage: 0,
        endPage: 5,
        pages: []
    },
    pageSize: print.PrintPageType.PAGE_ISO_A3,
    directionMode: print.PrintDirectionMode.DIRECTION_MODE_AUTO,
    colorMode: print.PrintColorMode.COLOR_MODE_MONOCHROME,
    duplexMode: print.PrintDuplexMode.DUPLEX_MODE_NONE
}
let context = getContext();

print.print(jobName, printAdapter, printAttributes, context).then((printTask: print.PrintTask) => {
    printTask.on('succeed', () => {
        console.log('print state is succeed');
    })
    // ...
}).catch((error: BusinessError) => {
    console.log('print err ' + JSON.stringify(error));
})

PrintAttributes11+

Defines the print attributes.

System capability: SystemCapability.Print.PrintFramework

Attributes

Name Type Mandatory Description
copyNumber number No Copy of the file list.
pageRange PrintPageRange No Range of pages to print.
pageSize PrintPageSize | PrintPageType No Page size of the files to print.
directionMode PrintDirectionMode No Print direction mode.
colorMode PrintColorMode No Color mode of the files to print.
duplexMode PrintDuplexMode No Duplex mode of the files to print.

PrintPageRange11+

Defines the print range.

System capability: SystemCapability.Print.PrintFramework

Attributes

Name Type Mandatory Description
startPage number No Start page.
endPage number No End page.
pages Array<number> No Discrete pages.

PrintPageSize11+

Defines the size of the printed page.

System capability: SystemCapability.Print.PrintFramework

Attributes

Name Type Mandatory Description
id string Yes Page size ID.
name string Yes Page size name.
width number Yes Page width, in millimeters.
height number Yes Page height, in millimeters.

PrintDirectionMode11+

Enumerates the print direction modes.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
DIRECTION_MODE_AUTO 0 Automatic.
DIRECTION_MODE_PORTRAIT 1 Portrait mode.
DIRECTION_MODE_LANDSCAPE 2 Landscape mode.

PrintColorMode11+

Enumerates the color modes.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
COLOR_MODE_MONOCHROME 0 Black and white.
COLOR_MODE_COLOR 1 Color.

PrintDuplexMode11+

Enumerates the duplex modes.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
DUPLEX_MODE_NONE 0 Simplex (single-sided).
DUPLEX_MODE_LONG_EDGE 1 Duplex (double-sided) with flipping on long edge.
DUPLEX_MODE_SHORT_EDGE 2 Duplex (double-sided) with flipping on short edge.

PrintPageType11+

Enumerates the print page types.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
PAGE_ISO_A3 0 A3.
PAGE_ISO_A4 1 A4.
PAGE_ISO_A5 2 A5.
PAGE_JIS_B5 3 B5.
PAGE_ISO_C5 4 C5.
PAGE_ISO_DL 5 DL.
PAGE_LETTER 6 Letter.
PAGE_LEGAL 7 Legal.
PAGE_PHOTO_4X6 8 4 x 6 photo paper.
PAGE_PHOTO_5X7 9 5 x 7 photo paper.
PAGE_INT_DL_ENVELOPE 10 International envelope DL.
PAGE_B_TABLOID 11 B Tabloid.

PrintDocumentAdapterState11+

Enumerates the print job states.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
PREVIEW_DESTROY 0 The preview fails.
PRINT_TASK_SUCCEED 1 The print job is successful.
PRINT_TASK_FAIL 2 The print job failed.
PRINT_TASK_CANCEL 3 The print job is canceled.
PRINT_TASK_BLOCK 4 The print job is blocked.

PrintFileCreationState11+

Enumerates the print file creation status.

System capability: SystemCapability.Print.PrintFramework

Name Value Description
PRINT_FILE_CREATED 0 The print file is created successfully.
PRINT_FILE_CREATION_FAILED 1 The print file fails to be created.
PRINT_FILE_CREATED_UNRENDERED 2 The print file is successfully created but not rendered.