跳到主要内容

安装

装齐 @unif/react-native-hms-scan 的全部同伴包,配置原生权限,完成编译。peer 依赖需要完整配置 —— 本页以 package.json 的 peerDependencies 为准逐项列出。

环境要求​

要求版本
React Native新架构(Fabric + TurboModules)必须开启
React>=19.2.3 <20.0.0
AndroidminSdkVersion ≥ 24(Android 7.0)
iOS随宿主 RN 工程最低版本;原生构建和运行仅支持真机
仅支持新架构

本库是 Fabric 组件 + TurboModule 桥,仅支持新架构。旧架构(Bridge)不受支持。安装前确认宿主已启用新架构(android/gradle.properties 的 newArchEnabled=true 等)。

1. 安装依赖​

以下同伴包需要按清单安装(以 package.json 的 peerDependencies 为准):

yarn add @unif/react-native-hms-scan \
  '@unif/react-native-design@0.35.0' react-native-svg \
  '@callstack/liquid-glass@0.8.2' \
  react-native-gesture-handler react-native-reanimated \
  react-native-reanimated-carousel react-native-safe-area-context \
  react-native-worklets

2.0 起使用 Design 0.35 与 Liquid Glass。升级 1.x 宿主时，移除旧 @sbaiahmed1/react-native-blur，安装上述依赖并重新执行 iOS Pods 安装；扫码公共 API 保持不变。

各包的作用与版本约束:

包版本约束作用
@unif/react-native-design^0.35.0<Scanner> 的主题、取景框、工具栏、结果卡全用它绘制
react-native-svg>=15<Scanner> 图标
@callstack/liquid-glass>=0.8.2 <0.9.0Design Liquid Glass 原生材质
react-native-gesture-handler>=3.0.0 <4.0.0design / 手势
react-native-reanimated>=4.5.2 <4.7.0design 动画
react-native-reanimated-carousel>=5.0.0 <6.0.0design 组件依赖
react-native-safe-area-context>=5.0.0安全区适配
react-native-worklets>=0.11.0 <0.13.0reanimated 4 的 worklet 运行时
为什么扫码库要装这么多 UI 包

这些 peerDeps 几乎都是成品 <Scanner> 间接需要的:<Scanner> 的取景框 / 工具栏 / 结果卡全部复用 @unif/react-native-design,而 design 自身依赖 react-native-reanimated / react-native-gesture-handler 等。即便你只用 headless <HmsScanView> 或 decodeImage,这些仍是声明的 peer —— 装齐即可,通常项目里已有大半。宿主若需要 toast,可自行在 App 根部挂载 ToastHost。

2. Android 配置​

添加 Huawei Maven​

com.huawei.hms:scanplus 依赖已由本库声明,但 Gradle 的 library repositories 不会传播给 consumer。宿主必须在实际参与 App 依赖解析的仓库列表中加入:

android/build.gradle
allprojects {
  repositories {
    google()
    mavenCentral()
    maven { url 'https://developer.huawei.com/repo/' }
  }
}

若工程在 settings.gradle 统一管理仓库,就把同一个 Maven 地址加到 dependencyResolutionManagement.repositories;关键是它必须进入实际解析 :app 依赖的列表。

仍然无需 agconnect / API Key

Scan SDK-Plus 是内置引擎,非华为机型也能用;不需要 agconnect-services.json、AppGallery Connect 插件或 API Key。

唯一硬要求是 minSdkVersion ≥ 24。若宿主低于 24,在 android/build.gradle 提升:

android/build.gradle
buildscript {
  ext {
    minSdkVersion = 24  // 本库要求 ≥ 24（Android 7.0）
  }
}

权限声明​

本库的 AndroidManifest.xml 已声明 CAMERA 以及 camera feature,会通过 manifest 合并进入宿主 App。通常无需在宿主重复声明。decodeImage 读取调用方准备的本地文件；本库不声明或申请相册读取权限。

若宿主的清单合并策略覆盖了它们,或你想显式声明,可在 android/app/src/main/AndroidManifest.xml 的 <manifest> 节点下补:

权限说明
android.permission.CAMERA相机扫码所需权限
相册 / 文件读取由宿主图片选择器决定；将相册资源准备为可读的本地 file URI
android/app/src/main/AndroidManifest.xml
<uses-permission android:name="android.permission.CAMERA" />

CAMERA 是运行时权限,声明之外还要请求。<Scanner> 已自动处理;用 <HmsScanView> 时自行请求。decodeImage 的可读文件由宿主图片选择能力准备,见权限处理。

3. iOS 配置​

pod install​

cd ios && bundle exec pod install

pod install 会通过 CocoaPods 自动安装华为官方 ScanKitFrameWork 1.1.2.305,无需额外配置,同样不需要 AppGallery Connect / API Key。安装过程不会在 node_modules 中生成 XCFramework。

iOS Simulator 不支持

iOS 相机扫码与 decodeImage 原生路径都只支持真机。Simulator 的架构 / 链接失败属于当前明确的 unsupported target;请切换物理设备,不要通过清理 cache、生成本地 framework 或修改宿主 Podfile 追求 Simulator 成功。无硬件逻辑测试使用随包 Jest mock。pod install 的 LICENSE 提示需与安装或编译错误分别判断。详见常见问题。

Info.plist 权限​

在宿主 ios/<AppName>/Info.plist 中添加:

Key说明
NSCameraUsageDescription相机使用说明(必须,展示给用户的文案)
NSPhotoLibraryUsageDescription仅当宿主自己的图片选择器需要读相册时(本库 decodeImage 不直接读相册,见下)
ios/<AppName>/Info.plist
<key>NSCameraUsageDescription</key>
<string>用于扫描商品条码与门店二维码</string>
<!-- 仅当宿主图片选择器需要访问相册时 -->
<key>NSPhotoLibraryUsageDescription</key>
<string>用于从相册选取图片识别条码</string>
iOS 上 decodeImage 与相册权限

本库的 decodeImage 只接受可读的 file:///... URI。相册选择由宿主图片选择器（如 react-native-image-picker）完成；该能力决定是否需要 NSPhotoLibraryUsageDescription，并在选图后准备本地文件。详见图片识别。

4. 最小示例​

安装完成后,参阅快速上手用 <Scanner> 跑通第一个扫码页。

下一步​