BarQode：C# 条码二维码生成库

【开源推荐】一个库搞定 19 种条码/二维码！BarQode：C# 条码生成库

零售系统要打 EAN-13、仓储物流要 ITF 带外框、医药邮政要 Pharmacode / IMB 四态条码、电子凭证要 QR / DataMatrix、物流单号要 MaxiCode 六边形......一个项目里混搭好几种码制，怎么破？今天介绍一个库覆盖 19 种主流码制的开源项目 ------ BarQode。

---

一、BarQode 是什么？

BarQode 是一个用 C# 编写、多目标框架支持的条码 / 二维码生成库，零第三方依赖 ，同时输出 SVG 和 PNG 两种格式。

一句话总结：19 种码制，9 个目标框架，2 种输出格式，0 个第三方依赖。

---

二、核心特性

• 🧰 19 种码制：一维 + 二维全覆盖，零售/物流/医药/邮政/GS1 场景通吃
• 🖥️ 9 个目标框架 ：.NET Framework 4.0/4.5/4.6.1/4.8、.NET Standard 2.0、.NET 6/7/8/9
• 🎨 双渲染输出 ：SVG（纯文本，全平台）+ PNG（依赖 System.Drawing）
• 🪶 零第三方依赖 ：核心编码完全独立，PNG 渲染才需 System.Drawing.Common
• 🔌 统一 API ：所有编码器实现 IBarcodeEncoder，BarcodeRenderer 一个静态类搞定全部调度
• 🛡️ 完整纠错：内置 Reed-Solomon 实现，QR / Aztec / DataMatrix / PDF417 / MaxiCode 纠错等级可配
• 🧩 特殊渲染：EAN/UPC 护条、ITF 外框、IMB 四态条、MaxiCode 六边形模块，全部按标准实现

---

三、支持的 19 种码制

二维码（2D）

码制	编码器	典型场景
QR Code	QrCodeEncoder	支付、电子凭证、网址
Aztec	AztecEncoder	交通票据、电子票
DataMatrix	DatamatrixEncoder	电子元器件、医药包装
PDF417	Pdf417Encoder	身份证、物流标签（大容量）
MaxiCode	MaxiCodeEncoder	UPS 物流（六边形 + 牛眼）

一维码（1D）

码制	编码器	典型场景
Code 128	Code128Encoder	物流、GS1
Code 39 / 93	Code39Encoder / Code93Encoder	工业控制、资产标签
EAN-13 / EAN-8	Ean13Encoder / Ean8Encoder	零售商品（带护条）
UPC-A / UPC-E	UpcAEncoder / UpcEEncoder	北美零售（带护条）
ITF	ItfEncoder	仓储物流（带外框）
CodaBar	CodaBarEncoder	图书馆、血库
MSI	MsiEncoder	超市货架
Plessey	PlesseyEncoder	老式零售
Pharmacode	PharmacodeEncoder	医药包装
RSS-14	Rss14Encoder	GS1 DataBar
IMB	ImbEncoder	美国邮政（四态条码）

---

四、3 分钟快速上手

安装

dotnet add package BarQode

一行生成 QR 码

using BarQode;
using BarQode.Encoders;
using BarQode.Rendering;
using System.IO;

var encoder = new QrCodeEncoder(new QrCodeOptions());

// SVG：纯文本，无任何依赖
string svg = BarcodeRenderer.RenderSvg(encoder, "https://gitee.com", null);
File.WriteAllText("qrcode.svg", svg);

// PNG：图片字节
byte[] png = BarcodeRenderer.RenderPng(encoder, "https://gitee.com", null);
File.WriteAllBytes("qrcode.png", png);

就这两步：建编码器 → 调 BarcodeRenderer。不管是 QR 还是 EAN-13、ITF、MaxiCode，API 长一个样。

---

五、实战示例：6 种典型场景

1. QR 码（中文 + 高容错）

var opts = new QrCodeOptions {
    ErrorLevel = QrCodeErrorCorrectionLevel.H,   // 30% 容错
    CharacterSet = "UTF-8",                       // 支持中文
    Width = 320, Height = 320, Margin = 4,
    TextPosition = TextPosition.Bottom
};
var encoder = new QrCodeEncoder(opts);
byte[] png = BarcodeRenderer.RenderPng(encoder, "中文 QR 测试", opts);

2. EAN-13（带护条 + 文本分段）

零售商品条码，护条自动加高、文本按护条区段自动分三段居中------完全符合标准。

var encoder = new Ean13Encoder();
encoder.Options.GuardBarExtraHeight = 25;
encoder.Options.Height = 140;
encoder.Options.TextPosition = TextPosition.Bottom;
byte[] png = BarcodeRenderer.RenderPng(encoder, "5901234123457", encoder.Options);

3. ITF（带外框）

仓储物流标配，ITF 标准要求外框，BarQode 默认就给你画好（4 条填充矩形，上下紧贴条码）。

var encoder = new ItfEncoder();
encoder.Options.ShowBorder = true;
encoder.Options.BorderWidth = 6;
encoder.Options.Height = 120;
byte[] png = BarcodeRenderer.RenderPng(encoder, "1234567890", encoder.Options);

4. IMB（四态条码）

美国邮政智能邮件条码，Full / Ascender / Descender / Tracker 四种高度自动编码。

var encoder = new ImbEncoder();
encoder.Options.FourState = true;
encoder.Options.Height = 120;
byte[] png = BarcodeRenderer.RenderPng(encoder, "01234567094987654321", encoder.Options);

5. MaxiCode（六边形 + 牛眼）

UPS 物流码，标准六边形模块 + 中央同心圆牛眼。BarQode 先画牛眼（背景层）再画六边形（前景层），避免牛眼白环遮挡数据。

var encoder = new MaxiCodeEncoder();
encoder.Options.Mode = MaxiCodeMode.Mode4;
encoder.Options.Hexagonal = true;
encoder.Options.Width = 320;
encoder.Options.Height = 320;
byte[] png = BarcodeRenderer.RenderPng(encoder, "Hello MaxiCode!", encoder.Options);

6. Code128 + GS1

带 GS1 应用标识符的物流码，(01) 这种括号语法自动解析。

var encoder = new Code128Encoder();
encoder.Options.CompactEncoding = true;
encoder.Options.GS1Format = true;
encoder.Options.Height = 120;
encoder.Options.TextPosition = TextPosition.Bottom;
string svg = BarcodeRenderer.RenderSvg(encoder, "(01)12345678901231", encoder.Options);

---

六、框架兼容性：从 .NET 4.0 到 9.0 全覆盖

这是 BarQode 的一个亮点------真的支持 .NET Framework 4.0。老项目不用升级框架也能用。

框架	PNG 支持	说明
net40 / net45 / net461 / net48	✅	.NET Framework 自带 GDI+
netstandard2.0	✅	System.Drawing.Common 8.0
net6.0 / net7.0	✅	System.Drawing.Common 8.0
net8.0 / net9.0	✅	System.Drawing.Common 9.0

⚠️ Linux/macOS 用 PNG 渲染需装 libgdiplus；只输出 SVG 则无此限制。

为了兼容 net40，库内做了不少工程处理：禁用隐式 using、禁用可空引用类型、nameof 全部替换为字符串字面量、属性用显式 getter、特性在构造函数中赋值。细节拉满。

---

七、架构设计：统一 API 的秘密

所有编码器实现统一接口，BarcodeRenderer 自动判断 1D / 2D 并分派：

Encoder.Encode1D / Encode2D   →   原始编码结果（int[] / BarcodeMatrix）
        │
        ▼
BarcodeRenderer.RenderSvg / RenderPng(encoder, data, options)
        │   内部：ApplyEncoderMetadata（自动填护条索引 / 文本分段 / PureBarcode 同步）
        ▼
SvgRenderer / PngRenderer   →   SVG 字符串 / PNG byte[]

接口层级：

public interface IBarcodeEncoder {           // 根接口
    object Encode(string data);
    string BarcodeType { get; }
}
public interface I1DBarcodeEncoder : IBarcodeEncoder {   // 一维码
    int[] Encode1D(string data);
}
public interface I2DBarcodeEncoder : IBarcodeEncoder {   // 二维码
    BarcodeMatrix Encode2D(string data);
}
public interface IGuardBarEncoder {          // 带护条（EAN/UPC）
    int[] GetGuardBarIndices();
    TextSegmentLayout[] GetTextSegments(string data);
}

调用方完全不用关心码制差异 ------传编码器、传数据、传选项，剩下的 BarcodeRenderer 搞定。

---

八、踩过的坑（技术干货）

开发过程中踩了不少标准里的暗坑，挑几个有意思的：

1. DataMatrix 的本原多项式 ：用的是 0x12D（x⁸+x⁵+x³+x²+1），不是 QR 码的 0x11D。用错多项式，RS 编码自洽性检查能过，但真实扫描器全拒------这个 bug 找了好久。
2. QR 版本信息位序：V7+ 的版本信息必须 LSB-first 存放。如果按 MSB-first，所有 V7+ 二维码都扫不出来。
3. DataMatrix 253 状态填充 ：必须用条件减法，不能用取模。(value + pseudoRandom) % (maxVal+1) 在和等于 maxVal+1 时会错算成 0（应为 1）。
4. MaxiCode 牛眼遮挡：六边形和牛眼有重叠区域，必须先画牛眼再画六边形，否则牛眼的白环会把数据六边形挖空。
5. EAN/UPC 文本分段：文本不是一整串居中，而是按护条分隔的三个区段分别居中，这是扫描器和人眼对齐的关键。

完整的踩坑记录和工程约定都在项目的 project_memory.md 里，感兴趣的可以去源码仓库翻。

---

九、项目地址

项	链接
NuGet	dotnet add package BarQode
项目地址	gitee.com/li_qi_lang/...
许可证	Apache License 2.0

如果这个库对你有帮助，欢迎 Star ⭐ 支持！也欢迎提 Issue、PR 一起完善。

---

十、总结

BarQode 适合谁？

• 需要在 C# 项目里生成多种条码/二维码的开发者
• 老项目（.NET Framework 4.0+）想直接引用、不想升级框架
• 对第三方依赖敏感、想要零依赖的纯净库
• 需要标准合规的护条、外框、四态、六边形等特殊渲染

19 种码制、9 个框架、2 种输出、0 依赖------一个库搞定条码生成，这就是 BarQode。

---

📌 如果你也在做条码/二维码相关的项目，欢迎留言交流使用场景，作者会持续维护这个库。

觉得有用的话，点个赞 + 收藏 + Star 三连，是对开源作者最大的鼓励！我们下篇见 👋