15LabelEngine SDK 嵌入说明

15.1 概述

LabelEngine 是 aBiao 标签打印系统的核心引擎 SDK，位于 AbiaoLabel.Shared.dll 中。 你的贴标系统直接引用此 DLL，即可完成模板加载 → 数据绑定 → 脚本评估 → ZPL 生成 → 打印的完整流程，无需依赖 BarTender 或其他第三方软件。

15.2 引用方式

方式一：NuGet 包

# 将 nupkg 添加到本地源
nuget add AbiaoLabel.Shared.1.0.0.nupkg -Source D:\nuget-local

# 项目引用
dotnet add package AbiaoLabel.Shared -s D:\nuget-local

方式二：直接引用 DLL

<Reference Include="AbiaoLabel.Shared">
  <HintPath>路径\AbiaoLabel.Shared.dll</HintPath>
</Reference>

方式三：拉源码作为子项目

git clone <仓库地址>
在解决方案中添加现有项目 → AbiaoLabel.Shared\AbiaoLabel.Shared.csproj

15.3 安装要求

SDK 运行需要安装阿标标签设计软件（v2.1+），安装目录下包含核心 DLL：

项目中直接引用 AbiaoLabel.Shared.dll，同时需要将以下依赖 DLL 复制到项目本地（如 lib/ 目录）：

lib/
├── zxing.dll                 # 条码生成
├── zxing.presentation.dll    # 条码 WPF 支持
├── Microsoft.CodeAnalysis.CSharp.Scripting.dll
├── Microsoft.CodeAnalysis.CSharp.dll
├── Microsoft.CodeAnalysis.Common.dll
├── Microsoft.CodeAnalysis.Scripting.Common.dll
├── System.Drawing.Common.dll
├── System.Private.Windows.Core.dll
└── System.Private.Windows.GdiPlus.dll

可以在 WEB/SDKTest/lib/ 和 WEB/ZplStudio/lib/ 找到完整依赖集合。

项目配置

<ItemGroup>
  <Reference Include="AbiaoLabel.Shared">
    <HintPath>C:\Program Files\iBarcode\AbiaoLabel.Shared.dll</HintPath>
  </Reference>
</ItemGroup>

完整示例项目参见：

• WEB/SDKTest/ — LabelEngine 全功能示例
• WEB/ZplStudio/ — ZPL 预览工具

15.4 快速开始

using AbiaoLabelDesigner.Services;

var engine = new LabelEngine();
engine.LoadTemplate(@"C:\templates\重量标签.iba");
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = "螺丝",
    ["PZHONGLIANG"] = "105",
    ["PTIAOMA"] = "1234567890"
});
await engine.PrintAsync("Zebra-1");

15.5 API 参考

模板加载

// 从文件加载 .iba 模板
engine.LoadTemplate(@"C:\templates\标签模板.iba");

// 从 JSON 字符串加载
engine.LoadTemplateFromJson(jsonString);

模板创建（从代码新建 .iba）

无需设计器，直接用代码创建完整的 .iba 模板并保存：

// 创建空白模板（宽 100mm × 高 60mm，2 列 3 行）
engine.CreateTemplate("我的标签", 100, 60, cols: 2, rows: 3);

// 添加文本组件
engine.AddComponent("标题", ComponentType.Text, 10, 5, 80, 10);
engine.SetProperty("标题", "Content", "Hello World");
engine.SetProperty("标题", "FontSize", 24);
engine.SetProperty("标题", "IsBold", true);

// 添加条形码
engine.AddComponent("条码", ComponentType.Barcode, 10, 20, 70, 20);
engine.SetProperty("条码", "Content", "1234567890");
engine.SetProperty("条码", "BarcodeFormat", "CODE_128");

// 保存为 .iba 文件
engine.SaveTemplate(@"C:\templates\新标签.iba");

支持的组件类型：

组件查找

// 按 Name 查找单个组件（返回 LabelComponent?）
var comp = engine.FindComponent("LOGO");

// 按 SharedName 查找一组组件
var group = engine.FindComponentsBySharedName("重量区域");

// 按类型查找
var texts = engine.FindComponentsByType<TextComponent>();
var barcodes = engine.FindComponentsByType<BarcodeComponent>();

设置组件属性（无需类型转换）

// 单个属性
engine.SetProperty("LOGO", "ImagePath", @"C:\logo.png");
engine.SetProperty("产品名称", "Content", "螺丝");
engine.SetProperty("产品名称", "FontSize", 24);
engine.SetProperty("产品名称", "IsBold", true);
engine.SetProperty("重量文本", "IsPrintable", weight > 100);

// 批量设置
engine.SetProperties("产品名称",
    ("Content", "螺丝"),
    ("FontSize", 24),
    ("IsBold", true)
);

所有可通过属性面板设置的属性均支持：

类型强转方式（替代 SetProperty）

var logo = engine.FindComponent("LOGO") as ImageComponent;
if (logo != null)
{
    logo.ImagePath = @"C:\logo.png";
    logo.Width = 80;
}

数据绑定

// 变量绑定 + 条件评估 + 脚本评估（完整流程）
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = Text1.Text,
    ["PZHONGLIANG"] = lblZL.Caption,
    ["PTIAOMA"] = GenerateBarcode()
});

// 仅变量绑定（不执行脚本和条件）
engine.BindVariables(new Dictionary<string, object>
{
    ["PNAME"] = "螺丝"
});

可打印组件控制

// 设置组件是否打印
engine.SetProperty("重量文本", "IsPrintable", weight <= 100);
engine.SetProperty("NG标识", "IsPrintable", status == "NG");

// 获取可打印组件列表
var printable = engine.GetPrintableComponents();

脚本控制（C# 脚本中设 IsPrintable）

组件的脚本编辑器中写：

// 当重量超过 100 时不打印该组件
if (Weight > 100)
{
    IsPrintable = false;
    return "超重不打印";
}
return $"重量: {Weight}kg";

引擎中可用的全局变量：Weight、Price、Quantity、ProductName、Status、IsPrintable

ZPL 生成

// 只生成可打印组件的 ZPL
string zpl = engine.GenerateZPL();
string zpl200 = engine.GenerateZPL(dpi: 200);

// 保存到文件
File.WriteAllText(@"C:\output.zpl", zpl);

打印

// 直接打印（通过 Windows 打印机驱动发送 ZPL）
await engine.PrintAsync("Zebra-1");
await engine.PrintAsync("Zebra-1", copies: 2);

// GDI 位图打印（支持普通打印机，渲染 ZPL 为图像后打印）
await engine.PrintWithGdiAsync("HP-LaserJet");
await engine.PrintWithGdiAsync("HP-LaserJet", copies: 3);

注：PrintAsync 通过 Win32 RawPrinter API（OpenPrinter → WritePrinter）将 ZPL 指令直接发送到 Windows 打印机驱动，与 BarTender 原理相同。PrintWithGdiAsync 适合不支持 ZPL 的普通打印机。

模板信息

double w = engine.LabelWidthMm;   // 模板宽度 mm
double h = engine.LabelHeightMm;  // 模板高度 mm
int rows = engine.LabelRows;      // 标签行数
int cols = engine.LabelCols;      // 标签列数

15.6 授权与试用

SDK 授权独立于标签设计器，首次运行时自动激活 90 天试用（从安装日期计算）。

• 试用期内功能无限制
• 试用到期后需购买授权码激活
• 机器码格式：GD:XXXXXXXXXXXXXXXX 或 HW:XXXXXXXXXXXXXXXX
• 未授权时 PrintAsync / PrintWithGdiAsync 将抛出授权异常

15.7 完整示例

完整可运行项目参见 WEB/SDKTest（WPF 示例，含界面和打印逻辑）和 WEB/ZplStudio（ZPL 预览工具）。

与原来 VB6 + BarTender 对比

' ===== VB6 + BarTender（原来） =====
Set btFormat = btApp.Formats.Open(App.Path & "\lab\重量标签.btw")
btFormat.SetNamedSubStringValue "PNAME", Text1.Text
btFormat.SetNamedSubStringValue "PZHONGLIANG", lblZL.Caption
btFormat.Objects.Find("LOGO").PicturePath = App.Path & "\logo.png"
btFormat.Printer = cbPrinter.Text
btFormat.IdenticalCopiesOfLabel = Val(Text10.Text)
btFormat.PrintOut

// ===== C# + LabelEngine（现在） =====
var engine = new LabelEngine();
engine.LoadTemplate(@".\lab\重量标签.iba");

engine.SetProperty("LOGO", "ImagePath", @".\logo.png");
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = Text1.Text,
    ["PZHONGLIANG"] = lblZL.Text
});

await engine.PrintAsync(cbPrinter.Text, copies: int.Parse(Text10.Text));

贴标系统完整流程

using AbiaoLabelDesigner.Services;

public class LabelPrintHelper
{
    private readonly LabelEngine _engine = new();

    public async Task<bool> PrintLabel(string templatePath, LabelData data, string printerName)
    {
        try
        {
            _engine.LoadTemplate(templatePath);

            // 设组件属性
            _engine.SetProperty("LOGO", "ImagePath", data.LogoPath);
            _engine.SetProperty("条码", "Content", data.Barcode);

            // 变量绑定 + 脚本评估
            _engine.SetData(new Dictionary<string, object>
            {
                ["PNAME"] = data.ProductName,
                ["PZHONGLIANG"] = data.Weight,
                ["PSTATUS"] = data.Status
            });

            // 打印
            return await _engine.PrintAsync(printerName, data.Copies);
        }
        catch (Exception ex)
        {
            Log.Error(ex, "打印失败");
            return false;
        }
    }
}

public class LabelData
{
    public string LogoPath { get; set; } = "";
    public string Barcode { get; set; } = "";
    public string ProductName { get; set; } = "";
    public string Weight { get; set; } = "";
    public string Status { get; set; } = "";
    public int Copies { get; set; } = 1;
}

15.8 NuGet 打包

# 生成 .nupkg
dotnet pack AbiaoLabel.Shared\AbiaoLabel.Shared.csproj -c Release -o publish_output

# 输出文件
publish_output\AbiaoLabel.Shared.1.0.0.nupkg