此页面由 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，而打印机 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”
打印作业已发送以供打印。

“失败”
打印作业因出现错误而中断。

“CANCELED”
打印作业已被用户或通过 API 取消。

"PRINTED"
打印作业已打印，未出现任何错误。

Printer

属性

说明

字符串

打印机的直观易懂的说明。
id

字符串

打印机的标识符；保证在设备上的打印机中是唯一的。
isDefault

布尔值

用于显示打印机是否符合 DefaultPrinterSelection 规则的标志。请注意，可能会有多个打印机被标记。
name

字符串

打印机的名称。
recentlyUsedRank

number 可选

显示最近一次使用打印机通过 Chrome 进行打印的时间。值越低，表示打印机最近一次使用的时间越近。最小值为 0。如果缺少值，则表示打印机最近未使用过。此值保证在打印机之间是唯一的。
来源

PrinterSource

打印机的来源（用户或政策配置）。
uri

字符串

打印机 URI。扩展程序可以使用此属性为用户选择打印机。

PrinterSource

打印机的来源。

枚举

“USER”
打印机由用户添加。

“政策”
打印机是通过政策添加的。

PrinterStatus

打印机的状态。

枚举

"DOOR_OPEN"
打印机的机盖未关好。打印机仍接受打印作业。

“TRAY_MISSING”
打印机的托盘缺失。打印机仍接受打印作业。

“OUT_OF_INK”
打印机墨尽。打印机仍接受打印作业。

“OUT_OF_PAPER”
打印机缺纸。打印机仍接受打印作业。

“OUTPUT_FULL”
打印机的出纸区域（例如出纸盘）已满。打印机仍接受打印作业。

“PAPER_JAM”
打印机卡纸。打印机仍接受打印作业。

“GENERIC_ISSUE”
某些一般性问题。打印机仍接受打印作业。

“已停止”
打印机已停止，无法打印，但仍可接受打印作业。

“UNREACHABLE”
打印机无法连接，且不接受打印作业。

“EXPIRED_CERTIFICATE”
SSL 证书已过期。打印机接受作业，但作业失败。

“AVAILABLE”
打印机可用。

SubmitJobRequest

属性

作业

PrintJob

要提交的打印作业。支持的内容类型为“application/pdf”和“image/png”。云作业票证不应包含 FitToPageTicketItem、PageRangeTicketItem 和 ReverseOrderTicketItem 字段，因为这些字段与本机打印无关。VendorTicketItem 为可选项。必须提供所有其他字段。

SubmitJobResponse

属性

jobId

字符串可选

已创建的打印作业的 ID。这是设备上所有打印作业的唯一标识符。如果状态不是“OK”，jobId 将为 null。
状态

SubmitJobStatus

请求的状态。

SubmitJobStatus

submitJob 请求的状态。

枚举

“确定”
已接受发送的打印作业请求。

“USER_REJECTED”
发送的打印作业请求被用户拒绝。

属性

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

每分钟可调用 getPrinterInfo 的次数上限。

值

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

每分钟可调用 submitJob 的次数上限。

值

方法

cancelJob()

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

取消之前提交的作业。

参数

jobId

字符串

要取消的打印作业的 ID。此值应与在 SubmitJobResponse 中收到的 ID 相同。

Promise<void>

Chrome 100 及更高版本

getJobStatus()

Chrome 135 及更高版本

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

返回打印作业的状态。如果具有指定 jobId 的打印作业不存在，此调用将失败并显示运行时错误。jobId：要返回状态的打印作业的 ID。此值应与在 SubmitJobResponse 中收到的 ID 相同。

参数

jobId

字符串

Promise<JobStatus>

getPrinterInfo()

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

以 CDD 格式返回打印机的状态和功能。如果没有安装具有指定 ID 的打印机，此调用将失败并显示运行时错误。

参数

printerId

字符串

Promise<GetPrinterInfoResponse>

Chrome 100 及更高版本

getPrinters()

chrome.printing.getPrinters(): Promise<Printer[]>

返回设备上可用打印机的列表。包括手动添加的打印机、企业打印机和发现的打印机。

Promise<Printer[]>

Chrome 100 及更高版本

submitJob()

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

提交打印作业。如果扩展程序未列在 PrintingAPIExtensionsAllowlist 政策中，系统会提示用户接受打印作业。在 Chrome 120 之前，此函数不返回 promise。

参数

request

SubmitJobRequest

Promise<SubmitJobResponse>

Chrome 100 及更高版本

事件

onJobStatusChanged

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

当作业的状态发生变化时触发的事件。仅针对此扩展程序创建的作业触发此事件。

参数

callback

函数

callback 参数如下所示：
```
(jobId: string, status: JobStatus) => void
```
- jobId
  
  字符串
- 状态
  
  JobStatus

chrome.printing 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

权限

可用性

示例

cancelJob()

getPrinters() and getPrinterInfo()

submitJob()

卷筒纸打印

类型

GetPrinterInfoResponse

属性

JobStatus

枚举

Printer

属性

PrinterSource

枚举

PrinterStatus

枚举

SubmitJobRequest

属性

SubmitJobResponse

属性

SubmitJobStatus

枚举

属性

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

值

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

值

方法

cancelJob()

参数

返回

getJobStatus()

参数

返回

getPrinterInfo()

参数

返回

getPrinters()

返回

submitJob()

参数

返回

事件

onJobStatusChanged

参数

chrome.printing