前言看到社區(qū)有個有趣的提問是關于文字識別的, 原話如下:在做發(fā)票文字提取功能,按照官方示例的十來行代碼,結果一跑翻車啦:第一次調 recognizeText 直接拋錯,報運行失敗;處理完圖片再識別,接口調用成功,但返回的文本是空的;偶爾結果只有一半,或明明有文字卻顯示 未識別。想搞清楚 textRecognition 從初始化到拿結果,到底哪一步容易漏或踩坑問題地址: textRecognition 識別圖片:直接調用拋錯、換張圖返回空文本、結果還不完整,哪里沒寫對?。其實關于文字識別還是比較簡單的(相對而言),這篇文章我會詳細的把每一步為什么這樣寫講清楚。你也可以直接跳到最后的完整示例對照自己的項目排查。相關效果圖手里沒有合適的發(fā)票我從網上下載了一張發(fā)票接下來主要是對該發(fā)票的識別UI 界面如下文字識別結果如下語言識別結果如下先記住這條鏈路完整流程可以壓縮成下面 6 步用PhotoViewPicker選擇圖片拿到file://URI。通過fileIo.openSync()打開 URI拿到文件描述符fd。用fd創(chuàng)建ImageSource再生成RGBA_8888格式的PixelMap。API 12 及以上先調用textRecognition.init()。保證PixelMap一直存活到recognizeText()完成。識別結束后按順序釋放PixelMap、文件和 OCR 引擎資源。后面所有代碼都是圍繞這條鏈路展開的。開始之前導入和權限用textRecognition需要從kit.CoreVisionKit導入。圖片處理用kit.ImageKit選圖用kit.CoreFileKit的 picker讀文件也要kit.CoreFileKit的fileIoimport{textRecognition}fromkit.CoreVisionKitimport{image}fromkit.ImageKitimport{picker}fromkit.CoreFileKitimport{fileIoasfs}fromkit.CoreFileKitimport{BusinessError}fromkit.BasicServicesKit權限方面用PhotoViewPicker選圖不需要額外權限picker 自己處理了。module.json5里已有的READ_IMAGEVIDEO權限在 API 12 上其實也不需要了。如果你直接用photoAccessHelper訪問相冊而不是用 picker那才需要。如下圖所示直接訪問我的本地相冊先把圖片正確交給 OCR選圖picker 返回的 URI 不能直接用選圖這部分本身不難用PhotoViewPicker就行constoptionsnewpicker.PhotoSelectOptions()options.MIMETypepicker.PhotoViewMIMETypes.IMAGE_TYPEoptions.maxSelectNumber1constphotoPickernewpicker.PhotoViewPicker()constresult:picker.PhotoSelectResultawaitphotoPicker.select(options)constimageUri:stringresult.photoUris[0]拿到imageUri之后關鍵問題來了。坑 1createImageSource(imageUri)報路徑錯誤picker 返回的 URI 長這樣file://media/Photo/1925/IMG_xxx.jpg。很多人直接拿這個字符串傳給image.createImageSource(imageUri)然后報錯path (media/Photo/1925/...) to realpath error: No such file or directory [FileSourceStream] input the file path exception, errno:2. CreateImageSourceExec error原因是createImageSource(path)接受的是沙箱文件路徑不是file://URI。picker 返回的 URI 需要通過fileIo打開拿到 fd再用 fd 創(chuàng)建 ImageSourceconstfile:fs.Filefs.openSync(imageUri,fs.OpenMode.READ_ONLY)constsource:image.ImageSourceimage.createImageSource(file.fd)用完 fd 記得關fs.closeSync(file)但是closeSync的時機有講究——必須在createPixelMap完成之后再關。因為createPixelMap是異步的fd 提前關了PixelMap 數據就丟了。這個生命周期問題也是華為開發(fā)者論壇相關問題中反復出現(xiàn)的排查重點建議結合論壇問題與解決記錄一起看。OCR 引擎API 12 之后必須初始化這是第二個坑也是最容易踩的?？?2跳過init()直接調recognizeText報錯 1001400001在 API 12 之前textRecognition沒有init()方法直接調recognizeText就行。但從 API 12HarmonyOS 5.0開始必須先調init()初始化引擎否則報錯BusinessError 1001400001: Failed to run OCR, please try again.正確做法constinitResult:booleanawaittextRecognition.init()if(!initResult){// 初始化失敗設備可能不支持 OCRreturn}init()返回Promisebooleantrue表示成功。如果返回false或拋異常說明當前設備不支持 OCR 能力。頁面銷毀時記得釋放aboutToDisappear():void{textRecognition.release()}這一步很關鍵不 release 的話 OCR 引擎資源不會被回收多次進出頁面可能內存泄漏。PixelMap格式不對結果可能直接為空圖片加載到 PixelMap 這步是第三個坑的高發(fā)區(qū)?？?3PixelMap 格式不是 RGBA_8888識別結果為空textRecognition的VisionInfo接口只支持RGBA_8888格式的 PixelMap。如果你不指定格式createPixelMap默認可能返回BGRA_8888或其他格式調用recognizeText不會報錯但返回的value是空字符串。必須在DecodingOptions里顯式指定constimageInfo:image.ImageInfoawaitsource.getImageInfo()constdecodingOptions:image.DecodingOptions{editable:true,desiredPixelFormat:image.PixelMapFormat.RGBA_8888,desiredSize:{width:imageInfo.size.width,height:imageInfo.size.height}}constpm:image.PixelMapawaitsource.createPixelMap(decodingOptions)這里有兩點要注意editable: true——PixelMap 需要可編輯某些后續(xù)操作比如方向校正可能會需要desiredSize保留原始尺寸——不要在這里壓縮圖片OCR 對分辨率敏感壓縮后再識別準確率會下降如果你想預覽縮略圖可以單獨創(chuàng)建一個小尺寸的 PixelMap 給 UI 展示用OCR 用原始尺寸的。fd的生命周期異步操作沒結束文件不能關前面說過fs.openSync拿到的 fd 必須在createPixelMap完成后才能關。把完整流程放在一起看letfile:fs.File|undefinedundefinedletsource:image.ImageSource|undefinedundefinedtry{// 1. 通過 URI 打開文件拿到 fdfilefs.openSync(imageUri,fs.OpenMode.READ_ONLY)// 2. 用 fd 創(chuàng)建 ImageSourcesourceimage.createImageSource(file.fd)// 3. 創(chuàng)建 RGBA_8888 格式的 PixelMap異步操作constpm:image.PixelMapawaitsource.createPixelMap(decodingOptions)this.pixelMapForOCRpm// 4. 再創(chuàng)建一個縮略圖給 UI 預覽this.previewPixelMapawaitsource.createPixelMap(previewOpts)}catch(e){// 異常時也要關 fdif(file!undefined){fs.closeSync(file)}return}// 5. createPixelMap 都完成了安全關閉 fdif(file!undefined){fs.closeSync(file)}劃重點closeSync一定要在所有createPixelMap的await之后。如果提前關了 fdPixelMap 里就是空數據OCR 識別出來自然是空的。調用recognizeText結果怎么拿、怎么定位前面四步都做對了這一步就簡單了constvisionInfo:textRecognition.VisionInfo{pixelMap:this.pixelMapForOCR}constconfig:textRecognition.TextRecognitionConfiguration{isDirectionDetectionSupported:true}constocrResult:textRecognition.TextRecognitionResultawaittextRecognition.recognizeText(visionInfo,config)isDirectionDetectionSupported建議設為true。手機拍發(fā)票經常是歪的或倒著的開啟方向檢測能自動糾正。如果你能確定圖片方向是正的設false可以提升性能。識別結果的數據結構TextRecognitionResult是個嵌套結構TextRecognitionResult ├── value: string // 全部識別文本拼成一個字符串 └── blocks: TextBlock[] // 文本塊數組 ├── value: string // 該塊的文本 └── lines: TextLine[] // 行數組 ├── value: string // 該行的文本 └── words: TextWord[] // 詞數組 ├── value: string // 該詞的文本 └── cornerPoints: PixelPoint[] // 四角坐標最常用的就是result.value直接拿到全部文字。如果你需要按塊或按行定位比如發(fā)票上提取某個字段就遍歷blocks和linesconstblocks:ArraytextRecognition.TextBlockocrResult.blocksfor(leti0;iblocks.length;i){constblock:textRecognition.TextBlockblocks[i]console.info(塊${i1}:${block.value})constlines:ArraytextRecognition.TextLineblock.linesfor(letj0;jlines.length;j){console.info(行${j1}:${lines[j].value})}}每個TextWord還帶有cornerPoints四個角的像素坐標可以用來在圖上畫框高亮。識別結果只有一半先查PixelMap是否被提前釋放隱藏原因結果只有一半還有一種情況識別結果只出來一部分或者明明有文字卻顯示未識別。排查后發(fā)現(xiàn)是 PixelMap 在識別完成前被release()了。比如在aboutToAppear里創(chuàng)建了 PixelMap識別還沒跑完頁面切換觸發(fā)aboutToDisappear把 PixelMap 釋放了recognizeText還在用這塊內存結果就是數據不完整。解決辦法PixelMap 的生命周期必須覆蓋整個識別過程。在我的代碼里pixelMapForOCR作為組件的私有成員只在下一次選圖時才釋放上一張// 釋放上一張的 PixelMapif(this.pixelMapForOCR!undefined){this.pixelMapForOCR.release()this.pixelMapForOCRundefined}頁面銷毀時才釋放當前這張aboutToDisappear():void{if(this.pixelMapForOCR!undefined){this.pixelMapForOCR.release()}textRecognition.release()}完整代碼把整條鏈路串起來把上面所有步驟串起來下面是通用文字識別的核心邏輯。我把完整代碼貼出來方便你直接對照import { textRecognition } from kit.CoreVisionKit import { image } from kit.ImageKit import { picker } from kit.CoreFileKit import { fileIo as fs } from kit.CoreFileKit import { BusinessError } from kit.BasicServicesKit Entry Component struct Qa4 { State recognizedText: string State statusMsg: string 點擊按鈕選擇圖片進行文字識別 State isRecognizing: boolean false State previewPixelMap: image.PixelMap | undefined undefined State blockDetails: string State supportedLangs: string private pixelMapForOCR: image.PixelMap | undefined undefined aboutToDisappear(): void { if (this.pixelMapForOCR ! undefined) { this.pixelMapForOCR.release() } if (this.previewPixelMap ! undefined) { this.previewPixelMap.release() } textRecognition.release() } private async pickAndRecognize(): Promisevoid { if (this.isRecognizing) { return } this.isRecognizing true this.recognizedText this.blockDetails this.statusMsg 選擇圖片中... let imageUri: string try { const options new picker.PhotoSelectOptions() options.MIMEType picker.PhotoViewMIMETypes.IMAGE_TYPE options.maxSelectNumber 1 const photoPicker new picker.PhotoViewPicker() const result: picker.PhotoSelectResult await photoPicker.select(options) if (result.photoUris.length 0) { this.statusMsg 未選擇圖片 this.isRecognizing false return } imageUri result.photoUris[0] } catch (e) { const err e as BusinessError this.statusMsg 選擇圖片失敗: ${err.code} this.isRecognizing false return } this.statusMsg 正在初始化 OCR 引擎... try { const initResult: boolean await textRecognition.init() if (!initResult) { this.statusMsg OCR 引擎初始化失敗 this.isRecognizing false return } } catch (e) { const err e as BusinessError this.statusMsg OCR init 失敗: ${err.code} this.isRecognizing false return } this.statusMsg 正在加載圖片... if (this.pixelMapForOCR ! undefined) { this.pixelMapForOCR.release() this.pixelMapForOCR undefined } if (this.previewPixelMap ! undefined) { this.previewPixelMap.release() this.previewPixelMap undefined } let file: fs.File | undefined undefined let source: image.ImageSource | undefined undefined try { file fs.openSync(imageUri, fs.OpenMode.READ_ONLY) source image.createImageSource(file.fd) const imageInfo: image.ImageInfo await source.getImageInfo() const decodingOptions: image.DecodingOptions { editable: true, desiredPixelFormat: image.PixelMapFormat.RGBA_8888, desiredSize: { width: imageInfo.size.width, height: imageInfo.size.height } } const pm: image.PixelMap await source.createPixelMap(decodingOptions) this.pixelMapForOCR pm const previewOpts: image.DecodingOptions { editable: false, desiredSize: { width: 360, height: 360 } } try { this.previewPixelMap await source.createPixelMap(previewOpts) } catch (_) { this.previewPixelMap pm } } catch (e) { const err e as BusinessError this.statusMsg 圖片加載失敗: ${err.code} - ${err.message} if (file ! undefined) { fs.closeSync(file) } this.isRecognizing false return } if (file ! undefined) { fs.closeSync(file) } this.statusMsg 正在識別文字... try { const visionInfo: textRecognition.VisionInfo { pixelMap: this.pixelMapForOCR as image.PixelMap } const config: textRecognition.TextRecognitionConfiguration { isDirectionDetectionSupported: true } const ocrResult: textRecognition.TextRecognitionResult await textRecognition.recognizeText(visionInfo, config) const fullText: string ocrResult.value if (fullText.length 0) { this.recognizedText 未識別到文字 this.statusMsg 識別完成但結果為空 this.isRecognizing false return } this.recognizedText fullText this.statusMsg 識別完成共 ${fullText.length} 字符${ocrResult.blocks.length} 個文本塊 let detail: string const blocks: ArraytextRecognition.TextBlock ocrResult.blocks for (let i 0; i blocks.length; i) { const block: textRecognition.TextBlock blocks[i] detail 【塊${i 1}】${block.value}\n const lines: ArraytextRecognition.TextLine block.lines for (let j 0; j lines.length; j) { const line: textRecognition.TextLine lines[j] detail 行${j 1}: ${line.value}\n } } this.blockDetails detail } catch (e) { const err e as BusinessError this.statusMsg 識別失敗: ${err.code} - ${err.message} this.recognizedText } this.isRecognizing false } private async querySupportedLanguages(): Promisevoid { try { const langs: Arraystring await textRecognition.getSupportedLanguages() this.supportedLangs langs.join(, ) } catch (e) { const err e as BusinessError this.supportedLangs 查詢失敗: ${err.code} } } build() { Scroll() { Column() { Text(textRecognition 文字識別) .fontSize(22) .fontWeight(FontWeight.Bold) .fontColor(#1A1A1A) .width(100%) .padding({ left: 20, right: 20, top: 20, bottom: 8 }) Row() { Button(選擇圖片識別) .type(ButtonType.Capsule) .backgroundColor(#3274F6) .fontColor(Color.White) .enabled(!this.isRecognizing) .onClick(() { this.pickAndRecognize() }) Button(查詢支持語言) .type(ButtonType.Capsule) .backgroundColor(#FF9800) .fontColor(Color.White) .onClick(() { this.querySupportedLanguages() }) } .width(92%) .justifyContent(FlexAlign.SpaceEvenly) .margin({ top: 16 }) Text(this.statusMsg) .fontSize(14) .fontColor(#666666) .width(92%) .margin({ top: 12 }) .maxLines(6) .textOverflow({ overflow: TextOverflow.Ellipsis }) if (this.previewPixelMap ! undefined) { Image(this.previewPixelMap) .width(92%) .height(240) .objectFit(ImageFit.Contain) .borderRadius(12) .margin({ top: 12 }) .backgroundColor(#F5F5F5) } if (this.recognizedText.length 0) { Column() { Text(識別結果) .fontSize(16) .fontWeight(FontWeight.Medium) .margin({ bottom: 8 }) Text(this.recognizedText) .fontSize(14) .fontColor(#333333) .lineHeight(22) .width(100%) .maxLines(20) .textOverflow({ overflow: TextOverflow.Ellipsis }) .copyOption(CopyOptions.LocalDevice) } .width(92%) .padding(16) .backgroundColor(Color.White) .borderRadius(12) .margin({ top: 12 }) .alignItems(HorizontalAlign.Start) } if (this.blockDetails.length 0) { Column() { Text(分塊詳情) .fontSize(16) .fontWeight(FontWeight.Medium) .margin({ bottom: 8 }) Text(this.blockDetails) .fontSize(12) .fontColor(#555555) .lineHeight(20) .width(100%) .maxLines(30) .textOverflow({ overflow: TextOverflow.Ellipsis }) } .width(92%) .padding(16) .backgroundColor(Color.White) .borderRadius(12) .margin({ top: 8 }) .alignItems(HorizontalAlign.Start) } if (this.supportedLangs.length 0) { Column() { Text(支持的語言) .fontSize(16) .fontWeight(FontWeight.Medium) .margin({ bottom: 8 }) Text(this.supportedLangs) .fontSize(14) .fontColor(#333333) .width(100%) } .width(92%) .padding(16) .backgroundColor(Color.White) .borderRadius(12) .margin({ top: 8, bottom: 24 }) .alignItems(HorizontalAlign.Start) } } .width(100%) } .scrollBar(BarState.Auto) .edgeEffect(EdgeEffect.Spring) .width(100%) .height(100%) .backgroundColor(#F2F3F5) } }出錯時怎么查錯誤碼速查識別過程中可能遇到的 BusinessError錯誤碼含義常見原因200運行超時圖片太大縮小后重試401參數檢查失敗VisionInfo 里的 PixelMap 為空或格式不對1001400001OCR 運行失敗沒調init()、PixelMap 已釋放、格式非 RGBA_88881001400002OCR 服務異常引擎內部錯誤重啟應用重試支持哪些語言textRecognition目前支持簡體中文、英文、日文、韓文、繁體中文?？梢酝ㄟ^getSupportedLanguages()查詢當前設備實際支持的語言列表constlangs:ArraystringawaittextRecognition.getSupportedLanguages()返回[zh-CN, en, ja, ko, zh-TW]之類的數組。不同設備可能不同最好運行時查一下。寫在最后回頭看textRecognition的 API 本身并不復雜真正讓人卡住的是數據和資源的交接URI 不能直接當路徑要通過fileIo.openSync轉 fd必須先init()API 12 新增的要求官方文檔更新了但很多人沒注意到PixelMap 格式必須是RGBA_8888不指定就可能是別的格式識別結果為空fd 和 PixelMap 的生命周期提前關 fd 或釋放 PixelMap 都會導致識別失敗或結果不完整把這四點搞對了textRecognition基本就能穩(wěn)定跑通。發(fā)票、名片、截圖提取文字都不在話下。