180******22ArkTS
调用打印服务打印条码
阿家@ohos.print (打印)模块的on(type: 'printerChange', callback: PrinterChangeCallback): void可注册打印机变动事件回调。看看回调返回什么:
| 参数名 | 类型 | 说明 |
|---|---|---|
| event | PrinterEvent | 表示打印机事件。 |
| printerInformation | PrinterInformation | 表示打印机信息。 |
不羁的木木这个问题需要先区分两个概念:打印任务提交成功,不代表打印机已经完成打印;打印服务任务结束,也不一定代表纸张已经实际输出。
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. 建议先确认三个关键信息
这个问题目前还缺少一个重要信息:你使用的究竟是哪种打印链路?
- HarmonyOS 系统打印服务:通过系统打印框架提交打印任务。
- 蓝牙直接打印:通过 Bluetooth API 连接打印机,发送 ESC/POS、TSPL 等指令。
- 厂商 SDK:通过打印机厂商提供的 SDK 完成打印。
这三种方案的完成状态监听方式完全不同。
如果方便,最好补充一下:
- 使用的 HarmonyOS 打印 API 名称。
- 出问题的便携打印机品牌和型号。
- 打印的是一张任务包含多张条码,还是连续提交多个独立打印任务。
尤其是第一点,确认使用的 API 后,才能准确判断系统打印服务是否提供任务状态监听接口,以及应该监听哪个回调,而不是盲目增加延迟或轮询。
北墨NoLimit
你好,官方 Print Kit 的 PrintTask 只提供 block / succeed / fail / cancel 四种状态监听,`succeed` 表示打印服务"数据下发成功",并不保证打印机物理出纸完成,所以便携打印机在打印机侧把任务截断时,系统仍可能回调 succeed、不报 fail。
建议做法:
print.print()返回的PrintTask上把四个状态全部注册监听做兜底;- 多张条码不要一次性塞进一个任务,改成"上一张收到终态(succeed/fail/cancel)再打下一张"的串行方式,避免打印机侧队列被截断;
- 如果指定机型稳定复现"只出第一张且无 fail 回调",这属于打印机型号与打印框架的兼容问题,应用层无法根治,建议收集设备型号、系统版本、打印机型号和 hilog(过滤 Print 标签)在线提单反馈:https://developer.huawei.com/consumer/cn/support/feedback/#@command:ticketCard
文档参考:
- @ohos.print 打印 API(PrintTask 状态监听):https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-print
- 打印错误码(13100001–13100006):https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-print
蓝瘦的蜕变
用系统打印时,拿到 print.print(files, context) 返回的 PrintTask 后,立即用 on() 监听 succeed(成功)、fail(失败)、cancel(取消)和 block(阻塞)。如果用的是 PrintDocumentAdapter,也可以在 onJobStateChanged(jobId, state) 里按任务 ID 记录状态。 鸿蒙打印 API
这些是任务级回调,无法逐张确认出纸。 对于只出第一张的机型,先确认预览页数、选中的打印范围和份数,再试试把每张标签做成一页,合成一个多页 PDF,按 1 份提交。如果预览完整、系统回调成功但仍只出一张,就需要看厂商 SDK 或打印协议能否回读设备状态。超时无回调时,把任务记为「结果未知」,核对已出纸张数后再补打。
吴同学132可以监听系统打印任务的状态,但需要区分“调用打印接口成功”和“打印任务成功”。没有收到失败回调,不能直接判断全部条码已经打印完成。
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. “多张只出第一张”需要单独定位
上述回调是任务级通知,并没有提供“每张条码实际出纸完成”的回调。针对当前现象,建议做以下对照:
- 确认“多张”的实现方式:是同一页多份、一个多页 PDF、多个图片文件,还是循环提交多个打印任务。它们涉及的份数、页码范围和任务调度不同。
- 检查打印预览及源文件:确认页数、页码范围、份数、标签纸尺寸正确;如果使用适配器,确认已向传入的 fd 写入完整 PDF,再通知文件创建成功。
- 拆开测试:分别测试“单页一份”“单页多份”“多页一份”,并记录四类任务事件及系统队列状态。若代码循环提交多个任务,先改为单任务测试,排除并发提交的影响。
- 用相同文件、相同设置交叉验证:对比正常型号、异常型号,以及厂商应用的打印结果,帮助区分文件生成问题、系统打印适配问题和设备问题。
如果系统已经回调 succeed,但实际只出一张,应把“服务报告成功、实际输出不完整”作为问题证据,结合打印机型号、连接方式、固件、系统版本及打印日志进一步排查。目前信息不足,不能直接认定是缓存不足或设备不支持多份。
3. 如果业务要求确认每张标签真正打印完
需要确认该型号的厂商 SDK 或通信协议是否提供任务完成、已打印张数等设备反馈,并核实其含义。系统任务成功事件不能直接替代逐张出纸确认。
对于长时间没有终态回调的任务,可以设置业务超时并标记为“状态待确认”,但不宜直接自动重打,避免已部分出纸时产生重复条码。
以上为官方接口文档核对及排查建议,尚未在所述便携打印机上实测。
丿未来丶背景知识:
监听打印完成状态的核心方式是:通过 print.print() 发起打印后拿到返回的 PrintTask 实例,再调用 printTask.on() 注册状态事件监听。PrintTask 提供四类事件回调:succeed(任务成功)、fail(任务失败)、cancel(任务被取消)、block(任务阻塞),覆盖了打印任务从提交到结束的全部状态变化。
针对您描述的"打印多张只出第一张、队列没有回调失败"的现象,需要先理解状态回调的来源:系统打印框架对任务终态的判定,依赖打印机侧(打印扩展/驱动)上报的状态。部分型号便携打印机在多份拷贝场景下只实际输出第一张,却向框架上报了"任务完成",框架据此触发的是 succeed 而非 fail,应用侧自然收不到失败回调——这属于打印机驱动/扩展的状态上报问题,应用层无法凭空感知。
应用侧能做的针对性措施有三点:
- 四个事件全量注册:很多开发者只监听了 succeed 和 fail,漏掉了 block。任务因缺纸、卡纸、离线、被占用等原因停住时,走的是阻塞事件而非失败事件 ,漏监听会导致"什么回调都没有"的假象。
- 超时兜底:终态事件(成功/失败/取消)一个都没来时,用定时器主动结束等待并提示用户检查打印机。
- 多张改为逐张串行提交:不要把多张作为一个任务的多个拷贝提交,而是每张独立提交一个任务,上一张到达终态后再提交下一张。这样每张的完成状态都可精确跟踪,异常也能定位到具体某一张。
问题解决:
示例代码
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)
}
}
全栈若城
KevinChaos
打印调用返回成功,通常只是拿到任务,不代表所有条码已经出纸。取得 PrintTask 后监听 succeed、fail、cancel、block,注意完成事件名是 succeed,不是 success;block 是阻塞状态,不能直接当作终态。使用相关接口还需按文档声明 PRINT 权限。
如果走 PrintDocumentAdapter,可在 onJobStateChanged 中按 jobId 记录任务状态。任务对象和监听器要保留到任务结束,再清理,避免页面返回后丢失回调。
“只打印第一张”建议先构造两页、条码明显不同的 PDF:检查文件实际页数、预览是否两页、选择的页范围、份数及纸张大小。预览已有缺页就查应用生成文档;预览正常而设备只出一页,再对照打印服务和设备适配日志,不宜先归因于没有完成监听。
系统任务状态通常不能证明每张物理标签都已打印。业务侧最好记录批次和标签序号,把明确失败、取消与结果未知分开;超时后先核对已输出标签,只补缺项,别直接重打整批导致条码重复。
橙动创意文件打印应监听返回的 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,则必须看该协议的状态回执。阻塞或超时未知时不要自动整批重打,避免重复标签。

云上针对“打印多张只出第一张且无失败回调”的现象,根本原因通常不在应用侧的监听方式,而在于便携打印机的 PrintExtensionAbility 插件没有正确上报后续任务的状态。应用侧通过 print.print() 返回的 PrintTask 实例注册的 on('success')、on('fail')、on('block')、on('cancel') 四类回调,其数据源是“打印机/厂商打印扩展 → 打印框架 → 应用”这条链路,如果扩展在第一张之后“静默失联”,应用侧无论怎么监听都收不到任何事件。因此,要可靠地感知打印完成,不能单纯依赖状态回调,而应改用“串行下发 + 超时兜底”的策略:将多张条码拆分为独立的打印任务,每一张都等待 success、fail、cancel 任一回调,或触发自定义超时(便携打印机出纸较慢,建议超时时间设为 30 秒左右),只有在上一张确认完成(或超时判定失败)后,才下发下一张,避免任务在打印队列中堆积导致后续任务被静默丢弃。这样即使某个型号的扩展不上报后续状态,应用也能通过超时机制及时止损并给出明确提示,而不是陷入“队列无回调”的黑盒等待。
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS rpc通信如何实现数据流,即一次调用,服务端会发送数据流(API12+)
HarmonyOS Animator 主动调用 finish & cancel 时有额外 onFrame 回调 (API12+)
HarmonyOS 原生调用拨打电话的能力(API12+)
HarmonyOS 播放音频调用stop()方法,onComplete回调执行了(API12+)
HarmonyOS OH_print模块应该怎么连接打印机使用? (API12+)
消息推送pushService.receiveMessage函数监听不到内容
HarmonyOS 如何监听广告加载过程中的回调(成功与失败)?(API12+)
HarmonyOS new Error().stack打印的堆栈不全(API12+)




































苏公安网备 32011402010933号