chrome.printing

說明

權限

可用性

所有 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
  },
  ...
  ]
}

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

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

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

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

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