跳到主要内容

图片识别

decodeImage(uri, options?) 从一张本地图片解码条码 / 二维码,返回命中的结果数组(可能为空)。它不走相机,是独立的识图路径。

import { decodeImage } from '@unif/react-native-hms-scan';

const results = await decodeImage('file:///path/to/photo.jpg');
if (results.length > 0) {
  const code = results[0].value;
  // 处理识别结果 ...
} else {
  // 空数组 = 图里没有码（正常，不是错误）
}

限定码制​

传 formats 限定识别哪些码制,不传 = 识别全部 14 种:

const results = await decodeImage('file:///path/photo.jpg', {
  formats: ['QR_CODE', 'EAN_13'],
});

接受的 URI:本地路径,不下载远程​

decodeImage 只接受本地 uri。两端接受的形式略有差异(源自各自原生实现):

形式AndroidiOS
file:///...(文件 URI)✅✅
绝对路径(无 scheme,如 /data/.../a.jpg)✅✅
content://...(Android Content URI)✅❌
data:...(base64 等)——✅
ph://...(iOS Photos)/ assets-library://——❌
http(s)://...(远程 URL)❌❌
跨平台安全输入:file:// 或绝对路径

要两端都稳的输入,用 file:// 或绝对路径。content:// 仅 Android;iOS 不接受 ph://(相册 URI)。从相册选图时,让你的图片选择器(如 react-native-image-picker)返回本地文件路径(它通常已落地为 file:// / 路径)再传给 decodeImage,跨平台最省心。

不下载远程 URL

decodeImage 不会下载远程 URL(http(s):// 两端都不支持)。如需识别网络图片,请宿主先下载到本地,再把本地 uri 传进来。

// ❌ Incorrect：传远程 URL，decodeImage 不下载，解不出（会抛 E_IMAGE_LOAD_FAILED）
const results = await decodeImage('https://example.com/qr.png');

// ✅ Correct：先下到本地，再传本地 uri（file:// / 绝对路径）
const local = await downloadToLocal('https://example.com/qr.png');
const results = await decodeImage(local);

空数组是正常结果,不是错误​

图里没有检测到码时,decodeImage resolve 一个空数组 [],不会抛错。这是最容易踩的坑:

// ❌ Incorrect：把空数组当失败抛异常 —— 把"图里没码"误判成错误
const results = await decodeImage(localUri);
if (!results.length) throw new Error('decode failed'); // 错：[] 是正常结果

// ✅ Correct：空数组 = 图里没码（正常），据此提示即可
const results = await decodeImage(localUri);
if (results.length === 0) {
  // 图里没码，正常 —— 提示"未识别到条码"之类
} else {
  use(results[0].value);
}

错误处理:真正的失败才抛 HmsScanError​

只有图片加载失败 / 读权限缺失 / 解码异常等真正的失败才抛 HmsScanError(带 code):

import { decodeImage, HmsScanError } from '@unif/react-native-hms-scan';

try {
  const results = await decodeImage(uri);
  // results 可能为空数组（图中无码）—— 不会走到 catch
} catch (e) {
  if (e instanceof HmsScanError) {
    switch (e.code) {
      case 'E_IMAGE_LOAD_FAILED':   /* 路径无效 / 非本地 uri / 格式不支持 */ break;
      case 'E_NO_READ_PERMISSION':  /* 缺相册读取权限（Android）*/ break;
      case 'E_DECODE_FAILED':       /* 解码过程异常 */ break;
      default: /* E_UNKNOWN 等 */ break;
    }
  }
}
场景结果
图里没码resolve [](不抛错)
传了远程 URL / 非本地 uri / 路径无效抛 E_IMAGE_LOAD_FAILED
缺相册读取权限(Android)抛 E_NO_READ_PERMISSION
解码过程异常抛 E_DECODE_FAILED

完整错误码见 API → HmsScanErrorCode。

相关​