更新记录

1.1.2（2026-05-09）

• Android 四角识别主链路升级为 OpenCV：通过灰度、降噪、Canny、findContours、approxPolyDP、四边形评分和角点排序生成实时预览框，旧自研边缘/亮度算法仅作为兜底。
• Android 透视矫正切换为 OpenCV getPerspectiveTransform + warpPerspective，让自动检测角点和最终矫正输出使用同一套视觉算法。
• Android 实时预览新增多帧稳定、首次识别提速、贴边/近全屏四边形过滤和安全兜底策略，减少预览框跳动、贴屏误判和复杂背景下的错误识别。
• Android 新增 CaptureFrameState：实时预览只缓存最后一份可信状态，记录预览 View 角点、分析帧角点、旋转角、尺寸、置信度、来源和时间戳。
• Android 点击拍摄时冻结当前可信预览状态，拍照完成后把冻结角点按 PreviewView.ScaleType.FILL_CENTER 语义映射到高清照片手动矫正页，避免拍完后四角跳位。
• Android 手动矫正页同样采用全屏 FILL_CENTER 显示，并按预览视图坐标反算到照片像素；本地文件解码时读取 EXIF Orientation 并旋正图片，避免角点和图片方向不一致。
• Android 拍后高清二次检测同样使用可信度和贴边过滤；没有可信冻结角点或高清检测失败时进入手动微调，并在最终 warnings 中追加兜底来源。
• iOS 接入系统 Vision VNDetectRectanglesRequest 检测文档矩形，图片检测和拍照后矫正均优先使用 Vision 角点，失败时回退手动微调默认角点。
• warnings 增加识别来源标记：opencv_preview、opencv_capture、preview_locked、edge_contour、vision_rectangle、preview_fallback、manual_adjust、manual_adjust_fallback，方便业务侧排查自动识别来源。
• Android config.json 新增 org.opencv:opencv:4.10.0 依赖；文档补充 OpenCV 依赖、自定义基座和包体积说明。

1.1.1（2026-05-08）

• 修复 Android 调试基座/动态 dex 环境下 ImageAnalysis.Analyzer 默认接口方法可能触发 ImageAnalysis$Analyzer$-CC 类缺失的问题，避免点击“开始扫描并手动矫正”后预览页一闪而过。
• Android 实时四角识别新增降级保护：分析用例绑定失败时自动回退到“预览 + 拍照”主流程，保证用户仍可拍摄并进入手动矫正。
• 补充 Android ImageAnalysis 兼容问题复盘，后续相机分析类能力可复用避坑记录。

1.1.0（2026-05-08）

• 新增推荐主入口 detect(options)，一键完成“打开原生拍摄页 -> 拍照 -> 手动四角微调 -> 确认矫正 -> 回调结果 -> 自动结束会话”的用户流程。
• 新增分段结果回调：cameraResult 返回拍照原图阶段信息，adjustResult 返回手动矫正后的最终结果；兼容保留 onCaptured。
• Android 拍照后默认进入手动矫正页，支持拖动四个角点贴合文档边缘，确认后输出透视矫正图。
• 修复 Android 一键扫描完成后再次打开预览可能黑屏的问题：相机会话释放改为只解绑当前会话创建的 Preview / ImageCapture，避免旧会话误伤新预览。
• 修复 Android 手动矫正页点击“重拍”可能闪退的问题：切回预览前先移除旧父布局中的 PreviewView，并在视图重新挂载后再绑定 CameraX。
• 修复 Android 手动矫正页复用图片解码方法时的 Kotlin 可见性编译错误。
• Demo 页面改为“开始扫描并手动矫正”推荐入口，旧会话调试入口保留在高级调试区，降低接入歧义。
• 文档以 detect(options) 作为首个 API，补充“是否拍摄时就矫正”、最短可用示例、权限/基座/会话失效常见问题。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-doc-corrector

lizhao-doc-corrector 是纯 UTS API 插件，用于合同、身份证、银行卡、相片、海报、试卷等矩形文档的捕捉、检测、矫正、增强、批量处理、导出与 OCR 字段抽取。

本插件不使用老式 App 原生语言插件，不支持 uni.requireNativePlugin 调用方式。页面端必须从插件根目录 import。

import { correctDocument, recognizeDocument } from "@/uni_modules/lizhao-doc-corrector";

支持平台

目录结构

uni_modules/lizhao-doc-corrector
├─ package.json
├─ readme.md
├─ changelog.md
└─ utssdk
   ├─ interface.uts
   ├─ unierror.uts
   ├─ index.uts
   ├─ app-android
   ├─ app-ios
   ├─ app-harmony
   ├─ web
   ├─ mp-weixin
   └─ mp-alipay

权限与自定义基座

相机权限来自插件原生全屏拍摄页的 Android CameraX / iOS AVFoundation 调用，不是依赖 uni.chooseImage 或 uni 页面相机组件完成核心拍摄。

Android 端 config.json 引入 org.opencv:opencv:4.10.0，用于实时纸张四角检测和透视矫正。接入方需要制作包含 CameraX、ML Kit、OpenCV 依赖的自定义基座；OpenCV 会增加安装包体积，请在发布前按目标渠道做包体积评估。

四角识别策略

自动识别会尽量贴合文档边缘，但反光、阴影、文档边缘出画、背景与纸张颜色接近时仍可能不准。推荐保留 enableManualAdjust: true，让用户在拍照后拖动四角做最终确认。结果 warnings 可能包含 opencv_preview、opencv_capture、preview_locked、edge_contour、vision_rectangle、preview_fallback、manual_adjust 或 manual_adjust_fallback，用于判断角点来源。

API 列表

detect(options)（推荐）

说明
一键拉起原生拍摄页，执行“拍照 -> 手动四角微调 -> 确认矫正 -> 返回结果”的完整链路。
默认会在拍后回调结果并自动结束会话，用户不需要再手动点“捕捉当前文档”。

支持平台
Android / iOS

参数

最短可用示例

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

detect({
  sessionId: "main",
  documentType: "contract",
  enableManualAdjust: true,
  cameraResult(res) {
    console.log("拍照结果", res.imagePath);
  },
  adjustResult(res) {
    console.log("矫正结果", res.imagePath, res.corners);
  },
  fail(err) {
    console.log("扫描失败", err.errCode, err.errMsg);
  },
});

startDocumentSession(options)

说明 启动原生文档捕捉会话。

支持平台 Android / iOS

参数

返回值

captureDocument(options)

说明 触发当前原生全屏捕捉会话拍摄一张文档图片，并复用插件的检测、矫正和增强流程输出结果。

支持平台 Android / iOS

参数

返回值

correctDocument(options)

说明 对已有图片执行文档四角检测、透视矫正与可选增强。

支持平台 Android / iOS

参数

返回值

recognizeDocument(options)

说明 对图片执行通用 OCR、文档类型判别与结构化字段抽取。

支持平台 Android / iOS

参数

返回值

错误码

uni-app 示例

import {
  correctDocument,
  recognizeDocument,
  exportDocument,
} from "@/uni_modules/lizhao-doc-corrector";

correctDocument({
  imagePath: "/storage/emulated/0/DCIM/sample.jpg",
  documentType: "contract",
  enhanceMode: "color",
  success(res) {
    console.log("矫正结果", res.imagePath, res.corners);
    recognizeDocument({
      imagePath: res.imagePath,
      documentType: "contract",
      success(ocr) {
        console.log("OCR", ocr.rawText, ocr.structuredFields);
      },
    });
  },
  fail(err) {
    console.log("矫正失败", err.errCode, err.errMsg);
  },
});

exportDocument({
  imagePaths: ["/storage/emulated/0/DCIM/sample.jpg"],
  format: "pdf",
  fileName: "contract.pdf",
  success(res) {
    console.log("导出文件", res.filePath);
  },
});

uni-app x 示例

import {
  startDocumentSession,
  captureDocument,
  stopDocumentSession,
  correctDocument,
} from "@/uni_modules/lizhao-doc-corrector";

startDocumentSession({
  sessionId: "main",
  documentType: "examPaper",
  enableManualAdjust: true,
  enableOcr: true,
  onStatus(res) {
    console.log("会话状态", res.status);
  },
  onCaptured(res) {
    console.log("原生相机拍摄完成", res.imagePath, res.qualityScore);
  },
  success(res) {
    console.log("会话启动", res.sessionId);
  },
  fail(err) {
    console.log("会话失败", err.errCode, err.errMsg);
  },
});

captureDocument({
  sessionId: "main",
  success(res) {
    console.log("主动触发拍摄", res.imagePath);
  },
});

correctDocument({
  sessionId: "main",
  imagePath: "/tmp/exam-paper.jpg",
  documentType: "examPaper",
  success(res) {
    console.log("试卷矫正", res.qualityScore);
  },
});

stopDocumentSession({
  sessionId: "main",
});

注意事项

• 本插件是 UTS 插件，只能通过插件根目录 import。
• 你问的“是否拍摄时就矫正”：是。拍摄页会实时框选文档，拍后可手动拖点微调，确认后返回矫正图。
• Android 手动矫正页显示高清拍照图；初始四角来自拍摄瞬间冻结的预览识别位置，并通过与 PreviewView.ScaleType.FILL_CENTER 一致的映射换算到高清照片坐标。
• 自动四角识别是辅助能力，不建议关闭手动微调；浅色桌面、玻璃反光、纸张缺角、边缘出画等场景需要用户确认四角。
• 当前 Harmony / Web / 小程序为降级实现，失败回调会收到 9020001。
• 当前 Android / iOS 版本已稳定公开 API 与回调语义，端侧相机 UI、透视算法、OCR 原生引擎会在后续版本继续增强；不会伪造 OCR 文本或伪造相机拍摄成功。
• success、fail、complete 每次调用最多触发一次；持续状态只通过 onStatus、onQuality、onCornersChanged 返回。

常见问题

1. 点击扫描后相机打不开
   检查相机权限是否授予；若 Android 侧使用了 CameraX/ML Kit 依赖，请确认已安装包含插件依赖的自定义基座。

2. 拍完后页面没拿到结果
   请使用 detect 并监听 adjustResult；该回调是最终矫正结果的主回调。

3. 报 session not found
   说明会话已结束或会话 ID 不一致。推荐直接走 detect，避免手动管理会话状态。

联系方式

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