chrome.printing

สำคัญ: API นี้ใช้งานได้เฉพาะใน ChromeOS

คำอธิบาย

ใช้ 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

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

• capabilities

  ออบเจ็กต์ ไม่บังคับ

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

• status

  PrinterStatus

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

JobStatus

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

ค่าแจกแจง

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

"IN_PROGRESS"
ส่งงานพิมพ์ไปพิมพ์แล้ว

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

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

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

Printer

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

• คำอธิบาย

  string

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

• id

  string

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

• isDefault

  boolean

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

• ชื่อ

  string

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

• recentlyUsedRank

  ตัวเลข ไม่บังคับ

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

• source

  PrinterSource

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

• 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

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

• งาน

  PrintJob

  งานพิมพ์ที่จะส่ง เนื้อหาที่รองรับประเภทเดียวคือ "application/pdf" และ Cloud Job Ticket ไม่ควรมีช่อง FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem และ VendorTicketItem เนื่องจากไม่เกี่ยวข้องกับการพิมพ์แบบดั้งเดิม ต้องมีช่องอื่นๆ ทั้งหมด

SubmitJobResponse

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

• jobId

  string ไม่บังคับ

  รหัสของงานพิมพ์ที่สร้าง นี่คือตัวระบุที่ไม่ซ้ำกันในงานพิมพ์ทั้งหมดในอุปกรณ์ หากสถานะไม่เป็น "ตกลง" รหัสงานจะเป็น Null

• status

  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,
  callback?: function,
)

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

พารามิเตอร์

• jobId

  string

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

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  ()=>void

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

• Promise<void>

  Chrome 100 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getPrinterInfo()

สัญญา

chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

พารามิเตอร์

• printerId

  string

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  (response: GetPrinterInfoResponse)=>void

  • การตอบกลับ

    GetPrinterInfoResponse

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

• Promise<GetPrinterInfoResponse>

  Chrome 100 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getPrinters()

สัญญา

chrome.printing.getPrinters(
  callback?: function,
)

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

พารามิเตอร์

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  (printers: Printer[])=>void

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

    เครื่องพิมพ์[]

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

• สัญญา<เครื่องพิมพ์[]>

  Chrome 100 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

submitJob()

สัญญา

chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

พารามิเตอร์

• ส่งคำขอ

  SubmitJobRequest

• Callback

  ฟังก์ชัน ไม่บังคับ

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

  (response: SubmitJobResponse)=>void

  • การตอบกลับ

    SubmitJobResponse

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

• Promise<SubmitJobResponse>

  Chrome 100 ขึ้นไป

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onJobStatusChanged

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

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

พารามิเตอร์

• Callback

  ฟังก์ชัน

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

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

  • jobId

    string

  • status

    JobStatus