文档开发者中心
我的
|

ArkTS

调用打印服务打印条码

调用打印服务打印条码,部分型号便携打印机,打印多张时只出第一张,打印任务队列没有回调失败,怎么监听打印完成状态?
点赞
1
收藏
回复
21
分享
举报
浏览64 发布于3天前广西
全部评论
最多点赞
最新发布
最早发布

@ohos.print (打印)模块的on(type: 'printerChange', callback: PrinterChangeCallback): void可注册打印机变动事件回调。看看回调返回什么:

参数名 类型 说明
event PrinterEvent 表示打印机事件。
printerInformation PrinterInformation 表示打印机信息。
19楼回复于昨天03:25 来自北京

这个问题需要先区分两个概念:打印任务提交成功,不代表打印机已经完成打印;打印服务任务结束,也不一定代表纸张已经实际输出。

HarmonyOS 调用打印服务打印条码时,如果部分便携打印机只打印第一张,后续任务没有失败回调,建议从打印任务生命周期、打印服务状态和打印机设备状态三个层面排查。

1. 首先明确打印状态回调的边界

打印流程通常可以分为:

收起
自动换行
深色代码主题
复制
应用提交打印任务
      |
      v
打印服务接收任务
      |
      v
打印数据生成
      |
      v
打印服务发送数据
      |
      v
打印机接收数据
      |
      v
打印机执行打印
      |
      v
纸张实际输出

这里有一个关键问题:

打印服务返回成功,通常只能说明当前阶段的操作成功,不能直接证明打印机已经完成物理打印。

尤其是蓝牙便携打印机,可能存在数据发送成功,但打印机内部缓冲区尚未处理完的情况。

2. 如何监听打印任务状态?

首先检查当前使用的打印 API 是否提供任务状态监听能力。

如果使用 HarmonyOS 标准打印框架,需要重点关注:

  • 打印任务创建是否成功。
  • 打印任务是否进入执行状态。
  • 打印任务是否完成或取消。
  • 打印任务是否发生异常。
  • 打印服务是否提供任务状态查询接口。

需要注意,不能将 Promise 成功、数据发送成功和打印完成混为一谈。

如果使用的是系统打印服务,应用侧能够获取的状态还受到具体打印 API 和设备驱动实现的限制。并非所有打印机都能向应用反馈真实的纸张输出状态。

3. 为什么多张只打印第一张?

便携式打印机出现这种情况,常见原因包括:

可能原因

具体表现

打印机缓冲区溢出

第一张正常,后续数据丢失

任务提交过快

多个任务连续提交,设备处理不过来

打印任务没有串行化

多个任务同时发送,数据交错

打印机协议限制

需要等待打印机返回就绪状态

蓝牙数据传输不完整

数据包发送成功,但设备没有完整接收

纸张或走纸状态异常

第一张打印后设备进入等待状态

建议先做一个简单实验:

连续打印 3 张条码,每张之间增加 500ms、1000ms、2000ms 延迟。

如果增加间隔后恢复正常,说明问题可能与打印机缓冲区、数据发送节奏或任务串行化有关,但还不能据此认定具体原因。

4. 推荐的打印任务管理方案

如果业务需要连续打印多张条码,建议不要直接循环调用打印接口,而是建立一个串行任务队列。

例如:

收起
自动换行
深色代码主题
复制
interface PrintTask {
  id: number;
  content: string;
}

class PrintManager {
  private tasks: Array<PrintTask> = [];
  private printing: boolean = false;

  addTask(task: PrintTask): void {
    this.tasks.push(task);
    this.processQueue();
  }

  private async processQueue(): Promise<void> {
    if (this.printing || this.tasks.length === 0) {
      return;
    }

    this.printing = true;

    try {
      while (this.tasks.length > 0) {
        const task = this.tasks.shift();

        if (task === undefined) {
          continue;
        }

        await this.printOne(task);

        // 根据打印机实际处理能力调整间隔
        await new Promise<void>((resolve) => {
          setTimeout(resolve, 500);
        });
      }
    } catch (error) {
      console.error(`打印失败: ${JSON.stringify(error)}`);
    } finally {
      this.printing = false;
    }
  }

  private async printOne(task: PrintTask): Promise<void> {
    // 替换为实际打印接口
  }
}

这只是任务串行化的管理示例,printOne() 必须等待真正可用的任务完成信号,不能仅仅等待打印接口提交成功。

如果打印服务没有提供真实完成回调,可以结合设备协议实现状态确认。

5. 如果是蓝牙便携打印机,还需要关注设备协议

很多便携式条码打印机采用 ESC/POS、TSPL、CPCL 或厂商私有协议。

不同协议对打印状态查询的支持不同。

例如:

  • ESC/POS:部分设备支持实时状态查询。
  • TSPL:部分设备支持 ~HS 等状态查询命令。
  • CPCL:需要结合具体设备型号和厂商协议确认。
  • 私有协议:通常需要厂商提供状态查询指令。

如果设备支持状态查询,可以设计:

收起
自动换行
深色代码主题
复制
发送第一张条码
      |
      v
等待打印机返回就绪状态
      |
      v
确认第一张完成
      |
      v
发送第二张条码
      |
      v
等待打印机返回就绪状态
      |
      v
发送第三张条码

注意:并不是所有打印机都支持打印完成状态查询。有些只能返回缓冲区状态或打印机就绪状态,不能准确确认纸张已经输出。


6. 建议先确认三个关键信息

这个问题目前还缺少一个重要信息:你使用的究竟是哪种打印链路?

  1. HarmonyOS 系统打印服务:通过系统打印框架提交打印任务。
  2. 蓝牙直接打印:通过 Bluetooth API 连接打印机,发送 ESC/POS、TSPL 等指令。
  3. 厂商 SDK:通过打印机厂商提供的 SDK 完成打印。

这三种方案的完成状态监听方式完全不同。

如果方便,最好补充一下:

  • 使用的 HarmonyOS 打印 API 名称。
  • 出问题的便携打印机品牌和型号。
  • 打印的是一张任务包含多张条码,还是连续提交多个独立打印任务。

尤其是第一点,确认使用的 API 后,才能准确判断系统打印服务是否提供任务状态监听接口,以及应该监听哪个回调,而不是盲目增加延迟或轮询。

展开全部
16楼回复于3天前 来自辽宁

你好,官方 Print Kit 的 PrintTask 只提供 block / succeed / fail / cancel 四种状态监听,`succeed` 表示打印服务"数据下发成功",并不保证打印机物理出纸完成,所以便携打印机在打印机侧把任务截断时,系统仍可能回调 succeed、不报 fail。

建议做法:

  1. print.print() 返回的 PrintTask 上把四个状态全部注册监听做兜底;
  2. 多张条码不要一次性塞进一个任务,改成"上一张收到终态(succeed/fail/cancel)再打下一张"的串行方式,避免打印机侧队列被截断;
  3. 如果指定机型稳定复现"只出第一张且无 fail 回调",这属于打印机型号与打印框架的兼容问题,应用层无法根治,建议收集设备型号、系统版本、打印机型号和 hilog(过滤 Print 标签)在线提单反馈:https://developer.huawei.com/consumer/cn/support/feedback/#@command:ticketCard

文档参考:

11楼回复于3天前 来自湖南

用系统打印时,拿到 print.print(files, context) 返回的 PrintTask 后,立即用 on() 监听 succeed(成功)、fail(失败)、cancel(取消)和 block(阻塞)。如果用的是 PrintDocumentAdapter,也可以在 onJobStateChanged(jobId, state) 里按任务 ID 记录状态。 鸿蒙打印 API

这些是任务级回调,无法逐张确认出纸。 对于只出第一张的机型,先确认预览页数、选中的打印范围和份数,再试试把每张标签做成一页,合成一个多页 PDF,按 1 份提交。如果预览完整、系统回调成功但仍只出一张,就需要看厂商 SDK 或打印协议能否回读设备状态。超时无回调时,把任务记为「结果未知」,核对已出纸张数后再补打。

6楼回复于3天前 来自广东

可以监听系统打印任务的状态,但需要区分“调用打印接口成功”和“打印任务成功”。没有收到失败回调,不能直接判断全部条码已经打印完成。

1. 在获取 PrintTask 后注册任务状态监听

文件打印可以监听 succeed、fail、cancel、block 四类事件。下面是 API 11+ 带 context 的文件打印接口用法,需声明 ohos.permission.PRINT:

收起
自动换行
深色代码主题
复制
import { print, BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

// files 为待打印文件的 URI 列表。
// 调用方保存返回的 PrintTask,便于管理任务及取消订阅。
async function submitPrint(
  files: string[],
  context: common.UIAbilityContext
): Promise<print.PrintTask> {
  const task = await print.print(files, context);

  task.on('succeed', () => {
    console.info('打印服务报告任务成功');
  });
  task.on('fail', () => {
    console.error('打印任务失败');
  });
  task.on('cancel', () => {
    console.info('打印任务已取消');
  });
  task.on('block', () => {
    console.warn('打印任务阻塞,需检查设备和打印队列');
  });

  return task;
}

调用 submitPrint 时还应捕获异常并记录 BusinessError 的 code、message。接口返回 PrintTask 后仍需等待任务事件,不能直接把 await print.print(...) 返回当作全部出纸完成。任务监听不再需要时,使用对应的 off 取消订阅。

如果使用的是 PrintDocumentAdapter 方式,则在 onJobStateChanged(jobId, state) 中监听:

  • PRINT_TASK_SUCCEED:任务成功。
  • PRINT_TASK_FAIL:任务失败。
  • PRINT_TASK_CANCEL:任务取消。
  • PRINT_TASK_BLOCK:任务阻塞。

PRINT_FILE_CREATED 只表示打印文件创建成功,预览界面退出也不代表打印完成。

2. “多张只出第一张”需要单独定位

上述回调是任务级通知,并没有提供“每张条码实际出纸完成”的回调。针对当前现象,建议做以下对照:

  1. 确认“多张”的实现方式:是同一页多份、一个多页 PDF、多个图片文件,还是循环提交多个打印任务。它们涉及的份数、页码范围和任务调度不同。
  2. 检查打印预览及源文件:确认页数、页码范围、份数、标签纸尺寸正确;如果使用适配器,确认已向传入的 fd 写入完整 PDF,再通知文件创建成功。
  3. 拆开测试:分别测试“单页一份”“单页多份”“多页一份”,并记录四类任务事件及系统队列状态。若代码循环提交多个任务,先改为单任务测试,排除并发提交的影响。
  4. 用相同文件、相同设置交叉验证:对比正常型号、异常型号,以及厂商应用的打印结果,帮助区分文件生成问题、系统打印适配问题和设备问题。

如果系统已经回调 succeed,但实际只出一张,应把“服务报告成功、实际输出不完整”作为问题证据,结合打印机型号、连接方式、固件、系统版本及打印日志进一步排查。目前信息不足,不能直接认定是缓存不足或设备不支持多份。

3. 如果业务要求确认每张标签真正打印完

需要确认该型号的厂商 SDK 或通信协议是否提供任务完成、已打印张数等设备反馈,并核实其含义。系统任务成功事件不能直接替代逐张出纸确认。

对于长时间没有终态回调的任务,可以设置业务超时并标记为“状态待确认”,但不宜直接自动重打,避免已部分出纸时产生重复条码。

以上为官方接口文档核对及排查建议,尚未在所述便携打印机上实测。

展开全部
22楼回复于4小时前 来自浙江

背景知识:

监听打印完成状态的核心方式是:通过 print.print() 发起打印后拿到返回的 PrintTask 实例,再调用 printTask.on() 注册状态事件监听。PrintTask 提供四类事件回调:succeed(任务成功)、fail(任务失败)、cancel(任务被取消)、block(任务阻塞),覆盖了打印任务从提交到结束的全部状态变化。

针对您描述的"打印多张只出第一张、队列没有回调失败"的现象,需要先理解状态回调的来源:系统打印框架对任务终态的判定,依赖打印机侧(打印扩展/驱动)上报的状态。部分型号便携打印机在多份拷贝场景下只实际输出第一张,却向框架上报了"任务完成",框架据此触发的是 succeed 而非 fail,应用侧自然收不到失败回调——这属于打印机驱动/扩展的状态上报问题,应用层无法凭空感知。

应用侧能做的针对性措施有三点:

  1. 四个事件全量注册:很多开发者只监听了 succeed 和 fail,漏掉了 block。任务因缺纸、卡纸、离线、被占用等原因停住时,走的是阻塞事件而非失败事件 ,漏监听会导致"什么回调都没有"的假象。
  2. 超时兜底:终态事件(成功/失败/取消)一个都没来时,用定时器主动结束等待并提示用户检查打印机。
  3. 多张改为逐张串行提交:不要把多张作为一个任务的多个拷贝提交,而是每张独立提交一个任务,上一张到达终态后再提交下一张。这样每张的完成状态都可精确跟踪,异常也能定位到具体某一张。

问题解决:

示例代码

收起
自动换行
深色代码主题
复制
import { print } from '@kit.BasicServicesKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';
import { Context } from '@kit.AbilityKit';

// 单张任务的终态
type PrintResult = 'succeed' | 'fail' | 'cancel' | 'timeout';
// 状态提示回调
type OnStatusChange = (message: string) => void;

// 打印一张并监听全部状态事件,带超时兜底
function printOnePage(filePath: string, context: Context,
  timeoutMs: number, onStatus: OnStatusChange): Promise<PrintResult> {
  return new Promise<PrintResult>((resolve): void => {
    let finished: boolean = false;
    // 超时兜底:终态事件一个都没来时,主动结束等待
    const timerId: number = setTimeout((): void => {
      if (!finished) {
        finished = true;
        onStatus('超时未收到打印终态回调,请检查打印机状态');
        resolve('timeout');
      }
    }, timeoutMs);
    // 终态收口:保证 Promise 只被 resolve 一次
    const finish = (result: PrintResult): void => {
      if (finished) {
        return;
      }
      finished = true;
      clearTimeout(timerId);
      resolve(result);
    };
    print.print([fileUri.getUriFromPath(filePath)], context)
      .then((printTask: print.PrintTask): void => {
        // 任务成功:框架判定整个任务完成
        printTask.on('succeed', (): void => {
          onStatus('打印成功');
          finish('succeed');
        });
        // 任务失败
        printTask.on('fail', (): void => {
          onStatus('打印失败');
          finish('fail');
        });
        // 任务被取消
        printTask.on('cancel', (): void => {
          onStatus('打印已取消');
          finish('cancel');
        });
        // 阻塞是可恢复的中间态:缺纸、卡纸、离线、被占用等,不作为终态
        printTask.on('block', (): void => {
          onStatus('打印阻塞,请检查打印机(缺纸、卡纸、离线、被占用等)');
        });
      })
      .catch((error: BusinessError): void => {
        // 拉起打印框架本身失败(参数、权限等问题)
        onStatus(`发起打印失败:code=${error.code}, message=${error.message}`);
        finish('fail');
      });
  });
}

// 批量串行打印:每张独立提交,上一张到达终态后再提交下一张
async function printBatch(filePaths: string[], context: Context,
  onStatus: OnStatusChange): Promise<void> {
  for (let i = 0; i < filePaths.length; i++) {
    onStatus(`正在打印第 ${i + 1}/${filePaths.length} 张`);
    const result: PrintResult = await printOnePage(filePaths[i], context, 60000, onStatus);
    if (result !== 'succeed') {
      onStatus(`第 ${i + 1} 张未成功(${result}),已中止后续打印`);
      return;
    }
  }
  onStatus('全部打印完成');
}

@Entry
@Component
struct BarcodePrintPage {
  @State statusText: string = '待打印';

  build() {
    Column({ space: 16 }) {
      Text(this.statusText)
        .fontSize(16)
        .textAlign(TextAlign.Center)
        .padding(16)
      Button('开始批量打印条码')
        .width('60%')
        .height(48)
        .onClick((): void => {
          const context: Context | undefined = this.getUIContext().getHostContext();
          if (context === undefined) {
            this.statusText = '页面上下文未就绪,请稍后重试';
            return;
          }
          // 条码文件需先保存到应用沙箱,此处路径替换为实际文件
          const files: string[] = [
            '/data/storage/el2/base/haps/entry/files/barcode_1.pdf',
            '/data/storage/el2/base/haps/entry/files/barcode_2.pdf',
            '/data/storage/el2/base/haps/entry/files/barcode_3.pdf'
          ];
          printBatch(files, context, (message: string): void => {
            this.statusText = message;
          });
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}
展开全部
21楼回复于昨天15:42 来自广东
print.print(uri).then((printTask: print.PrintTask) => { printTask.on('succeed', () => {}); printTask.on('fail', () => {}); printTask.on('block', () => {}); printTask.on('cancel', () => {}); }) 可监听任务状态,需在 module.json5 声明 ohos.permission.PRINT。但 succeed 仅代表打印框架判定任务完成,便携机只出第一张且队列不报错时 succeed 照样回调,属于该型号打印驱动(PrintExtensionAbility)上报状态失真,回调层面感知不到少纸少打,只能绕过:改为逐张提交任务,收到上一张 succeed 再发下一张,同时用超时兜底;根治需让该打印机扩展适配方修复多页任务状态上报。 
20楼回复于昨天12:35 来自北京

打印调用返回成功,通常只是拿到任务,不代表所有条码已经出纸。取得 PrintTask 后监听 succeed、fail、cancel、block,注意完成事件名是 succeed,不是 success;block 是阻塞状态,不能直接当作终态。使用相关接口还需按文档声明 PRINT 权限。

如果走 PrintDocumentAdapter,可在 onJobStateChanged 中按 jobId 记录任务状态。任务对象和监听器要保留到任务结束,再清理,避免页面返回后丢失回调。

“只打印第一张”建议先构造两页、条码明显不同的 PDF:检查文件实际页数、预览是否两页、选择的页范围、份数及纸张大小。预览已有缺页就查应用生成文档;预览正常而设备只出一页,再对照打印服务和设备适配日志,不宜先归因于没有完成监听。

系统任务状态通常不能证明每张物理标签都已打印。业务侧最好记录批次和标签序号,把明确失败、取消与结果未知分开;超时后先核对已输出标签,只补缺项,别直接重打整批导致条码重复。

18楼回复于前天09:31 来自上海

文件打印应监听返回的 PrintTask;print.print() 成功只表示拿到了任务,并不能当成所有条码已出纸。API 11+、已声明 ohos.permission.PRINT 时,关键接法如下:

收起
自动换行
深色代码主题
复制
import { print } from '@kit.BasicServicesKit';
import { fileUri } from '@kit.CoreFileKit';

// 放在能取得 UIContext 的组件方法中,pdfPath 为沙箱 PDF 路径。
const context = this.getUIContext().getHostContext();
if (context) {
  const task = await print.print([fileUri.getUriFromPath(pdfPath)], context);
  task.on('succeed', () => console.info('任务成功'));
  task.on('fail', () => console.error('任务失败'));
  task.on('cancel', () => console.info('任务取消'));
  task.on('block', () => console.warn('任务阻塞'));
}

外围捕获提交异常,并持有 task,在业务结束时取消相应监听。先用“两页且条码不同”的 PDF 核对生成页数、预览页数、页码范围/份数,再查纸张尺寸及厂商打印插件;如果实际走厂商蓝牙 SDK,则必须看该协议的状态回执。阻塞或超时未知时不要自动整批重打,避免重复标签。

技术示意图

打印任务事件

17楼回复于前天02:34 来自四川

针对“打印多张只出第一张且无失败回调”的现象,根本原因通常不在应用侧的监听方式,而在于便携打印机的 PrintExtensionAbility 插件没有正确上报后续任务的状态。应用侧通过 print.print() 返回的 PrintTask 实例注册的 on('success')、on('fail')、on('block')、on('cancel') 四类回调,其数据源是“打印机/厂商打印扩展 → 打印框架 → 应用”这条链路,如果扩展在第一张之后“静默失联”,应用侧无论怎么监听都收不到任何事件。因此,要可靠地感知打印完成,不能单纯依赖状态回调,而应改用“串行下发 + 超时兜底”的策略:将多张条码拆分为独立的打印任务,每一张都等待 success、fail、cancel 任一回调,或触发自定义超时(便携打印机出纸较慢,建议超时时间设为 30 秒左右),只有在上一张确认完成(或超时判定失败)后,才下发下一张,避免任务在打印队列中堆积导致后续任务被静默丢弃。这样即使某个型号的扩展不上报后续状态,应用也能通过超时机制及时止损并给出明确提示,而不是陷入“队列无回调”的黑盒等待。

15楼回复于3天前 来自湖北
共3页
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。