chrome.printing

Mô tả

Sử dụng API chrome.printing để gửi lệnh in đến máy in được cài đặt trên Chromebook.

Quyền

printing

Phạm vi cung cấp

Chrome 81 trở lên Chỉ ChromeOS

Tệp kê khai

Mọi phương thức và sự kiện chrome.printing đều yêu cầu bạn khai báo quyền "printing" trong tệp kê khai tiện ích. Ví dụ:

{
  "name": "My extension",
  ...
  "permissions": [
    "printing"
  ],
  ...
}

Ví dụ

Các ví dụ dưới đây minh hoạ cách sử dụng từng phương thức trong không gian tên in. Mã này được sao chép từ hoặc dựa trên api-samples/printing trong kho lưu trữ GitHub extensions-samples.

cancelJob()

Ví dụ này sử dụng trình xử lý onJobStatusChanged để ẩn nút "cancel" (huỷ) khi jobStatus không phải là PENDING hoặc IN_PROGRESS. Xin lưu ý rằng trên một số mạng hoặc khi Chromebook kết nối trực tiếp với máy in, các trạng thái này có thể trôi qua quá nhanh khiến nút huỷ không hiển thị đủ lâu để được gọi. Đây là ví dụ in được đơn giản hoá đáng kể.

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()

Một ví dụ duy nhất được dùng cho các hàm này vì việc lấy thông tin máy in cần có mã máy in, được truy xuất bằng cách gọi getPrinters(). Ví dụ này ghi tên và nội dung mô tả của máy in mặc định vào bảng điều khiển. Đây là phiên bản đơn giản của ví dụ in.

​​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()

Phương thức submitJob() yêu cầu 3 điều.

  • Cấu trúc ticket chỉ định những chức năng của máy in sẽ được sử dụng. Nếu người dùng cần chọn trong số các chức năng có sẵn, bạn có thể truy xuất các chức năng đó cho một máy in cụ thể bằng getPrinterInfo().
  • Cấu trúc SubmitJobRequest chỉ định máy in cần sử dụng và tệp hoặc ngày cần in. Cấu trúc này chứa tham chiếu đến cấu trúc ticket.
  • Một blob của tệp hoặc dữ liệu cần in.

Việc gọi submitJob() sẽ kích hoạt một hộp thoại yêu cầu người dùng xác nhận in. Sử dụng PrintingAPIExtensionsAllowlist để bỏ qua bước xác nhận.

Đây là phiên bản đơn giản của ví dụ in. Lưu ý rằng ticket được đính kèm vào cấu trúc SubmitJobRequest (dòng 8) và dữ liệu cần in được chuyển đổi thành blob (dòng 10). Việc lấy mã nhận dạng máy in (dòng 1) trong mẫu sẽ phức tạp hơn so với cách minh hoạ ở đây.

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);
  }
});

In cuộn

Ví dụ này cho biết cách tạo phiếu in cho máy in để in liên tục (hoặc cuộn), thường được dùng để in biên nhận. Đối tượng submitJobRequest để in cuộn giống với đối tượng được hiển thị cho ví dụ submitJob().

Nếu bạn cần thay đổi giá trị mặc định cho thao tác cắt giấy, hãy sử dụng phím vendor_ticket_item. (Chế độ mặc định sẽ khác nhau tuỳ theo máy in.) Khi được đưa vào, khoá này phải là một mảng có một phần tử: một đối tượng có id là 'finishings'. Giá trị có thể là 'trim' đối với máy in cắt cuộn ở cuối quá trình in hoặc 'none' đối với máy in yêu cầu xé lệnh in.

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}
  }
};

Một số máy in không hỗ trợ tuỳ chọn "finishings". Để xác định xem máy in của bạn có hỗ trợ hay không, hãy gọi getPrinterInfo() và tìm "display_name" của "finishings/11".

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

Các giá trị trong khoá media_size của vé là dành riêng cho từng máy in. Để chọn kích thước phù hợp, hãy gọi getPrinterInfo(). GetPrinterResponse được trả về chứa một mảng kích thước nội dung nghe nhìn được hỗ trợ tại "media_size"."option". Chọn một tuỳ chọn có giá trị "is_continuous_feed" là true. Sử dụng giá trị chiều cao và chiều rộng cho vé.

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

Loại

GetPrinterInfoResponse

Thuộc tính

  • chức năng

    đối tượng không bắt buộc

    Các chức năng của máy in ở định dạng CDD. Cơ sở lưu trú này có thể bị thiếu.

  • trạng thái

    PrinterStatus

    Trạng thái của máy in.

JobStatus

Trạng thái của công việc in.

Enum

"PENDING"
Lệnh in đã nhận được trên Chrome nhưng chưa được xử lý.

"IN_PROGRESS"
Lệnh in đã được gửi để in.

"KHÔNG THÀNH CÔNG"
Công việc in bị gián đoạn do một số lỗi.

"CANCELED"
Lệnh in đã bị người dùng hoặc API huỷ.

"PRINTED"
Lệnh in đã được in mà không gặp lỗi nào.

Printer

Thuộc tính

  • description

    string

    Nội dung mô tả mà con người có thể đọc được về máy in.

  • id

    string

    Giá trị nhận dạng của máy in; đảm bảo là duy nhất trong số các máy in trên thiết bị.

  • isDefault

    boolean

    Cờ cho biết máy in có phù hợp với các quy tắc DefaultPrinterSelection hay không. Lưu ý rằng có nhiều máy in có thể bị gắn cờ.

  • tên

    string

    Tên máy in.

  • recentlyUsedRank

    số không bắt buộc

    Giá trị cho biết thời điểm gần đây nhất bạn sử dụng máy in để in từ Chrome. Giá trị càng thấp thì máy in càng được sử dụng gần đây. Giá trị tối thiểu là 0. Giá trị bị thiếu cho biết máy in không được sử dụng gần đây. Giá trị này được đảm bảo là duy nhất giữa các máy in.

  • nguồn

    PrinterSource

    Nguồn của máy in (người dùng hoặc chính sách đã định cấu hình).

  • uri

    string

    URI máy in. Tiện ích có thể sử dụng thông tin này để chọn máy in cho người dùng.

PrinterSource

Nguồn của máy in.

Enum

"USER"
Máy in do người dùng thêm.

"POLICY"
Máy in đã được thêm thông qua chính sách.

PrinterStatus

Trạng thái của máy in.

Enum

"DOOR_OPEN"
Cửa của máy in đang mở. Máy in vẫn chấp nhận các lệnh in.

"TRAY_MISSING"
Khay của máy in bị thiếu. Máy in vẫn chấp nhận các lệnh in.

"OUT_OF_INK"
Máy in đã hết mực. Máy in vẫn chấp nhận các lệnh in.

"OUT_OF_PAPER"
Máy in đã hết giấy. Máy in vẫn chấp nhận các lệnh in.

"OUTPUT_FULL"
Khay giấy ra của máy in (ví dụ: khay) đã đầy. Máy in vẫn chấp nhận các lệnh in.

"PAPER_JAM"
Máy in bị kẹt giấy. Máy in vẫn chấp nhận các lệnh in.

"GENERIC_ISSUE"
Một số vấn đề chung. Máy in vẫn chấp nhận các lệnh in.

"ĐÃ DỪNG"
Máy in đã dừng và không in nhưng vẫn chấp nhận lệnh in.

"UNREACHABLE"
Máy in không kết nối được và không nhận lệnh in.

"EXPIRED_CERTIFICATE"
Chứng chỉ SSL đã hết hạn. Máy in chấp nhận công việc nhưng không thực hiện được.

"CÓ"
Máy in có sẵn.

SubmitJobRequest

Thuộc tính

  • việc làm

    PrintJob

    Lệnh in cần gửi. Loại nội dung duy nhất được hỗ trợ là "application/pdf" và Cloud Job Ticket (Phiếu công việc trên đám mây) không được chứa các trường FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem và VendorTicketItem vì các trường này không liên quan đến tính năng in gốc. Bạn phải điền vào tất cả các trường khác.

SubmitJobResponse

Thuộc tính

  • jobId

    chuỗi không bắt buộc

    Mã của lệnh in đã tạo. Đây là giá trị nhận dạng duy nhất trong số tất cả lệnh in trên thiết bị. Nếu trạng thái không OK, JobId sẽ là rỗng.

  • trạng thái

    SubmitJobStatus

    Trạng thái của yêu cầu.

SubmitJobStatus

Trạng thái của yêu cầu submitJob.

Enum

"OK"
Yêu cầu về lệnh in đã gửi đã được chấp nhận.

"USER_REJECTED"
Người dùng từ chối yêu cầu công việc in đã gửi.

Thuộc tính

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Số lần tối đa có thể gọi getPrinterInfo mỗi phút.

Giá trị

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Số lần tối đa có thể gọi submitJob mỗi phút.

Giá trị

40

Phương thức

cancelJob()

Promise
chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

Huỷ công việc đã gửi trước đó.

Thông số

  • jobId

    string

    Mã của lệnh in cần huỷ. Đây phải là mã nhận dạng giống với mã nhận được trong SubmitJobResponse.

  • số gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    () => void

Giá trị trả về

  • Lời hứa<vô hiệu>

    Chrome 100 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getPrinterInfo()

Lời hứa 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

Trả về trạng thái và chức năng của máy in ở định dạng CDD. Lệnh gọi này sẽ không thực hiện được kèm theo lỗi thời gian chạy nếu không có máy in nào có mã nhận dạng nhất định được cài đặt.

Thông số

Giá trị trả về

  • Chrome 100 trở lên

    Lời hứa chỉ được hỗ trợ cho Tệp kê khai V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

getPrinters()

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

Trả về danh sách máy in có sẵn trên thiết bị. Danh sách này bao gồm cả máy in được thêm theo cách thủ công, máy in doanh nghiệp và máy in được phát hiện.

Thông số

  • số gọi lại

    hàm không bắt buộc

    Tham số callback có dạng như sau: 

    (printers: Printer[]) => void

Giá trị trả về

  • Cam kết<Printer[]>

    Chrome 100 trở lên

    Lời hứa chỉ được hỗ trợ cho Tệp kê khai V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

submitJob()

Lời hứa 
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

Gửi công việc để in. Nếu tiện ích này không có trong chính sách PrintingAPIExtensionsAllowlist, thì người dùng sẽ được nhắc chấp nhận lệnh in. Trước Chrome 120, hàm này không trả về một lời hứa.

Thông số

Giá trị trả về

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100 trở lên

    Lời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.

Sự kiện

onJobStatusChanged

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

Sự kiện được kích hoạt khi trạng thái của công việc thay đổi. Lệnh này chỉ được kích hoạt cho các công việc do tiện ích này tạo ra.

Thông số

  • lệnh gọi lại

    hàm

    Tham số callback sẽ có dạng như sau: 

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