chrome.printing

คำอธิบาย

ใช้ chrome.printing API เพื่อส่งงานพิมพ์ไปยังเครื่องพิมพ์ที่ติดตั้งใน Chromebook

สิทธิ์

printing

ความพร้อมใช้งาน

Chrome 81 ขึ้นไป ChromeOS เท่านั้น

เมธอดและเหตุการณ์ทั้งหมดของ 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

พร็อพเพอร์ตี้

  • ความสามารถ

    object ไม่บังคับ

    ความสามารถของเครื่องพิมพ์ในรูปแบบ CDD พร็อพเพอร์ตี้อาจหายไป

  • สถานะ

    PrinterStatus

    สถานะของเครื่องพิมพ์

JobStatus

สถานะของงานพิมพ์

ค่าแจกแจง

"รอดำเนินการ"
ได้รับงานพิมพ์ในฝั่ง Chrome แต่ยังไม่ได้ประมวลผล

"IN_PROGRESS"
ส่งงานพิมพ์เพื่อพิมพ์

"ไม่สำเร็จ"
งานพิมพ์ถูกขัดจังหวะเนื่องจากมีข้อผิดพลาดบางอย่าง

"ยกเลิกแล้ว"
ผู้ใช้หรือ API ยกเลิกงานพิมพ์

"พิมพ์แล้ว"
พิมพ์งานพิมพ์โดยไม่มีข้อผิดพลาด

Printer

พร็อพเพอร์ตี้

  • คำอธิบาย

    สตริง

    คำอธิบายเครื่องพิมพ์ที่มนุษย์อ่านได้

  • id

    สตริง

    ตัวระบุของเครื่องพิมพ์ ซึ่งรับประกันว่าจะไม่ซ้ำกันในบรรดาเครื่องพิมพ์ในอุปกรณ์

  • isDefault

    บูลีน

    แฟล็กที่แสดงว่าเครื่องพิมพ์เป็นไปตามกฎ DefaultPrinterSelection หรือไม่ โปรดทราบว่าอาจมีการแจ้งว่าเครื่องพิมพ์หลายเครื่องไม่ปลอดภัย

  • ชื่อ

    สตริง

    ชื่อเครื่องพิมพ์

  • recentlyUsedRank

    หมายเลข ไม่บังคับ

    ค่าที่แสดงว่าใช้เครื่องพิมพ์ล่าสุดเมื่อใดในการพิมพ์จาก Chrome ค่าที่ต่ำกว่าหมายถึงมีการใช้เครื่องพิมพ์เมื่อเร็วๆ นี้ ค่าต่ำสุดคือ 0 ค่าที่ขาดหายไปแสดงว่าไม่ได้ใช้เครื่องพิมพ์เมื่อเร็วๆ นี้ ค่านี้รับประกันได้ว่าจะไม่ซ้ำกันในบรรดาเครื่องพิมพ์

  • source

    PrinterSource

    แหล่งที่มาของเครื่องพิมพ์ (ผู้ใช้หรือนโยบายที่กำหนดค่าไว้)

  • uri

    สตริง

    URI ของเครื่องพิมพ์ ส่วนขยายสามารถใช้ข้อมูลนี้เพื่อเลือกเครื่องพิมพ์ให้ผู้ใช้ได้

PrinterSource

แหล่งที่มาของเครื่องพิมพ์

ค่าแจกแจง

"ผู้ใช้"
ผู้ใช้เพิ่มเครื่องพิมพ์

"นโยบาย"
เพิ่มเครื่องพิมพ์ผ่านนโยบายแล้ว

PrinterStatus

สถานะของเครื่องพิมพ์

ค่าแจกแจง

"DOOR_OPEN"
ฝาเครื่องพิมพ์เปิดอยู่ เครื่องพิมพ์ยังคงรับงานพิมพ์

"TRAY_MISSING"
ไม่มีถาดของเครื่องพิมพ์ เครื่องพิมพ์ยังคงรับงานพิมพ์

"OUT_OF_INK"
เครื่องพิมพ์หมึกหมด เครื่องพิมพ์ยังคงรับงานพิมพ์

"OUT_OF_PAPER"
เครื่องพิมพ์กระดาษหมด เครื่องพิมพ์ยังคงรับงานพิมพ์

"OUTPUT_FULL"
พื้นที่สำหรับกระดาษออกของเครื่องพิมพ์ (เช่น ถาด) เต็มแล้ว เครื่องพิมพ์ยังคงรับงานพิมพ์

"PAPER_JAM"
เครื่องพิมพ์มีกระดาษติด เครื่องพิมพ์ยังคงรับงานพิมพ์

"GENERIC_ISSUE"
ปัญหาทั่วไปบางอย่าง เครื่องพิมพ์ยังคงรับงานพิมพ์

"หยุดแล้ว"
เครื่องพิมพ์หยุดทำงานและไม่พิมพ์ แต่ยังรับงานพิมพ์ได้

"เข้าถึงไม่ได้"
เข้าถึงเครื่องพิมพ์ไม่ได้และไม่ยอมรับงานพิมพ์

"EXPIRED_CERTIFICATE"
ใบรับรอง SSL หมดอายุแล้ว เครื่องพิมพ์รับงานแต่ดำเนินการไม่สำเร็จ

"พร้อมใช้งาน"
เครื่องพิมพ์พร้อมใช้งาน

SubmitJobRequest

พร็อพเพอร์ตี้

  • งาน

    PrintJob

    งานพิมพ์ที่จะส่ง ประเภทเนื้อหาที่รองรับคือ "application/pdf" และ "image/png" ตั๋วงานในระบบคลาวด์ไม่ควรรวมฟิลด์ FitToPageTicketItem, PageRangeTicketItem และ ReverseOrderTicketItem เนื่องจากไม่เกี่ยวข้องกับการพิมพ์แบบดั้งเดิม คุณจะระบุ VendorTicketItem หรือไม่ก็ได้ ต้องมีฟิลด์อื่นๆ ทั้งหมด

SubmitJobResponse

พร็อพเพอร์ตี้

  • jobId

    สตริง ไม่บังคับ

    รหัสของงานพิมพ์ที่สร้างขึ้น ซึ่งเป็นตัวระบุที่ไม่ซ้ำกันในบรรดางานพิมพ์ทั้งหมดในอุปกรณ์ หากสถานะไม่ใช่ OK, jobId จะเป็น null

  • สถานะ

    SubmitJobStatus

    สถานะของคำขอ

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,
): Promise<void>

ยกเลิกงานที่ส่งก่อนหน้านี้

พารามิเตอร์

  • jobId

    สตริง

    รหัสของงานพิมพ์ที่จะยกเลิก ซึ่งควรเป็นรหัสเดียวกับที่ได้รับใน SubmitJobResponse

การคืนสินค้า

  • Promise<void>

    Chrome 100 ขึ้นไป

getJobStatus()

Chrome 135 ขึ้นไป 
chrome.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

แสดงสถานะของงานพิมพ์ การเรียกนี้จะล้มเหลวพร้อมข้อผิดพลาดรันไทม์หากไม่มีงานพิมพ์ที่มี jobId ที่ระบุ jobId: รหัสของงานพิมพ์ที่จะแสดงสถานะ ซึ่งควรเป็นรหัสเดียวกับที่ได้รับใน SubmitJobResponse

พารามิเตอร์

  • jobId

    สตริง

การคืนสินค้า

getPrinterInfo()

chrome.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

แสดงผลสถานะและความสามารถของเครื่องพิมพ์ในรูปแบบ CDD การเรียกนี้จะล้มเหลวพร้อมข้อผิดพลาดรันไทม์หากไม่ได้ติดตั้งเครื่องพิมพ์ที่มีรหัสที่ระบุ

พารามิเตอร์

  • printerId

    สตริง

การคืนสินค้า

getPrinters()

chrome.printing.getPrinters(): Promise<Printer[]>

แสดงรายการเครื่องพิมพ์ที่พร้อมใช้งานในอุปกรณ์ ซึ่งรวมถึงเครื่องพิมพ์ที่เพิ่มด้วยตนเอง เครื่องพิมพ์ขององค์กร และเครื่องพิมพ์ที่ค้นพบ

การคืนสินค้า

  • Promise<Printer[]>

    Chrome 100 ขึ้นไป

submitJob()

chrome.printing.submitJob(
  request: SubmitJobRequest,
): Promise<SubmitJobResponse>

ส่งงานไปพิมพ์ หากส่วนขยายไม่ได้อยู่ในนโยบาย PrintingAPIExtensionsAllowlist ระบบจะแจ้งให้ผู้ใช้ยอมรับงานพิมพ์ ในเวอร์ชันก่อนหน้า Chrome 120 ฟังก์ชันนี้จะไม่แสดงผล Promise

พารามิเตอร์

การคืนสินค้า

กิจกรรม

onJobStatusChanged

chrome.printing.onJobStatusChanged.addListener(
  callback: function,
)

เหตุการณ์ที่ทริกเกอร์เมื่อมีการเปลี่ยนสถานะของงาน เหตุการณ์นี้จะทริกเกอร์เฉพาะสำหรับงานที่สร้างโดยส่วนขยายนี้เท่านั้น

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (jobId: string, status: JobStatus) => void

    • jobId

      สตริง

    • สถานะ

      JobStatus