說明
使用 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
時隱藏「cancel」按鈕。請注意,在某些網路或 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,才能呼叫 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()
,並尋找 "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 格式。該屬性可能遺失。
-
status
印表機的狀態。
JobStatus
列印工作的狀態。
列舉
"PENDING"
在 Chrome 端收到列印工作,但尚未處理。
"IN_PROGRESS"
已傳送列印工作以進行列印。
"FAILED"
列印工作因發生錯誤而中斷。
「已取消」
已由使用者或 API 取消列印工作。
"列印"
列印工作未出現任何錯誤。
Printer
屬性
-
description
字串
使用者可理解的印表機說明。
-
id
字串
印表機的 ID;裝置上所有印表機的 ID 不得重複。
-
isDefault
boolean
顯示印表機是否符合 DefaultPrinterSelection 規則的標記。請注意,系統可能會標記多部印表機。
-
名稱
字串
印表機名稱。
-
recentlyUsedRank
數字 選填
這個值代表最近使用印表機透過 Chrome 列印的情形。值越低表示印表機使用時間越新。最小值為 0。缺少值表示最近並未使用印表機。保證這個值不會與其他印表機重複。
-
印表機的來源 (已設定使用者或政策)。
-
uri
字串
印表機 URI。擴充功能可利用這項資訊為使用者選擇印表機。
PrinterSource
印表機的來源。
列舉
「使用者」
由使用者新增印表機。
「POLICY」
透過政策新增印表機。
PrinterStatus
印表機的狀態。
列舉
"DOOR_OPEN"
印表機門打開了。印表機仍接受列印工作。
"TRAY_MISSING"
缺少印表機匣。印表機仍接受列印工作。
"OUT_OF_INK"
印表機已用盡墨水。印表機仍接受列印工作。
"OUT_OF_PAPER"
印表機已移出紙。印表機仍接受列印工作。
"OUTPUT_FULL"
印表機的輸出區域 (例如托盤) 已滿。印表機仍接受列印工作。
"PAPER_JAM"
印表機有迴紋路。印表機仍接受列印工作。
"GENERIC_ISSUE"
一些一般問題。印表機仍接受列印工作。
「STOPPED」
印表機已停止且無法列印,但仍接受列印工作。
「無法連線」
無法連上印表機,因此無法接受列印工作。
"EXPIRED_CERTIFICATE"
SSL 憑證已到期,印表機接受工作,但工作失敗。
"AVAILABLE"
可供列印。
SubmitJobRequest
屬性
-
工作
要提交的列印工作。僅支援「application/pdf」這個類型。Cloud 工作票券不應包含
FitToPageTicketItem
、PageRangeTicketItem
、ReverseOrderTicketItem
和VendorTicketItem
欄位,因為這些欄位與原生列印無關。所有其他欄位都必須填寫。
SubmitJobResponse
屬性
-
jobId
字串 選用
已建立列印工作的 ID,這是裝置上所有列印工作的專屬 ID。如果狀態有誤,jobId 將為空值。
-
status
要求的狀態。
SubmitJobStatus
submitJob
要求的狀態。
列舉
「確定」
已接受列印工作要求。
"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,
callback?: function,
)
取消先前提交的工作。
參數
-
jobId
字串
要取消的列印工作 ID。此 ID 必須與
SubmitJobResponse
中收到的 ID 相同。 -
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 100 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
以 CDD 格式傳回印表機的狀態和功能。如果沒有安裝指定 ID 的印表機,這個呼叫就會失敗,並顯示執行階段錯誤。
參數
-
printerId
字串
-
回呼
函式選用
callback
參數如下所示:(response: GetPrinterInfoResponse) => void
傳回
-
Promise<GetPrinterInfoResponse>
Chrome 100 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
傳回裝置上可用的印表機清單。包括手動新增、企業和發現的印表機。
傳回
-
Promise<印表機[]>
Chrome 100 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
提交要列印的工作。如果 PrintingAPIExtensionsAllowlist
政策中未列出這項擴充功能,系統會提示使用者接受列印工作。
在 Chrome 120 之前的版本中,這個函式沒有傳回承諾。
參數
-
申請。
-
回呼
函式選用
callback
參數如下所示:(response: SubmitJobResponse) => void
傳回
-
Promise<SubmitJobResponse>
Chrome 100 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。