更新记录

1.1.11（2026-08-06）

• iOS 拍后全屏微调页改为模糊 aspectFill 背景与完整 aspectFit 前景双层结构，重拍、提示和确认操作使用安全区悬浮胶囊，四个拖动点始终限制在真实前景图片区域内。
• 修复 iOS 拖动四角后的矫正结果与框选区域不一致：手动页使用规范化 CGImage 真实像素尺寸，Core Image 通过 CIImage(cgImage:) 和实际 extent 统一 UIKit 左上原点到滤镜坐标。
• uni-app 与 uni-app x 示例升级为专业扫描工具：首屏突出扫描入口，矫正结果大图优先，质量摘要和两列工具适配窄屏，高级 API、路径和日志默认折叠但完整保留。
• iOS 原生 Swift 已变化，升级后必须重新运行 iOS 原生联编或制作并安装匹配源码的 iOS 自定义基座；Android 原生代码未修改，不需要因本版本重新制作 Android 基座。

1.1.10（2026-08-06）

• iOS 实时四角参考框：原生相机新增 Vision 矩形检测，未可靠识别到文档时明确清空提示框，不伪造检测结果。
• iOS 拍照后新增拍后手动四角微调、重拍和确认矫正，确认时使用四个真实原图像素角点完成透视矫正，不再使用空角点直接输出。
• 修复 iOS 扫描原图和矫正结果图生成成功但 uni-app 页面无法显示的问题：文件复制到当前 DCloud _doc 应用目录后再回传可访问路径。
• 公共 API、Demo 的 detect(...) 调用和 Android 实现均未改变；升级后需重新运行 iOS 原生联编或重新制作并安装匹配源码的 iOS 自定义基座。

1.1.9（2026-07-31）

• 修复 uni-app x 示例日志样式在 HarmonyOS 编译时使用不受支持的 white-space: pre-wrap 导致构建失败的问题，改用平台支持的 normal 并保留自动换行。
• 本版本只修改示例样式和发布元数据，不改变文档检测、矫正、OCR、导出或平台原生实现，无需因此重新制作自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-doc-corrector

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

Android 成像清晰度优化

插件针对华为 Mate30 拍照后手动微调预览和最终矫正图偏模糊的问题，重做 Android 拍摄、精确有界解码和输出处理链路；同时保留华为 P40 等高像素设备的 OOM 防护。最终效果仍会受镜头对焦、拍摄距离、光线和手持稳定性影响。

iOS 拍后矫正与示例体验

• iOS 拍后全屏微调使用完整原图作为业务坐标基准，拖动点只落在真实图片区域；确认时按原图像素和 Core Image 实际 extent 输出框选区域。
• iOS 原生相机、实时参考框、重拍、四角微调和确认矫正均由插件内部完成；升级原生实现后需要重新运行 iOS 原生联编或制作匹配的 iOS 自定义基座。
• uni-app 与 uni-app x 提供一致的专业扫描工具示例，首屏突出扫描入口，结果图优先展示；高级 API、文件路径和调试日志仍可在“开发者工具”中展开。
• 示例页视觉和布局属于前端资源，单独调整示例时无需重新制作自定义基座。

功能特色

• 原生全屏拍摄、实时四角参考、拍后全屏微调、透视矫正和增强在一个插件内闭环，不依赖 uni 页面相机组件拼接核心能力。
• fast：速度优先，适合连续拍摄或更关注响应速度的场景。
• balanced：默认，画质与内存平衡，适合合同、试卷和日常文档扫描。
• accurate：质量优先，适合文字较小且设备内存充足的场景。
• Android 会按当前可用堆内存预估解码与输出峰值，内存不足时会安全降档，并保留最多一次 OOM 降档重试。
• 最终图会重新读取拍摄 JPEG 处理；JPEG 压缩、写入或可解码校验失败时返回明确错误，不会把原图伪装成矫正成功结果。

Android 三档处理策略

三档只影响 Android 原生拍摄会话；iOS 保持现有处理策略。档位是质量目标而不是无条件分辨率承诺，插件会先按设备真实支持尺寸和剩余内存选择安全配置。

接入方式选择

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

// 页面端只能从插件根目录导入需要的 API。
import { correctDocument, recognizeDocument } from "@/uni_modules/lizhao-doc-corrector";

最短可用示例

// Android 默认使用 balanced；先接收拍照阶段结果，再接收最终矫正结果。
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);
  },
});

支持平台

目录结构

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 CameraX、UTS 与 Kotlin 原生逻辑，升级相关实现后需要重新打 Android 自定义基座或重新运行原生联编；只更新 wgt/appResource 不会把新原生实现装入旧基座。

API 列表

detect(options)（推荐）

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

支持平台
Android / iOS

参数

startDocumentSession(options)

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

支持平台 Android / iOS

参数

返回值

captureDocument(options)

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

支持平台 Android / iOS

参数

返回值

correctDocument(options)

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

支持平台 Android / iOS

参数

返回值

recognizeDocument(options)

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

支持平台 Android / iOS

参数

返回值

错误码

uni-app 示例

// 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 示例

// uni-app x：会话 API 需要保持同一个 sessionId，并在业务结束时主动停止。
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。
• 你问的“是否拍摄时就矫正”：是。拍摄页会实时框选文档，拍后可手动拖点微调，确认后返回矫正图。
• 当前 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（-去掉，不这样写会被和谐）

作者系列UTS插件

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