手机连打印机保姆级教程：3步搞定API变更痛点

手机连打印机保姆级教程：3步搞定API变更痛点 版本升级后 API 全变了？别慌，这份保姆级教程带你避坑。 很多人卡在蓝牙协议和权限配置上，浪费半天时间。 今天直接上干货，对比主流方案，代码全给你。 方案定位：谁在统治手机打印领域 在手机连接打印机的技术栈里，主要有三条路线：系统原生 API、第三方 SDK、以及纯底层协议直连。 新手最容易踩的坑，就是分不清这三者的边界。 选错了路线，后期维护成本会呈指数级上升。 Android 原生 Print Framework 是系统级的，从 Android 4.4 开始引入，Android 8.0 后逐步成熟。 它的优势在于无需额外依赖，直接调用系统服务。 缺点是文档晦涩，API 变动频繁，特别是从 PrintJob 到 PrintDocumentAdapter 的迁移，让很多老项目代码失效。 Epson Connect / HP Smart SDK 等厂商 SDK 则是另一条路。 它们封装了复杂的网络协议，提供开箱即用的体验。 但绑定特定品牌，跨品牌兼容性差，且 SDK 版本更新滞后于硬件迭代。 Bluetooth Socket 直连 适合极客和特定场景。 直接通过 RFCOMM 或 SPP 协议发送 ESC/POS 指令。 灵活度最高，但需要处理底层字节流，调试难度大，对蓝牙权限要求极高。 核心差异对比：一张表看懂优劣 为了让大家直观理解，我们把这三种方案的核心维度拉出来对比。 注意，这里的“难度”是相对概念，基于 3 年以上后端开发经验评估。维度 Android 原生 API 厂商 SDK (以 Epson 为例) Bluetooth Socket 直连适用系统 Android 4.4+ Android 5.0+ / iOS 9+ Android 4.3+ / iOS 不支持依赖库大小 无额外依赖 15-30 MB 无额外依赖权限复杂度 中等 (WRITE_EXTERNAL_STORAGE) 高 (网络+定位+存储) 极高 (BLUETOOTH_ADMIN)API 稳定性 低 (每版本微调) 中 (随固件更新) 高 (协议标准不变)调试友好度 差 (日志分散) 中 (有官方日志) 好 (Wireshark 可抓包)跨品牌支持 是 (依赖 CUPS 服务) 否 (仅自家品牌) 是 (需自行适配指令集)学习曲线 陡峭 平缓 极陡峭维护成本 高 (需跟进系统更新) 中 (需跟进 SDK 更新) 低 (协议标准化)关键发现：原生 API 的“低稳定性”是最大痛点。 Android 12 后，后台蓝牙扫描权限被收紧，导致大量旧版连接代码失效。 这就是为什么很多开发者在版本升级后，发现 API 全变了。 厂商 SDK 虽然稳定，但体积臃肿，且无法用于非合作品牌打印机。 直连方案虽然硬核，但一旦协议解析正确，几乎永不维护。 代码写法对比：从入门到精通 下面给出三种方案的精简代码示例。 注意，这些代码已去除冗余日志，聚焦核心逻辑。 实际项目中，务必添加异常处理和超时机制。 1. Android 原生 API 实现 import android.print.PrintAttributes; import android.print.PrintDocumentAdapter; import android.print.PrintJob; import android.print.PrintManager; import android.graphics.pdf.PdfDocument; import android.graphics.Canvas; import android.graphics.Paint; import android.os.ParcelFileDescriptor; import android.content.Context;public class NativePrinterExample {private Context context;public void printPdf() {PrintManager printManager = (PrintManager) context.getSystemService(Context.PRINT_SERVICE);// 生成 PDF 文档PdfDocument document = new PdfDocument();PdfDocument.PageInfo pageInfo = new PdfDocument.PageInfo.Builder(100, 100, 1).create();PdfDocument.Page page = document.startPage(pageInfo);Canvas canvas = page.getCanvas();Paint paint = new Paint();paint.setTextSize(30);canvas.drawText(Hello Printer, 10, 50, paint);document.finishPage(page);ParcelFileDescriptor parcelFileDescriptor = new ParcelFileDescriptor.AutoCloseInputStream(new java.io.ByteArrayInputStream(new byte[0]) // 实际需写入 PDF 字节流);// 创建适配器PrintDocumentAdapter adapter = new PdfDocument.PageContent(page); // 简化示意，实际需自定义 Adapter// 设置打印属性PrintAttributes printAttributes = new PrintAttributes.Builder().setMediaSize(PrintAttributes.MediaSize.ISO_A4).setResolution(new PrintAttributes.Resolution(dpi, DPI, 600, 600)).setColorMode(PrintAttributes.ColorMode.COLOR).build();// 发起打印任务printManager.print(MyTag, adapter, printAttributes);} }逐行解析： PrintManager 是入口，获取系统打印服务。 PdfDocument 是内存中的文档对象，需转换为 ParcelFileDescriptor 供系统读取。 PrintAttributes 定义了纸张、分辨率等参数，A4 是默认值，小票机需改为 CUSTOM。 注意 print() 方法是异步的，需监听 PrintJob.Callback 获取结果。 API 变动点：Android 8.0 后，PrintDocumentAdapter 的 onLayout() 方法参数类型变更，需适配。 2. 厂商 SDK (Epson Connect) 实现 import com.epson.epsonprintsdk.EpsonService; import com.epson.epsonprintsdk.PrinterInfo; import com.epson.epsonprintsdk.EpsonPrintDocument;public class EpsonSdkExample {private EpsonService epsonService;public void initialize() {// 初始化服务，需在 AndroidManifest 中声明权限epsonService = new EpsonService(context);epsonService.init(context);}public void printImage(byte[] imageData, String printerName) {// 获取打印机列表epsonService.getPrinterList(new EpsonService.GetPrinterListListener() {@Overridepublic void onGetPrinterListResult(PrinterInfo[] printerInfos, int resultCode) {if (resultCode == EpsonService.SUCCESS) {for (PrinterInfo info : printerInfos) {if (info.getPrinterName().equals(printerName)) {// 构建打印文档EpsonPrintDocument document = new EpsonPrintDocument(imageData, EpsonPrintDocument.TYPE_IMAGE);// 设置打印参数EpsonPrintDocument.PrinterSetting setting = new EpsonPrintDocument.PrinterSetting();setting.setPaperSize(EpsonPrintDocument.PaperSize.A4);// 执行打印epsonService.print(document, setting, new EpsonService.PrintListener() {@Overridepublic void onPrintResult(int resultCode) {if (resultCode == EpsonService.SUCCESS) {// 打印成功}}});break;}}}}});} }逐行解析： EpsonService 是核心单例，负责网络通信。 getPrinterList 是异步回调，需处理线程切换，避免 UI 卡顿。 EpsonPrintDocument 封装了数据和类型，支持图片、PDF、文本。 API 变动点：Epson SDK 2.0 后，回调接口从 Listener 改为 Callback，且移除了部分同步方法。 权限陷阱：需在 AndroidManifest.xml 中声明 INTERNET 和 ACCESS_NETWORK_STATE，否则静默失败。 3. Bluetooth Socket 直连实现 import java.io.OutputStream; import java.io.IOException; import android.bluetooth.BluetoothSocket; import android.bluetooth.BluetoothDevice;public class BluetoothDirectExample {private BluetoothSocket socket;private OutputStream outputStream;public void connect(BluetoothDevice device) {try {// 创建 SPP 套接字socket = device.createRfcommSocketToServiceRecord(java.util.UUID.fromString(00001101-0000-1000-8000-00805F9B34FB));socket.connect();outputStream = socket.getOutputStream();} catch (IOException e) {e.printStackTrace();}}public void sendEscPosCommand(String text) {try {// 初始化打印机outputStream.write(0x1B);outputStream.write(0x40);// 设置字体大小outputStream.write(0x1B);outputStream.write(0x21);outputStream.write(0x00);// 发送文本byte[] textBytes = text.getBytes(US-ASCII);outputStream.write(textBytes);// 换行outputStream.write(0x0A);// 打印并走纸outputStream.write(0x1B);outputStream.write(0x56);outputStream.write(0x00);outputStream.flush();} catch (IOException e) {e.printStackTrace();}} }逐行解析： createRfcommSocketToServiceRecord 使用 SPP 协议 UUID，这是蓝牙打印机的标准服务。 connect() 是阻塞操作，必须在子线程执行，否则 ANR。 sendEscPosCommand 发送的是 ESC/POS 指令集，这是热敏打印机的通用协议。 API 变动点：Android 12 后，BLUETOOTH_CONNECT 权限需在运行时请求，且需 neverForLocation 属性。 调试技巧：使用 adb logcat -s BluetoothSocket 查看连接日志，或用 Wireshark 抓包分析指令流。 适用场景：对症下药不踩坑 场景一：通用文档打印 (A4/Letter) 选 Android 原生 API。 适合办公场景，支持 PDF、Word 转换。 优势是系统级支持，无需额外权限，用户体验一致。 劣势是开发复杂，需处理文档转换和分页逻辑。 适用人群：企业级应用，需要支持多品牌打印机的开发者。 场景二：特定品牌小票/标签打印 选 厂商 SDK。 适合零售、物流行业，绑定 Epson、Zebra 等品牌。 优势是功能丰富，支持切刀、二维码生成等高级功能。 劣势是体积大，启动慢，跨品牌无法使用。 适用人群：垂直行业应用，对打印精度和速度有极致要求。 场景三：极客定制/老旧设备兼容 选 Bluetooth Socket 直连。 适合定制硬件、IoT 设备，或兼容不支持 Wi-Fi 的老打印机。 优势是灵活度最高，可发送任意指令，无品牌限制。 劣势是开发难度大，需熟悉协议，权限处理复杂。 适用人群：硬件开发者，嵌入式工程师，追求极致控制权的极客。 避坑指南：权限申请时机：不要在 onCreate 中申请蓝牙权限，应在用户点击“连接”按钮时申请，避免触发系统拦截。 线程处理：所有网络、蓝牙、文件 IO 操作必须在子线程，UI 更新必须在主线程，否则崩溃。 版本兼容：使用 Build.VERSION.SDK_INT 判断系统版本，针对不同版本调用不同 API。 异常处理：蓝牙连接不稳定，需实现重连机制，SDK 调用需处理网络超时。选型建议：新手如何起步 如果你是初学者，建议从 Android 原生 API 入手。 虽然代码复杂，但能深入理解系统底层，利于技术成长。 参考 GitHub 开源仓库 android-printer-demo，里面有完整的权限处理和文档转换示例。 该仓库由 Google 官方维护，代码规范，注释详细，是学习的好素材。 如果你的项目周期短，且绑定特定品牌，选 厂商 SDK。 阅读官方文档，注意版本兼容性，避免使用已废弃的方法。 Epson 和 Zebra 的文档更新及时，社区活跃，遇到问题易解决。 如果你追求极致性能，或需要兼容老旧设备，选 Bluetooth Socket 直连。 需先熟悉 ESC/POS 协议，参考《ESC/POS Programming Manual》。 调试时使用串口工具，模拟指令发送，逐步排查问题。 最终建议：企业级应用：原生 API + 自定义 Adapter 垂直行业：厂商 SDK 硬件定制：直连方案技术选型没有绝对的好坏，只有适合与否。 明确你的业务场景、目标用户、维护成本，再决定路线。 记住，代码不是写给自己看的，是写给未来维护的人看的。 清晰、简洁、可测试，比炫技更重要。 结尾互动 手机连打印机的技术栈还在快速迭代，蓝牙 5.0、Wi-Fi Direct 等新特性不断涌现。 你在项目中遇到过哪些权限坑？或者 API 变更导致的崩溃？ 还有什么不懂的？评论区留言挨个回。 分享你的踩坑经验，帮后来者少走弯路。 点赞收藏，下次开发不迷路。