# Unif HMS Scan

> Unif HMS Scan 文档索引。每个链接是该页的纯 Markdown 版(供 LLM 抓取);需要完整全文一次性喂入时用 /llms-full.txt。

## 概览

- [介绍](/md/intro.md) — @unif/react-native-hms-scan 是华为 HMS Scan Kit 的 React Native 新架构封装：Android 用内置引擎 Scan SDK-Plus（非华为机也能用、无需 agconnect）、iOS 用 ScanKitFrameWork。三种用法：成品 <Scanner> 页 / headless <HmsScanView> / decodeImage 图片识别。
- [平台差异](/md/platform-differences.md) — Android（内置引擎 Scan SDK-Plus / 零配置 / 无 agconnect）与 iOS（ScanKitFrameWork / 仅真机 / 手电 best-effort / onTorchStatus.available 非暗光信号 / decodeImage URI 受限）的逐项能力差异：原生实现、码制、权限四态、手电、暗光提示、图片识别 URI。
- [AI Skill](/md/skills.md) — unif-hms-scan 是一个 Agent Skill,教 AI 编码助手正确调用 @unif/react-native-hms-scan 的 API、避免常见幻觉。
- [测试(Mock)](/md/testing.md) — 用官方 mock 在 Jest 中替换 @unif/react-native-hms-scan，避免加载 TurboModule / Fabric 组件：require('@unif/react-native-hms-scan/mock') 后 decodeImage→[]、权限→granted、<HmsScanView>/<Scanner>→null；纯函数 coerceFormat/coerceContentType/formatsToCsv 与类型 / HmsScanError 保留真实实现。可按需覆盖单次返回。
- [常见问题](/md/troubleshooting.md) — @unif/react-native-hms-scan 排障决策树（症状→因→解）：iOS 模拟器链接错误（预期，须真机）、ScanKitFrameWork LICENSE 警告无害、Android minSdk<24 / 缺 CAMERA、decodeImage 空数组非错误 / 不下载远程、iOS 手电 best-effort（onTorchStatus.available iOS 永不上报）。

## api

- [函数](/md/api/functions.md) — decodeImage(uri, options?)（本地图片解码，URI 规则两端有别、空数组非错误）、getCameraPermissionStatus / requestCameraPermission（granted/denied/blocked/undetermined）、码制工具 coerceFormat / coerceContentType / formatsToCsv 完整签名。
- [HmsScanView](/md/api/hms-scan-view.md) — <HmsScanView> 底层 headless 扫码相机组件完整 props 参考：formats / continuous / paused / torch / onScanResult / onScanError / onTorchStatus，以及 TorchStatus 类型与 onScanError 的 code（E_CAMERA_INIT / E_NO_RESULT）。
- [Scanner](/md/api/scanner.md) — <Scanner> 成品扫一扫页完整 props 参考：title / formats / hintText / topInset / bottomInset / showTorch / onClose / resolveProduct / onConfirm / autoConfirm / pickImage，以及回调用到的 ScanResult / ScanProduct 类型。自带状态机 + 权限流 + 主题。
- [类型](/md/api/types.md) — @unif/react-native-hms-scan 所有公开类型定义：BarcodeFormat（14 种 + UNKNOWN）、BarcodeContentType、ScanResult、ScanProduct、CameraPermissionStatus（granted/denied/blocked/undetermined）、HmsScanErrorCode、HmsScanError、ScanCornerPoint、DecodeImageOptions。

## getting-started

- [安装](/md/getting-started/installation.md) — 安装 @unif/react-native-hms-scan 及全部必装 peerDependencies（含 @unif/react-native-design 与其 UI 依赖），Android 零配置（华为 Maven 内置、无 agconnect、minSdk≥24），iOS pod install + NSCameraUsageDescription。仅支持新架构。
- [快速上手](/md/getting-started/quick-start.md) — 用 <Scanner> 5 分钟跑通第一个扫码页：丢一个 <Scanner> 进路由，传 onClose / resolveProduct / onConfirm，扫到条码弹浮层确认卡，确认带回上一级。pickImage 可选（相册）。

## guides

- [图片识别](/md/guides/decode-image.md) — decodeImage(localUri) 从本地图片解码条码/二维码：接受 file:// / 绝对路径（两端通用），content:// 仅 Android；不下载远程 URL；空数组 [] = 图里没码（正常，不抛错）；图片加载失败/读权限缺失才抛 HmsScanError。
- [底层 headless 组件](/md/guides/headless.md) — 用 <HmsScanView> 完全自定义扫码 UI：只出相机预览 + 抛事件，取景框/手电按钮自绘。props：formats（省略=全部）、continuous（默认 true）、paused（默认 false）、torch（默认 false，iOS best-effort）、onScanResult(results)、onScanError、onTorchStatus（available 仅 Android）。
- [权限处理](/md/guides/permissions.md) — 相机权限：<Scanner> 自动处理；headless <HmsScanView> 用 requestCameraPermission / getCameraPermissionStatus 自管（granted/denied/blocked/undetermined）。iOS 需 NSCameraUsageDescription，Android 需 CAMERA；decodeImage 解相册图另需 READ_MEDIA_IMAGES。
- [成品扫一扫页](/md/guides/scanner.md) — 用 <Scanner> 快速接入完整扫码页：title / onClose / resolveProduct（返回 null=未识别）/ onConfirm / pickImage（传了才显示相册）/ showTorch / formats / 安全区 topInset·bottomInset。自带状态机 + 权限流 + 主题，一次扫一个。