คำอธิบาย
ใช้ chrome.printing
API เพื่อส่งงานพิมพ์ไปยังเครื่องพิมพ์ที่ติดตั้งใน Chromebook
สิทธิ์
printing
ความพร้อมใช้งาน
ไฟล์ Manifest
วิธีการและเหตุการณ์ chrome.printing
ทั้งหมดกำหนดให้คุณประกาศสิทธิ์ "printing"
ในไฟล์ Manifest ของส่วนขยาย เช่น
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
ตัวอย่าง
ตัวอย่างด้านล่างแสดงให้เห็นการใช้แต่ละเมธอดในเนมสเปซการพิมพ์ โค้ดนี้คัดลอกมาจากหรืออิงตาม api-samples/printingในที่เก็บ GitHub สำหรับตัวอย่างส่วนขยาย
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()
มีการใช้ตัวอย่างเดียวสำหรับฟังก์ชันเหล่านี้เนื่องจากการรับข้อมูลเครื่องพิมพ์ต้องใช้รหัสเครื่องพิมพ์ ซึ่งดึงขึ้นมาโดยการเรียกใช้ 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()
ต้องใช้ 3 สิ่ง
- โครงสร้าง
ticket
ที่ระบุความสามารถของเครื่องพิมพ์ที่จะใช้ หากผู้ใช้ต้องเลือกจากความสามารถที่มี คุณสามารถเรียกดูข้อความสำหรับเครื่องพิมพ์ที่ระบุได้โดยใช้getPrinterInfo()
- โครงสร้าง
SubmitJobRequest
ซึ่งระบุเครื่องพิมพ์ที่จะใช้ และไฟล์หรือวันที่ที่จะพิมพ์ โครงสร้างนี้มีการอ้างอิงไปยังโครงสร้างticket
- Blob ของไฟล์หรือข้อมูลที่จะพิมพ์
การเรียกใช้ submitJob()
จะเป็นการทริกเกอร์กล่องโต้ตอบที่ขอให้ผู้ใช้ยืนยันการพิมพ์ ใช้ PrintingAPIExtensionsAllowlist
เพื่อข้ามการยืนยัน
นี่คือตัวอย่างการพิมพ์แบบง่าย โปรดสังเกตว่า ticket
แนบอยู่กับโครงสร้าง SubmitJobRequest
(บรรทัดที่ 8) และข้อมูลที่จะพิมพ์ถูกแปลงเป็น BLOB (บรรทัดที่ 10) การดูรหัสของเครื่องพิมพ์ (บรรทัดที่ 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
(ค่าเริ่มต้นจะแตกต่างกันไปตามเครื่องพิมพ์แต่ละรุ่น) เมื่อรวมไว้แล้ว คีย์นี้ต้องเป็นอาร์เรย์ที่มีสมาชิก 1 ราย ซึ่งเป็นออบเจ็กต์ที่ 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"
เป็นจริง ใช้ค่าความสูงและความกว้างของคำขอแจ้งปัญหา
"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
สถานะของงานพิมพ์
ค่าแจกแจง
"รอดำเนินการ"
ได้รับงานพิมพ์ที่ฝั่ง Chrome แต่ยังไม่ได้ประมวลผล
"IN_PROGRESS"
ส่งงานพิมพ์ไปพิมพ์แล้ว
"ล้มเหลว"
งานพิมพ์ถูกขัดจังหวะเนื่องจากเกิดข้อผิดพลาดบางอย่าง
"CANCELED"
ผู้ใช้ยกเลิกงานพิมพ์หรือผ่าน API
"PRINTED"
พิมพ์งานพิมพ์โดยไม่มีข้อผิดพลาด
Printer
พร็อพเพอร์ตี้
-
คำอธิบาย
string
คำอธิบายเครื่องพิมพ์ที่มนุษย์อ่านได้
-
id
string
ตัวระบุของเครื่องพิมพ์ซึ่งรับประกันว่าจะไม่ซ้ำกันระหว่างเครื่องพิมพ์ต่างๆ บนอุปกรณ์
-
isDefault
boolean
ธงที่ระบุว่าเครื่องพิมพ์เป็นไปตามกฎ DefaultPrinterSelection โปรดทราบว่าอาจมีการแจ้งเครื่องพิมพ์หลายเครื่อง
-
ชื่อ
string
ชื่อเครื่องพิมพ์
-
recentlyUsedRank
ตัวเลข ไม่บังคับ
ค่าที่แสดงความล่าสุดในการใช้เครื่องพิมพ์ในการพิมพ์จาก Chrome ยิ่งค่าต่ำเท่าใด ก็จะยิ่งใช้เครื่องพิมพ์ล่าสุดมากขึ้นเท่านั้น ค่าต่ำสุดคือ 0 ค่าที่ขาดหายไปบ่งบอกว่าไม่มีการใช้เครื่องพิมพ์เมื่อเร็วๆ นี้ ค่านี้ได้รับการรับประกันว่าไม่ซ้ำกันในเครื่องพิมพ์ทั้งหมด
-
source
แหล่งที่มาของเครื่องพิมพ์ (กำหนดค่าผู้ใช้หรือนโยบายแล้ว)
-
uri
string
URI ของเครื่องพิมพ์ ซึ่งส่วนขยายจะใช้การเลือกเครื่องพิมพ์ให้ผู้ใช้ได้
PrinterSource
แหล่งที่มาของเครื่องพิมพ์
ค่าแจกแจง
"USER"
ผู้ใช้เพิ่มเครื่องพิมพ์แล้ว
"POLICY"
เพิ่มเครื่องพิมพ์ผ่านนโยบาย
PrinterStatus
สถานะของเครื่องพิมพ์
ค่าแจกแจง
"DOOR_OPEN"
ประตูเครื่องพิมพ์เปิดอยู่ ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"TRAY_MISSING"
ไม่มีถาดเครื่องพิมพ์ ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"OUT_OF_INK"
เครื่องพิมพ์หมึกหมด ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"OUT_OF_PAPER"
เครื่องพิมพ์กระดาษหมด ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"OUTPUT_FULL"
พื้นที่เอาต์พุตของเครื่องพิมพ์ (เช่น ถาดข้อมูล) เต็ม ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"PAPER_JAM"
เครื่องพิมพ์ติดกระดาษติด ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"GENERIC_ISSUE"
ปัญหาทั่วไปบางประการ ทั้งนี้เครื่องพิมพ์ยังคงยอมรับงานพิมพ์อยู่
"หยุดแล้ว"
เครื่องพิมพ์หยุดทำงานและไม่พิมพ์ แต่ยังคงยอมรับงานพิมพ์
"ไม่สามารถเข้าถึงได้"
เข้าถึงเครื่องพิมพ์ไม่ได้และไม่รับงานพิมพ์
"EXPIRED_CERTIFICATE"
ใบรับรอง SSL หมดอายุแล้ว เครื่องพิมพ์ยอมรับงานแต่ล้มเหลว
"AVAILABLE"
เครื่องพิมพ์พร้อมใช้งาน
SubmitJobRequest
พร็อพเพอร์ตี้
-
งาน
งานพิมพ์ที่จะส่ง เนื้อหาที่รองรับประเภทเดียวคือ "application/pdf" และ Cloud Job Ticket ไม่ควรมีช่อง
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
และVendorTicketItem
เนื่องจากไม่เกี่ยวข้องกับการพิมพ์แบบดั้งเดิม ต้องมีช่องอื่นๆ ทั้งหมด
SubmitJobResponse
พร็อพเพอร์ตี้
-
jobId
string ไม่บังคับ
รหัสของงานพิมพ์ที่สร้าง นี่คือตัวระบุที่ไม่ซ้ำกันในงานพิมพ์ทั้งหมดในอุปกรณ์ หากสถานะไม่เป็น "ตกลง" รหัสงานจะเป็น Null
-
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
string
รหัสของงานพิมพ์ที่จะยกเลิก ซึ่งควรเป็นรหัสเดียวกับที่ได้รับใน
SubmitJobResponse
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้() => void
การคืนสินค้า
-
Promise<void>
Chrome 100 ขึ้นไปPromiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
แสดงผลสถานะและความสามารถของเครื่องพิมพ์ในรูปแบบ CDD การเรียกใช้นี้จะล้มเหลวโดยมีข้อผิดพลาดรันไทม์หากไม่ได้ติดตั้งเครื่องพิมพ์ที่มีรหัสที่กำหนด
พารามิเตอร์
-
printerId
string
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(response: GetPrinterInfoResponse) => void
-
การตอบกลับ
-
การคืนสินค้า
-
Promise<GetPrinterInfoResponse>
Chrome 100 ขึ้นไปPromiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
แสดงรายการเครื่องพิมพ์ที่ใช้งานได้ในอุปกรณ์ ซึ่งรวมถึงเครื่องพิมพ์ระดับองค์กรและเครื่องพิมพ์ที่ค้นพบด้วยตนเอง
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(printers: Printer[]) => void
-
เครื่องพิมพ์
-
การคืนสินค้า
-
สัญญา<เครื่องพิมพ์[]>
Chrome 100 ขึ้นไปPromiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
ส่งงานไปพิมพ์ หากส่วนขยายนั้นไม่แสดงในนโยบาย PrintingAPIExtensionsAllowlist
ระบบจะแจ้งให้ผู้ใช้ยอมรับงานพิมพ์
ก่อนที่จะมี Chrome 120 ฟังก์ชันนี้ไม่ได้แสดงคำมั่นสัญญา
พารามิเตอร์
-
ส่งคำขอ
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
มีลักษณะดังนี้(response: SubmitJobResponse) => void
-
การตอบกลับ
-
การคืนสินค้า
-
Promise<SubmitJobResponse>
Chrome 100 ขึ้นไปPromiss รองรับเฉพาะไฟล์ Manifest V3 ขึ้นไป ส่วนแพลตฟอร์มอื่นๆ จะต้องใช้โค้ดเรียกกลับ
กิจกรรม
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
เหตุการณ์เริ่มทำงานเมื่อสถานะของงานมีการเปลี่ยนแปลง การดำเนินการนี้จะเริ่มทำงานเฉพาะสำหรับงานที่สร้างโดยส่วนขยายนี้เท่านั้น