chrome.printing

重要提示：此 API 仅适用于 ChromeOS。

说明

使用 chrome.printing API 将打印作业发送到 Chromebook 上安装的打印机。

权限

printing

可用性

Chrome 81 及更高版本 仅限 ChromeOS

您需要在扩展程序清单中声明 "printing" 权限，才能使用所有 chrome.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"
    }
  },
  ...
]

注意 ：从 Chrome 124 开始，vendor_ticket_item 允许使用打印机的 vendor_capabilities 中的所有项。例如，getPrinterInfo() 返回的任何值都是有效的。以前，仅支持 finishings 键。

票券的 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

  字符串

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

• isDefault

  布尔值

  用于指示打印机是否符合 DefaultPrinterSelection 规则的标志。请注意，系统可能会标记多台打印机。

• name

  字符串

  打印机的名称。

• 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 证书已过期。打印机接受作业，但作业会失败。

“可用”
打印机可用。

SubmitJobRequest

属性

• 作业

  PrintJob

  要提交的打印作业。唯一支持的内容类型是“application/pdf”，并且 Cloud 作业工单不应包含 FitToPageTicketItem、PageRangeTicketItem、ReverseOrderTicketItem 和 VendorTicketItem 字段，因为它们与原生打印无关。必须填写所有其他字段。

SubmitJobResponse

属性

• jobId

  字符串（选填）

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

• 状态

  SubmitJobStatus

  请求的状态。

SubmitJobStatus

submitJob 请求的状态。

枚举

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

"USER_REJECTED"
用户拒绝了发送的打印作业请求。

属性

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

值

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

值

40

方法

cancelJob()

prometido

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

取消之前提交的作业。

参数

• jobId

  字符串

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

• callback

  函数（可选）

  callback 参数如下所示：

  () => void

返回

• Promise<void>

  Chrome 100+

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getJobStatus()

prometido 待处理

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

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

参数

• jobId

  字符串

• callback

  函数（可选）

  callback 参数如下所示：

  (status: JobStatus) => void

  • 状态

    JobStatus

返回

• Promise<JobStatus>

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getPrinterInfo()

prometido

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

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

参数

• printerId

  字符串

• callback

  函数（可选）

  callback 参数如下所示：

  (response: GetPrinterInfoResponse) => void

  • Response

    GetPrinterInfoResponse

返回

• Promise<GetPrinterInfoResponse>

  Chrome 100+

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

getPrinters()

prometido

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

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

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (printers: Printer[]) => void

  • 打印机

    打印机[]

返回

• Promise<Printer[]>

  Chrome 100+

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

submitJob()

prometido

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

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

参数

• request

  SubmitJobRequest

• callback

  函数（可选）

  callback 参数如下所示：

  (response: SubmitJobResponse) => void

  • Response

    SubmitJobResponse

返回

• Promise<SubmitJobResponse>

  Chrome 100+

  清单 V3 及更高版本支持 Promise，但为了实现向后兼容性，我们提供了回调。您不能在同一函数调用中同时使用这两种方法。promise 的解析结果与传递给回调的类型相同。

事件

onJobStatusChanged

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

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

参数

• callback

  函数

  callback 参数如下所示：

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

  • jobId

    字符串

  • 状态

    JobStatus