chrome.printing

重要事項：這個 API僅適用於 ChromeOS。

說明

使用 chrome.printing API 將列印工作傳送至安裝在 Chromebook 上的印表機。

權限

printing

可用性

Chrome 81 以上版本 僅適用於 ChromeOS

資訊清單

所有 chrome.printing 方法和事件都需要在擴充功能資訊清單中宣告 "printing" 權限。例如：

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

範例

以下範例示範如何使用列印命名空間中的每個方法。這個程式碼是從 extensions-samples GitHub 存放區的 api-samples/printing 複製而來，或以該程式碼為基礎。

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

這類函式僅使用單一範例，因為取得印表機資訊需要印表機 ID (可透過呼叫 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() 方法需要三個項目。

• ticket 結構定義了要使用的印表機功能。如果使用者需要從可用功能中選取，您可以使用 getPrinterInfo() 擷取特定印表機的可用功能。
• SubmitJobRequest 結構，指定要使用的印表機，以及要列印的檔案或日期。這個結構包含 ticket 結構的參照。
• 要列印的檔案或資料 Blob。

呼叫 submitJob() 會觸發對話方塊，要求使用者確認列印。使用 PrintingAPIExtensionsAllowlist 略過確認程序。

這是簡化版的列印範例。請注意，ticket 會附加至 SubmitJobRequest 結構 (第 8 行)，且要列印的資料會轉換為 blob (第 10 行)。在範例中，取得印表機 ID (第 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 鍵。(預設選項會因印表機而異)。加入此鍵時，這個鍵必須是包含一個成員的陣列：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()，然後找出 "finishings/11" 的 "display_name"。

"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" 值為 true 的選項。請使用票券的高度和寬度值。

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

類型

GetPrinterInfoResponse

屬性

• capabilities

  物件 選填

  CDD 格式的印表機功能。可能缺少屬性。

• 狀態

  PrinterStatus

  印表機的狀態。

JobStatus

列印工作的狀態。

列舉

"PENDING"
表示系統已在 Chrome 端接收列印工作，但尚未處理。

"IN_PROGRESS"
已傳送列印工作。

"FAILED"
由於某些錯誤導致列印工作中斷。

「CANCELED」
使用者或 API 已取消列印工作。

「PRINTED」
列印工作已順利完成，且沒有任何錯誤。

Printer

屬性

• 說明

  字串

  使用者可理解的印表機說明。

• id

  字串

  印表機的 ID，保證在裝置上不會重複。

• isDefault

  布林值

  標記，顯示印表機是否符合 DefaultPrinterSelection 規則。請注意，系統可能會標記多部印表機。

• 名稱

  字串

  印表機名稱。

• recentlyUsedRank

  編號 選填

  這個值代表使用者最近使用 Chrome 進行列印的時間。值越低，表示印表機越新。最小值為 0。缺少值表示最近沒有使用印表機。這個值在所有印表機中不會重複。

• 來源

  PrinterSource

  印表機來源 (使用者或已設定的政策)。

• uri

  字串

  印表機 URI。擴充功能可使用這項資訊，為使用者選擇印表機。

PrinterSource

印表機來源。

列舉

「USER」
使用者已新增印表機。

"POLICY"
已透過政策新增印表機。

PrinterStatus

印表機狀態。

列舉

"DOOR_OPEN"
印表機的門已打開。印表機仍可接受列印工作。

"TRAY_MISSING"
印表機缺少紙匣。印表機仍可接受列印工作。

"OUT_OF_INK"
印表機不再墨水。印表機仍會接受列印工作。

"OUT_OF_PAPER"
印表機不在紙張上。印表機仍可接受列印工作。

"OUTPUT_FULL"
印表機的輸出區域 (例如匣) 已滿。印表機仍可接受列印工作。

"PAPER_JAM"
印表機有紙卡，印表機仍可接受列印工作。

"GENERIC_ISSUE"
某些一般性問題。印表機仍可接受列印工作。

「STOPPED」
印表機已停止運作，不會列印，但仍會接受列印工作。

「UNREACHABLE」
無法連上印表機，且印表機不會接受列印工作。

"EXPIRED_CERTIFICATE"
SSL 憑證已過期。印表機接受工作，但失敗。

「AVAILABLE」
印表機可供使用。

SubmitJobRequest

屬性

• 工作

  PrintJob

  要提交的列印工作。唯一支援的內容類型為「application/pdf」，且 Cloud Job Ticket 不應包含 FitToPageTicketItem、PageRangeTicketItem、ReverseOrderTicketItem 和 VendorTicketItem 欄位，因為這些欄位與原生列印無關。但其他欄位都必須填寫。

SubmitJobResponse

屬性

• jobId

  string 選填

  已建立的列印工作的 ID。這是裝置上所有列印工作的唯一識別碼。如果狀態不是「確定」，jobId 就會是 null。

• 狀態

  SubmitJobStatus

  要求的狀態。

SubmitJobStatus

submitJob 要求的狀態。

列舉

"OK"
已接受已傳送的列印工作要求。

"USER_REJECTED"
使用者已拒絕傳送的列印工作要求。

屬性

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

每分鐘可呼叫 getPrinterInfo 的次數上限。

值

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

每分鐘可呼叫 submitJob 的次數上限。

值

40

方法

cancelJob()

Promise

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

取消先前提交的工作。

參數

• jobId

  字串

  要取消的列印工作 ID。這個 ID 應與 SubmitJobResponse 中收到的 ID 相同。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• Promise<void>

  Chrome 100 以上版本

  Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。

getPrinterInfo()

Promise

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

以 CDD 格式傳回印表機的狀態和功能。如果沒有安裝任何具有指定 ID 的印表機，這個呼叫就會失敗，並顯示執行階段錯誤。

參數

• printerId

  字串

• 回呼

  函式 選用

  callback 參數如下所示：

  (response: GetPrinterInfoResponse) => void

  • 回應

    GetPrinterInfoResponse

傳回

• Promise<GetPrinterInfoResponse>

  Chrome 100 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

getPrinters()

Promise

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

傳回裝置上可用的印表機清單。包括手動新增、企業和偵測到的印表機。

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (printers: Printer[]) => void

  • 印表機

    Printer[]

傳回

• Promise<Printer[]>

  Chrome 100 以上版本

  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

submitJob()

Promise

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

提交列印工作。如果擴充功能未列在 PrintingAPIExtensionsAllowlist 政策中，系統會提示使用者接受列印工作。在 Chrome 120 之前，這個函式不會傳回承諾。

參數

• 申請。

  SubmitJobRequest

• 回呼

  函式 選用

  callback 參數如下所示：

  (response: SubmitJobResponse) => void

  • 回應

    SubmitJobResponse

傳回

• Promise<SubmitJobResponse>

  Chrome 100+

  承諾僅支援資訊清單 V3 以上版本，其他平台則需要使用回呼。

活動

onJobStatusChanged

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

工作狀態變更時會觸發事件。這項事件只會針對此擴充功能建立的工作觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

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

  • jobId

    字串

  • 狀態

    JobStatus