更新记录

1.2.5（2026-09-20）

• 修复 iOS 拍摄预览与拍照原图取景范围不一致的问题：拍照原图现在与快门时预览的可见位置保持对应，拍后拖动四角和矫正继续使用同一张原图。
• 升级后无需修改调用代码；需要重新制作并安装 iOS 自定义基座或重新云打正式 IPA。Android、HarmonyOS 无需因本次修复重新制作基座或重新打包。

1.2.4（2026-09-18）

• 修复 iOS 正式包扫描后图片无法显示的问题：原图、矫正图、增强图和导出文件使用当前应用可访问的本地目录，返回路径也可继续传入插件处理。
• 修复图片写入或复制失败后仍返回成功的问题，现在通过失败回调报告文件处理错误。
• 升级后无需修改原有调用代码；需要重新制作并安装 iOS 自定义基座或重新云打正式 IPA，仅更新页面资源不会生效。Android 无需因本次修复重新制作基座。

1.2.3（2026-09-17）

• 新增扫描界面文字配置：通过 detect 或 startDocumentSession 的 uiTexts 自定义拍摄提示、关闭、拍摄、重拍、确认按钮及调整说明；HarmonyOS 同时支持处理进度和失败重试提示。
• 可仅设置需要修改的文字，未配置项保留原有默认值；原有调用代码无需调整。系统权限弹窗和系统界面文字不在此配置范围内。
• 升级后需要重新制作并安装 Android、iOS 自定义基座，HarmonyOS 需要重新打包安装，之后调整文字参数即可生效。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-doc-corrector

介绍

lizhao-doc-corrector 是面向 uni-app / uni-app x 的文档扫描与矫正插件。通过 API 打开原生拍摄页，拍照后拖动四角调整边框，得到矫正图片；也可以处理已有图片、增强文字、识别内容和导出 PDF。

功能特色

适合哪些场景

下载与导入

1. 在插件市场选择“使用 HBuilderX 导入插件”，导入自己的 uni-app 或 uni-app x 项目。
2. 保留完整插件名称，从插件根目录导入需要的 API：

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

完整页面示例按项目类型选择：

• uni-app：docCorrector.vue。
• uni-app x：index.uvue。

两个示例的“开始扫描”均包含自定义文案，分步会话入口保留默认文字，可对照体验。

5 分钟跑通：拍摄并取得矫正图片

首次接入推荐使用 detect。它直接打开插件原生界面，不需要自己编写相机或四角调整组件。下面是一个 uni-app .vue 页面示例：

<template>
  <view>
    <button @tap="scanDocument">开始扫描</button>
    <image v-if="imagePath" :src="imagePath" mode="widthFix" />
  </view>
</template>

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

export default {
  data() {
    // 保存确认后的矫正图片路径。
    return { imagePath: '' }
  },
  onUnload() {
    stopDocumentSession({ sessionId: 'main' })
  },
  methods: {
    scanDocument() {
      detect({
        sessionId: 'main',
        documentType: 'contract',
        adjustResult: (res) => {
          this.imagePath = res.imagePath
        },
        fail: (err) => {
          uni.showToast({ title: err.errMsg, icon: 'none' })
        }
      })
    }
  }
}
</script>

读取最终图片用 adjustResult 的 res.imagePath。 success 表示扫描会话已打开；cameraResult 是原图阶段，adjustResult 才是确认后的矫正结果。

uni-app x 使用相同 API 和配置，页面脚本为 UTS。可直接将上面的 index.uvue 示例注册为页面，从 detectWithManualGuide 方法开始接入；其中已包含各平台所需的回调类型写法。

核心配置

先使用默认值跑通，再增加业务需要的参数。detect 与 startDocumentSession 共用以下扫描配置。

接入方式选择

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

下面的短示例用于页面按钮事件或业务方法。图片路径从拍摄、相册选择或业务已有文件中取得；请替换示例路径，并保留成功和失败处理。

模块一：拍摄合同、证件或试卷

适合从纸质材料取得矫正图片。用 documentType 指定业务类型，并根据用途分别接收原图和矫正图。

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

detect({
  documentType: 'examPaper',
  enableManualAdjust: true,
  cameraResult(res) {
    console.log('拍照原图', res.imagePath)
  },
  adjustResult(res) {
    console.log('确认后的矫正图', res.imagePath, res.corners)
  },
  fail(err) {
    console.log('扫描失败', err.errCode, err.errMsg)
  }
})

证件识别还需继续调用模块五的识别 API；仅设置 documentType 不等于已经取得识别字段。

模块二：自定义扫描提示与按钮文字

适合将“文档”改为“合同”“试卷”等业务名称，或替换为其他语言。只需传入想修改的字段，其他文字保留默认值。

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

detect({
  uiTexts: {
    closeButton: '取消',
    captureButton: '拍照',
    scanHint: '请将合同放入画面，确保文字清晰',
    retakeButton: '重新拍照',
    confirmButton: '使用照片',
    adjustTitle: '调整合同边框',
    adjustHint: '拖动四个圆点，使边框贴合合同边缘'
  },
  adjustResult(res) {
    console.log('矫正结果', res.imagePath)
  },
  fail(err) {
    console.log('扫描失败', err.errMsg)
  }
})

startDocumentSession 也可使用同样的 uiTexts。配置只作用于本次会话，重拍继续使用本次文字；未传、null、空串或纯空白回退默认值。有效文字保留原内容，可用 \n 换行，按钮建议保持简短。

HarmonyOS 还可配置读取、矫正、增强、保存及失败重试提示。全部字段见后面的“界面文字配置查询”；系统权限弹窗、系统界面和业务页面文字不受此配置控制。

模块三：矫正已有图片与指定四角

适合相册图片或已保存的照片。通常只传 imagePath 即可自动检测；需要自定义边框时，先取得同一张图片的真实四角，再传给矫正接口。

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

// 替换为业务实际取得的本地图片路径。
const imagePath = '/storage/emulated/0/DCIM/document.jpg'
detectDocumentCorners({
  imagePath,
  success(detected) {
    correctDocument({
      imagePath,
      corners: detected.corners,
      enhanceMode: 'color',
      success(res) {
        console.log('矫正图片', res.imagePath)
      },
      fail(err) {
        console.log('矫正失败', err.errMsg)
      }
    })
  },
  fail(err) {
    console.log('四角检测失败', err.errMsg)
  }
})

corners 按左上、右上、右下、左下排列，单位是输入图片像素。自定义拖点界面必须把显示坐标转换回同一原图的像素坐标，不要用固定尺寸角点套所有图片。

模块四：增强图片中的文字

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

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

enhanceDocument({
  imagePath: '/storage/emulated/0/DCIM/document.jpg',
  enhanceMode: 'bw',
  success(res) {
    console.log('黑白增强图片', res.imagePath)
  },
  fail(err) {
    console.log('增强失败', err.errMsg)
  }
})

增强无法恢复原图中已经模糊或缺失的文字，拍摄时仍需保证对焦和光线。

模块五：识别文字与证件字段

适合文档检索、证件录入或材料整理。输入图片后，通过 rawText 读取全文，通过 structuredFields 读取识别到的业务字段。

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

recognizeDocument({
  imagePath: '/storage/emulated/0/DCIM/document.jpg',
  documentType: 'contract',
  success(res) {
    console.log('识别文字', res.rawText)
    console.log('结构化字段', res.structuredFields)
  },
  fail(err) {
    console.log('识别失败', err.errCode, err.errMsg)
  }
})

专用 API 使用相同的图片输入方式。字段可能因图片质量、语言或版式而缺失，应允许使用者核对和补充，不将识别结果视为身份或材料真实性认证。

模块六：批量处理多张图片

适合多页合同、整套试卷或材料批次。一次传入图片列表，通过开关选择是否矫正、增强和识别。

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

batchProcessDocuments({
  imagePaths: ['/storage/emulated/0/DCIM/page1.jpg', '/storage/emulated/0/DCIM/page2.jpg'],
  correct: true,
  enhance: true,
  recognize: false,
  enhanceMode: 'color',
  success(res) {
    console.log('成功图片', res.results)
    console.log('失败项', res.failures)
  },
  fail(err) {
    console.log('批量处理无法完成', err.errMsg)
  }
})

批量调用的成功回调不代表每张图片都成功，需同时检查 results 和 failures。

模块七：导出 JPEG 或多页 PDF

适合把扫描结果保存为文件或交给上传、分享功能。把前面取得的图片路径按目标页序传入，等待 success 后使用 filePath。

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

exportDocument({
  imagePaths: ['/storage/emulated/0/DCIM/page1.jpg', '/storage/emulated/0/DCIM/page2.jpg'],
  format: 'pdf',
  fileName: 'contract.pdf',
  success(res) {
    console.log('导出文件', res.filePath, res.pageCount)
  },
  fail(err) {
    console.log('导出失败', err.errMsg)
  }
})

单张 JPEG 导出使用 format: 'jpeg'，quality 可取 1–100，默认 92。fileName 只传文件名，不传目录或路径分隔符。

模块八：控制拍摄会话与生命周期

适合需要自己控制拍摄时机的业务。打开会话后，按用户操作分别调用拍摄、暂停、恢复或关闭，不要把这些操作连续执行在同一段初始化代码中。

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

// 同一业务流程始终使用相同的会话 ID。
const sessionId = 'main'
function openDocumentSession() {
  startDocumentSession({
    sessionId,
    uiTexts: { scanHint: '请准备好需要扫描的材料' },
    onCaptured(res) { console.log('界面拍摄完成', res.imagePath) },
    fail(err) { console.log('会话失败', err.errMsg) }
  })
}
function captureNow() {
  captureDocument({
    sessionId,
    success(res) { console.log('主动拍摄完成', res.imagePath) },
    fail(err) { console.log('拍摄失败', err.errMsg) }
  })
}
function pauseSession() { pauseDocumentSession({ sessionId }) }
function resumeSession() { resumeDocumentSession({ sessionId }) }
function closeSession() { stopDocumentSession({ sessionId }) }

在会话成功打开后才能主动拍摄；页面隐藏、恢复、卸载时按业务需要绑定暂停、恢复和关闭函数。普通单次扫描继续使用 detect 即可。

API 用途速查

图片处理参数查询

各异步图片 API 可传 success / fail / complete，sessionId 默认 default。下表列出各业务操作需要的参数。

界面文字配置查询

DocumentUiTexts 的以下字段均为可选字符串，传给扫描入口的 uiTexts。不传的项采用平台默认值。

回调与返回值说明

扫描会话回调

图片处理结果

OCR、批量与导出结果

支持平台

必要的平台差异

• mode 三档用于 Android / HarmonyOS 的拍摄处理预算，iOS 保持平台现有策略；fast 偏速度，balanced 平衡速度与质量，accurate 偏质量。Android 内存不足时可能安全降档，不能保证每台设备输出相同分辨率。
• adjustTitle 用于 Android / iOS 调整页；HarmonyOS 没有独立标题，其处理进度和失败重试提示可通过专属文案字段设置。
• content:// 是 Android 图片来源形式。跨端使用前，应确保输入文件可由目标设备读取；示例中的 Android 文件路径需替换为实际取得的图片路径。
• 扫描需要相机权限以及包含当前插件原生实现的安装包。原生插件升级后需更新对应平台自定义基座或安装包；此后仅调整 uiTexts 参数通常无需重新制作基座。

错误码说明

常见问题

扫描时的提示语能改吗？

可以，设置 uiTexts.scanHint。关闭、拍摄、重拍、确认及调整说明也可独立配置，见模块二。

拍完后为什么没有拿到最终图片？

使用 detect 时监听 adjustResult，不要把表示会话打开成功的 success 当作图片结果。

已有图片必须重新打开相机吗？

不需要，直接使用 correctDocument、enhanceDocument 或 OCR API。

iOS 基座能显示图片，正式包却不能显示怎么办？

请升级至 1.2.4 或更高版本并重新云打、安装正式 IPA。插件会把结果写入当前应用可访问的目录：uni-app 返回 _doc/lizhao-doc-corrector/...，uni-app x 返回 unifile://cache/lizhao-doc-corrector/...。将 adjustResult.imagePath 直接绑定到 <image :src="imagePath" />，也可以把该路径继续传给插件的增强、OCR 或导出接口。不要手工拼接沙盒 UUID 或固定 Library/Caches 地址；仅更新页面资源无法更新此原生修复。

提示会话不存在怎么办？

检查是否已打开会话、是否已关闭，以及各次操作的 sessionId 是否一致。普通单次扫描推荐使用 detect。

注意事项

• 页面只能从插件根目录 import，不使用 uni.requireNativePlugin 调用。
• 扫描时尽量让纸张完整入镜，保持边缘清晰、光线均匀，避免反光和手抖。
• 文案只影响展示，不改变识别能力、拍摄结果或错误码；它也不会替换 API 回调中的错误信息。
• 先等待图片处理成功，再使用返回路径执行 OCR、导出或其他操作，避免在文件尚未准备好时读取。
• 批量处理完成后检查失败项，OCR 结果应按业务需要核对；不可靠字段可能为空。
• 页面离开时按业务流程关闭会话，避免相机继续占用。
• 插件处理本地图片，不主动上传；如需上传、分享或长期保存，由业务在取得结果后执行。

联系方式

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

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。