目录

安装和使用

二次开发手册

常见问题

Spirit REST API Java Client SDK 文档

概述

Java SDK 是对REST API的封装, 简化与 PrintSpirit 服务的交互. 相关功能详见打印精灵开放平台。

初始化客户端

构造函数

1public Client(String ip, int port)
2public Client(String ip) // 默认端口 9011

示例：

1Client client = new Client("192.168.1.100", 9011);
2Client client = new Client("192.168.1.100"); // 使用默认端口 9011

标签打印选项配置 (Options 类)

初始化

1Options opts = new Options("打印机名称", PrinterType.ZPL);
2// 或使用默认类型
3Options opts = new Options("打印机名称");

第一个参数"打印机名", 为打印机(条码打印机或Windows系统打印机)的名称, 第一个参数"打印机类型", 如ZPL斑马兼容打印机, TSPL, CPCL等打印机。

配置方法

方法 描述 示例
.row(int r) 设置打印行数 opts.row(2)
.col(int c) 设置打印列数 opts.col(3)
.size(int size) 设置尺寸（统一值） opts.size(50)
.size(int w, int h) 设置尺寸（分别指定宽高） opts.size(100, 200)
.gap(int gapX, int gapY) 设置标签的行列间距 opts.gap(5, 10)
.quality(Qty q) 设置打印质量 opts.quality(Options.Qty.Hight)
.flush(boolean f) 是否立即刷新打印 opts.flush(false)

说明：

  • 打印行数和列数：主要用于拼板打印，可以在单张打印纸上同时打印多个标签。
  • 打印质量：
    • 快速模式：使用打印机的原生指令打印，速度较快。但需要打印机配备相应字体，否则会自动选择最接近的字体。
    • 高质量模式：使用图形方式打印文字，确保打印效果准确，但速度相对较慢。

枚举类型

1enum PrinterType { ZPL, CPCL, TSPL, ESCPOS }
2enum Qty { Fast, Middle, Hight }

核心 API 方法

1. 打印标签

1public Result Print(..., String label_id, List data)

支持多种重载形式：

形式 1 - 使用 Options 配置

1Result Print(Options opts, String label_id, List data)

形式 2 - 使用 Map 配置

1Result Print(Map<String, Object> opts, String label_id, List data)

参数说明：

  • label_id: 模板 ID
  • data: 可变数据列表（支持 List 或 Map 格式）
  • opts: 打印机配置（推荐使用 Options 类）

示例：

1Options opts = new Options("Zebra_123")
2    .row(2)
3    .quality(Options.Qty.Hight);
4
5Map<String, Object> data = new HashMap<>();
6data.put("barcode", "ABC123");
7
8Result res = client.Print(opts, "label_template_1", data);

2. 重置打印机

1public Result ResetPrinter(String prnname)

清除打印机队列和缓存。

示例：

1Result res = client.ResetPrinter("Zebra_123");

3. 清理缓存

1public void ClearCache()

清理服务端缓存。

示例：

1client.ClearCache();

4. 注册虚拟打印机

1public String RegisterVirtualPrinter(Options opts)

返回可用于获取渲染数据的令牌。

示例：

1Options opts = new Options("Virtual_Printer", PrinterType.ZPL);
2String token = client.RegisterVirtualPrinter(opts);

5. 数据解码

1public static byte[] decode(String data)

解码 BASE64 + ZLIB 压缩的数据（用于处理虚拟打印机返回数据）。

示例：

1byte[] decoded = Client.decode(base64Data);

结果处理 (Result 类)

1public class Result {
2    public String rc;  // 返回码 ("OK" 表示成功)
3    public int cnt;    // 打印计数
4    public String msg; // 附加信息/错误信息
5}

异常处理

自定义异常

1public class RegisterErrorException extends RuntimeException

常见异常

  • IOException: 网络通信错误
  • DataFormatException: 数据解码失败

使用示例

完整打印流程示例

 1Client client = new Client("192.168.1.100");
 2
 3Options opts = new Options("Zebra_123", PrinterType.ZPL)
 4    .row(2)
 5    .quality(Options.Qty.Hight);
 6
 7Map<String, Object> data = new HashMap<>();
 8data.put("productCode", "P12345");
 9data.put("batchNo", "B67890");
10
11try {
12    Result res = client.Print(opts, "product_label", data);
13    if ("OK".equals(res.rc)) {
14        System.out.println("打印成功，数量：" + res.cnt);
15    } else {
16        System.out.println("打印失败：" + res.msg);
17    }
18} catch (IOException e) {
19    e.printStackTrace();
20}

留言

登录