說明
使用 chrome.printing API 將列印工作傳送至 Chromebook 上安裝的印表機。
權限
printing可用性
所有 browser.printing 方法和事件都必須在擴充功能資訊清單中宣告 "printing" 權限。例如：
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
範例
以下範例示範如何使用列印命名空間中的各個方法。這段程式碼是複製或改編自 extensions-samples GitHub 存放區中的 api-samples/printing。
cancelJob()
這個範例使用 onJobStatusChanged 處理常式，在 jobStatus 不是 PENDING 或 IN_PROGRESS 時隱藏「取消」按鈕。請注意，在某些網路上或 Chromebook 直接連接印表機時，這些狀態可能會過快通過，導致取消按鈕顯示的時間不夠長，無法呼叫。這是非常簡化的列印範例。
browser.printing.onJobStatusChanged.addListener((jobId, status) => {
const cancelButton = document.getElementById("cancelButton");
cancelButton.addEventListener('click', () => {
browser.printing.cancelJob(jobId).then((response) => {
if (response !== undefined) {
console.log(response.status);
}
if (browser.runtime.lastError !== undefined) {
console.log(browser.runtime.lastError.message);
}
});
});
if (status !== "PENDING" && status !== "IN_PROGRESS") {
cancelButton.style.visibility = 'hidden';
} else {
cancelButton.style.visibility = 'visible';
}
}
getPrinters() and getPrinterInfo()
這些函式會使用單一範例，因為取得印表機資訊需要印表機 ID，而印表機 ID 是透過呼叫 getPrinters() 擷取。這個範例會將預設印表機的名稱和說明記錄到控制台。這是列印範例的簡化版本。
const printers = await browser.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
const printerInfo = await browser.printing.getPrinterInfo(printer.id);
return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);
submitJob()
submitJob() 方法需要三個引數。
ticket結構，指定要使用的印表機功能。如果使用者需要從可用功能中選取，您可以使用getPrinterInfo()擷取特定印表機的功能。SubmitJobRequest結構，用於指定要使用的印表機，以及要列印的檔案或資料。這個結構包含ticket結構的參照。- 要列印的檔案或資料 blob。
呼叫 submitJob() 會觸發對話方塊，要求使用者確認列印。使用 PrintingAPIExtensionsAllowlist 略過確認。
這是列印範例的簡化版本。請注意，ticket 會附加至 SubmitJobRequest 結構 (第 8 行)，且要列印的資料會轉換為 blob (第 10 行)。範例中取得印表機 ID (第 1 行) 的方式比這裡顯示的更複雜。
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'
});
}
};
browser.printing.submitJob(submitJobRequest, (response) => {
if (response !== undefined) {
console.log(response.status);
}
if (browser.runtime.lastError !== undefined) {
console.log(browser.runtime.lastError.message);
}
});
捲筒列印
這個範例說明如何建立連續 (或捲筒) 列印的印表機票證，這通常用於列印收據。捲筒列印的 submitJobRequest 物件與 submitJob() 範例中顯示的物件相同。
如要變更切紙的預設值，請使用 vendor_ticket_item 鍵。(預設值因印表機而異)。如要變更值，請提供包含一個成員的陣列：id 為 'finishings' 的物件。如果印表機會在列印結束時裁切捲筒紙，這個值可以是 'trim'；如果印表機需要撕下列印工作，這個值可以是 'none'。
const ticket = {
version: '1.0',
print: {
vendor_ticket_item: [{id: 'finishings', value: 'trim'}],
color: {type: 'STANDARD_MONOCHROME'},
duplex: {type: 'NO_DUPLEX'},
page_orientation: {type: 'PORTRAIT'},
copies: {copies: 1},
dpi: {horizontal_dpi: 300, vertical_dpi: 300},
media_size: {
width_microns: 72320,
height_microns: 100000
},
collate: {collate: false}
}
};
部分印表機不支援 "finishings" 選項。如要判斷印表機是否支援，請呼叫 getPrinterInfo()，並尋找 "finishings/11" 的 "display_name"。
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
票證 media_size 鍵中的值因印表機而異。如要選取適當的大小，請呼叫 getPrinterInfo()。傳回的 GetPrinterResponse 包含 "media_size"."option" 支援的媒體大小陣列。選擇 "is_continuous_feed" 值為 true 的選項。並使用其高度和寬度值。
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
類型
GetPrinterInfoResponse
屬性
-
capabilities
物件 選填
CDD 格式的印表機功能。可能缺少該屬性。
-
印表機的狀態。
JobStatus
列印工作的狀態。
列舉
「PENDING」
Chrome 端已收到列印工作，但尚未處理。
"IN_PROGRESS"
列印工作已傳送至印表機。
「FAILED」
列印工作因發生錯誤而中斷。
「CANCELED」
列印工作已由使用者或透過 API 取消。
"PRINTED"
列印工作已完成，未發生任何錯誤。
Printer
屬性
-
說明
字串
印表機的人類可讀說明。
-
id
字串
印表機的 ID，保證在裝置上的印表機中不重複。
-
isDefault
布林值
這個標記會顯示印表機是否符合 DefaultPrinterSelection 規則。請注意，系統可能會標記多部印表機。
-
名稱
字串
印表機名稱。
-
recentlyUsedRank
數字 選填
這個值代表最近一次使用印表機從 Chrome 列印的時間。值越低，代表印表機越近期使用。最小值為 0。如果缺少值，表示最近未使用印表機。這個值在印表機中不重複。
-
印表機來源 (使用者或政策設定)。
-
uri
字串
印表機 URI。擴充功能可使用這項資訊為使用者選擇印表機。
PrinterSource
印表機的來源。
列舉
"USER"
印表機是由使用者新增。
「政策」
印表機是透過政策新增。
PrinterStatus
印表機的狀態。
列舉
"DOOR_OPEN"
印表機的門已開啟。印表機仍會接受列印工作。
"TRAY_MISSING"
印表機缺少紙匣。印表機仍會接受列印工作。
"OUT_OF_INK"
印表機墨水用盡。印表機仍會接受列印工作。
"OUT_OF_PAPER"
印表機缺紙。印表機仍會接受列印工作。
"OUTPUT_FULL"
印表機的出紙區域 (例如托盤) 已滿。印表機仍會接受列印工作。
"PAPER_JAM"
印表機卡紙。印表機仍會接受列印工作。
"GENERIC_ISSUE"
一般問題。印表機仍會接受列印工作。
「STOPPED」
印表機已停止，不會列印，但仍接受列印工作。
「UNREACHABLE」
無法連上印表機，且印表機不接受列印工作。
"EXPIRED_CERTIFICATE"
SSL 憑證已過期。印表機接受工作，但工作失敗。
「可用」
印表機可供使用。
SubmitJobRequest
屬性
-
工作
要提交的列印工作。支援的內容類型為「application/pdf」和「image/png」。Cloud Job Ticket 不應包含
FitToPageTicketItem、PageRangeTicketItem和ReverseOrderTicketItem欄位，因為這些欄位與原生列印無關。VendorTicketItem為選用項目。其他欄位則必須存在。
SubmitJobResponse
屬性
-
jobId
字串 選填
已建立列印工作的 ID。這是裝置上所有列印工作的專屬 ID。如果狀態不是「OK」，jobId 會是空值。
-
要求的狀態。
SubmitJobStatus
submitJob 要求的狀態。
列舉
「OK」
系統已接受傳送的列印工作要求。
"USER_REJECTED"
使用者拒絕傳送的列印工作要求。
屬性
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
每分鐘可呼叫 getPrinterInfo 的次數上限。
值
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
每分鐘可呼叫 submitJob 的次數上限。
值
40
方法
cancelJob()
browser.printing.cancelJob(
jobId: string,
): Promise<void>
取消先前提交的工作。
參數
-
jobId
字串
要取消的列印工作 ID。這應該與
SubmitJobResponse中收到的 ID 相同。
傳回
-
承諾<void>
Chrome 100+ browser.* (自 Chrome 148 起)
getJobStatus()
browser.printing.getJobStatus(
jobId: string,
): Promise<JobStatus>
傳回列印工作的狀態。如果具有指定 jobId 的列印工作不存在，這項呼叫會失敗，並顯示執行階段錯誤。jobId：要傳回狀態的列印工作 ID。這應該與 SubmitJobResponse 中收到的 ID 相同。
參數
-
jobId
字串
傳回
-
Promise<JobStatus>
getPrinterInfo()
browser.printing.getPrinterInfo(
printerId: string,
): Promise<GetPrinterInfoResponse>
以 CDD 格式傳回印表機的狀態和功能。如果未安裝指定 ID 的印表機，這項呼叫會失敗，並顯示執行階段錯誤。
參數
-
printerId
字串
傳回
-
Promise<GetPrinterInfoResponse>
Chrome 100+ browser.* (自 Chrome 148 起)
傳回
-
Promise<Printer[]>
Chrome 100+ browser.* (自 Chrome 148 起)
submitJob()
browser.printing.submitJob(
request: SubmitJobRequest,
): Promise<SubmitJobResponse>
提交列印工作。如果擴充功能未列在 PrintingAPIExtensionsAllowlist 政策中，系統會提示使用者接受列印工作。
在 Chrome 120 之前，這個函式不會傳回 Promise。
參數
-
申請。
傳回
-
Promise<SubmitJobResponse>
Chrome 100+ browser.* (自 Chrome 148 起)