簡介這是一份面向安卓開發(fā)者的二維碼與條形碼掃描實現(xiàn)示例基于ZXing開源庫配套完整可運行工程與說明文檔。資源共1874個文件壓縮包18.42MB主要包含Java源碼、安卓資源文件、構(gòu)建配置及APK成品其中.java、.xml、.gradle文件便于查看集成邏輯.jar與.dex文件是庫依賴和編譯產(chǎn)物可對照實際運行效果學習。已有2535人瀏覽學習。壓縮包內(nèi)含MyApplication示例應用演示了從Gradle依賴引入、自定義掃描界面、相機預覽到解碼結(jié)果回調(diào)的完整流程附帶《說明使用文檔.docx》對集成步驟、常見權(quán)限問題和掃碼體驗優(yōu)化做了整理。讀者可通過閱讀源碼與文檔快速掌握在Android項目中集成ZXing、處理掃描結(jié)果以及加入閃光燈和掃描區(qū)域指示等功能適合移動開發(fā)入門或需要在項目中落地掃碼功能的工程師。1. 把掃碼能力接進項目zxing 解碼庫的真實邊界很多 App 的需求清單里二維碼掃描和條形碼掃描看著不起眼真做起來才知道牽扯到預覽、圖像格式、解碼策略一堆細節(jié)。我最早接觸 zxing是被拉去給一個識別率極低的內(nèi)部工具“擦屁股”——那套方案對圖片二值化處理不干凈稍微有點反光就罷工后來把解析層換成 zxing 的 MultiFormatReader問題才壓住。zxing 能做的是從攝像頭幀或靜態(tài)圖片中定位條碼、做旋轉(zhuǎn)矯正、二值化和解碼兼容 QR Code、Code 128、EAN-13、UPC-A 等常見碼制并返回條碼內(nèi)容和格式。它不負責相機預覽 UI更不包含商品信息查詢。它的最佳受眾是客戶端的掃碼登錄/掃碼支付開發(fā)者、服務端批量解析條碼的后端以及想快速驗證識別率的測試工程師。2. 不急著接代碼zxing 的解碼鏈路與依賴邊界2.1 從像素到結(jié)果二值化、定位、解碼在干什么掃碼識別的復雜度不在“讀出來”這一步而在“怎么從真實世界的圖像里把碼分離出來”。zxing 的處理管線大致是亮度源 → 二值化 → 定位 → 解碼。第一步是提取 LuminanceSource亮度源。zxing 不關(guān)心色彩只要每個像素的灰度亮度。手機攝像頭拍照出來的是 YUV、NV21 或 RGBA 數(shù)據(jù)直接用 Y 分量亮度做輸入是最省內(nèi)存的做法。如果拿 Bitmap則通過 getPixels 取到像素數(shù)組后做一次灰度轉(zhuǎn)換。第二步是二值化。真實環(huán)境下光照不均勻同一個碼上半部分亮、下半部分在陰影里很常見。如果全圖用同一個閾值黑色模塊會被一刀切成兩半解碼自然失敗。所以 HybridBinarizer 把圖像切成 8x8 的子塊逐塊計算亮度統(tǒng)計值找出局部閾值再把相鄰塊的閾值做平滑。大多數(shù)手機掃碼場景都用它。GlobalHistogramBinarizer 更快但對光照波動敏感適合可控光線的服務端圖片。第三步是定位。zxing 需要在二值圖上找到條碼區(qū)域。QR Code 靠三個角上的“回”字形定位圖案鎖定方向線性條碼則依賴邊緣梯度和黑白條紋寬度的比例關(guān)系做掃描線搜索。第四步是解碼。對應每一種格式有專門的 Reader 實現(xiàn)比如 QRCodeReader 會按版本和糾錯等級去還原數(shù)據(jù)塊Code128Reader 根據(jù)起始符和終止符推算信息。MultiFormatReader 會在內(nèi)部把支持的 Reader 挨個嘗試直到某一種解碼成功或全部失敗。真正需要設計的地方就在這里多格式同時解碼會讓你省事但也會帶來不必要的耗時。把這套鏈路理解清楚后面所有參數(shù)和坑都有了解釋不會有“加個開關(guān)就好”的玄學。2.2 依賴怎么選core、javase、android 模塊差異zxing 項目分多個模塊我只說常用的三條路徑?？蛻舳酥灰獯a能力依賴core包自己做相機預覽。相機幀數(shù)據(jù)的采集、旋轉(zhuǎn)、裁剪由 CameraX 或 Camera2 處理zxing 只負責從幀里找碼。一般寫法是把幀轉(zhuǎn)成 PlanarYUVLuminanceSource再交給 HybridBinarizer 和 MultiFormatReader 去解碼。桌面端或服務端批量識別圖片依賴javase包。它提供了 BufferedImageLuminanceSource可以直接讀java.awt.image.BufferedImage同時帶了命令行工具能一次跑一個目錄下的所有圖片。對批量生產(chǎn)圖片模擬測試非常實用。至于 zxing 的 android 模塊很多老項目還在用它把 Camera、取景框、解碼 Activity 都封裝好了。如果你接手的是一個歷史包袱重的項目可能還會見到CaptureActivity這種類但如果這是新項目我更建議只引 core 配合自有 UI 來做。原因很簡單android 模塊的設備適配邏輯停更很久現(xiàn)代機型攝像頭輸出格式差異大它封裝的 Camera 接口未必能處理最后還是要自己改。依賴模塊典型使用場景需要自己準備的部分coreAndroid 客戶端實時識別相機預覽、取幀、旋轉(zhuǎn)、UIjavase服務端/桌面批量識別圖片JVM 運行環(huán)境、圖片路徑處理android老項目掃碼頁面快速改造相機權(quán)限、生命周期適配android-integration跳轉(zhuǎn)外部掃碼 App外部 App 的安裝與兼容性2.3 版本與運行環(huán)境匹配別盲目升新版我常用的做法是根據(jù)最低系統(tǒng)版本定庫版本。zxing core 3.5.x 分支對 JDK 版本有要求如果服務端還在 Java 8選太新的版本可能編譯不過Android 項目把 minSdk 提到 21 以上基本順暢minSdk 低于 19 時會遇到 API 不支持的風險。這里給不出一個“萬能版本”但可以反向判斷在依賴配置里寫死大版本號鎖一個穩(wěn)定小版本不要在項目交付前順手改版本——我吃過一次虧升級后解碼耗時波動變大最后查出來是新版本里的多格式解碼線程配置不同導致。提示版本升級后最少要做一輪真機回歸不要只跑單元測試。掃碼這種功能模擬器上通過不代表實拍也能過尤其是低端機的圖像采集延遲和設備旋轉(zhuǎn)角度。2.4 調(diào)優(yōu)的最關(guān)鍵入口DecodeHintType 參數(shù)zxing 的解碼行為不是寫死的通過DecodeHintType可以顯著改變識別率和速度。這幾個參數(shù)我?guī)缀趺看味加脜?shù)作用我的建議POSSIBLE_FORMATS限定只嘗試哪些碼制能多省就多省全格式解碼會拖慢速度TRY_HARDER用更細的掃描線、更多輪次去定位弱光或條碼破損時打開平時關(guān)掉CHARACTER_SET指定解碼后的字符串編碼中文二維碼要設 UTF-8ALSO_INVERTED允許對反色條碼白碼黑底解碼外貿(mào)單據(jù)和部分產(chǎn)品包裝會用到ALLOWED_EAN_EXTENSIONSEAN/UPC 附加碼的位數(shù)書本條碼常見按需開啟值得多說一句POSSIBLE_FORMATS不是越多越好。同一幀圖像里如果同時開了 QR、Data Matrix、PDF417、Code 128MultiFormatReader 會逐個嘗試每多一種格式耗時就多一截。我平時的習慣是業(yè)務上明確只掃二維碼就只傳BarcodeFormat.QR_CODE需要兼容一維碼時再補CODE_128和EAN_13。全格式解碼只留在調(diào)試模式里用上線前務必收緊。3. 把 zxing 接進項目CameraX 取幀與解碼邏輯落地3.1 取到 Y 平面別拿到 Bitmap 再轉(zhuǎn)換先看依賴。項目里除了 zxing core還需要攝像頭取幀的庫。CameraX 是現(xiàn)代 Android 項目里比較穩(wěn)妥的選擇它把 Camera2 的細節(jié)封得比較干凈ImageAnalysis 可以直接拿到 YUV 幀。implementation(androidx.camera:camera-core:1.3.0) implementation(androidx.camera:camera-camera2:1.3.0) implementation(androidx.camera:camera-lifecycle:1.3.0) implementation(com.google.zxing:core:3.5.2)依賴就這四個。注意到我刻意沒有引 zxing 的 android 模塊因為用 CameraX 自己取幀控制力更強。CameraX 的 ImageAnalysis 每一幀都是一份ImageProxy里面包含三個圖像平面Y、U、V。解碼只需要亮度也就是 Y 平面。Y 平面并不是一個簡單的ByteArray(width * height)。它的rowStride可能大于圖像寬度因為攝像頭硬件會做行對齊每行末尾補幾個字節(jié)的 padding。如果直接用buffer.remaining()取全部字節(jié)亮度源行尾會串入 padding 數(shù)據(jù)圖案錯位識別率直接掉一截。正確做法是逐行復制fun extractYArray(imageProxy: ImageProxy): ByteArray { val width imageProxy.width val height imageProxy.height val yPlane imageProxy.planes[0] val yBuffer yPlane.buffer val rowStride yPlane.rowStride val yArray ByteArray(width * height) var row 0 var offset 0 while (row height) { yBuffer.position(row * rowStride) yBuffer.get(yArray, offset, width) offset width row } return yArray }這段代碼是在做“去 padding”的操作。rowStride是每一行在內(nèi)存里實際占用的字節(jié)數(shù)width是有效像素寬度二者不一定相等。逐行把有效數(shù)據(jù)拷貝進目標數(shù)組后面 zxing 拿到的亮度源就是干凈平整的。如果設備支持也可以直接用ImageProxy.PlaneProxy的rowStride做整圖映射但逐行復制是最不容易踩坑的思路性能開銷在解碼面前可以忽略。3.2 分析器里構(gòu)造亮度源和解碼器拿到 Y 數(shù)組之后下一步是構(gòu)造 zxing 需要的數(shù)據(jù)結(jié)構(gòu)。這里有個常見誤區(qū)直接把 Y 數(shù)組當成RGBLuminanceSource來用。RGBLuminanceSource接收的是 RGBA 像素數(shù)組傳 Y 數(shù)據(jù)進去等于讓解碼器把灰度值當成顏色通道去解讀結(jié)果永遠不對。YUV 幀必須用PlanarYUVLuminanceSource。class ScannerAnalyzer : ImageAnalysis.Analyzer { private val hints mapOf( DecodeHintType.POSSIBLE_FORMATS to listOf( BarcodeFormat.QR_CODE, BarcodeFormat.CODE_128, BarcodeFormat.EAN_13 ), DecodeHintType.TRY_HARDER to true, DecodeHintType.CHARACTER_SET to UTF-8 ) private val reader MultiFormatReader().apply { setHints(hints) } private var onResult: ((String, String) - Unit)? null override fun analyze(imageProxy: ImageProxy) { val width imageProxy.width val height imageProxy.height val yArray extractYArray(imageProxy) val source PlanarYUVLuminanceSource( yArray, width, height, 0, 0, width, height, false ) val bitmap BinaryBitmap(HybridBinarizer(source)) try { val result reader.decodeWithState(bitmap) onResult?.invoke(result.text, result.barcodeFormat.name) } catch (_: NotFoundException) { // 當前幀沒找到條碼繼續(xù)預覽不打斷 } catch (_: ChecksumException) { // 定位到了但校驗失敗常見于遮擋或角度太大 } finally { imageProxy.close() } } }核心邏輯就是三步Y(jié) 數(shù)組 → 亮度源 → 二值圖 → 解碼。PlanarYUVLuminanceSource構(gòu)造函數(shù)里的六個數(shù)字分別是yArrayData, width, height, left, top, cropWidth, cropHeight, reverseHorizontal。這里的left/top是 0先做全圖解碼。decodeWithState會復用MultiFormatReader內(nèi)部狀態(tài)比每次都 new 一個 Reader 省分配。imageProxy.close()必須放在 finally 里漏掉的話 CameraX 會一直認為幀還在處理中畫面逐漸變卡。需要注意MultiFormatReader不是線程安全的。如果同一個ScannerAnalyzer實例在多個執(zhí)行線程里跑解析會出現(xiàn)奇怪的崩潰我一般會給解碼方法加一個synchronized或者直接保證ImageAnalysis使用單線程 Executor。3.3 綁定預覽并處理結(jié)果回調(diào)分析器寫好后需要在頁面里把Preview和ImageAnalysis都綁定到同一個ProcessCameraProvider上。val analysis ImageAnalysis.Builder() .setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_YUV_420_888) .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST) .build() analysis.setAnalyzer(Executors.newSingleThreadExecutor(), scannerAnalyzer) cameraProvider.bindToLifecycle( lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis )STRATEGY_KEEP_ONLY_LATEST很關(guān)鍵。它表示分析器處理不過來時直接丟棄中間幀只處理最新幀。這樣解碼慢一點只會降低識別幀率不會讓預覽越來越卡。如果選STRATEGY_BLOCK_PRODUCER相機采集會被阻塞畫面直接掉幀。另一個點OUTPUT_IMAGE_FORMAT_YUV_420_888要顯式指定否則不同設備默認輸出格式不一致有的會給你 RGBA分析代碼就得寫兩套分支。結(jié)果回調(diào)到 UI 層后還要做防抖。不然一個碼被連續(xù)識別幾十次掃碼頁面會抖得像抽風private var lastScanAt 0L private fun onScanResult(text: String, format: String) { val now System.currentTimeMillis() if (now - lastScanAt 2000L) { return } lastScanAt now viewModel.onScanCompleted(text, format) }兩秒閾值是我常用的經(jīng)驗值。識別完成后如果業(yè)務需要繼續(xù)掃下一個碼過兩秒再恢復解析如果不需要可以在拿到結(jié)果后直接解綁分析器避免后臺繼續(xù)耗電。許多項目在這里偷懶結(jié)果掃碼完成后相機還在偷偷逐幀分析發(fā)熱和內(nèi)存問題都從這兒來。4. 掃碼實戰(zhàn)中的避坑與排查四條最典型的現(xiàn)場問題4.1 豎屏場景識別率低到懷疑人生現(xiàn)象手機明明是豎著拿的取景框里二維碼顯示也正常但識別率低到 10% 以下尤其是一維條碼幾乎全滅。橫屏旋轉(zhuǎn)手機反而能掃出來。原因攝像頭傳感器是橫著安裝的CameraX 輸出的 Y 平面數(shù)據(jù)方向并不等于手機屏幕方向。zxing 拿到的亮度源是傳感器原始方向二維碼有定位圖案轉(zhuǎn)幾個角度還能勉強識別Code 128、EAN-13 這類線性條碼對方向極其敏感角度不對就完全解不出來。解決在構(gòu)造亮度源之后根據(jù)imageProxy.imageInfo.rotationDegrees對亮度源做旋轉(zhuǎn)。常見做法是判斷 90、180、270 三個旋轉(zhuǎn)角對應調(diào)用rotateCounterClockwise()。注意這個方法會重新拷貝一次圖像內(nèi)存放到解碼前的 try 塊里就行不用單獨緩存。我一般會寫一個函數(shù)把旋轉(zhuǎn)邏輯包起來避免每個分析器里都堆一段 if-else。注意有些設備rotationDegrees會返回 0 或 180但預覽畫面依然是正的這是因為 CameraX 在預覽路徑上已經(jīng)做了坐標系轉(zhuǎn)換。分析器拿到的幀不一定和預覽方向一致一定要以ImageInfo.rotationDegrees為準不要以預覽顯示效果為準。4.2 弱光環(huán)境下連續(xù)翻車現(xiàn)象暗光場景下畫面里明明能看到二維碼輪廓但識別過程反復失敗偶爾成功一次要卡好幾秒。同樣的代碼在白天自然光下非常流暢。原因光線不足時傳感器會提高增益來補償曝光噪點被一并放大。HybridBinarizer 的局部閾值對這種噪點圖穩(wěn)定性有限黑色模塊邊緣會被噪點打斷導致定位失敗。解決兩條路并行。第一條是產(chǎn)品層面加手電筒按鈕讓用戶主動補光這是市面上大多數(shù)掃碼 App 的做法第二條是代碼層面開TRY_HARDER它會用更密集的掃描線去搜索識別率有提升但耗時也會增加。我一般還會順便檢驗一下圖像質(zhì)量先算 Y 數(shù)組的平均亮度低于某個閾值就直接跳過本幀不執(zhí)行解碼。這個閾值我習慣定在 64 到 96 之間太亮也不行全是白板的時候解碼純屬浪費 CPU。val avgBrightness yArray.average().toInt() if (avgBrightness 64) { imageProxy.close() return }這段代碼放在構(gòu)造亮度源之后可以有效過濾掉過暗的幀。平均亮度的計算成本不高但能避免大量無效解碼。所謂“掃碼暗光翻車”多半不是 zxing 不行而是把每幀都拿去硬啃實際該放棄的幀沒放棄。4.3 某些條碼反復掃不出來現(xiàn)象同一個二維碼相冊里的截圖掃出來了攝像頭對著屏幕掃不出來換一臺手機卻能掃出來?；蛘?Code 128 條碼打出來的標簽上面能掃下面那截掃不出。原因原因有好幾層按概率排序。第一POSSIBLE_FORMATS沒把這種格式加進去第二二維碼在畫面里占比太小zxing 定位完發(fā)現(xiàn)面積不夠直接放棄第三條碼被產(chǎn)品包裝的曲面遮擋邊緣有斷裂第四商家自己生成的條碼質(zhì)量差模塊邊緣不整齊。解決先在POSSIBLE_FORMATS里補上對應格式這是最容易被忽略的一步。如果格式?jīng)]問題試著把取景框裁剪到畫面中間區(qū)域只對 ROI 做解碼。ROI 區(qū)域越小條碼在解碼圖里的相對占比越大識別率會明顯提升。做法是改PlanarYUVLuminanceSource的left/top/cropWidth/cropHeight參數(shù)。裁剪的時候ROI 的寬度和高度最好是偶數(shù)部分設備的 YUV 數(shù)據(jù)對奇數(shù)寬度會報錯。如果是對著屏幕掃碼還有一個常見問題屏幕本身會閃爍產(chǎn)生明暗條紋。解決思路是把分析器的曝光時間調(diào)長一點或者用硬件層面的電頻同步但這一般較難做到。我實際更常用的是讓用戶把手機稍微拉遠一點減少摩爾紋干擾。4.4 內(nèi)存抖動與日志刷屏現(xiàn)象掃碼頁面打開 5 分鐘內(nèi)存漲得很明顯Logcat 里不斷出現(xiàn)ArrayIndexOutOfBoundsException或者大量NotFoundException堆棧。原因ImageAnalysis的每一幀都是一次內(nèi)存分配Y 數(shù)組、亮度源、二值圖全部要建對象。如果imageProxy.close()沒有執(zhí)行緩存幀不斷堆積。NotFoundException本身是正常的——哪一幀沒有碼都會拋這個異常但有些項目直接在分析器里打了Log.e導致 logcat 幾十條幾百條地刷。解決第一imageProxy.close()放 finally第二NotFoundException和ChecksumException屬于“預期內(nèi)失敗”不需要寫日志第三控制分配頻率。MultiFormatReader.decodeWithState內(nèi)部會復用 Reader 的對象池但我們的 Y 數(shù)組和亮度源是每次都要新建的這部分省不掉。更好的辦法是降低分析幀率比如ImageAnalysis只處理每兩幀中的一幀。實驗數(shù)據(jù)上解碼成功率并不會明顯下降內(nèi)存和電量的改善卻很直接。5. 進階從相冊選圖解析與反向生成二維碼5.1 相冊選圖的解碼路徑除了攝像頭實時識別很多業(yè)務場景還需要從相冊里選一張圖片解析比如截圖里的收款碼、文檔里的條形碼。靜態(tài)圖片的解碼和實時幀不同它沒有 YUV 數(shù)據(jù)拿到手的是 Bitmap。這時要把像素數(shù)組喂給RGBLuminanceSource。fun decodeImage(bitmap: Bitmap): Result? { val width bitmap.width val height bitmap.height val pixels IntArray(width * height) bitmap.getPixels(pixels, 0, width, 0, 0, width, height) val source RGBLuminanceSource(width, height, pixels) val bitmapImage BinaryBitmap(HybridBinarizer(source)) return MultiFormatReader().apply { setHints(mapOf( DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE), DecodeHintType.TRY_HARDER to true )) }.decode(bitmapImage) }這段代碼和攝像頭路徑的主要區(qū)別在亮度源。RGBLuminanceSource內(nèi)部的像素格式必須是 RGBA_8888所以bitmap.getPixels之前先確認 Bitmap 的配置是 ARGB_8888。如果源頭是黑白圖或 RGB_565轉(zhuǎn)一下格式再做不然像素值解析會混亂。相冊圖片有可能很大解碼前先做壓縮把長邊壓到 1024 左右再解析速度會快很多識別率也不會降。5.2 生成二維碼把BitMatrix畫成圖很多時候掃碼功能是雙向的——不僅要讀碼還要展示一個二維碼給別人掃。zxing 的生成接口藏在MultiFormatWriter里它返回一個BitMatrix也就是一個布爾矩陣需要自己把它畫到 Bitmap 上。fun createQrBitmap(content: String, size: Int 512): Bitmap { val bitMatrix MultiFormatWriter().encode( content, BarcodeFormat.QR_CODE, size, size ) val bitmap Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888) for (x in 0 until size) { for (y in 0 until size) { val color if (bitMatrix[x, y]) Color.BLACK else Color.WHITE bitmap.setPixel(x, y, color) } } return bitmap }參數(shù)上size指的是輸出圖像的像素寬高不是二維碼實際模塊數(shù)。zxing 會根據(jù)內(nèi)容和容量決定二維碼的版本也就是模塊數(shù)量然后在傳入的size范圍內(nèi)自動縮放。如果內(nèi)容很長比如帶了一長串 URL生成出來的二維碼會有很多小模塊建議增大size避免掃描失敗。反向生成時還有個坑默認生成的 BitMatrix 二維碼四周邊距很窄有些掃碼工具會識別失敗。解決方式是手動加白邊把BitMatrix繪制到更大的白色 Bitmap 中間四周各留 8 到 16 像素。另外邏輯上生成二維碼時最好在 UI 線程外操作。encode過程對長文本內(nèi)容耗時可能在幾十毫秒到幾百毫秒之間如果在主線程直接調(diào)用頁面會掉幀。直接用Executors.newSingleThreadExecutor()包一層即可。掃碼功能做久了我養(yǎng)成一個習慣每次接入新項目都會先列一個驗證清單攝像頭實時解碼、相冊靜態(tài)圖解碼、批量生成后再解碼三條鏈路分開測。那次因為只在真機上驗證了實時掃碼、沒測相冊路徑結(jié)果圖片解析漏了RGBLuminanceSource的格式轉(zhuǎn)換上線當天就被用戶翻到相冊掃碼的問題。從那以后每條鏈路我都會強制走一遍尤其是“生成→解碼→對比原文”的閉環(huán)能少走很多彎路。希望幫到你。本文還有配套的精品資源點擊獲取