MagoZplRender 1.0.3

Mago.ZplRender 类库说明文档

概述

Mago.ZplRender 是一个用于将 PDF 文件转换为 ZPL（Zebra Programming Language）命令的 .NET 类库。该类库可以将 PDF 文档渲染为图像，然后转换为适用于 Zebra 标签打印机的 ZPL 命令字符串。

主要功能

• PDF 处理：支持从 PDF 文件、字节数组、Base64 字符串或流中读取 PDF
• PDF 展平：自动展平 PDF 表单字段，确保所有内容可见
• 图像渲染：将 PDF 页面渲染为高质量图像
• 图像处理：
  • 自动旋转图像以匹配标签方向
  • 智能缩放以适配标签尺寸
  • 多种单色转换模式（二进制、抖动、优化抖动）
• ZPL 编码：支持多种 ZPL 编码格式（ASCII Hex、ASCII 压缩、Base64、Z64）
• 批量处理：支持多页 PDF 和多图像处理

系统要求

• .NET 8.0 或更高版本
• 支持 Windows、Linux、macOS、iOS、Android 等平台

依赖项

• itext (9.3.0) - PDF 处理
• itext.bouncy-castle-adapter (9.3.0) - 加密支持
• PDFtoImage (5.0.0) - PDF 渲染
• SharpZipLib (1.4.2) - 压缩支持
• SkiaSharp - 图像处理（通过 PDFtoImage 间接依赖）

快速开始

基本用法

using Mago.ZplRender;

// 从 PDF 文件生成 ZPL 命令
string zplCommand = ZplGenerator.FromPdfFile("label.pdf");

// 从 PDF 字节数组生成 ZPL 命令
byte[] pdfBytes = File.ReadAllBytes("label.pdf");
string zplCommand = ZplGenerator.FromPdf(pdfBytes);

// 从 Base64 字符串生成 ZPL 命令
string pdfBase64 = Convert.ToBase64String(pdfBytes);
string zplCommand = ZplGenerator.FromPdf(pdfBase64);

使用自定义选项

var options = new ZplOptions
{
    LabelWidthMm = 100,           // 标签宽度（毫米）
    LabelHeightMm = 150,          // 标签高度（毫米）
    Dpi = 203,                    // 打印分辨率
    MarginRatio = 0.95f,          // 边距比例（0-1）
    MonoMode = MonoMode.DitherOptimized,  // 单色转换模式
    EncodingKind = BitmapEncodingKind.Z64,  // 编码方式
    Threshold = 128               // 黑白阈值（0-255）
};

string zplCommand = ZplGenerator.FromPdf(pdfBytes, options);

核心类说明

ZplGenerator

主入口类，提供从 PDF 生成 ZPL 命令的静态方法。

主要方法

• FromPdfFile(string pdfPath, ZplOptions? options = null) - 从文件路径生成
• FromPdf(byte[] pdfBytes, ZplOptions? options = null) - 从字节数组生成
• FromPdf(string pdfAsBase64String, ZplOptions? options = null) - 从 Base64 字符串生成
• FromPdfStream(Stream pdfStream, bool leaveOpen = false, ZplOptions? options = null) - 从流生成
• FromPdfAsync(byte[] pdfBytes, ZplOptions? options = null, CancellationToken cancellationToken = default) - 异步生成（.NET 6+）

ZplOptions

ZPL 生成选项配置类，用于自定义标签生成参数。

主要属性

MonoMode

单色转换模式枚举。

• Binary - 二进制模式：直接阈值转换，速度快但质量较低
• Dither - 抖动模式：使用 Floyd-Steinberg 抖动算法，质量较好
• DitherOptimized - 优化抖动模式：在抖动基础上优化，平衡质量和性能（推荐）

BitmapEncodingKind

位图编码方式枚举。

• AsciiHex - 十六进制字符串（不推荐，输出可能过大）
• AsciiCompressed - ASCII 压缩（默认，比 AsciiHex 节省空间）
• MimeBase64 - Base64 编码（不推荐，输出可能过大）
• Z64 - Deflate 压缩 + Base64（推荐，压缩率最高）

ZplComposer

ZPL 组合器类，负责将多个图像组合成最终的 ZPL 命令。

主要方法

• FromImages(IEnumerable<byte[]> imageList, ZplOptions options) - 从图像列表生成 ZPL 命令

ZplEncoder

ZPL 编码器类，负责将单色位图编码为 ZPL 命令字符串。

主要方法

• Encode(SKBitmap bmp, int offsetX, int offsetY, int labelW, int labelH, ZplOptions options) - 编码位图为 ZPL 命令

ImageTransformer

图像转换类，负责图像的旋转、缩放和单色转换。

主要方法

• RotateIfNeeded(SKBitmap bmp, int targetW, int targetH) - 根据目标尺寸判断是否需要旋转图像
• Scale(SKBitmap bmp, float ratio) - 按比例缩放位图
• ConvertToMono(SKBitmap bmp, MonoMode mode, byte threshold = 128) - 将彩色/灰度位图转换为单色

PdfProcessor

PDF 处理类，负责 PDF 的展平和渲染操作。

主要方法

• Flatten(byte[] pdfBytes) - 展平 PDF 表单字段
• RenderToImages(byte[] pdfBytes, int dpi) - 将 PDF 的所有页面渲染为 PNG 图像

使用示例

示例 1：基本转换

using Mago.ZplRender;

// 最简单的用法
string zpl = ZplGenerator.FromPdfFile("label.pdf");
Console.WriteLine(zpl);

示例 2：自定义标签尺寸和分辨率

var options = new ZplOptions
{
    LabelWidthMm = 50,   // 50mm 宽
    LabelHeightMm = 30,  // 30mm 高
    Dpi = 300            // 300 DPI 高分辨率
};

string zpl = ZplGenerator.FromPdf(pdfBytes, options);

示例 3：使用最佳质量设置

var options = new ZplOptions
{
    MonoMode = MonoMode.DitherOptimized,      // 优化抖动模式
    EncodingKind = BitmapEncodingKind.Z64,    // Z64 压缩编码
    Threshold = 140,                          // 调整阈值以获得更好的对比度
    MarginRatio = 0.98f                       // 更大的边距比例
};

string zpl = ZplGenerator.FromPdf(pdfBytes, options);

示例 4：批量打印设置

var options = new ZplOptions
{
    PrintQuantity = 10        // 打印 10 份
};

string zpl = ZplGenerator.FromPdf(pdfBytes, options);

示例 5：标签偏移调整

var options = new ZplOptions
{
    LabelTop = 5,      // 向下偏移 5 点行
    LabelShift = -10   // 向左偏移 10 点
};

string zpl = ZplGenerator.FromPdf(pdfBytes, options);

示例 6：异步处理

using Mago.ZplRender;

byte[] pdfBytes = await File.ReadAllBytesAsync("label.pdf");
string zpl = await ZplGenerator.FromPdfAsync(pdfBytes);

示例 7：从图像生成 ZPL

var images = new List<byte[]>
{
    File.ReadAllBytes("image1.png"),
    File.ReadAllBytes("image2.png")
};

var options = new ZplOptions
{
    LabelWidthMm = 100,
    LabelHeightMm = 150
};

string zpl = ZplComposer.FromImages(images, options);

工作流程

1. PDF 输入：接收 PDF 文件、字节数组、Base64 字符串或流
2. PDF 展平：自动展平 PDF 表单字段，确保所有内容可见
3. PDF 渲染：将 PDF 页面渲染为 PNG 图像（灰度）
4. 图像处理：
   • 自动旋转以匹配标签方向
   • 智能缩放以适配标签尺寸（保持宽高比）
   • 转换为单色（黑白）位图
5. ZPL 编码：将单色位图编码为 ZPL 命令字符串
6. 输出：返回完整的 ZPL 命令字符串

性能优化建议

1. 编码方式选择：

   • 对于小标签，使用 AsciiCompressed（默认）
   • 对于大标签或复杂图像，使用 Z64 以获得最佳压缩率

2. 单色转换模式：

   • 简单图像：使用 Binary（最快）
   • 复杂图像：使用 DitherOptimized（推荐，平衡质量和性能）
   • 最高质量：使用 Dither（较慢但质量最好）

3. 分辨率设置：

   • 标准标签：203 DPI（默认）
   • 高精度标签：300 DPI
   • 注意：更高的 DPI 会增加处理时间和输出大小

4. 阈值调整：

   • 较暗的图像：降低阈值（如 100-120）
   • 较亮的图像：提高阈值（如 140-160）
   • 默认值：128

注意事项

1. 内存管理：类库会自动管理图像内存，但在处理大量大文件时请注意内存使用
2. PDF 兼容性：支持标准 PDF 格式，某些特殊格式可能需要预处理
3. 标签尺寸：确保设置的标签尺寸与实际标签纸匹配
4. DPI 设置：DPI 应与打印机分辨率匹配以获得最佳效果
5. 多页 PDF：多页 PDF 会生成多个标签

错误处理

try
{
    string zpl = ZplGenerator.FromPdfFile("label.pdf");
    // 使用 ZPL 命令
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"文件未找到: {ex.Message}");
}
catch (ArgumentException ex)
{
    Console.WriteLine($"参数错误: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"处理错误: {ex.Message}");
}

许可证

请参考项目根目录的许可证文件。

技术支持

如有问题或建议，请联系开发团队或提交 Issue。