更新记录

1.0.0（2026-05-30） 下载此版本

初次提交

平台兼容性

uni-app x(4.75)

其他

laoqianjunzi-ocr

laoqianjunzi-ocr 是一个面向 uni-app x 的本地 OCR 与文档处理插件，提供图片文本识别、文档整理增强、结构化字段提取、会话式分析、JPEG/PDF/Base64 导出等能力。

插件当前文档只说明现有正式接口与现有组件能力，示例全部基于 uni-app x 当前 API 编写。

功能概览

• 图片全文 OCR
• 按行 OCR 结果输出
• 文档边界整理与图像增强
• 身份证、银行卡、车牌、VIN、营业执照、社保卡、登机牌、答题卡、合同等场景提取
• 会话式连续分析
• JPEG、PDF、Base64 导出
• 运行时能力探测

适用平台

版本要求

• HBuilderX >= 5.07
• uni-app x >= 4.75
• Android 最低版本 21
• iOS 最低版本 15

权限与运行说明

Android

插件已声明相机权限：

• android.permission.CAMERA

如果业务流程需要从系统相册选图，实际项目中还应根据目标平台版本确认相册访问授权流程。

iOS

插件已包含以下权限说明：

• 相机使用说明
• 相册读取说明
• 相册写入说明

导出图片或 PDF 时，若业务需要保存到系统相册或文件位置，应确保目标环境具备对应写入权限。

Web

• Web 端 OCR 识别依赖全局 Tesseract
• Web 端 PDF 导出不可用
• Web 端导出 jpeg 或 base64 时，结果通常是 Data URL 字符串

安装后导入

import {
    describeOcrRuntime,
    inspectDocumentImage,
    polishDocumentImage,
    readTextFromImage,
    exportDocumentFile,
    openSmartSession,
    pushSmartSessionFrame,
    pauseSmartSession,
    resumeSmartSession,
    closeSmartSession,
    scanIdCard,
    scanBankCard,
    scanVehiclePlate
} from "@/uni_modules/laoqianjunzi-ocr"

import type {
    LqjDocumentOptions,
    LqjDocumentResult,
    LqjExportOptions,
    LqjOcrFailure,
    LqjOcrLanguage,
    LqjPolishOptions,
    LqjSessionActionOptions,
    LqjSessionFrameOptions,
    LqjSessionOptions,
    LqjTextReadOptions
} from "@/uni_modules/laoqianjunzi-ocr"

快速开始

推荐先通过 uni.chooseImage 获取图片路径，再调用插件接口处理。imagePath 需要传入当前平台可访问的本地图片路径。

<script setup lang="uts">
import { inspectDocumentImage } from "@/uni_modules/laoqianjunzi-ocr"
import type { LqjDocumentOptions, LqjDocumentResult, LqjOcrFailure } from "@/uni_modules/laoqianjunzi-ocr"

const imagePath = ref("")
const resultText = ref("等待识别")

function chooseImage() : void {
    uni.chooseImage({
        count : 1,
        success : (res) => {
            if (res.tempFilePaths.length > 0) {
                imagePath.value = res.tempFilePaths[0]
            }
        }
    })
}

function runInspect() : void {
    if (imagePath.value.length == 0) {
        uni.showToast({
            title : "请先选择图片",
            icon : "none"
        })
        return
    }

    const options : LqjDocumentOptions = {
        imagePath : imagePath.value,
        languages : ["zh", "en"] as LqjOcrLanguage[],
        mode : "balanced",
        documentHint : "auto",
        polishBeforeRead : true,
        polishMode : "color",
        success : (res : LqjDocumentResult) => {
            resultText.value = res.fullText.length > 0 ? res.fullText : "未识别到文本"
        },
        fail : (err : LqjOcrFailure) => {
            uni.showToast({
                title : err.errMsg,
                icon : "none"
            })
        }
    }

    inspectDocumentImage(options)
}
</script>

运行时能力探测

使用 describeOcrRuntime() 可以在页面初始化时读取当前平台支持情况。

const runtimeInfo = describeOcrRuntime()

console.log(runtimeInfo.platformName)
console.log(runtimeInfo.engineName)
console.log(runtimeInfo.supportsOcr)
console.log(runtimeInfo.supportsPdfExport)
console.log(runtimeInfo.supportsSession)
console.log(runtimeInfo.usesNativeBridge)

返回结构：

核心数据类型

OCR 语言 LqjOcrLanguage

识别模式 LqjOcrMode

文档提示 LqjDocumentHint

整理模式 LqjPolishMode

导出格式 LqjExportFormat

API 一览

1. describeOcrRuntime()

读取当前平台运行时支持情况。

2. readTextFromImage(options)

执行全文 OCR。

关键参数：

返回结果重点字段：

示例：

const options : LqjTextReadOptions = {
    imagePath : imagePath.value,
    languages : ["zh", "en"] as LqjOcrLanguage[],
    mode : "balanced",
    success : (res) => {
        console.log(res.fullText)
    }
}

readTextFromImage(options)

3. readLinesFromImage(options)

按行输出 OCR 结果，参数与 readTextFromImage 一致，适合票据、表单、段落拆行预览等场景。

4. polishDocumentImage(options)

执行文档裁切、拉伸修正、灰度化、二值化或增强处理。

关键参数：

返回结果重点字段：

示例：

const options : LqjPolishOptions = {
    imagePath : imagePath.value,
    polishMode : "contrast",
    stretchFix : true,
    success : (res) => {
        console.log(res.outputPath)
    }
}

polishDocumentImage(options)

5. inspectDocumentImage(options)

执行文档分析，输出全文、行块结果、文档类型标签、字段提取、整理结果和质量信息。

关键参数：

返回结果重点字段：

6. 场景化快捷方法

这些方法本质上是对 inspectDocumentImage 的语义化封装，内部会自动带上对应 documentHint：

• scanPlainText(options)
• scanIdCard(options)
• scanBankCard(options)
• scanVehiclePlate(options)
• scanVehicleVin(options)
• scanBusinessPermit(options)
• scanSocialCard(options)
• scanBoardingPass(options)
• scanExamSheet(options)
• scanContract(options)

示例：

scanIdCard({
    imagePath : imagePath.value,
    polishBeforeRead : true,
    polishMode : "color",
    success : (res) => {
        console.log(res.documentLabel)
        console.log(res.fields)
    }
} as LqjDocumentOptions)

7. exportDocumentFile(options)

将图片按指定模式整理后导出为 jpeg、pdf 或 base64。

关键参数：

返回结果重点字段：

示例：

const options : LqjExportOptions = {
    imagePath : imagePath.value,
    format : "pdf",
    polishMode : "color",
    quality : 92,
    success : (res) => {
        console.log(res.outputPath)
    }
}

exportDocumentFile(options)

8. readImageBase64(options)

直接读取图片 Base64 内容。

适用场景：

• 需要把图片内容转成字符串后再上传或二次处理
• 只需要读取原图内容，不需要文档分析或字段提取

9. 会话式分析 API

会话接口适合连续扫描或多次推送图像的流程。

openSmartSession(options)

开启一个分析会话，返回 LqjSessionSnapshot。

pushSmartSessionFrame(options)

向会话推送一张图片，输出 LqjDocumentResult。

pauseSmartSession(options) / resumeSmartSession(options) / closeSmartSession(options)

用于暂停、恢复、关闭会话。成功回调返回最新 LqjSessionSnapshot。

会话示例：

const session = openSmartSession({
    sessionId : "demo-session",
    documentHint : "contract",
    polishMode : "color",
    autoPolish : true
} as LqjSessionOptions)

const frameOptions : LqjSessionFrameOptions = {
    sessionId : session.sessionId,
    imagePath : imagePath.value,
    languages : ["zh", "en"] as LqjOcrLanguage[],
    mode : "balanced",
    success : (res) => {
        console.log(res.documentLabel)
    }
}

pushSmartSessionFrame(frameOptions)

pauseSmartSession({
    sessionId : session.sessionId
} as LqjSessionActionOptions)

resumeSmartSession({
    sessionId : session.sessionId
} as LqjSessionActionOptions)

closeSmartSession({
    sessionId : session.sessionId
} as LqjSessionActionOptions)

可选组件

插件内置 easycom 组件：lqj-ocr-live

用途：

• 封装实时扫描容器
• 通过 params 字符串驱动内部行为
• 通过 onEvent 事件向外输出结果

当前组件对外暴露的基础约定：

Web 兼容模式下支持的业务指令：

• startScan
• stopScan
• switchCamera
• setParams

示例：

<template>
    <view class="page-root">
        <lqj-ocr-live :params="liveParams" @onEvent="handleLiveEvent"></lqj-ocr-live>
    </view>
</template>

<script setup lang="uts">
const liveParams = ref('{"businessArray":[{"business":"startScan","params":{"type":"TextDetectorChinese"}}]}')

function handleLiveEvent(event : any) : void {
    const detail = event != null && event.detail != null ? event.detail as UTSJSONObject : null
    if (detail == null) {
        return
    }
    console.log(detail)
}
</script>

<style>
.page-root {
    display: flex;
    flex-direction: column;
    flex: 1;
}
</style>

错误码

使用建议

1. 图片路径建议

• 推荐优先使用 uni.chooseImage 获取本地图片路径
• Android 某些环境下可能返回 content:// 路径，若业务现场遇到读取失败，可先复制到应用可访问目录后再传入插件
• imagePath 不能为空，否则会直接触发 8802

2. 文档场景建议

• 普通文本建议使用 scanPlainText 或 inspectDocumentImage({ documentHint : "plainText" })
• 证件类场景建议直接使用对应快捷方法，例如 scanIdCard、scanBankCard
• 当文档边界清晰时，开启 polishBeforeRead 往往更容易获得稳定结果

3. Web 端建议

• 在页面启动阶段先调用 describeOcrRuntime() 判断是否已注入 Tesseract
• 若 supportsOcr 为 false，应在业务层提示当前 Web 环境缺少 OCR 引擎
• Web 端不要把 pdf 作为默认导出格式

4. 会话使用建议

• sessionId 建议由业务侧显式传入，便于多实例隔离
• 推帧前先确保会话处于 running 状态
• 会话结束后主动调用 closeSmartSession 释放状态

目录说明

建议验证方式

集成后建议至少验证以下流程：

• 选择图片并执行全文 OCR
• 执行一个结构化场景识别，例如身份证或银行卡
• 执行一次文档整理增强
• 分别验证 jpeg 与目标平台可用的导出格式
• 在业务页启动时打印 describeOcrRuntime() 结果确认平台能力