說明
使用 chrome.printing API 將列印工作傳送至 Chromebook 上安裝的印表機。
權限
printing可用性
所有 chrome.printing 方法和事件都需要在擴充功能資訊清單中聲明 "printing" 權限。例如：
{ "name": "My extension", ... "permissions": [ "printing" ], ... } 範例
以下範例示範如何使用列印命名空間中的每種方法。這段程式碼是從 extensions-samples Github 存放區的 api-samples/printing 複製或改編而來。
cancelJob()
這個範例會使用 onJobStatusChanged 處理常式，在 jobStatus 不是 PENDING 或 IN_PROGRESS 時隱藏「取消」按鈕。請注意，在某些網路中，或當 Chromebook 直接連線至印表機時，這些狀態可能會快速通過，導致取消按鈕無法顯示足夠時間供呼叫。這是大幅簡化的列印範例。
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()
這些函式會使用單一範例，因為取得印表機資訊需要印表機 ID，而這項 ID 是透過呼叫 getPrinters() 擷取。這個範例會將預設印表機的名稱和說明記錄到控制台。這是簡化版的列印範例。
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()
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' }); } }; chrome.printing.submitJob(submitJobRequest, (response) => { if (response !== undefined) { console.log(response.status); } if (chrome.runtime.lastError !== undefined) { console.log(chrome.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() 並尋找 "display_name" 的 "finishings/11"。
"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
object 選填
CDD 格式的印表機功能。可能缺少屬性。
-
印表機狀態。
JobStatus
列印工作狀態。
列舉
「待處理」
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」
Some generic issue. 印表機仍可接受列印工作。
「已停止」
印表機已停止運作，不會列印，但仍會接受列印工作。
「無法連線」
印表機無法連線，且不接受列印工作。
「EXPIRED_CERTIFICATE」
SSL 憑證已過期。印表機接受工作，但工作失敗。
「AVAILABLE」(可用)
印表機可用。
SubmitJobRequest
屬性
- 工作
要提交的列印工作。支援的內容類型為「application/pdf」和「image/png」。雲端作業單不應包含
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()
chrome.printing.cancelJob(
jobId: string,
): Promise<void>
取消先前提交的工作。
參數
- jobId
字串
要取消的列印工作 ID。這應與
SubmitJobResponse中收到的 ID 相同。
傳回
-
Promise<void>
Chrome 100 以上版本
getJobStatus()
chrome.printing.getJobStatus(
jobId: string,
): Promise<JobStatus>
傳回列印工作的狀態。如果具有指定 jobId 的列印工作不存在，這項呼叫就會失敗並顯示執行階段錯誤。jobId：要傳回狀態的列印工作 ID。這應與 SubmitJobResponse 中收到的 ID 相同。
參數
- jobId
字串
傳回
-
Promise<JobStatus>
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
): Promise<GetPrinterInfoResponse>
以 CDD 格式傳回印表機的狀態和功能。如果未安裝具有指定 ID 的印表機，這項呼叫會失敗並顯示執行階段錯誤。
參數
- printerId
字串
傳回
-
Promise<GetPrinterInfoResponse>
Chrome 100 以上版本
傳回
-
Promise<Printer[]>
Chrome 100 以上版本
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
): Promise<SubmitJobResponse>
提交列印工作。如果擴充功能未列在 PrintingAPIExtensionsAllowlist 政策中，系統會提示使用者接受列印工作。 在 Chrome 120 之前，這項函式不會傳回 Promise。
參數
- 申請。
傳回
-
Promise<SubmitJobResponse>
Chrome 100 以上版本