更新记录

1.3.9（2026-11-07）

• 优化说明文档，补齐“作者系列 UTS 插件”清单及插件市场链接，便于按能力查找。

1.3.8（2026-10-29）

• 修复文档“下载与导入”中的重复内容，改用表格集中展示 uni-app 与 uni-app x 完整示例路径。
• 优化接入说明，移除 Android 车牌内核手动下载介绍，保留云打包自动获取依赖和安装后离线使用的说明。
• 本版仅调整文档、发布及示例诊断版本；已有匹配 1.3.7 的基座或原生安装包无需因本次更新重新制作。

1.3.7（2026-10-28）

• 优化 Android 车牌依赖交付：运行库、模型和词典改为构建阶段解析固定版本仓储依赖，减少插件及提交云打包的本地文件体积，保留安装后的离线识别能力。
• 同步插件与示例诊断版本；升级后需重新制作包含当前依赖的 Android 自定义基座或原生安装包，页面热更新无法更新这些原生依赖。
• 优化：Android 车牌内核 Maven 仓储统一迁移至 lizhao-doc-corrector 英文云目录，同步客户依赖下载路径；保留固定坐标、模型、词典和 AAR 原字节。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-doc-corrector

介绍

面向 uni-app / uni-app x 的文档扫描与 OCR 插件：拍摄或导入图片，完成四角矫正、文字及证件信息提取，人工核对后用于业务录入，也可导出 JPEG 或 PDF。

功能特色

五类识别均提供原生拍摄与核对界面，支持相册入口、重拍、修改、复制和确认；已有图片也可以直接调用识别 API。识别在设备端完成，无需配置云 OCR 账号或密钥。

适合哪些场景

下载与导入

在插件市场选择“使用 HBuilderX 导入插件”，导入项目。

从基础到进阶：按业务模块使用

通用 uni-app 片段使用 Vue2/Vue3 均可使用的选项式写法；uni-app x 的强类型 UTS 页面与参数说明见 uni_modules/lizhao-doc-corrector/readme.md（API 用途速查）。下列业务方法应绑定到按钮或页面生命周期，按需调用。

模块：拍摄或选图后核对文字

适合有人工确认环节的录入页面。success 返回确认结果；用户关闭进入 fail(9020016)，complete 负责解除按钮忙碌。

<template>
  <view>
    <button :disabled="recognizing" @tap="readText">OCR 文字识别</button>
    <text selectable>{{ resultText }}</text>
  </view>
</template>

<script>
import { openDocumentRecognition, closeDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 本页面使用自己的会话 ID，离开时按同一 ID 关闭。
const sessionId = 'text-entry'
export default {
  data() {
    // 识别界面打开期间禁用重复点击；结果留在当前页面展示。
    return { recognizing: false, resultText: '' }
  },
  onUnload() {
    closeDocumentRecognition({ sessionId })
  },
  methods: {
    readText() {
      if (this.recognizing) return
      this.recognizing = true
      openDocumentRecognition({
        sessionId,
        recognitionType: 'text',
        success: (res) => {
          // 用户点击“确认结果”后才触发，读取核对后的全文。
          this.resultText = res.confirmedText
        },
        fail: (err) => {
          // 关闭界面属于正常取消，其他错误再提示使用者。
          if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
        },
        complete: () => { this.recognizing = false }
      })
    }
  }
}
</script>

模块：证件与号牌录入

用于中国大陆居民身份证录入。人像面使用 front，国徽面使用 back，界面内也可以切换。一张图、一次确认只返回当前面的结果；需要正反面资料时，分别识别并由业务汇总。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 识别人像面；识别国徽面时将 side 改为 'back'。
function recognizeIdentity() {
  openDocumentRecognition({
    recognitionType: 'idCard',
    side: 'front',
    success: (res) => {
      // 按 key 查找，不能假设字段总在数组的固定位置。
      const idNumber = res.confirmedFields.find((field) => field.key === 'idNumber')
      if (idNumber != null) {
        uni.showModal({ title: '已确认的身份证号', content: idNumber.value, showCancel: false })
      }
      // 最终识别的是哪一面，以 res.side 为准。
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

银行卡、车牌、驾驶证分别使用 recognitionType: bankCard / licensePlate / driverLicense；确认字段与双面识别示例见 uni_modules/lizhao-doc-corrector/readme.md（从基础到进阶：按业务模块使用）。

模块：识别已有图片

适合已拍摄的图片、业务文件或自行选择的相册图片。下面通过系统相册取得真实本地路径，再执行 OCR；直接识别 API 不提供核对界面，success 返回原始识别结果。

import { recognizeDocument } from '@/uni_modules/lizhao-doc-corrector'

// 由按钮调用；识别类型为 paper，不能把 UI 的 'text' 填到 documentType。
function readExistingImage() {
  uni.chooseImage({
    count: 1,
    sourceType: ['album'],
    success: (selected) => {
      if (selected.tempFilePaths.length === 0) return
      recognizeDocument({
        imagePath: selected.tempFilePaths[0],
        documentType: 'paper',
        timeoutMs: 8000,
        success: (res) => {
          // 这里只是识别原文；需要人工核对时由业务展示或使用原生识别界面。
          uni.showModal({ title: '识别文字', content: res.rawText, showCancel: false })
        },
        fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
      })
    }
  })
}

专项 API 使用相同的 imagePath、success / fail / complete 结构，自动指定识别类型，不必再传 documentType。

import { recognizeIdCard, recognizeBankCard, recognizeLicensePlate, recognizeDriverLicense } from '@/uni_modules/lizhao-doc-corrector'

// imagePath 必须来自相册、拍摄结果或应用已有的可读本地文件。
// 这些函数各自调用一次，不要对同一图片同时执行四种识别。
function readIdBack(imagePath) {
  recognizeIdCard({ imagePath, side: 'back', success: showFields, fail: showError })
}
function readBankCard(imagePath) {
  recognizeBankCard({ imagePath, success: showFields, fail: showError })
}
function readLicensePlate(imagePath) {
  recognizeLicensePlate({ imagePath, success: showFields, fail: showError })
}
function readDriverSecondary(imagePath) {
  recognizeDriverLicense({ imagePath, side: 'secondary', success: showFields, fail: showError })
}
function showFields(res) {
  // structuredFields 是数组；按 key 读取需要的值，同时保留 warnings 供核对。
  const lines = res.structuredFields.map((field) => field.key + '：' + field.value)
  uni.showModal({ title: '识别字段', content: lines.join('\n'), showCancel: false })
}
function showError(err) {
  uni.showToast({ title: err.errMsg, icon: 'none' })
}

uni-app x 的图片识别回调可从插件根目录导入 RecognizeDocumentResult，例如 success: (res: RecognizeDocumentResult) => { ... }。

模块：扫描矫正

用于合同、试卷、纸质材料归档。detect 会打开原生相机，拍照后可拖动四角，确认后得到矫正图。

import { detect, stopDocumentSession } from '@/uni_modules/lizhao-doc-corrector'

// 单次扫描始终使用同一会话 ID。
function scanDocument() {
  detect({
    sessionId: 'document-entry',
    documentType: 'contract',
    enableManualAdjust: true,
    cameraResult: (res) => { console.log('拍摄原图路径', res.imagePath) },
    adjustResult: (res) => {
      // 确认后的图片在这里获取，可绑定 image 组件或继续 OCR、导出。
      uni.previewImage({ urls: [res.imagePath] })
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}
// 在页面卸载或业务取消时调用，不能在 scanDocument() 后立即调用。
function closeScan() { stopDocumentSession({ sessionId: 'document-entry' }) }

detect.success 表示扫描页已打开，最终矫正图从 adjustResult.imagePath 获取。 这与识别界面的 openDocumentRecognition.success 表示“用户已确认识别结果”不同。只设置 documentType 不会开启 OCR；设置 enableOcr: true 后，从最终结果的 recognitionResult 读取原始 OCR。OCR 失败时图片仍返回，原因在 recognitionError。

模块：四角检测与图片增强

适合相册图片或已有照片。先取得真实四角，再把同一原图与角点交给矫正接口；业务也可在两步之间让用户拖点调整。

import { detectDocumentCorners, correctDocument } from '@/uni_modules/lizhao-doc-corrector'

// imagePath 是已有本地图片路径；四角与原图必须配对使用。
function correctExistingImage(imagePath) {
  detectDocumentCorners({
    imagePath,
    success: (detected) => {
      correctDocument({
        imagePath: detected.originalImagePath,
        corners: detected.corners,
        enhanceMode: 'color',
        success: (res) => { uni.previewImage({ urls: [res.imagePath] }) },
        fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
      })
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

corners 顺序为左上、右上、右下、左下。Android / iOS 独立检测返回的是按照片方向旋正后的完整原图像素坐标；Android 的检测结果 imagePath 可能是缩小的预览图，不能直接配用原图角点。自行绘制拖点时，需把显示坐标换算回同一原图像素。

correctDocument 可以省略 corners 或传空数组，自动检测后矫正；找不到可靠边缘时返回 9020007。非空数组必须包含 4 个有效点，显式传四角时按传入区域处理。stretchFix 保留为兼容参数；当前透视流程始终按四角拉正，不提供独立开关式的曲面/书页展平。

适合已完成矫正、只需要调整颜色或文字清晰度的图片，不会打开相机。

import { enhanceDocument } from '@/uni_modules/lizhao-doc-corrector'

// 已取得的矫正图使用黑白模式增强；成功路径可继续用于导出。
function enhanceTextImage(imagePath) {
  enhanceDocument({
    imagePath,
    enhanceMode: 'bw',
    success: (res) => { uni.previewImage({ urls: [res.imagePath] }) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

增强无法恢复已经模糊或缺失的文字。四角矫正用于拉正平面文档，不等于文字行自动纠斜或弯曲书页展平。

模块：多页导出

适合将处理结果保存为文件，再用于上传、分享或归档。按 PDF 页序传入输出图片，等待导出成功后读取文件。

import { exportDocument } from '@/uni_modules/lizhao-doc-corrector'

// 传入矫正/增强结果的 imagePath 列表；传原图路径就会导出原图。
function exportPdf(imagePaths) {
  exportDocument({
    imagePaths,
    format: 'pdf',
    fileName: 'documents.pdf',
    success: (res) => { console.log('导出文件路径与页数', res.filePath, res.pageCount) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}
// 单张图片导出为 JPEG：质量范围 1–100，默认 92。
function exportJpeg(imagePath) {
  exportDocument({
    imagePaths: [imagePath], format: 'jpeg', fileName: 'document.jpg', quality: 92,
    success: (res) => { console.log('JPEG 文件路径', res.filePath) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

fileName 只传文件名，不传目录、路径分隔符、. 或 ..。为保留已有导出，实际文件名可能补充唯一标识，应始终使用返回的 filePath。

PDF 需要每张输入图片都可读取，任一页失败会通过 fail 返回，不会静默丢页并报告成功；pageCount 表示实际导出页数。PDF 不会自动再矫正或添加可搜索文字层；长期保存、上传、分享由业务取得 filePath 后完成。

批量 OCR、完整会话、自动识别配置、原始/确认结果区分及主动关闭的完整代码见 uni_modules/lizhao-doc-corrector/readme.md（从基础到进阶：按业务模块使用）。

完整业务示例与接入说明

快速开始

先跑通“点击按钮 → 拍照或选图 → 核对 → 返回文字”。下面两份最小页面按项目类型选一份使用。

uni-app x 页面

以下为 uni-app x UTS 页面写法。

<template>
  <view>
    <button :disabled="recognizing" @tap="readText">OCR 文字识别</button>
    <text selectable>{{ resultText }}</text>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'
import { onUnload } from '@dcloudio/uni-app'
import { openDocumentRecognition, closeDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'
import type { DocumentRecognitionResult, DocumentCorrectorFail } from '@/uni_modules/lizhao-doc-corrector'

// 页面状态与本页面专用的识别会话 ID。
const recognizing = ref<boolean>(false)
const resultText = ref<string>('')
const sessionId: string = 'text-entry'

function readText() {
  if (recognizing.value) return
  recognizing.value = true
  openDocumentRecognition({
    sessionId: sessionId,
    recognitionType: 'text',
    success: (res: DocumentRecognitionResult) => {
      // UTS 回调使用公开结果类型；最终文字来自用户确认结果。
      resultText.value = res.confirmedText
    },
    fail: (err: DocumentCorrectorFail) => {
      if (err.errCode != 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    },
    complete: () => { recognizing.value = false }
  })
}

onUnload(() => { closeDocumentRecognition({ sessionId: sessionId }) })
</script>

先选对入口： 需要拍照、相册、核对界面用 openDocumentRecognition；只处理已有图片用 recognizeDocument 或专项识别 API；需要拍照后拖动四角并取得矫正图片用 detect。

按需查阅：五类识别 · 已有图片 · 扫描与处理 · 特殊用法 · API 与参数 · 常见问题。

后面的 js 示例用于 uni-app 页面的按钮事件或业务方法；uni-app x 的识别调用使用相同参数，结果和错误可按上面的 DocumentRecognitionResult、DocumentCorrectorFail 声明类型。涉及旧扫描会话的 uni-app x 完整写法请参照随插件提供的 .uvue 示例。

五类识别

以下五个模块都使用 openDocumentRecognition，每次只打开一种场景。success 在使用者核对并确认后触发，关闭界面进入 fail，错误码为 9020016。

OCR 文字

用于复制纸张、截图或照片中的文字。可在结果页修改全文，也可直接使用界面的复制按钮。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 放在按钮点击事件中，确认后复制用户核对过的文字。
function recognizeText() {
  openDocumentRecognition({
    recognitionType: 'text',
    success: (res) => {
      uni.setClipboardData({ data: res.confirmedText })
      // 需要识别原文时读取 res.originalResult.rawText。
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

通用文字没有证件面，不传 side。confirmedFields 可以是空数组；提取全文应读取 confirmedText。

银行卡

用于从卡片图片录入卡号。当前字段为卡号和图片中的银行名称，不承诺提取持卡人、有效期或卡类型，也不会查询账户余额或开户资料。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 银行卡不传 side；对照原卡核对后再把号码填入业务表单。
function recognizeBank() {
  openDocumentRecognition({
    recognitionType: 'bankCard',
    success: (res) => {
      const card = res.confirmedFields.find((field) => field.key === 'cardNumber')
      if (card != null) {
        uni.showModal({ title: '已确认的银行卡号', content: card.value, showCancel: false })
      }
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

字段：cardNumber 卡号、bankName 银行名称。银行名称来自图片文字，图片中没有或未识别到时可能缺失。Luhn 校验只检查数字组合是否满足规则，不能判断银行卡是否真实、有效或属于某个人。

车牌号

用于中国大陆普通车牌和新能源车牌录入。拍摄时尽量让整块车牌清晰入框，特别保留最左侧的省份简称。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 普通车牌和新能源车牌使用同一个入口，不传 side。
function recognizePlate() {
  openDocumentRecognition({
    recognitionType: 'licensePlate',
    success: (res) => {
      const plate = res.confirmedFields.find((field) => field.key === 'plateNumber')
      if (plate != null) {
        uni.showModal({ title: '已确认的车牌号', content: plate.value, showCancel: false })
      }
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

字段：plateNumber 车牌号码。特殊号牌、其他国家或地区的号牌可改用 OCR 文字识别，再由业务判断。识别结果不包含车辆登记信息。

驾驶证

用于中国大陆驾驶证信息录入。主页使用 main，副页使用 secondary，默认主页；需要两面的资料时分别调用。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 识别主页；副页改用 side: 'secondary'，读取 fileNumber 等字段。
function recognizeDrivingLicense() {
  openDocumentRecognition({
    recognitionType: 'driverLicense',
    side: 'main',
    success: (res) => {
      const license = res.confirmedFields.find((field) => field.key === 'licenseNumber')
      if (license != null) {
        uni.showModal({ title: '已确认的驾驶证号', content: license.value, showCancel: false })
      }
      // 允许用户在界面切面，按 res.side 选择业务表单。
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

原始 OCR 字段依赖图片内容和识别效果，可能缺失或为空。三端核对界面均显示当前证件面的标准字段，漏识别时可以补录；可选项允许留空。人工补录只出现在 confirmedFields，不会写入 originalResult，也不代表证件真实性验证。

合同与试卷

用于提取全文、辅助检索和整理。合同、试卷没有独立的 recognitionType 取景模式；先取得图片，再调用专项 API。

import { recognizeContract, recognizeExamPaper } from '@/uni_modules/lizhao-doc-corrector'

// 传入前一步取得的合同图片；主要读取全文，字段作为辅助信息。
function readContract(imagePath) {
  recognizeContract({
    imagePath,
    success: (res) => { uni.showModal({ title: '合同文字', content: res.rawText, showCancel: false }) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}
// 试卷使用独立函数，在用户选择试卷图片后调用。
function readExamPaper(imagePath) {
  recognizeExamPaper({
    imagePath,
    success: (res) => { uni.showModal({ title: '试卷文字', content: res.rawText, showCancel: false }) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

三端合同的辅助字段为 title / party / partyA / partyB / date / amount，试卷为 title / score / sections / questionNumbers。只填写能从原文提取的信息，缺失时为空；历史 party 保留各端旧含义，不保证含有双方，读取甲乙方请使用 partyA / partyB。插件不提供合同条款分析、题目解答或自动阅卷。

批量处理

适合多页合同、整套试卷。每张图片分别处理，单项失败不会阻断其余图片。

import { batchProcessDocuments } from '@/uni_modules/lizhao-doc-corrector'

// imagePaths 是已取得的本地图片路径数组，按业务需要排列。
function processPages(imagePaths) {
  batchProcessDocuments({
    imagePaths,
    correct: true,
    enhanceMode: 'color',
    success: (res) => {
      // success 表示这一批处理结束；仍需检查失败项。
      const outputPaths = res.results.map((item) => item.imagePath)
      console.log('成功图片路径', outputPaths)
      console.log('失败项数量', res.failures.length)
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

三端每批支持 1–20 张，按输入顺序处理。

• correct: true（默认）自动检测并矫正，图像处理失败进入 failures。
• enhance: false 关闭滤镜增强；同时关闭 correct 时不会要求图片存在纸张边框。
• recognize: true 执行逐页 OCR，通过 recognitionResult 返回全文；OCR 失败保留该图片并附 recognitionError。

success 表示批处理结束，应同时检查 failures 和每项的 recognitionError。超过 20 张请分批提交。

import { batchProcessDocuments } from '@/uni_modules/lizhao-doc-corrector'

// 只读取照片/截图中的文字：不矫正、不增强，不要求存在纸张边框。
function recognizePages(imagePaths) {
  batchProcessDocuments({
    imagePaths, correct: false, enhance: false, recognize: true,
    success: (res) => {
      const textPages = res.results.map((item) => item.recognitionResult ? item.recognitionResult.rawText : '')
      const ocrErrors = res.results.filter((item) => item.recognitionError != null)
      uni.showModal({ title: '批量文字', content: textPages.join('\n\n'), showCancel: false })
      // 不记录全文或证件信息；业务可按原图逐项重试。
      console.log('OCR 失败页数', ocrErrors.length, '图像失败页数', res.failures.length)
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

自动识别、相册入口与提示文字

适合连续取景后自动尝试识别，或需要统一业务用语的场景。自动模式仍需用户核对并点击确认；timeoutMs 限制一次识别耗时，不限制核对时间。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 识别界面的 uiTexts 和扫描界面的 uiTexts 是两套配置，不要混用字段。
function openAutomaticRecognition() {
  openDocumentRecognition({
    sessionId: 'auto-text-entry',
    recognitionType: 'text',
    captureMode: 'auto',
    albumEnabled: true, // false 只隐藏本次识别界面的相册入口。
    torchEnabled: true, // 允许用户切换补光灯，不表示一进入就开灯。
    timeoutMs: 10000,
    uiTexts: {
      title: '资料录入', scanHint: '请保持文字清晰，识别后核对内容',
      resultTitle: '检查录入文字', confirmButton: '使用这些文字'
    },
    success: (res) => { uni.setClipboardData({ data: res.confirmedText }) },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

三端相册导入身份证、银行卡、车牌或驾驶证后，均可调整目标矩形范围，再确认识别。多证件拼图请只框住当前目标；选择“使用全图”时，将选中的完整媒体交给识别入口，避免在导入阶段重复压缩。最终返回的 imagePath 可能是识别引擎旋正或规范化后的图片，不能用它判断与相册文件逐字节一致；文本框坐标对应返回的结果图。取消选区会返回取景页；通用 OCR 从相册导入后默认识别整图。系统相册选择器和手势样式由平台决定。

自定义文档扫描文字

适合将通用扫描提示替换为“合同”“试卷”等业务用语。只填写需要覆盖的文字，其他项目保留默认值。

import { detect } from '@/uni_modules/lizhao-doc-corrector'

// 此处配置的是文档扫描及四角调整页；不传识别界面的 title 等字段。
function scanContractWithHints() {
  detect({
    documentType: 'contract',
    uiTexts: {
      closeButton: '取消', captureButton: '拍摄合同',
      scanHint: '请将整页合同放入画面', retakeButton: '重新拍照',
      confirmButton: '使用照片', adjustTitle: '调整合同边框',
      adjustHint: '拖动四个圆点，使边框贴合合同边缘'
    },
    adjustResult: (res) => { uni.previewImage({ urls: [res.imagePath] }) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

文字配置仅作用于本次会话；未传、空串或纯空白采用默认文字。系统权限弹窗、系统选择器、业务页面和错误回调中的信息不受 uiTexts 控制。

区分原始识别与人工确认

用于表单录入时保留用户更正的内容，同时允许回看识别原文。人工修改不会写回 originalResult，也没有 OCR 置信度。

import { openDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 在成功回调中分别读取原始内容和确认内容，再更新自己的表单。
function readAndReviewText() {
  openDocumentRecognition({
    recognitionType: 'text',
    success: (res) => {
      const originalText = res.originalResult.rawText // 用于对照识别原文。
      const confirmedText = res.confirmedText // 用于填入业务表单。
      const confirmedFields = res.confirmedFields // 元素为 key、value、edited。
      const userEdited = res.edited // 表明全文或字段是否被人工修改。
      uni.showModal({
        title: userEdited ? '已人工修改' : '已确认原文',
        content: confirmedText, showCancel: false
      })
    },
    fail: (err) => {
      if (err.errCode !== 9020016) uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  })
}

图片 API 返回的 structuredFields 还可能有 validation、candidates、sourceText、rect，适合在自有界面中展示校验提示和候选值。validation.status 为 conflict 时请让用户核对候选，不默认采用第一个。

主动关闭识别界面

页面卸载、业务取消或切换流程时，关闭自己打开的识别会话。识别界面与文档扫描会话分别使用不同的关闭 API。

import { closeDocumentRecognition } from '@/uni_modules/lizhao-doc-corrector'

// 'text-entry' 必须与本页面 openDocumentRecognition 的 sessionId 相同。
function closeRecognition() {
  closeDocumentRecognition({
    sessionId: 'text-entry',
    success: (res) => {
      // closed=false 表示已经结束或没有这个会话，重复关闭也算成功。
      console.log('本次是否关闭了活动识别界面', res.closed)
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}

主动关闭活动识别界面，会先让原 openDocumentRecognition 收到一次 9020016 的 fail / complete，再完成本次 close 回调。该 API 不关闭 detect 或 startDocumentSession 打开的扫描页；后者使用 stopDocumentSession。

分步控制扫描会话

用于需要自行决定拍摄、暂停、恢复或关闭时机的业务。以下函数由对应操作分别触发，不能在初始化时连续调用。

import { startDocumentSession, captureDocument, pauseDocumentSession, resumeDocumentSession, stopDocumentSession } from '@/uni_modules/lizhao-doc-corrector'

// 同一流程保持相同的会话 ID。
const scanSessionId = 'controlled-scan'
function openScanSession() {
  startDocumentSession({
    sessionId: scanSessionId,
    onCaptured: (res) => { uni.previewImage({ urls: [res.imagePath] }) },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}
function captureNow() {
  // 在会话成功打开后调用；不要紧跟在 startDocumentSession 后立即拍照。
  captureDocument({
    sessionId: scanSessionId,
    success: () => {
      // HarmonyOS 此处返回会话状态；三端统一在 onCaptured 中消费图片。
      console.log('拍摄操作已完成')
    },
    fail: (err) => { uni.showToast({ title: err.errMsg, icon: 'none' }) }
  })
}
function pauseScan() { pauseDocumentSession({ sessionId: scanSessionId }) }
function resumeScan() { resumeDocumentSession({ sessionId: scanSessionId }) }
function stopScan() { stopDocumentSession({ sessionId: scanSessionId }) }

查看调用轨迹

用于接入出错时查看调用顺序，不影响识别流程。

import { getDebugTrace, clearDebugTrace } from '@/uni_modules/lizhao-doc-corrector'

// 复现问题前按需清空，复现后再读取；不要在两者之间省略实际操作。
function beginTroubleshooting() { clearDebugTrace() }
function copyTrace() { uni.setClipboardData({ data: getDebugTrace().join('\n') }) }

接入说明补充

以下保留原说明中的调用前置、业务范围、平台条件与接入顺序，配合上述模块阅读。

lizhao-doc-corrector

面向 uni-app / uni-app x 的文档扫描与 OCR 识别插件：拍摄或导入图片，完成四角矫正、文字与证件信息提取，核对后用于业务录入，也可将文档整理为 JPEG 或 PDF。

API 用途速查

完整参数、回调字段、平台差异和扩展流程见 uni_modules/lizhao-doc-corrector/readme.md · API 用途速查。

识别界面 recognitionType 与图片 OCR documentType 不是同一组取值；图片 OCR 的 paper 对应通用文字。detect.success 仅表示界面打开，最终矫正图从 adjustResult / onCaptured 获取。

完整参数、返回结果与事件

识别界面参数

传给 openDocumentRecognition；仅 recognitionType 必填。

已有图片 OCR 参数

传给 recognizeDocument 或专项图片识别 API。

扫描与图片处理参数

detect、startDocumentSession 的常用扫描配置如下。

各图片处理 API 均可传 sessionId、success / fail / complete。

批量三种开关独立生效，imagePaths 长度为 1–20。可使用批次的 sessionId 调用 stopDocumentSession，也可用同一 ID 开始新批次；未完成的旧批次会取消并返回 9020008。绑定已打开扫描会话的批次，还会在该扫描会话停止或被替换时取消。已经生成的缓存图片不自动删除。独立图片 OCR 仍可直接调用。

界面文案字段

字段均为可选字符串；两套 uiTexts 只应用于各自入口。

识别界面确认结果

openDocumentRecognition.success 返回 DocumentRecognitionResult。

图片 OCR 原始结果

rect 是 { x, y, width, height }，使用对应识别图片按方向处理后的像素坐标，不是屏幕坐标。取景或相册选区识别返回的 imagePath 指向实际识别区域，位置要相对该图绘制。

Android 车牌识别在通用 OCR 未取得有效号码时还会尝试离线车牌识字；该路径没有定位框，因此 textBlocks 为空、字段可能没有 rect。不能把“没有框”直接当作没有识别结果，应同时检查 rawText 与 structuredFields。

字段可选信息：sourceText 为来源文本，rect 为来源位置，candidates 为候选值，validation 包含 status / rule / message。confidenceAvailable 为 false 或未提供时，不能用置信度判断可靠程度；它也不是准确率百分比。

扫描、图片处理与导出结果

开启扫描 OCR 或批量 OCR 后，DocumentProcessResult 可附带 recognitionResult（完整 RecognizeDocumentResult）或 recognitionError（errSubject / errCode / errMsg）。两者都未提供时表示本次未请求 OCR。原图阶段 cameraResult 不附带尚未执行的 OCR。

实时 onCornersChanged 的坐标使用事件声明的坐标空间及宽高/旋转信息，不要直接拿预览缓冲区坐标矫正拍摄原图；最终图片的 corners 才与该结果的原图对应。鸿蒙可重试的运行错误或能力提示通过 onStatus 发送，保留 status / message 和原有状态字段。

图片处理的 qualityScore 为 0–100 的参考质量分，quality 包含 score / blurry / glare / tooDark / edgeMissing。不同平台检测能力不同，不能据此当作完整的模糊、反光检测或跨平台准确率比较。

回调时机：

• 五类识别界面：最终 success 或 fail 后触发一次 complete；打开界面、取得候选结果不会提前触发成功。
• 图片 OCR：一次识别结束后 success 或 fail，随后 complete；不存在用户确认步骤。
• Android / iOS detect：success 表示已打开；完成矫正通过 adjustResult / onCaptured 返回，失败或取消走 fail，最后一次 complete。未完成就主动关闭的扫描可能返回 9020011，与新识别界面的取消码不同。
• startDocumentSession 以及 HarmonyOS detect 的 complete 用于会话打开阶段；取得最终图片始终监听 adjustResult / onCaptured。会话状态、质量、四角变化分别通过 onStatus / onQuality / onCornersChanged 观察。
• HarmonyOS 启用手动调整时，拍摄动作可先返回原图与待调整四角；用户确认后的最终图通过 adjustResult / onCaptured 返回。三端业务统一在这两个事件中读取最终图片，避免将拍摄动作的即时返回值当作矫正结果。

错误码说明

失败对象的 errSubject 为 lizhao-doc-corrector，请同时读取 errCode / errMsg。

注意事项

• 使用包含当前插件原生能力的 App 安装包；首次接入或更新原生实现/依赖后，需要重新制作对应平台自定义基座或原生安装包。仅调整文案参数、页面示例或阅读文档不需要重打基座。

• Android / HarmonyOS 打开识别界面前需要相机授权；iOS 相机授权被拒后可在界面改用相册。仅识别已有图片时使用图片 OCR API。iOS 14 及以上使用系统照片选择器，旧系统按相册授权状态处理。

• 三端使用各自端侧识别能力，支持的语言、字体、版式、可用置信度及识别效果可能不同。Android 使用中文与拉丁文字模型；iOS 语言以系统支持范围为准，不支持的语言会报错；HarmonyOS 按端侧能力识别，不能通过 languages 切换语言。身份证、驾驶证与车牌字段规则面向中国大陆常见版式。

• Android 车牌有随包的离线识字补充路径，iOS / HarmonyOS 使用各自端侧识别实现；字段接口统一，识别效果和置信度不作跨端等值承诺。

• Android 云打包会按插件配置自动获取依赖；安装后的车牌识别仍可离线使用。

• 文件路径使用插件或系统 API 的实际返回值。iOS 的返回路径可直接交给图片组件或本插件继续处理，不手工拼接系统沙盒目录。

• 从插件根目录 import，不使用 uni.requireNativePlugin 调用。

• 扫描时保持边缘完整、对焦清晰和光线均匀；多证件图片先分开处理或只选择目标区域。

• 异步处理成功后再使用输出路径，不在文件尚未准备好时开始下一步。

• 页面离开时关闭自己打开的会话；短示例中的多个函数应由用户操作分别调用。

• 插件不主动上传图片或识别内容，数据保存与后续使用由业务控制。

Android 离线车牌识字使用 HyperLPR 模型（Apache-2.0）和 ONNX Runtime 运行库（MIT）；相关许可证和第三方声明随插件提供。

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

平台条件与常见问题补充

常见问题

只想拿到文字，要先扫描矫正吗？

不一定。清晰的图片可以直接 OCR；纸张倾斜、背景干扰明显时，先矫正或在 Android 相册选区中框住目标通常更便于识别。

五个识别按钮点击后会发生什么？

进入对应的原生取景页，拍照或从相册选图，查看原图和识别结果，必要时修改或重拍，最后点击确认。示例页在确认后显示结果并提供复制入口。

银行卡或车牌有文字，为什么专项识别失败？

专项识别需要符合当前类型的候选内容。尽量只保留一张卡或一块车牌，避免反光、模糊和裁掉关键字符；检查选择的场景是否正确。仅需提取任意文字时，使用通用 OCR。返回字段后仍要检查校验提示。

为什么自动模式一直没有进入结果页？

自动模式需要满足当前类型的关键识别条件。示例卡号、反光或缺字可能无法满足条件，可切换手动拍照，核对具体文字和校验提示；自动识别也不会代替最终人工确认。

四个角点没贴住纸张怎么办？

预览检测与拍后检测可能有差异；没有可靠边缘时，扫描页也可显示供手动调整的初始框。请把四个点拖到真实边缘后确认，不能仅凭“出现四个点”判断检测准确。独立四角检测失败则返回 9020007。

为什么已经打开界面，却没有收到识别 success？

识别界面的成功表示用户确认最终结果。等待确认即可；如果主动关闭，会收到 9020016。文档扫描的回调时机不同，请查看“返回结果与回调”。

返回的字段可以直接作为最终业务信息吗？

请先核对。OCR 可能漏字、错字，部分字段可能没有返回；校验通过只说明满足规则。识别界面的人工修改结果读取 confirmedFields，直接图片识别读取 structuredFields。

图片或 PDF 如何长期保存、分享？

等待成功回调，使用返回的 imagePath 或 filePath，由业务保存到自己的目录或交给分享、上传接口。不要依赖临时图片长期存在。

作者系列 UTS 插件

以下为作者已发布的 UTS 插件，可按能力方向查找。