更新记录

1.0.0（2026-10-21）

首次发布

• 提供 Android / iOS / HarmonyOS 三端统一的本机图片文字识别：Android 用 ML Kit 内置模型（text-recognition 拉丁档 + text-recognition-chinese 中英档）、iOS 用系统 Vision 的 VNRecognizeTextRequest、HarmonyOS 用系统 Core Vision Kit 的 textRecognition.recognizeText。三端全程离线，不发起任何网络请求、不上传图片。
• API 为 uni 风格 options 入参 + success / fail / complete 回调，返回 void：recognizeText 识别、warmup 预热引擎句柄、releaseEngine 释放句柄、getEnvInfo 同步查本端能力。
• 结果口径：text 整段文本（块间换行、块内行以空格拼接）+ blocks 按块分组 + lines 逐行（text、blockIndex、confidence、四角点 points），并给出送入引擎尺寸 width/height 与原图尺寸 sourceWidth/sourceHeight。三端坐标统一换算为「左上角为原点、以原图为基准的像素坐标」，换算只在 core.uts 写一遍。
• lang 支持 auto（中英混排）/ zh / en，mode 支持 accurate / fast（档位只有 iOS 的引擎有）。显式传入本端不支持的语言或档位一律返回 9060008，不静默忽略；getEnvInfo().languages / modes 是本端真实可选值。
• maxSide 长边降采样开关（默认 0 按原图），timeout 看门狗（默认 15000ms，允许 1000–120000，越界夹边界），到点回 9060007 并作废之后迟到的引擎结果。
• 单飞保护：同一时刻只允许一次识别，重复调用回 9060005；成功、失败、超时三路结算由 core.uts 的 OcrSettler 收口，保证一次调用只结算一次。
• 错误码段位 9060，序号 001–009，009 固定为「当前平台不支持」；三端原生错误码体系不同，厂商原始码不占段位，统一归类后把原始码与文案拼进 errMsg。
• Web / 小程序等没有原生识别引擎的端走 utssdk/index.uts 兜底：recognizeText / warmup / releaseEngine 返回 9060009，getEnvInfo 照常可用并把 engine 标记为 none。
• 三端真机验收通过：Android / iOS / HarmonyOS 的 uni-app（vue2、vue3）与 uni-app-x 工程跑通案例页全部能力。
• HarmonyOS 直接支持 uni.chooseImage 回到的媒体库 URI（file://media/...）：本端整条透传给系统文件接口，不需要业务先 uni.saveFile 落沙盒；读字节改为「先 open、再按 fd 取大小」，因为媒体 URI 不支持按路径 stat，这样沙盒路径与 URI 两个通道共用一份代码。
• 不申请任何运行时权限、不随插件提供 AndroidManifest.xml 与 Info.plist：图片由业务侧用 uni.chooseImage / uni.chooseMedia / uni.saveFile 取得本机路径后传入，插件只读该路径。
• 案例页只留功能：顶部大字识别结果 + 「选图即识别」主操作，逐行结果（置信度与四角点）跟在下面。能力探测在 onLoad、引擎预热在首次识别前、句柄释放在 onUnload 自动完成，不再摆环境/生命周期按钮；错误码如实显示在调用那一行。样式全走行内 :style（鸿蒙不把页面级 css 打进包）。
• 附 license.txt 授权条款：普通授权与源码授权两档（与 package.json 的 dcloudext.sale 对应），写明授权主体、源码不得再分发、支持边界与免责；readme 标题段指向该文件。

平台兼容性

uni-app(4.75)

uni-app x(4.75)

其他

bear-ocr

用设备上的离线文字识别引擎识别本机图片里的文字，回整段文本、逐行文本与四角点坐标；支持 Android、iOS、HarmonyOS，全程不联网、不上传图片。

不申请任何运行时权限，图片路径由业务侧自己取得。收费插件，普通授权与源码授权两档，权利边界见 license.txt。

兼容性

三端都纯端侧执行、不发起网络请求，也不依赖任何在线 OCR 服务。uni-app 与 uni-app-x 共用同一份原生实现，最低版本一致。运行环境：HBuilderX 4.44+、uni-app / uni-app-x 4.75+。数值与 package.json 矩阵、各端 config.json 逐项一致。

验收口径：uni-app（vue2 与 vue3）与 uni-app-x 工程，在 Android / iOS / HarmonyOS 三端真机跑通案例页全部能力。

使用前提

1. Android 必须用云端自定义基座验收。config.json 声明了 ML Kit 的 Maven 依赖（text-recognition 与 text-recognition-chinese），本地标准基座不解析这类依赖，直接「运行到手机或模拟器」会在生成的 index.kt 报 找不到名称“com.google” 并附官方 known-issue 链接——这是环境限制，不要为此改动依赖声明（依据：DCloud 官方「带第三方依赖的 UTS 插件需云端编译」口径）。iOS 与 HarmonyOS 走系统框架，无此症状但同样需要自定义基座（UTS 插件不参与标准基座）。
2. 中文识别会增大 APK 体积：lang 为 auto 或 zh 时用中文档模型，只走纯拉丁（lang: 'en'）可以少带那一包。具体增量以你自己的云打包产物为准。
3. 不需要任何权限：本插件不申请运行时权限，也不随插件提供 AndroidManifest.xml 与 Info.plist。图片由业务侧用 uni.chooseImage / uni.chooseMedia 取得，选图阶段的相册/相机权限由宿主与系统决定，与本插件无关。
4. path 只接受本机可读路径：支持 _doc/、_downloads/、_temp/、沙盒相对路径、file:// 前缀，以及 HarmonyOS 上 uni.chooseImage 直接回到的媒体库 URI（file://media/...，本端整条透传给系统文件接口，无需先 uni.saveFile 落沙盒）。网络地址不支持，读不到字节时回 9060003，errMsg 会同时给出入参原文与展开后的路径。
5. 一次只跑一个识别：识别尚未结束时再次调用返回 9060005，需要连续识别请等上一次回调。
6. HarmonyOS 的两条硬限制：该端引擎只在国内正规真机可用，模拟器与海外机型会在初始化阶段回 9060002；图片边长有接口级判定（短边 ≥ 100、宽 ≤ 10000、高 ≤ 15210），越界回 9060003，用 maxSide 主动降采样即可避开上限。下限以下无法放大，只能换更大的图。
7. 语言与档位按端不同：getEnvInfo().languages / modes 是本端真实可选值，显式传入本端不支持的取值返回 9060008（不静默忽略）。拼错的语言名与档位不报错，按默认值处理。

快速开始

<script setup>
import { ref } from 'vue'
import { recognizeText, getEnvInfo } from '@/uni_modules/bear-ocr'

const text = ref('')

function pickAndRecognize() {
  uni.chooseImage({
    count: 1,
    success: (choose) => {
      const path = choose.tempFilePaths[0]
      recognizeText({
        path: path,
        lang: 'zh',
        maxSide: 1600,
        success: (res) => {
          // res.data：整段文本、逐行文本与四角点坐标
          const data = res.data
          if (data == null) return
          text.value = data.text
          console.log('语言', data.language, '耗时', data.duration, 'ms', '共', data.lines.length, '行')
        },
        fail: (err) => {
          console.log('识别失败', err.errCode, err.errMsg)
        }
      })
    }
  })
}

console.log(getEnvInfo())   // 同步返回，本端支持哪些语言与档位
</script>

import 只允许写到插件根目录 @/uni_modules/bear-ocr，MUST NOT 指到 utssdk/ 下的文件。

API

getEnvInfo() : OcrEnv

同步返回运行环境与本端真实能力，不需要权限、不会失败。

recognizeText(options)

OcrResult：

OcrData：

OcrLine：

OcrBlock：text（块内各行按识别顺序以空格拼接）、lines（块内的行）。OcrPoint：x、y。

warmup(options?)

把引擎初始化耗时从首次识别里挪走：Android 创建并缓存 ML Kit 识别器，HarmonyOS 调 textRecognition.init()，iOS 的 Vision 没有常驻句柄、用一张 1x1 空图同步预跑一次请求。可只传回调，lang 决定预热哪一档。

OcrEngineState：ready（句柄是否就绪）、engine（引擎标识）、duration（本次调用耗时，ms；Android 与 HarmonyOS 已预热过时为 0，iOS 每次都真跑一次空图所以始终大于 0）。引擎创建失败返回 9060002。

iOS 这一跳同步阻塞调用线程（主线程），是 warmup 契约里明说的行为——不阻塞就拿不到「首次耗时已被挪走」这个效果，所以建议放在进入识别页时调一次，不要放循环里。

releaseEngine(options?)

释放引擎并复位 engineReady，下次识别会重新初始化。页面 onUnload 或退出识别场景时调用；Android 关闭识别器、HarmonyOS 调 textRecognition.release()、iOS 只复位预热标记。没有可释放的句柄时返回 9060004（不算异常，按业务需要忽略即可）。参数与回调同 warmup，成功结果同样是 OcrEngineState（ready 为 false）。

错误码

错误码以 90 开头，本插件占 9060 段位，序号 009 固定表示「当前平台不支持」。原生引擎的原始码不占段位，会拼在 errMsg 末尾（native code= 或厂商码文案）。