简介面向使用Delphi开发原生Android应用的工程师本方案全部以Delphi代码实现安卓二维码扫码功能。与直接调用Zxing等第三方识别库不同项目自行完成摄像头图像捕获、预处理、二值化及识别流程并将核心逻辑封装为静态库以减少运行时依赖、保障扫码不卡顿适合对隐私可控、离线环境或底层原理有要求的场景。压缩包共14个文件大小约29.17MB内含dpr/pas源文件、fmx界面文件、dproj与deployproj工程配置、AndroidManifest部署模板、APK成品、mp3辅助文件及ReadMe说明等Source/Obj/Bin目录划分清楚便于对照编译与产物验证。该资源已有3295人学习使用。通过研读源码可掌握Delphi中摄像头图像流获取、二维码定位与解码思路以及静态库在安卓工程中的集成方式结合ReadMe还能快速搭建编译环境并识别常见坑点是一份兼顾学习与落地的实用工程参考。1. 全 Delphi 代码实现的安卓二维码扫码不卡顿的纯 Delphi 方案做安卓扫码需求时很多 Delphi 开发者的第一反应是封装一个 Java 的 ZXing 库或者找现成的第三方控件。但在真机上跑起来往往翻车预览卡顿、识别慢、打包体积膨胀出了问题还得开 Java 环境去查 JNI 崩溃日志。今天拆的这套源码全部用 Delphi 实现二维码扫码的完整链路——摄像头取流、YUV 转灰度、二维码定位与解码、结果回传中间没有任何 Java 桥接。特别适合对包体大小敏感、希望在 Delphi 生态内独立完成安卓扫码功能的团队新手能直接照着搭工程熟手也能看参数边界。2. 为什么坚持全 Delphi从 ZXing 移植原理到原生控件选型2.1 Java 桥接的隐性成本与全 Delphi 的边界如果只是调一个系统 APIJNI 还能接受但二维码解码不是一次调用。ZXing 在 Java 侧的解码流程包含图像灰度化、二值化、Finder Pattern 定位、采样、GF(256) 纠错、格式信息解析等十几个步骤每一步都要跨 JNI。跨 JNI 本身有性能损耗更现实的问题是崩溃定位难——Java 层异常不直接进 Delphi 的异常体系只能看 logcat 慢慢猜。全 Delphi 实现最大的收益不是性能而是可维护性。整个扫码模块从相机回调到解码结果都在一个语言体系里你可以在 Delphi 的断点里看解码到哪一步挂了也可以把解码器单独拿出来写单元测试。边界是移植版的解码速度在同等硬件上比原生 Java 略慢但通过控制解析帧率和降低分辨率实际体验差距很小后面第 4 章专门讲这个。再从包体角度看。封装 Java 版 ZXing 通常要带过去几十个 Java 类文件还要做 ProGuard 混淆配置最终 APK 体积增加 5MB 到 10MB 很常见纯 Delphi 方案只新增几个 pas 文件体积增加可以控制在几百 KB 内。如果你做的是工具类 App、POS 类应用或内部扫码器这差别不可忽略。2.2 ZXing 移植版的核心类与解码链路我用的这套源码以某社区维护的 ZXing 移植版为基础模拟项目X核心类是 TQRCodeReader、TDecodeHints以及图像源 TPlanarYUVLuminanceSource。解码链路大致是预览帧NV21→ TPlanarYUVLuminanceSource 包装成灰度源 → 二值化器HybridBinarizer 或 GlobalHistogramBinarizer→ 检测器定位三个 Finder Pattern → 透视校正 → 采样网格 → 解码纠错 → 返回结果。这里有个关键取舍TPlanarYUVLuminanceSource 可以直接消费相机给的 YUV 原始数据不需要转 Bitmap。很多人扫不出来是死磕 YUV 转 RGB 再调解码器多了一次全帧转换既慢又损耗灰度信息。NV21 的 Y 分量本身就是灰度图ZXing 只需要 Y 平面数据所以直接把 AData 指针交给亮度源即可。调试时可以通过断点看 Detector 返回的 Finder Pattern 数量。如果小于 3说明图像质量问题或二值化阈值不对如果等于 3 但解码失败问题多半出在透视校正或者版本信息读取上这两个环节对图像尺寸的奇偶性很敏感。记住这个排查顺序能省不少时间。2.3 摄像头组件选型与预览帧格式Delphi 从 10.3 起提供了 TCameraComponent 控件它在安卓下封装了 Camera 和 Camera2。我一般用它的 OnSampleBuffer 事件做帧回调。SampleBuffer 的事件参数里给的是 Pointer 和 Size格式是 NV21宽度高度通过 FPreviewWidth、FPreviewHeight 记录。要注意的是TCameraComponent 在不同 Delphi 版本上回调的帧格式略有差异有的版本是 NV21有的版本带旋转参数。拿到帧后先确认格式不要默认 YUV420否则图像会偏色或错位。还有一种做法是直接用原生 Camera API 的 JNI 封装但那样又回到桥接的老路。TCameraComponent 虽然还是 Delphi 自带的封装但至少事件回调里给的是原始指针我们可以把最容易出性能问题的解码环节留在 Delphi 侧这样可控性高很多。我的习惯是预览回调只做入队不做任何解码和 UI 操作把帧指针交给后台线程让 UI 线程保持随时可响应。2.4 移植版与原版 ZXing 的差异点移植版不是逐行翻译 Java 代码有几个地方容易踩第一部分移植版缺失 GS1 码的解析支持。如果你需要识别带 GS1 应用标识符的码选库时先确认有没有 FNC1 处理逻辑。第二Reader.Decode 的重载参数顺序不一致有的版是 Decode(Bitmap, Hints)有的版是 Decode(IntfLuminanceSource, Hints)直接用默认参数最容易踩坑。第三某些移植版对高分屏大图没有做内部降采样需要你外部先缩放。这些差异意味着拿到库以后别急着接业务先写一个独立的解码单测喂进去几幅已知的测试图确认行为。编译选项也会影响解码速度。Release 模式下建议开启优化、关闭范围检查和溢出检查解码耗能差 20% 到 40%。调试版下扫码慢是正常的别在 Debug 下判断性能问题。3. 把扫码工程跑起来工程配置、相机预览与解码流程3.1 AndroidManifest 权限与工程依赖先把工程配置做对这一步错了后面全是黑屏。安卓 6 以上属于危险权限的相机必须在运行时申请。Delphi 的做法是在 Project Options 里勾选 Camera 权限同时也要在 AndroidManifest.template.xml 里确认有 uses-permission。很多翻车案例是只在 options 里勾了但 Template 里的 uses-feature 没配 camera.any导致低版本机型直接找不到相机硬件。工程里需要引入 ZXing 移植版的源码单元一般是 ZXing.QRCode.Reader、ZXing.Common.HybridBinarizer、ZXing.PlanarYUVLuminanceSource 等几个单元。不要一股脑把整个库全部放进 uses只引解码链路相关的编译时间会短很多。代码里我会用接口或者单例把 TQRCodeReader 缓存起来避免每帧 New 一个实例因为 Reader 内部有 Detector 的临时对象频繁 New 会频繁触发 GC。3.2 相机预览TCameraComponent 与回调入队下面是初始化相机的核心代码这步的关键是把预览回调的帧数据送进队列不做任何重活。procedure TScanForm.InitCamera; begin FCamera : TCameraComponent.Create(Self); FCamera.OnSampleBuffer : CameraSampleBuffer; FCamera.FocusMode : TMobileFocusMode.ContinuousAutoFocus; // 连续对焦 FCamera.Active : True; // 打开相机 end; procedure TScanForm.CameraSampleBuffer(Sender: TObject; const AData: Pointer; ADataSize: Integer); begin if FFrameCount mod 3 0 then begin Inc(FFrameCount); Exit; // 每 3 帧才入队一次省掉 2/3 的解码工作量 end; Inc(FFrameCount); // 帧数据生命周期只在回调内有效所以这里做一次拷贝 // 也可以用环形缓冲区避免每次都分配内存但先保证正确 FDecodeQueue.Push(CopyFrame(AData, ADataSize)); end;逻辑说明OnSampleBuffer 是高频回调低端机一秒钟可能走 30 次。这里用计数抽样把解码负载直接降为三分之一。CopyFrame 是必须的因为回调结束系统可能会复用这块内存直接把 AData 指针交给后台线程是悬垂指针崩溃很难查。更高效的做法是预分配 N 块缓冲区轮转使用后面第 4 章展开。参数说明FCamera.FocusMode 设置为 ContinuousAutoFocus 能保证扫码时自动对焦但部分国产 ROM 对这个模式支持不好表现为反复拉风箱。遇到这种情况改成 Macro微距模式扫码距离更近识别率反而更高。3.3 后台解码线程从 YUV 到二维码结果解码线程用 TThread 的子类实现循环从队列取帧调用 ZXing 的 Reader 解码。type TDecodeThread class(TThread) private FQueue: TThreadedQueueTBytes; FReader: TQRCodeReader; FHints: TDecodeHints; protected procedure Execute; override; public procedure DecodeFinished(const AText: string); // 回调 end; procedure TDecodeThread.Execute; var Frame: TBytes; LuminanceSource: TPlanarYUVLuminanceSource; Bitmap: TBitmap; ResultData: TDecodeResult; begin FReader : TQRCodeReader.Create; FHints : TDecodeHints.Create; FHints.TryHarder : True; // 提高远距离和小尺寸码的识别率 while not Terminated do begin Frame : FQueue.Pop; // 阻塞等待帧数据 try LuminanceSource : TPlanarYUVLuminanceSource.Create( Frame[0], FWidth, FHeight); Bitmap : LuminanceSource.RenderToBitmap; // 生成灰度 Bitmap try ResultData : FReader.Decode(Bitmap, FHints); if ResultData nil then TThread.Synchronize(nil, procedure begin DecodeFinished(ResultData.Text); end); finally Bitmap.Free; end; except // 解码异常不能影响线程记录日志后继续取帧 end; end; FReader.Free; end;逻辑说明Execute 里是一个死循环FQueue.Pop 在没有数据时阻塞这个模式下线程不会空转吃 CPU。每次取到帧后构造亮度源并渲染成灰度 Bitmap 再喂给 Reader。TThread.Synchronize 把结果拉回 UI 线程避免在后台线程直接操作界面控件导致崩溃。RenderToBitmap 这一步其实可以绕开——ZXing 的 Decode 可以直接接收亮度源但大多数移植版本的 Reader.Decode 重载还是认 Bitmap 或灰度数组所以这里画出 Bitmap 是兼容性最好的写法。参数说明FHints.TryHarder 打开后解码器会在第一轮定位失败时对整张图做二次扫描识别率提升明显代价是耗时可能翻倍。在预览帧上建议打开在拍照模式解高清图时反而建议关闭避免识别太慢。有些版本还支持 PureBarcode 提示适用于整张图只有一个码的场景用不上就别开。3.4 结果处理与震动反馈扫码成功后的交互常见的做法是震动加提示音。安卓震动需要用到系统服务Delphi 里可以直接调用 JNI 的 Vibrator也可以简单点用 TNotificationCenter 的震动通知。这里给一段结果处理的容错代码procedure TScanForm.HandleResult(const AText: string); begin FCamera.Active : False; // 先停相机防止连续触发多次 if FCallback nil then FCallback(AText) else ShowMessage(扫码结果: AText); // 震动 100ms Vibrate(100); end;这段的关键是 FCamera.Active : False 放在最前面不然解码线程可能刚出结果又收到下一帧导致同一个码被反复弹窗。回调结果用了一个 FCallback 事件属性这样可以把扫码窗体做成通用组件调用方只要挂事件就能拿到结果不需要强耦合 UI。4. 不卡顿优化解码线程、帧率控制与内存调优4.1 队列深度与丢帧策略扫码最常见的玄学问题是单独的相机预览流畅一旦跑解码线程UI 就开始掉帧。原因不只是线程抢 CPU还有队列堆积。当解码速度跟不上帧产生速度时队列里积压大量帧后台线程永远在处理旧帧预览实时性会明显变差。解决方法是给队列加最大长度。我用 TThreadedQueue 时把队列容量设为 2Push 时设置 Timeout0满了直接丢弃新帧。这样后台线程永远在处理最近一两帧视觉上扫码框的反馈才是实时的。别担心丢帧丢码——二维码在预览里至少停留几百毫秒每秒解 5 帧足够抓住它。这个策略等价于「只认最新不认最早」。用户移动手机时旧帧的二维码可能已经出了画面解旧帧大概率失败还浪费 CPU。丢帧其实是主动放弃无效劳动换来的是每一次取到的帧都有更大概率对应当前画面中心。4.2 解析分辨率与裁剪的关注区ZXing 的耗时基本跟像素数成正比。预览帧如果是 1920x1080全帧解码在低端机上要 300ms 以上不卡才怪。常用做法是把解码用的灰度图像缩放到宽 640 或 480 再喂识别。缩放有两种路径一是直接改相机预览分辨率比如请求 PreviewSize 为 640x480二是拿到帧后只取中间区域的 Y 平面数据做裁剪。我推荐后者因为很多 ROM 对请求的分辨率会向上取整你请求 640 它给你 1280。裁剪关注区还有一个额外好处如果扫码框在界面中间识别区域也集中在中间那么把四周的干扰信息裁掉误识别率会下降。裁剪时注意宽高必须是偶数NV21 转换时奇数宽高会出绿边或偏色。裁剪的代码我一般这样写从 NV21 的 Y 平面中间截取一块构造亮度源时传新的宽高和 offset。其实 ZXing 的 PlanarYUVLuminanceSource 构造函数支持 cropLeft、cropTop、cropWidth、cropHeight 四个参数直接用就行不需要手动拷贝 Y 数据。4.3 内存管理Bitmap 复用与对象池扫码是个长时运行的功能如果每帧都 New 一个 TBitmap 再 Free时间长了内存碎片会非常严重尤其是 Delphi 的安卓内存管理器在频繁分配大对象时表现不好。我的做法是建立 Bitmap 对象池解码线程启动时预分配 2 张灰度 Bitmap轮流使用用完后回到池中而不是释放。这里有个坑ZXing 的 HybridBinarizer 会从 Bitmap 的 ScanLine 读取像素如果你复用 BitmapReader 内部生成的部分中间对象仍然是线程安全的但你不能同时让两个任务用同一张 Bitmap。所以对象池严格控制同一时刻最多借出 1 张。预分配 3 张就够循环了。还要注意帧数据的拷贝内存。回调里如果直接分配 TBytes等于每帧都在堆上折腾几十万字节。环形缓冲区加对象池是标准解法相机回调写入预先分配好的缓冲区解码线程读完后立刻标记该缓冲区可用零分配运行。4.4 绘制优化扫描框与遮罩不要全屏重绘扫码界面经常有四个角的亮框和半透明遮罩。如果直接在 FormPaint 里全屏重绘即使只是绘制几个矩形在低端机上也会占用不少 CPU。常见做法是把遮罩和扫描框缓存到一张 TImage 或 TCanvas 上只有位置变化时才更新平时不触发重绘。扫描线动画也不要每帧重绘遮罩。可以让扫描线在一个单独的小控件上画这个控件只有几十像素高Invalidate 范围只影响那一小块区域Overhead 小很多。我习惯把扫码框区域自己记录成 FScanRect动画定时器 50ms 更新一次实际对性能的影响可以忽略。把这几条归纳一下UI 线程只做两件事——把相机帧入队、把解码结果展示。中间所有图像处理、解码、纠错全放后台线程。检查是否卡顿的最快办法是看 CPU 负载如果 UI 渲染线程占用超过 15%多半是某个回调里做了重活。5. 避坑指南扫码集成中的常见问题与排查5.1 权限已开但预览一直黑屏现象AndroidManifest 里加了 CAMERA 权限运行时也弹窗允许了但预览区域是黑屏没有任何报错。原因大多数情况是相机权限声明了但 uses-feature 的 required 值导致应用在部分设备上被系统判定为不可用或者相机在后台被其他应用占用。另一种常见原因是 Activity 的启动模式导致相机初始化在错误时刻发生。解决先检查 AndroidManifest.template.xml 里是否包含uses-feature android:nameandroid.hardware.camera.any android:requiredfalse /。然后把 FCamera.Active : True 放在 FormActivate 或 OnResume 事件里不要在 FormCreate 里直接打开因为此时 Surface 还没准备好。最后用一个测试工程只保留相机预览排除其他业务代码干扰。5.2 扫码结果乱码或方向颠倒现象能识别出内容但字符串是颠倒的、乱码的或者同一个码横着扫扫不出。原因相机预览帧的方向和屏幕方向不一致。前置摄像头和后置摄像头在不同设备上旋转角度不一样有些 ROM 会额外旋转 90 度。ZXing 的解码器假设图像是正立的方向错了定位器就找不到。解决在构造 TPlanarYUVLuminanceSource 时传入 rotation 参数比如 90、180、270或者对亮度源做 transpose 预处理。最稳妥的做法是运行时从 Camera 的 CameraInfo 里拿到 orientation 值动态计算旋转角度。注意无论怎么旋转Y 平面的长度不变只是灰度图像的内容方向变化所以不用重新分配内存可以直接映射原缓冲区。5.3 关掉页面后相机仍在工作现象扫码页面关闭后状态栏提示相机图标一直亮着甚至重启应用后相机被占用。原因Activity 生命周期管理不当。OnPause 时没有释放相机或者 FCamera.Active 只在 OnDestroy 里设置 False而系统退回桌面时并未触发 OnDestroy。解决在 OnPause 里写 FCamera.Active : False在 OnResume 里重新赋 True。iOS 和安卓的生命周期差异很大这套代码按安卓的来。另外不要把 CameraComponent 挂在 Form 上让它随 Form 释放主动控制 Active 状态比依赖组件销毁更可靠。5.4 解码线程偶发崩溃Cannot access a destroyed view现象扫码偶尔闪退日志指向 TThread.Synchronize 的匿名过程异常信息是访问已销毁的视图或控件。原因解码线程的生命周期比窗口长。用户扫到一半退出页面时窗口控件已经销毁后台线程还在 Synchronize 里排队准备访问这些控件。解决在线程 Execute 的循环里增加一个 fTerminated 标志。退出页面时先设置终止标志再释放队列让线程 Pop 返回并退出循环。Synchronize 之前再判断一次标志如果窗口已销毁就直接放弃结果。这套「先停线程、再销毁资源」的顺序一定要遵守顺序反过来必然概率性崩溃。5.5 内存持续增长最终被杀现象连续扫码十分钟内存占用从 80MB 涨到 300MB最后应用被杀。原因忽视帧数据的拷贝。回调里如果只是把 AData 指针存起来内存不涨但一旦拷贝成 TBytes 并压进队列而队列里的帧处理速度跟不上内存就会堆积。还有一个隐蔽点TPlanarYUVLuminanceSource.RenderToBitmap 每次生成的灰度 Bitmap 可能被 ZXing 内部的某些状态持有Bitmap.Free 后内存不一定立即归还系统。解决用固定容量环形缓冲区代替无界队列并限制缓存帧数不超过 2。同时打开内存分析工具确认 Free 后堆内存曲线是否回落。如果问题依旧把临时对象放入对象池避免反复构造释放。6. 进阶技巧二维码生成、批量识别与扫描框动效6.1 用 TDelphiZXingQRCode 生成二维码解码之外这套资源里也带了一个生成二维码的单元。生成比解码简单得多设置文本、宽度、纠错等级即可。我常用来做模拟项目X的出入凭证uses DelphiZXingQRCode; var QR: TDelphiZXingQRCode; Bitmap: TBitmap; begin QR : TDelphiZXingQRCode.Create; try QR.Data : 模拟项目X-2025-001; // 内容 QR.Encoding : TQRCodeEncoding.qrAuto; QR.QuietZone : 2; // 静默区宽度过小会扫不出来 Bitmap : QR.GenerateBitmap(400, 400); // 输出 400x400 位图 try Image1.Picture.Bitmap.Assign(Bitmap); finally Bitmap.Free; end; finally QR.Free; end; end;逻辑说明GenerateBitmap 是封装好的单步方法第二个参数是图像尺寸。QuietZone 默认是 2很多新手清零结果生成的码贴到白底上没问题贴到深色背景上就扫不出来。纠错等级建议至少选 Q这样码有污损或遮挡 25% 以内的情况都能正常读取。6.2 批量识别从相册读图并解码扫码页面有时需要支持从相册选图识别。这里有个小技巧相册图是 JPEG直接喂给 ZXing 效果很差先转灰度再识别。如果有多个码在图中循环调用 Reader.DecodeMultiple 即可。我一般还会对图片做一次 2x 降采样因为相册原图动辄 3000 万像素全尺寸解码极慢降采样后识别率几乎不受影响。处理相册图时还有个细节部分手机相册会输出旋转后的缩略图而原图里带有 EXIF 方向信息。先检查 JPEG 的 EXIF 方向字段如果非 0旋转后再解码否则可能出现在预览模式能扫、相册模式扫不出的怪现象。6.3 扫描框动画的轻量实现最后聊扫描线动效。不要用动画线程每帧全屏刷新我之前的做法是扫描框 Rect 不变只有一条 4 像素高的扫描线在框内上下移动控件是一个自定义 TScanBarPaint 里只画一条渐变线。定时器 30ms 触发一次 Top 移动并 Invalidate负载几乎为零。从那以后我每次接扫码需求都强制先把「UI 线程职责」「队列深度」「内存释放时机」这三件事写在设计文档里再动手写代码。希望帮到你少走点我踩过的坑。本文还有配套的精品资源点击获取