事件订阅

任务进度、打印机状态、授权结果等实时通知的订阅方式与事件字段。

需要长连接的实时通知都通过事件推送，不用轮询。所有 on* 方法都返回 取消订阅函数，close() 会一并清理。

const off = client.onJobStatus((event) => console.log(event.jobId, event.status));
// 不再需要时：
off();

事件列表

方法	事件	说明
`onJobStatus(handler)`	`job.status`	本站点任务的状态流转
`onDuplicateSuppressed(handler)`	`job.duplicateSuppressed`	幂等键抑制了重复提交
`onPrinterStatusChanged(handler)`	`printer.statusChanged`	打印机状态变化（带递增 `revision`）
`onAuthDecisionChanged(handler)`	`auth.decisionChanged`	用户在电脑上批准 / 拒绝了配对
`onHealthAlert(handler)`	`health.alert`	打印机健康告警
`onServiceMigrated(handler)`	`system.serviceMigrated`	服务端口变更
`onScanStatus(handler)`	`scan.status`	扫描作业状态（含等待确认与终态）
`onScanPageReady(handler)`	`scan.pageReady`	一页成品可下载（只有元数据）
`onScannerListChanged(handler)`	`scanner.listChanged`	扫描仪列表变化

任务状态

created → validating → rendering → ready → queued → spooling → printing → completed
                                                                        ├─► failed
                                                                        └─► canceled

终态是 completed / failed / canceled 三种，可用 @printlink/types 导出的 isTerminalJobStatus() 判断。

client.onJobStatus((event) => {
  console.log(event.jobId, event.status, event.progress);
  if (event.warnings?.length) showWarnings(event.warnings);
  if (isTerminalJobStatus(event.status)) cleanup(event.jobId);
});

事件里带 queueId、progress、warnings、error。用 printAndWait(params, { onStatus }) 可以在等待终态的同时收这些中间状态—— 它的内部实现就是「提交 + 听这个事件」。

看任务为什么失败，不要只看事件

事件告诉你终态和错误码。任务详情（getJob）里还有提交参数、实际生效参数、降级警告与完整状态时间线，向用户解释「为什么和我选的不一样」时用那份数据。

连接状态

onConnectionStateChange 订阅的是快照而不是增量事件，适合直接驱动界面上的「连接中 / 待授权 / 就绪 / 断开」指示：

const off = client.onConnectionStateChange((state) => {
  // state: { transport, authorization, ready }
  setStatus(state.ready ? 'ready' : state.authorization);
});

端口变更

用户在控制台改了端口后，已连接页面会收到 system.serviceMigrated。收到后应 停止发起新请求，并引导用户用新地址重新进入：

client.onServiceMigrated((event) => {
  showReconnectPrompt(event.endpoint);
});

不要在旧地址上静默重试。

事件列表

任务状态

连接状态

端口变更

相关页面

API 总览

打印

打印机与配置档

本页目录