chrome.printing

说明

使用 chrome.printing API 将打印任务发送到安装在 Chromebook 上的打印机。

权限

printing

可用性

Chrome 81 及更高版本 仅限 ChromeOS

所有 chrome.printing 方法和事件都要求在扩展程序清单中声明 "printing" 权限。例如:

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

示例

以下示例演示了如何使用 print 命名空间中的每种方法。此代码复制自 extensions-samples GitHub 代码库中的 api-samples/printing,或以其为基础。

cancelJob()

此示例使用 onJobStatusChanged 处理程序隐藏“取消”按钮。jobStatusPENDINGIN_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 格式)。属性可能缺失。

  • 状态

    打印机的状态。

JobStatus

打印作业的状态。

枚举

"PENDING"
Chrome 端收到了打印作业,但尚未处理。

"IN_PROGRESS"
发送打印作业以进行打印。

"FAILED"
打印作业因出现错误而中断。

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

"PRINTED"
打印作业已打印,没有任何错误。

Printer

属性

  • 说明

    字符串

    直观易懂的打印机说明。

  • id

    字符串

    打印机的标识符;在设备上的打印机之间会保证其值是唯一的。

  • isDefault

    布尔值

    显示打印机是否符合 DefaultPrinterSelection 规则的标记。请注意,系统可能会标记多台打印机。

  • name

    字符串

    打印机的名称。

  • recentlyUsedRank

    编号(选填

    显示打印机最近一次通过 Chrome 打印的时间的值。该值越小,表示打印机越新。最小值为 0。缺少值表示该打印机最近未使用过。此值保证在各个打印机之间是唯一的。

  • 来源

    打印机的来源(已配置用户或策略)。

  • 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

属性

  • 作业

    要提交的打印作业。唯一支持的内容类型是“application/pdf”,Cloud Job Ticket 不应包含 FitToPageTicketItemPageRangeTicketItemReverseOrderTicketItemVendorTicketItem 字段,因为它们与本机打印无关。所有其他字段都必须填写。

SubmitJobResponse

属性

  • jobId

    字符串(可选)

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

  • 请求的状态。

SubmitJobStatus

submitJob 请求的状态。

枚举

“确定”
已接受发送的打印任务请求。

"USER_REJECTED"
发送的打印任务请求被用户拒绝。

属性

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

40

方法

cancelJob()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

取消之前提交的作业。

参数

  • jobId

    字符串

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

  • callback

    函数(可选)

    callback 参数如下所示:

    () => void

返回

  • 承诺<void>

    Chrome 浏览器 100 及以上版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getPrinterInfo()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

参数

返回

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 浏览器 100 及以上版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

getPrinters()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.printing.getPrinters(
  callback?: function,
)

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

参数

  • callback

    函数(可选)

    callback 参数如下所示:

    (printers: Printer[]) => void

返回

  • Promise<打印机 []>

    Chrome 浏览器 100 及以上版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

submitJob()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

参数

返回

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 浏览器 100 及以上版本

    Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。

事件

onJobStatusChanged

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

更改作业状态时触发的事件。仅对此扩展程序创建的作业触发此事件。

参数

  • callback

    函数

    callback 参数如下所示:

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