@unif/react-native-hms-scan

华为 HMS 统一扫码(HUAWEI Scan Kit) 的 React Native 封装,面向 RN 0.85 新架构(Fabric + TurboModule):成品扫一扫页、headless 自定义扫码 UI、从图片识别条码 / 二维码。

特性

• 三种用法 — 成品 <Scanner> 扫一扫页(自带权限流 / 状态机 / 主题)、headless <HmsScanView> 相机组件(自定义 UI)、decodeImage(uri) 从本地图片识别。
• Android 内置引擎 — 用 Scan SDK-Plus,非华为机型可用,不依赖设备装 HMS Core APK;华为 maven 与依赖已内置在库里,宿主无需改 gradle。
• 零云端配置 — 两端都不需要 AppGallery Connect / agconnect / API Key。
• 14 种码制 — QR_CODE / EAN_13 / CODE_128 / PDF417 / DATA_MATRIX 等,默认识别全部。
• 仅支持 RN 新架构;@unif/react-native-design 风格统一。

安装

yarn add @unif/react-native-hms-scan react-native-svg
cd ios && pod install

react-native-svg 是 peer 依赖(<Scanner> 图标用它绘制);<Scanner> 还依赖 peer @unif/react-native-design。宿主需开启新架构。Android 权限、iOS NSCameraUsageDescription 等见文档站 · 安装。

快速开始

成品「扫一扫」页 —— 扫到条码后由宿主解析商品、确认带回:

import { Scanner, type ScanResult, type ScanProduct } from '@unif/react-native-hms-scan';

function ScanScreen({ navigation }) {
  return (
    <Scanner
      title="扫一扫"
      onClose={() => navigation.goBack()}
      resolveProduct={async (r: ScanResult): Promise<ScanProduct | null> => {
        const p = await api.lookupByBarcode(r.value); // 你来解析;返回 null = 未识别
        return p ? { name: p.name, brand: p.brand, price: `¥${p.price}`, barcode: r.value } : null;
      }}
      onConfirm={(product, result) => navigation.navigate('Order', { product, barcode: result.value })}
    />
  );
}

headless <HmsScanView>(完全自定义 UI)、图片识别 decodeImage、权限、平台差异 —— 见文档站。

文档

• 完整文档(安装 · 平台配置 · API · 平台差异 · 故障排查):https://unif-design.github.io/react-native-hms-scan/
• AI / Agent(按需 fetch,别凭记忆猜 API):llms.txt · llms-full.txt
• Agent Skill unif-hms-scan(unif plugin):/plugin marketplace add unif-design/skills → /plugin install unif@unif-skills

兼容性

• React Native 新架构(Fabric + TurboModule)必须开启;在 RN 0.85 上开发与验证。
• Android minSdkVersion ≥ 24(Android 7.0)。
• iOS ScanKitFrameWork 扫码功能仅真机(模拟器可编译,相机要真机)。

许可

MIT © unif-design