QZXing 完全指南：Qt/QML 生态下最强大的条形码与二维码解码库

【免费下载链接】qzxingQt/QML wrapper library for the ZXing library. 1D/2D barcode image processing library项目地址: https://gitcode.com/gh_mirrors/qz/qzxing

如果你正在为Qt / QML 应用寻找一款开箱即用的条形码与二维码解码方案，QZXing几乎是绕不开的名字。作为 ZXing 官方 C++ 库的 Qt/QML 封装，QZXing 让开发者用几行代码即可完成二维码解码、一维条形码识别，甚至通过摄像头实现实时扫码，无需深入复杂的图像处理算法。本指南将从零开始，带你快速掌握 QZXing 的集成、解码、编码与实时扫描全流程。

什么是 QZXing？它解决了什么问题

QZXing 的本质是一个Qt/QML 封装库，底层依赖大名鼎鼎的 ZXing（Zebra Crossing）条形码图像处理库。它把 ZXing 底层繁琐的 API 封装成 Qt 开发者熟悉的信号、槽与属性机制，让你专注于业务逻辑而不是图像算法。

为什么选择 QZXing？

QZXing 支持的条码格式一览

QZXing 的解码能力非常全面，几乎覆盖了日常开发中遇到的所有条码类型：

也就是说，从超市商品上的 EAN-13，到物流单上的 Code 128，再到随处可见的微信/支付宝二维码，QZXing 都能一把搞定。

快速集成：两种方式把 QZXing 加入你的 Qt 项目

QZXing 支持两种集成方式，按项目需求二选一即可。

方式一：源码嵌入（最推荐）

这是最简单的方式。首先获取项目源码：

git clone https://gitcode.com/gh_mirrors/qz/qzxing

然后将src目录下的源码复制到你的工程中，并在.pro文件里添加一行：

include(QZXing/QZXing.pri)

就是这么简单！QZXing.pri会自动启用一维码、二维码、Data Matrix、Aztec、PDF 417 的解码能力以及 QR 编码能力。

方式二：编译为外部静态库

如果你的团队习惯复用预编译产物，可以打开QZXing.pro直接编译，并在文件中取消注释CONFIG += staticlib编译为静态库，随后在其他工程中链接使用。

按需裁剪依赖：只引入你需要的模块

QZXing 贴心地提供了三级依赖控制，避免引入用不到的模块：

如果你的项目只做静态图片识别，保持默认即可；如果需要 QML 界面或摄像头实时扫描，再逐级开启。

C++ 中如何用 QZXing 解码二维码

C++ 使用方式非常直观，核心 API 都集中在 QZXing.h 中。以解码一张图片为例：

#include "QZXing.h" QImage imageToDecode("barcode.png"); QZXing decoder; decoder.setDecoder(DecoderFormat_QR_CODE | DecoderFormat_EAN_13); QString result = decoder.decodeImage(imageToDecode);

几个常用的进阶配置：

• setTryHarderBehaviour()：开启TryHarderBehaviour_ThoroughScanning（彻底扫描）和TryHarderBehaviour_Rotate（自动旋转），可显著提高复杂场景下的识别率；
• setSourceFilterType()：支持正常图像与反色图像两种模式，深色背景上的浅色条码也能识别；
• decodeImageFromFile()：直接传入本地图片路径即可，无需手动加载 QImage；
• getProcessTimeOfLastDecoding()：获取上次解码耗时，方便做性能统计。

QML 中如何实现二维码识别

QML 使用同样简单。第一步，在main.cpp中注册类型：

QZXing::registerQMLTypes();

第二步，在 QML 文件中声明一个QZXing对象并绑定解码信号：

import QZXing 3.3 QZXing { id: decoder enabledDecoders: QZXing.DecoderFormat_QR_CODE onTagFound: console.log("识别结果: " + tag) onDecodingFinished: console.log(succeeded ? "解码成功" : "解码失败") }

配合decodeImageQML()方法，你可以轻松实现"选择图片 → 自动识别"的完整流程。对于需要裁剪识别区域（比如只识别图片中间部分的二维码）的场景，可以使用decodeSubImageQML()指定矩形区域，灵活性十足。

生成二维码：QZXing 的编码能力

除了识别，QZXing 还内置了 QR 码生成能力。在 C++ 中只需调用静态函数：

QImage qr = QZXing::encodeData("Hello QZXing!");

默认生成 240x240、纠错等级 L 的二维码。也支持自定义参数：

QImage qr = QZXing::encodeData(data, QZXing::EncoderFormat_QR_CODE, QSize(512, 512), QZXing::EncodeErrorCorrectionLevel_H);

在 QML 中更加优雅——QZXing 注册了一个图像提供器（Image Provider），直接在Image组件上动态生成二维码：

Image { source: "image://QZXing/encode/" + inputField.text + "?correctionLevel=H" sourceSize.width: 320 sourceSize.height: 320 }

输入框内容一变，二维码实时更新，非常适合"文本转二维码"的小工具。完整的编码示例可参考 BarcodeEncoder 示例。

实时扫码：用 QZXingFilter 打造摄像头扫码器

QZXing 最亮眼的功能当属QZXingFilter——一个可直接挂在VideoOutput上的视频过滤器，让摄像头画面里的条码被实时解码。参考官方示例 QZXingLive，核心思路如下：

1. 在.pro中启用CONFIG += qzxing_multimedia；
2. 在 QML 中创建Camera作为视频源；
3. 将QZXingFilter挂到VideoOutput.filters上，并绑定其内部decoder的信号；
4. 通过captureRect属性设置识别区域（比如只扫描画面中央的取景框）。

VideoOutput { source: camera filters: [ zxingFilter ] // 关键：挂载解码过滤器 } QZXingFilter { id: zxingFilter captureRect: videoOutput.mapRectToSource(/* 取景框区域 */) decoder { enabledDecoders: QZXing.DecoderFormat_QR_CODE onTagFound: console.log("扫码结果: " + tag) } }

这样一套组合拳下来，一个完整的实时扫码界面就诞生了，解码过程在独立线程中执行，不会阻塞 UI 渲染。早期基于 Qt Multimedia 的相机扫描示例（适用于 Qt 4.x/5.x）还可参考 QMLBarcodeScanner 示例，其中的相机设置弹窗、曝光补偿、变焦控制等组件同样值得借鉴。

Qt 6 兼容性与常见问题

不少开发者关心 QZXing 在 Qt 6 下的表现，这里重点提醒两点：

• 文本编码处理：Qt 6 移除了QTextCodec模块，QZXing 在 Qt 6 下会自动改用QStringDecoder解析条码内容，避免额外引入 core5compat 依赖；Qt 5 下则维持原有行为，两种版本都能正常工作；
• 多媒体模块：实时扫码依赖 QtMultimedia，使用前请确认你的 Qt 版本包含该模块。

高频疑问速答

Q：解码速度慢怎么办？优先裁剪识别区域（decodeSubImageQML）、缩小输入图像尺寸（decodeImage支持 maxWidth/maxHeight 参数），并合理精简enabledDecoders——只开启你真正需要的格式，识别效率会大幅提升。

Q：反色（深底浅码）识别不了？将imageSourceFilter设置为SourceFilter_ImageNormal | SourceFilter_ImageInverted即可同时兼容两种图像。

Q：如何查看识别出的条码类型和字符集？使用tagFoundAdvanced信号，它除了返回内容，还附带格式（format）与字符集（charSet）信息。

总结

作为 Qt/QML 生态中最成熟的 ZXing 封装方案，QZXing 用极低的上手成本，为你带来了完整的条形码与二维码解码、编码、实时扫描能力。无论是做一个简单的"图片扫码工具"，还是打造带取景框的移动端扫码 App，QZXing 都能让你把精力集中在产品本身。现在就把它接入你的 Qt 项目，体验一下几行代码完成二维码解码的爽快感吧！

【免费下载链接】qzxingQt/QML wrapper library for the ZXing library. 1D/2D barcode image processing library项目地址: https://gitcode.com/gh_mirrors/qz/qzxing