chrome.printing
- Description
Use the
chrome.printing
API to send print jobs to printers installed on Chromebook. - Permissions
printing
- AvailabilityChrome 81+
Manifest
All chrome.printing
methods and events require you to declare the "printing"
permission in the extension manifest. For example:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Examples
The examples below demonstrate using each of the methods in the printing namespace. This code is copied from or based on the api-samples/printing in the extensions-samples Github repo.
cancelJob()
This example uses the onJobStatusChanged
handler to hide a 'cancel' button when the jobStatus
is neither PENDING
or IN_PROGRESS
. Note that on some networks or when a Chromebook is connected directly to the printer, these states may pass too quickly for the cancel button to be visible long enough to be called. This is greatly simplified printing example.
chrome.printing.onJobStatusChanged.addListener((jobId, status) => {
const cancelButton = document.getElementById("cancelButton");
cancelButton.addEventListener('click', () => {
chrome.printing.cancelJob(jobId).then((response) => {
if (response !== undefined) {
console.log(response.status);
}
if (chrome.runtime.lastError !== undefined) {
console.log(chrome.runtime.lastError.message);
}
});
});
if (status !== "PENDING" && status !== "IN_PROGRESS") {
cancelButton.style.visibility = 'hidden';
} else {
cancelButton.style.visibility = 'visible';
}
}
getPrinters() and getPrinterInfo()
A single example is used for these functions because getting printer information requires a printer ID, which is retrieved by calling getPrinters()
. This example logs the name and description of the default printer to the console. This is a simplified version of the printing example.
const printers = await chrome.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
const printerInfo = await chrome.printing.getPrinterInfo(printer.id);
return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);
submitJob()
The submitJob()
method requires three things.
- A
ticket
structure specifying which capabilities of the printer are to be used. If the user needs to select from available capabilities, you can retrieve them for a specific printer usinggetPrinterInfo()
. - A
SubmitJobRequest
structure, which specifies the printer to use, and the file or date to print. This structure contains a reference to theticket
structure. - A blob of the file or data to print.
This is a simplified version of the printing example. Notice that the ticket
is attached to the SubmitJobRequest
structure (line 8) and that the data to print is converted to a blob (line 10). Getting the ID of the printer (line 1) is more complicated in the samplethan is shown here.
const defaultPrinter = getDefaultPrinter();
const ticket = getPrinterTicket(defaultPrinter);
const arrayBuffer = getPrintData();
const submitJobRequest = {
job: {
printerId: defaultPrinter,
title: 'test job',
ticket: ticket,
contentType: 'application/pdf',
document: new Blob([new Uint8Array(arrayBuffer)], {
type: 'application/pdf'
});
}
};
chrome.printing.submitJob(submitJobRequest, (response) => {
if (response !== undefined) {
console.log(response.status);
}
if (chrome.runtime.lastError !== undefined) {
console.log(chrome.runtime.lastError.message);
}
});
Summary
- Types
- Properties
- Methods
- Events
Types
GetPrinterInfoResponse
Properties
- capabilities
object optional
Printer capabilities in CDD format. The property may be missing.
- status
The status of the printer.
JobStatus
Status of the print job.
Type
"PENDING"
,"IN_PROGRESS"
,"FAILED"
,"CANCELED"
, or"PRINTED"
Printer
Properties
- description
string
The human-readable description of the printer.
- id
string
The printer's identifier; guaranteed to be unique among printers on the device.
- isDefault
boolean
The flag which shows whether the printer fits DefaultPrinterSelection rules. Note that several printers could be flagged.
- name
string
The name of the printer.
- recentlyUsedRank
number optional
The value showing how recent the printer was used for printing from Chrome. The lower the value is the more recent the printer was used. The minimum value is 0. Missing value indicates that the printer wasn't used recently. This value is guaranteed to be unique amongst printers.
- source
The source of the printer (user or policy configured).
- uri
string
The printer URI. This can be used by extensions to choose the printer for the user.
PrinterSource
The source of the printer.
Type
"USER"
, or"POLICY"
PrinterStatus
The status of the printer.
Type
"DOOR_OPEN"
,"TRAY_MISSING"
,"OUT_OF_INK"
,"OUT_OF_PAPER"
,"OUTPUT_FULL"
,"PAPER_JAM"
,"GENERIC_ISSUE"
,"STOPPED"
,"UNREACHABLE"
, or"AVAILABLE"
SubmitJobRequest
Properties
- job
The print job to be submitted. The only supported content type is "application/pdf", and the CJT ticket shouldn't include FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem and VendorTicketItem fields since they are irrelevant for native printing. All other fields must be present.
SubmitJobResponse
Properties
- jobId
string optional
The id of created print job. This is a unique identifier among all print jobs on the device. If status is not OK, jobId will be null.
- status
The status of the request.
SubmitJobStatus
The status of submitJob
request.
Type
"OK"
, or"USER_REJECTED"
Properties
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
The maximum number of times that getPrinterInfo
can be called per minute.
Value
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
The maximum number of times that submitJob
can be called per minute.
Value
40
Methods
cancelJob
chrome.printing.cancelJob(
jobId:
string,
callback?:
function,
)
Cancels previously submitted job.
Parameters
- jobId
string
The id of the print job to cancel. This should be the same id received in a
SubmitJobResponse
. - callback
function optional
The
callback
parameter looks like:() => void
Returns
Promise<void>
Chrome 100+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getPrinterInfo
chrome.printing.getPrinterInfo(
printerId:
string,
callback?:
function,
)
Returns the status and capabilities of the printer in CDD format. This call will fail with a runtime error if no printers with given id are installed.
Parameters
- printerId
string
- callback
function optional
The
callback
parameter looks like:(response: GetPrinterInfoResponse) => void
- response
Returns
Promise<GetPrinterInfoResponse>
Chrome 100+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getPrinters
chrome.printing.getPrinters(
callback?:
function,
)
Returns the list of available printers on the device. This includes manually added, enterprise and discovered printers.
Parameters
Returns
Promise<Printer[]>
Chrome 100+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
submitJob
chrome.printing.submitJob(
request:
SubmitJobRequest,
callback?:
function,
)
Submits the job for print. If the extension is not listed in PrintingAPIExtensionsAllowlist policy, the user will be prompted to accept the print job.
Parameters
- request
- callback
function optional
The
callback
parameter looks like:(response: SubmitJobResponse) => void
- response
Returns
Promise<SubmitJobResponse>
Chrome 100+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback:
function,
)
Event fired when the status of the job is changed. This is only fired for the jobs created by this extension.