本頁面由 Cloud Translation API 翻譯而成。

chrome.printing

說明

使用 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 的次數上限。

值

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

值

方法

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