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ất cả các 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ụ đơn giản hoá rất nhiều về việc in.

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ụ về hoạt động 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ụ về hoạt động 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 của máy in (dòng 1) trong mẫu phức tạp hơn so với nội dung hiển thị ở đâ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. (Mặc định thay đổi tuỳ theo máy in.) Để thay đổi giá trị, hãy cung cấp một mảng có một thành phần: một đối tượng có id là 'finishings'. Giá trị này có thể là 'trim' đối với máy in cắt cuộn giấy khi in xong hoặc 'none' đối với máy in yêu cầu phải xé bỏ 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 các 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 các giá trị chiều cao và chiều rộng của hình ảnh đó 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ó thể thiếu thuộc tính này.

  • 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

"ĐANG CHỜ"
Chrome đã nhận được công việc in nhưng chưa xử lý.

"IN_PROGRESS"
Công việc 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" (ĐÃ HUỶ)
Người dùng hoặc API đã huỷ lệnh in.

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

Printer

Thuộc tính

  • mô tả

    chuỗi

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

  • id

    chuỗi

    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. Xin lưu ý rằng một số máy in có thể bị gắn cờ.

  • tên

    chuỗi

    Tên của 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

    chuỗi

    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"
Máy in bị thiếu khay. 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"
Không thể kết nối với máy in và máy in không chấp 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

  • công việc

    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 (Vé 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. Tất cả các trường khác phải có.

SubmitJobResponse

Thuộc tính

  • jobId

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

    Mã của công việc in đã tạo. Đây là giá trị nhận dạng duy nhất trong số tất cả các công việc in trên thiết bị. Nếu trạng thái không phải là OK, thì jobId sẽ có giá trị 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 công việc 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

    chuỗi

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

  • lệnh 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ề

  • Promise<void>

    Chrome 100 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getJobStatus()

Lời hứa Đang chờ xử lý
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

Trả về trạng thái của công việc in. Lệnh gọi này sẽ không thành công và báo lỗi thời gian chạy nếu công việc in có jobId đã cho không tồn tại. jobId: Mã nhận dạng của công việc in để trả về trạng thái. Mã này phải giống với mã nhận được trong SubmitJobResponse.

Thông số

  • jobId

    chuỗi

  • lệnh gọi lại

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

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

    (status: JobStatus) => void

Giá trị trả về

  • Promise<JobStatus>

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

getPrinterInfo()

Promise 
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ành công 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 đã cho được cài đặt.

Thông số

Giá trị trả về

  • Chrome 100 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến 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ố

  • lệnh 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ề

  • Promise<Printer[]>

    Chrome 100 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến lệnh gọi lại.

submitJob()

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

Gửi công việc để in. Nếu tiện ích 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ề

  • Chrome 100 trở lên

    Lời hứa được hỗ trợ trong Tệp kê khai V3 trở lên, nhưng lệnh gọi lại được cung cấp để đảm bảo khả năng tương thích ngược. Bạn không thể sử dụng cả hai trong cùng một lệnh gọi hàm. Lời hứa sẽ phân giải bằng cùng một loại được truyền đến 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 có dạng như sau: 

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