目录

安装和使用

二次开发手册

常见问题

SpiritLabelLibrary C# SDK 使用手册

1. 概述

SpiritLabel 是打印精灵开放平台二次开发工具之一。基于 Spirit C 库开发的 C# 封装组件，提供开箱即用的标签打印解决方案。完整保留原生C语言版本功能特性.进一步简化C#桌面程序集成标签打印和标签编辑功能。

2. 环境要求与安装

2.1 系统要求

  • .NET 5.0 或更高版本
  • Windows/Linux 系统（需部署对应平台的libspirit动态库）
  • 安装打印精灵桌面版(SpiritDesktop)

2.2 安装方式

NuGet 安装（推荐）

SpiritLabel已经发布到NutGet, 可以直接通过NuGet包管理工具或Visual Studio安装

1# Visual Studio 包管理器
2Install-Package SpiritLabel
3
4# 或使用dotnet CLI
5dotnet add package SpiritLabel

3. 快速入门

3.1示例代码

请查看https://github.com/printspirit/spirit_example 项目c-sharp子目录下的示例。 demo-win-gui是windows下WPF程序，功能包括选择打印机、打印、创建并编辑标签。

效果如下：

demo

3.2 标签打印流程

 1try 
 2{
 3    // 连接打印机
 4    // "Spirit Image"为打印精灵内置的虚拟打印机, 可以在文档\打印精灵\outoput目录下生成一个png文件
 5    // 请修改为实际的打印机名称, 支持Windows系统打印机和ZPL,TSPL,CPCL, ESC/POS打印机, 无需驱动
 6    // 可通过piritLabel.PrnLst()获取系统可用打印机
 7    var printer = SpiritLabel.OpenPrinter("Spirit Image");
 8    
 9    // 配置打印参数
10    printer.size(500, 300)          // 设置纸张大小为50x30mm
11           .quality(Qty.High)       // 设置打印模式:高质量模式
12
13    // 创建打印变量, 实现可变数据套打
14    var printVars = new Dictionary<string, object> 
15    {
16        { "co_name", "打印精灵" },
17        { "name", "标签打印机" }
18    };
19    
20    // 执行打印（支持UUID或本地文件）
21    printer.Print("acae8013-28db-4b77-a500-1a6052633a22", printVars);
22}
23catch (SpiritException ex)
24{
25    Console.WriteLine($"[ERR] 打印失败: {ex.ErrorCode}-{ex.Message}");
26}

解释:

  • Spirit Image为打印精灵内置的虚拟打印机, 可以在当前用户文档\打印精灵\outoput目录下生成一个png文件
  • printer.Print()的第一个参数支持UUID或本地文件, 如果为UUID将从打印精灵官网获取标签内容

3.3 标签设计器集成

 1var newLabelPath = @"C:\Labels\product_label.psl";
 2
 3// 新建空白标签 或 复制基础模板
 4SpiritLabel.NewLabel(
 5    templatePath,
 6    "标签名称",
 7    "标签说明",
 8    1000,  // 宽度(0.1mm)
 9    600,   // 高度(0.1mm)
10    203,   // DPI
11    @"C:\Templates\base_template.psl" // 基础模板(可选, 请修改为你自己的参考模板, 否则将创建空白标签)
12);
13
14// 启动设计器编辑标签
15SpiritLabel.Design(newLabelPath);
16
17// 保存新标签文件名, 以便后续使用

系统集成时, 务必将标签文件名(newLabelPath)保存在你的软件系统中, 用于后续打印标签或编辑修改标签.

4. 核心API详解

4.1 打印机管理

获取打印设备列表

1var printers = SpiritLabel.PrnLst();
2Console.WriteLine($"检测到 {printers.Count} 台打印机:");
3foreach (var p in printers)
4{
5    Console.WriteLine($"- {p.Name} ({p.Type})");
6}

该功能可以自动发现Windows系统安装的打印机, USB接口打印机(包括主流的条码打印机如: ZPL,TSPL,CPCL, ESC/POS打印机, 无需驱动), 网络打印机(需要通过SpiritDeskop的管理界面设置添加)

打印机连接配置

1var printer = SpiritLabel.OpenPrinter(
2    "Zebra ZT410", 
3    PrinterType.ZPL  // 显式指定协议
4);

4.2 打印控制

链式参数配置

1p.row(2)              // 设置行数
2 .col(3)              // 设置列数
3 .gap(5)              // 设置水平和垂直间距
4 .gapX(10)            // 设置水平间距
5 .gapY(15)            // 设置垂直间距
6 .quality(Qty.Hight)  // 设置打印质量
7 .flush(true)         // 设置是否立即刷新打印
8 .Print("模板ID", vars);

4.3 异常处理

1try {
2    // 打印操作...
3}
4catch (SpiritException ex) when (ex.ErrorCode == 0x1001) {
5    // 处理连接错误
6}

4.4 许可证管理

1// 添加企业许可证
2SpiritLabel.AddLicense("SPRT-XXXX-YYYY-ZZZZ");
3

SDK和桌面版共享许可, 可使用管理界面添加许可. 该函数主要方便软件开发者开发自己的的许可证管理功能

留言

登录