chrome.printing

說明

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

權限

printing

可用性

Chrome 81 以上版本 僅適用於 ChromeOS

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

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

範例

下列範例示範輸出命名空間中每個方法的使用方法。這個程式碼是從擴充功能 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，範例中的印表機 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

    物件 optional

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

  • 狀態

    PrinterStatus

    印表機狀態。

JobStatus

列印工作的狀態。

列舉

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

"IN_PROGRESS"
已傳送列印工作進行列印。

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

"已取消"
使用者或透過 API 取消列印工作。

"PRINTED"
列印工作已順利列印，沒有任何錯誤。

Printer

屬性

  • 說明

    字串

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

  • id

    字串

    印表機的 ID；可確保裝置上各印表機的不重複名稱。

  • isDefault

    布林值

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

  • 名稱

    字串

    印表機名稱。

  • recentlyUsedRank

    編號 選填

    這個值代表使用者最近使用 Chrome 進行列印的時間。該值越低，表示使用印表機越近。最小值為 0。找不到值表示最近並未使用印表機。印表機中的這個值絕對不能重複。

  • 來源

    PrinterSource

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

  • uri

    字串

    印表機 URI。擴充功能可透過這個 ID 為使用者選擇印表機。

PrinterSource

印表機來源。

列舉

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

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

PrinterStatus

印表機狀態。

列舉

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

"TRAY_MISSING"
找不到印表機匣。印表機仍可接受列印工作。

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

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

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

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

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

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

「無法連接」
無法連上印表機，因此無法接受列印工作。

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

"AVAILABLE"
可以使用印表機。

SubmitJobRequest

屬性

  • 工作

    PrintJob

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

SubmitJobResponse

屬性

  • jobId

    string optional

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

  • 要求的狀態。

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

傳回

  • 承諾<void>

    Chrome 100 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getPrinterInfo()

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

以 CDD 格式傳回印表機的狀態和功能。如未安裝具有指定 ID 的印表機，這個呼叫會失敗並發生執行階段錯誤。

參數

傳回

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 100 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getPrinters()

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

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

參數

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (printers: Printer[]) => void

傳回

  • Promise<Printer[]>

    Chrome 100 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

submitJob()

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

提交列印工作。如果 PrintingAPIExtensionsAllowlist 政策中沒有列出這項擴充功能，系統會提示使用者接受列印工作。 在 Chrome 120 以下版本中，這項功能未傳回承諾。

參數

傳回

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onJobStatusChanged

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

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

參數

  • 回呼

    函式

    callback 參數如下所示： 

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