简介面向Delphi开发者的ZXing条形码扫描库封装包支持从Delphi XE到10.3.3 Rio多版本可快速集成二维码、Code 128、Data Matrix、EAN-13等格式的识别与生成功能。资源共263个文件压缩包15.5MB以92个pas单元源码为核心附带fmx界面组件、dpr工程示例、deployproj部署配置及png图片素材结构完整可直接导入项目参考。已有505人学习下载。包内包含TZXingScanner可视化扫描控件及视频流/静态图像解码示例配套Android静态库和自定义码型素材开发者可在此基础上调整摄像头参数、扫描区域与解码灵敏度实现条码生成、实时识别及结果事件处理等完整业务流程适合需要为一至多个Delphi版本应用添加扫码能力的初中级开发者。1. 扫码这件事别从零造轮子ZXing.Delphi 3.9.0 到底解决什么要在一个用 Delphi 10.3 开发的桌面工具里加扫码能力最稳妥的方案是选 ZXing.Delphi 3.9.0。它把 Java 版 ZXing 的解码逻辑完整移植到 Delphi 的 VCL/FMX 环境下Windows、Android、iOS 都能直接跑支持 QR Code、Code128、EAN/UPC、DataMatrix 等常见格式。做物流面单识别的、做支付码激活的、做内部资产盘点的人都会碰到原生 Delphi 没有扫码 API 的处境。与其去接一个收费控件不如用这套源码级的库自己封装。这篇文章会把拆包、装库、调接口、配参数、躲坑这几个阶段完整串起来照着做就能把扫码功能落地。2. 认识 ZXing.Delphi 3.9.0代码结构、安装路径与最小验证2.1 压缩包里有什么核心单元与依赖解压 ZXing.Delphi-3.9.0.zip 之后你不会看到一键安装的 exe而是一套完整源码目录。核心代码按命名空间拆成多个 .pas 文件ZXing 这个前缀贯穿所有单元。实际写代码时有三个单元最常用ZXing.ScanManager 里有 TZXingScanManager 和 TZXingScannerManager负责把 TBitmap 包装成 ZXing 需要的图像ZXing.BarcodeFormat 定义了 TBarCodeFormat 枚举QR_CODE、CODE_128、EAN_13、PDF417 这些格式都在里面ZXing.ReadResult 定义了 TReadResult也就是解码结果包含 Text、Bytes、BarcodeFormat 和定位点。依赖上有个硬门槛3.9.0 这个版本目标编译器是 Delphi 10.3 及以上因为它在内部大量使用了泛型、匿名方法和新版 RTL 类型。如果你还在用 XE8 之类的老版本不建议直接拿这个包否则会遇到语法不兼容。图形部分有 VCL 和 FMX 两套使用方式但 ScanBitmap 的输入输出是基于 FMX.Graphics 的 TBitmapVCL 项目需要先把 TBitmap 做一次转换或者直接用 FMX 架构成完成扫码窗体。解压后的目录名最好改成纯英文不要带空格和中文。Delphi 的 Library 搜索路径在带空格的目录下偶尔会截断路径我在一台 Windows Server 上因为这个原因浪费过近半小时。我的习惯是统一命名成 ZXing.Delphi-3.9.0再放进一个没有空格的路径下。2.2 在 Delphi 10.3 里安装 Library 路径我一般不做组件安装直接把源码目录加到 IDE 的 Library 路径需要的时候用 uses 引入对应单元。这样后续换版本只需替换目录不会被 IDE 的 bpl 包污染。操作步骤Tools - Options - Delphi Options - Library在 Library path 里把源码根目录加进去Win32 和 Win64 平台都要加。然后新建一个项目在代码里 uses ZXing.ScanManager、ZXing.ReadResult编译不报“找不到单元”就说明路径配置对了。更完整的路径配置参考下表配置项推荐值 / 动作源码目录解压后的 Source 根目录Win32 / Win64 Library path都指向同一 Source 目录Unit scope names保持默认直接 uses ZXing.*组件安装可选编译并安装 ZXing.Delphi.dpk 后可在组件面板看到 TZXingScannerManager如果你是 Android 目标理论上同一个源码目录会被 IDE 自动带入编译不需要额外复制。但要注意 Project - Options - Packages 里不要把编译好的调试期包限制在 Windows 平台否则开启 Android 后会出现搜索路径不包含源码的情况。如果编译时提示找不到 ZXing.Core.pas先检查是否把 Source 子目录又加了一层。常见做法是把源码根目录直接加进去编译器按搜索路径逐级寻找而不是靠项目文件里的相对路径。2.3 用自带 Demo 做最小验证ZXing.Delphi 3.9.0 通常带一个 Demos 目录里面有 FMX 和 VCL 示例。第一次跑的时候直接打开 FMX 版本它已经在窗体上放了一个 TZXingScannerManager 关联摄像头组件。如果你在 Windows 桌面环境没有摄像头Demo 里一般会有 Load Image from File 选项选一张二维码 PNG 就能立刻看到识别效果。这个最小验证环节值得认真做因为环境问题都集中在“路径有没有配好”这个点上。如果加载图片后返回空先别怀疑算法打开 Demo 源码看它是用 ScanBitmap 还是 ScanFile 完成解码。常见做法是先把图片加载成 TBitmap再调 TZXingScanManager.ScanBitmap。识别成功后TReadResult.Text 就是能看到结果的字符串。把这一小段验证代码记下来之后你的代码风格也可以按这个结构写uses ZXing.ReadResult, ZXing.BarcodeFormat; procedure DumpResult(const AResult: TReadResult); begin if AResult nil then OutputDebugString(No barcode found) else OutputDebugString(PChar(Format(%s | format%d | ts%f, [AResult.Text, Integer(AResult.BarcodeFormat), AResult.Timestamp]))); end;这里的逻辑很简单判断 AResult 是否为 nil然后取 Text、BarcodeFormat 和 Timestamp。输出到调试串不是最终产品形态但能快速确认整条链路是否通。Integer(AResult.BarcodeFormat) 把枚举转成数字方便在日志里对比格式。3. 把扫码集成进你的 Delphi 窗体两种调用方式与参数解读3.1 方式一拖控件走 TZXingScannerManager最省事的路径是在 FMX 窗体上放一个 TZXingScannerManager并把 TCameraComponent 也拖上去然后写好 OnBarcodeScan 事件回调。这也是实时扫码场景下最常用的方式摄像头预览由组件内部处理不需要自己维护帧数据。初始化时要把两者关联起来var FScanManager: TZXingScannerManager; ACamera: TCameraComponent; begin FScanManager : TZXingScannerManager.Create(Self); FScanManager.CameraComponent : ACamera; // 关联摄像头预览 FScanManager.OnBarcodeScan : HandleBarcodeScan; // 绑定识别回调 FScanManager.Active : True; // 启动识别 end;逻辑说明TZXingScannerManager 负责解码和管理视频帧CameraComponent 告诉它从哪一路摄像头取图OnBarcodeScan 是每当解码器成功解析出一段条码后触发的事件Active : True 让组件开始从摄像头取帧并持续尝试解码。注意这里整个过程是异步的不会卡住 UI 线程。事件方法建议这样写procedure TFrmScan.HandleBarcodeScan(AResult: TReadResult); begin if Assigned(AResult) and (AResult.Text ) then begin FScanManager.Active : False; // 扫到一次就先停避免重复触发 MemoLog.Lines.Add(Format([%s] %s, [AResult.FormatToString, AResult.Text])); end; end;参数说明AResult.FieldAccess 需要注意FormatToString 返回的是 “QR_CODE”“EAN_13” 这样的字符串适合直接打日志。为什么判断 Text 非空因为某些纯条码可能被识别但内容为空这种结果没有业务意义宁可跳过也不要让相机闪个不停。识别完成后把 Active 设为 False 是一个常见做法可以避免在连续模式下同一张码被反复上报。3.2 方式二纯代码调用 ScanBitmap 处理图片离线场景或 Windows 桌面工具不需要摄像头直接拿一张图片文件也能识别。我习惯把这一层封装成函数输入图片路径返回解码字符串uses System.SysUtils, FMX.Graphics, ZXing.ScanManager, ZXing.ReadResult, ZXing.DecodeHints, ZXing.BarcodeFormat; function ScanImageFile(const AFileName: string): string; var LBitmap: TBitmap; LScanner: TZXingScanManager; LHints: TDecodeHints; LResult: TReadResult; begin Result : ; LBitmap : TBitmap.CreateFromFile(AFileName); try LScanner : TZXingScanManager.Create; try LHints : TDecodeHints.Create; try LHints.TryHarder : True; // 低对比度图需要加大搜索力度 LHints.PureBarcode : False; // 图片内可能有条码外元素 LResult : LScanner.ScanBitmap(LBitmap, LHints); try if Assigned(LResult) then Result : LResult.Text; finally LResult.Free; end; finally LHints.Free; end; finally LScanner.Free; end; finally LBitmap.Free; end; end;逻辑说明TBitmap.CreateFromFile 从磁盘加载位图ZXing 内部会把位图转成灰度图再做二值化、定位和解码。TDecodeHints 是调优入口TryHarderTrue 会指示引擎对边缘条件做更深层搜索代价是耗时增加PureBarcodeFalse 表示允许图像里存在条码以外的元素。最后 LResult.Text 就是需要的内容用完立刻 Free避免泄漏。这个函数里的参数不是拍脑门定的。针式打印的快递面单对比度往往很低TryHarderFalse 时 Code128 经常解不出来改成 True 后识别率明显上升反过来说如果是包装盒上高对比度的二维码TryHarderTrue 会让单张识别时间翻倍。后面第 4 章会专门讲怎么按场景取舍。3.3 解码结果对象的字段与回调时机一次解码成功后你拿到的 TReadResult 不光是文本还有一些对业务有用的字段字段类型说明Textstring解码后的文本最常用BytesTBytes原始字节流适合非 UTF8 内容BarcodeFormatTBarCodeFormat识别出的格式可用来过滤噪音TimestampTDateTime解码时刻的时间戳PointsTArray条码四个角点的像素坐标回调时机需要分清ScanBitmap 是同步调用线程会一直阻塞到返回结果或失败。如果你在主线程里直接处理一张 3000x4000 的大图窗体就会卡住几百毫秒。而 TZXingScannerManager 的 OnBarcodeScan 事件是异步的组件内部已经把解码放到工作线程。两者的 API 形状完全不同不要在 ScannerManager 的事件里再调用同步 ScanBitmap 去解摄像头帧容易出现数据竞争。我见过有人把同步 ScanBitmap 的结果塞到事件参数里导致摄像头回调乱了。这里给一个原则凡是走 TZXingScannerManager 的代码只写在事件回调里凡是自己创建 TZXingScanManager 的就默认同步需要异步请自己开线程。第 4 章的线程模型就是围绕这个原则展开的。4. 识别率与性能调优格式白名单、图像预处理与线程模型4.1 按场景收缩解码格式白名单ZXing 默认的行为是拿所有已支持格式去尝试QR 解不出再试 EANEAN 不行再试 DataMatrix一次识别可能要遍历一遍格式列表才能告诉你失败。小图、单格式时无妨但流水线扫码或批量图片场景多余的尝试会让耗时从 50ms 变成 300ms。收缩格式白名单是提升速度和准确率最直接的手段。代码上通常是给 TDecodeHints 的 Formats 赋值LHints : TDecodeHints.Create; try LHints.Formats : [TBarCodeFormat.QR_CODE, TBarCodeFormat.CODE_128]; // 只留业务需要的格式 LResult : LScanner.ScanBitmap(LBitmap, LHints); finally LHints.Free; end;Formats 是集合类型把需要的枚举填进去即可。常见业务对照支付码只留 QR_CODE物流面单留 CODE_128 和 CODE_39商品结算留 EAN_13/UPC_A登机牌通常用 PDF417。如果发现某个格式一直识别出来但内容不是想要的比如 Code39 被误判成 Code128也可以通过白名单把 Code39 过滤掉。白名单不是越多越好。有些格式的前缀规则相近比如 EAN-8 和 UPC-A 同时开启时短条码更容易被误匹配。我的习惯是把所有与业务无关的格式全部关闭宁可识别失败重拍一次也不要让日志里堆满无意义结果。4.2 图像预处理缩放、灰度、旋转对识别的影响ScanBitmap 不是万能的。对超大图、暗光图、竖版旋转图识别率和耗时都不理想。常见做法是解码前先做三件事。第一是缩放。ZXing 内部会自行下采样分析但原图 4000 像素时内存和第一次灰度转换的 CPU 成本很高。把长边缩到 1024 到 1280 像素识别率基本不变速度能翻倍。注意保持等比例不要压扁条码否则 Code128 的宽窄比例会变坏。第二是灰度。ZXing 内部会做灰度转换但彩色背景噪声容易干扰二值化阈值。你可以提前把位图灰度化尤其是红色背景的二维码红色通道和黑色条码的对比度不足会导致二值化断裂。第三是旋转。ScanBitmap 不主动猜测旋转角度对竖版拍照得到的横向 QR Code需要自己做角度尝试。固定拍照台场景可以对图片做 0/90/180/270 度四次尝试如果担心速度就只对 QR_CODE 做旋转因为 QR 有三个定位角旋转一次不影响内部解码。下面是一个缩放到最大边的示例思路function ScaleToMax(const ASrc: TBitmap; const AMaxSize: Integer): TBitmap; var LScale: Double; LW, LH: Integer; begin Result : TBitmap.Create; try LScale : AMaxSize / Max(ASrc.Width, ASrc.Height); if LScale 1 then begin LW : Round(ASrc.Width * LScale); LH : Round(ASrc.Height * LScale); // 用 Canvas.Draw 或专用缩放函数从 ASrc 绘制到 Result // 这里省略具体绘制核心是把 LScale 算对 end else Result.Assign(ASrc); except Result.Free; raise; end; end;注意这个骨架代码不能直接用于生产FMX 的 TBitmap.Resize 在不同版本行为有差异真正落地时通常用 TBitmap.Create(LW, LH) 配合 Canvas.Draw或直接使用 TBitmapCodec。AMaxSize 我一般设 1024设太小会降低小条码的像素宽度反而解不出来。4.3 主线程卡顿问题把解码放到后台线程同步 ScanBitmap 在后台没问题但 UI 线程里直接调用必然丢帧。更好的模式是自己开一个 TThread把位图传进去解码完成后再回到主线程回调。我封装过的最小版本大致长这样type TScanJobThread class(TThread) private FBitmap: TBitmap; FResultText: string; FOnFinished: TProcstring; protected procedure Execute; override; public constructor Create(ABitmap: TBitmap; AOnFinished: TProcstring); end; implementation constructor TScanJobThread.Create(ABitmap: TBitmap; AOnFinished: TProcstring); begin inherited Create(False); // 创建后立即运行 FBitmap : ABitmap; // 主线程传入位图 FOnFinished : AOnFinished; end; procedure TScanJobThread.Execute; var LScanner: TZXingScanManager; LHints: TDecodeHints; LResult: TReadResult; begin LScanner : TZXingScanManager.Create; LHints : TDecodeHints.Create; try LHints.Formats : [TBarCodeFormat.QR_CODE]; LResult : LScanner.ScanBitmap(FBitmap, LHints); if Assigned(LResult) then FResultText : LResult.Text; finally LResult.Free; LHints.Free; LScanner.Free; FBitmap.Free; // 线程内部释放避免主线程提前释放 end; Synchronize(DoSync); end;代码里的关键点构造参数传入一张位图位图的生命周期由线程接管Execute 在线程池的上下文里做同步 ScanBitmap最后用 Synchronize 回到主线程触发 FOnFinished(FResultText)。这里省略了 DoSync 的具体实现它只需要调用 FOnFinished 即可。TProc 是 Delphi 10.3 很常用的泛型匿名方法。这个模型之后的坑在于并发。多张图片批量识别时我建议同时运行的扫描线程控制在 2 到 3 个不要用默认线程池直接铺满全部 CPU 核心。ZXing 的解码器实例不是全局单例多个实例同时跑虽然不会崩但 CPU 会迅速打满反而因为频繁切换降低吞吐。5. 避坑手记我在 Delphi 10.3 上遇到的五个典型问题5.1 现象IDE 搜索路径加好了却提示 “Unit ‘ZXing.Core’ not found”原因路径加到了 Library 的 Win32 平台但当前活动目标平台是 Win64 或 Android而 IDE 的搜索路径是分平台保存的。另一个常见原因是解压目录带空格比如 “ZXing.Delphi-3.9.0 (1)”编译器在拼接路径时截断。解决在 Tools - Options - Library 里把 Win32 和 Win64 都加上同一个 Source 目录同时把目录改名为 ZXing.Delphi-3.9.0 这样的纯英文路径重新编译。从那以后我每次解压第三方源码包都会先规范化目录名。5.2 现象Android 上摄像头权限已经勾了运行后预览黑屏OnBarcodeScan 一个都不触发原因ZXing.Delphi 3.9.0 在 Android 目标上依赖 TCameraComponent 的权限声明。只勾选 “Camera” 权限不够部分设备需要在 AndroidManifest.xml 里显式声明 android.permission.CAMERA并且权限申请流程要在相机启动前完成。我遇到的那次正好是测试机系统里相机状态异常。解决在项目管理器的 AndroidManifest.xml 里补全权限并在代码里先执行权限请求等回调成功后再把 FScanManager.Active 设为 True不要一进界面就开相机。5.3 现象用 ScanBitmap 扫同一张二维码Demo 能识别出来我的函数却返回空原因Demo 在解码前把位图转成了灰度图而我直接把 24 位 PNG 交给 ScanBitmap。ZXing 对彩色位图按像素通道转换遇到红底二维码时红色通道和黑色条码的对比度不足二值化后条码断裂。解决先转灰度或者对 BGR 位图做通道分离把 RGB 转成亮度值。另一个常见原因是 TDecodeHints.Formats 里没开 QR_CODE只留了 Code128自然扫不出二维码。解决后我给自己定了一条规矩新场景先写一个最小复现脚本用同一位图分别跑 Demo 和自定义函数直到输出一致再继续集成。5.4 现象Release 模式下连续扫描偶发 “Access violation at address...”Debug 又很难复现原因回调里保存了 TReadResult 对象。TZXingScannerManager 的 OnBarcodeScan 事件里AResult 由组件内部负责释放当你把它保存到字段里下次回调触发时上一次的对象已经被释放访问就崩。解决回调里只读取 Text 并拷贝到字符串字段不要持有 TReadResult 引用。如果确实需要完整结果做一个深拷贝。另外回调频率很高不要在回调里创建或释放大量对象避免踩中时机。5.5 现象批量识别 500 张图片前 200 张正常后面越来越慢内存涨了 200MB原因每轮解码都创建了新的 TZXingScanManager 和 TDecodeHints但在异常路径上忘记释放循环中的 TBitmap 局部变量如果放在 try 的 finally 外异常时也会泄漏。解决把每轮解码写成“创建、使用、释放”严格对称的结构释放语句放在 finally 中。图片文件预读到内存再解码比每次从磁盘读快很多。批量场景建议使用线程池但线程数量别超过 CPU 核心数的两倍。6. 进阶封装一个异步解码服务并验证识别率6.1 封装 TScanJob 线程类把第 4 章的线程模型整理成复用服务。一个典型的调用方式如下var LJob: TScanJobThread; begin LJob : TScanJobThread.Create( ABitmap, procedure(AResultText: string) begin if AResultText then Log.Info(decode ok: AResultText) else Log.Warn(decode fail); end ); // LJob 内部会自动释放你可以在这里保存指针用于取消 end;使用 TScanJobThread 时构造函数传入原始位图和匿名回调线程内部完成 ScanBitmap、释放位图、切回主线程回调整个闭环。需要注意 ABitmap 在传入后主线程不要再访问它所有权已经转移给线程。6.2 用标准测试图做回归验证我会准备 25 张测试图覆盖 QR、Code128、EAN-13、竖版旋转、模糊阴影、小尺寸条码这六类。每张图记录识别是否成功和耗时然后调整格式白名单和 TryHarder 参数看整体通过率。一张图从 80ms 变成 200ms 不可怕可怕的是同一张图换个角度就失败。测试图要固定版本放到资源目录里每次改动 ZXing 相关代码后都跑一遍回归列表。验证数据可以用日志输出也可以存到 CSV 表格里对比。我常用的做法是每张图输出格式、结果、耗时最后统计识别成功率。对定位点 Points 的检查也很重要如果 Points 返回的坐标明显偏离图片中心说明解码器有误匹配这类图片宁可不识别也别放行。整套验证跑完再把通过率不达标的图单独挑出来重新微调预处理参数。那次我用 3.9.0 做物流面单识别就是因为只测了三张干净二维码就上线结果现场遇到一堆糊的、反光的、畸形的 Code128识别率只有六成。重新走了格式白名单、灰度化、后台线程异步扫描这三步又用 300 张现场图片回归才把通过率拉到 95% 以上。从那以后我每次接扫码库都强制自己先跑一遍测试图集版本升级也重新跑一次再也不敢拿“Demo 能扫出来”当验收标准。希望帮到你。本文还有配套的精品资源点击获取