Trang này được dịch bởi Cloud Translation API.

chrome.printing

Mô tả

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

Quyền

printing

Phạm vi cung cấp

Chrome 81 trở lên Chỉ dành cho ChromeOS

Tệp kê khai

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. Đoạn 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 "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 được kết nối trực tiếp với máy in, các trạng thái này có thể chuyển đổi quá nhanh nên nút huỷ không xuất hiện đủ lâu để có thể được gọi. Đây là ví dụ in đơn giản hoá rất nhiều.

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 đòi hỏi phải có mã nhận dạng máy in. Mã nhận dạng này được truy xuất bằng cách gọi getPrinters(). Ví dụ này ghi nhật ký 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 kiện.

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 hiện có, bạn có thể truy xuất các chức năng đó cho một máy in cụ thể bằng cách sử dụng getPrinterInfo().
Một 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 một 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 việc 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. Xin 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 một blob (dòng 10). Việc lấy mã nhận dạng của máy in (dòng 1) phức tạp hơn trong mẫu so với những gì được 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 minh hoạ cách tạo một vé máy in để in liên tục (hoặc in 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 minh hoạ trong ví dụ về submitJob().

Nếu bạn cần thay đổi giá trị mặc định cho việc cắt giấy, hãy sử dụng phím vendor_ticket_item. (Giá trị mặc định sẽ khác nhau tuỳ theo từng máy in.) Khi được đưa vào, khoá này cần phải là một mảng có một thành phần: 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 giấy ở 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ợ lựa chọn "finishings". Để xác định xem máy in của bạn có hỗ trợ tính năng này hay không, hãy gọi đến số 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é 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 phương tiện được hỗ trợ tại "media_size"."option". Chọn một lựa 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 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.
trạng thái

PrinterStatus

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

JobStatus

Trạng thái của lệnh in.

Enum

"ĐANG CHỜ XỬ LÝ"
Lệnh in đã được nhận trên Chrome nhưng chưa được xử lý.

"IN_PROGRESS"
Đã gửi lệnh in để in.

"THẤT BẠI"
Lệnh in bị gián đoạn do xảy ra lỗi.

"ĐÃ HUỶ"
Người dùng đã huỷ lệnh in hoặc huỷ thông qua API.

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

Printer

Thuộc tính

mô tả

chuỗi

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

chuỗi

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

boolean

Cờ cho biết liệu máy in có phù hợp với các quy tắc DefaultPrinterSelection hay không. Xin lưu ý rằng có thể một số máy in sẽ bị gắn cờ.
tên

chuỗi

Tên của máy in.
recentlyUsedRank

number không bắt buộc

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

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 của máy in. Các 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

"NGƯỜI DÙNG"
Người dùng đã thêm máy in.

"CHÍNH SÁCH"
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 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 giấy. 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 đã đầ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 lệnh in nhưng không thực hiện được.

"AVAILABLE"
Máy in đang hoạt động.

SubmitJobRequest

Thuộc tính

công việc

PrintJob

Lệnh in cần gửi. Các loại nội dung được hỗ trợ là "application/pdf" và "image/png". Cloud Job Ticket không được bao gồm các trường FitToPageTicketItem, PageRangeTicketItem và ReverseOrderTicketItem vì chúng không liên quan đến tính năng in gốc. VendorTicketItem là không bắt buộc. Bạn phải cung cấp 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ả các lệnh in trên thiết bị. Nếu trạng thái không phải là OK, thì jobId sẽ là 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 gửi lệnh in đã được chấp nhận.

"USER_REJECTED"
Yêu cầu gửi lệnh in bị người dùng từ chối.

Thuộc tính

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

Giá trị

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

Giá trị

Phương thức

cancelJob()

Promise

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

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

Thông số

jobId

chuỗi

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

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

Các promise 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.

getJobStatus()

Promise Chrome 135 trở lên

chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

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

Thông số

jobId

chuỗi
callback

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

Tham số callback có dạng như sau:
```
(status: JobStatus) => void
```
- trạng thái
  
  JobStatus

Giá trị trả về

Promise<JobStatus>

Các promise 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()

Promise

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

Trả về trạng thái và các 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ố

printerId

chuỗi
callback

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

Tham số callback có dạng như sau:
```
(response: GetPrinterInfoResponse) => void
```
- phản hồi
  
  GetPrinterInfoResponse

Giá trị trả về

Promise<GetPrinterInfoResponse>

Chrome 100 trở lên

Các promise 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.

getPrinters()

Promise

chrome.printing.getPrinters(
  callback?: function,
): Promise<Printer[]>

Trả về danh sách máy in có sẵn trên thiết bị. Trong đó 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ố

callback

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

Tham số callback có dạng như sau:
```
(printers: Printer[]) => void
```
- máy in
  
  Máy in[]

Giá trị trả về

Promise<Printer[]>

Chrome 100 trở lên

Các promise 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.

submitJob()

Promise

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

Gửi lệnh 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 promise.

Thông số

request

SubmitJobRequest
callback

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

Tham số callback có dạng như sau:
```
(response: SubmitJobResponse) => void
```
- phản hồi
  
  SubmitJobResponse

Giá trị trả về

Promise<SubmitJobResponse>

Chrome 100 trở lên

Các promise 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. Sự kiện này chỉ được kích hoạt cho những công việc do tiện ích này tạo.

Thông số

callback

hàm

Tham số callback có dạng như sau:
```
(jobId: string, status: JobStatus) => void
```
- jobId
  
  chuỗi
- trạng thái
  
  JobStatus

chrome.printing Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mô tả

Quyền

Phạm vi cung cấp

Tệp kê khai

Ví dụ

cancelJob()

getPrinters() and getPrinterInfo()

submitJob()

In cuộn

Loại

GetPrinterInfoResponse

Thuộc tính

JobStatus

Enum

Printer

Thuộc tính

PrinterSource

Enum

PrinterStatus

Enum

SubmitJobRequest

Thuộc tính

SubmitJobResponse

Thuộc tính

SubmitJobStatus

Enum

Thuộc tính

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Giá trị

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Giá trị

Phương thức

cancelJob()

Thông số

Giá trị trả về

getJobStatus()

Thông số

Giá trị trả về

getPrinterInfo()

Thông số

Giá trị trả về

getPrinters()

Thông số

Giá trị trả về

submitJob()

Thông số

Giá trị trả về

Sự kiện

onJobStatusChanged

Thông số

chrome.printing