id-capture-rn

ID Capture React Native 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或错误的 Scandit ID Capture API。ID Capture API 在 v7 → v8 边界处进行了重构（scannerType 属性更名为 scanner，并重新设计为包装器；独立的 AamvaBarcodeVerifier 已被移除，改为使用设置标志；此外还新增了多项验证 API）。React Native 插件的接口（包名、枚举大小写、视图组件、AppState 生命周期）也与 iOS、Android、Web、Flutter、Cordova 和 Capacitor SDK 各不相同。

编写或建议代码前，务必对照本技能提供的参考资料核实 API。 不要依赖记忆中的方法签名、参数、包名或属性名。如果在提供的参考资料中找不到某个 API，请先获取相关文档页面，再作答。

值得特别指出的 React Native 注意事项：

• 无需调用插件初始化方法。 与 Flutter 不同，你无需调用 ScanditDataCaptureId.initialize()。核心模块会在导入时自动初始化。唯一的“initialize”调用是 DataCaptureContext.initialize(licenseKey)，然后使用 DataCaptureContext.sharedInstance——这是 RN 的惯例。
• 枚举成员名使用 PascalCase，传输值使用 camelCase。 请写 IdCaptureRegion.Us、IdImageType.CroppedDocument、IdSide.Front、RejectionReason.Timeout、IdAnonymizationMode.FieldsAndImages、IdFieldType.DocumentNumber、IdLayoutStyle.Rounded、FrameSourceState.On / .Off。在 RN 中切勿使用小写的 Dart/Flutter 形式（IdCaptureRegion.us）。
• CapturedId 的 MRZ/VIZ getter 是 mrzResult / vizResult（不是 Flutter 中的 mrz / viz）。其他特定来源的 getter：barcode、mobileDocument、mobileDocumentOcr。
• 图像以 base64 字符串形式返回。 images.face、images.frame、images.getCroppedDocument(IdSide.Front)、images.getFrame(IdSide.Front) 都会返回 string | null。使用 <Image source={{ uri: 'data:image/png;base64,' + face }} /> 进行渲染。它们不是 URI、文件或 Image 组件。
• 监听器是普通对象字面量。 IdCaptureListener 是一个包含两个可选方法的 TypeScript 接口——请写 const listener = { didCaptureId(_, captured) {...}, didRejectId(_, rejected, reason) {...} }。不要创建实现 IdCaptureListener 的类——那是 Dart/Flutter 的写法。
• addListener、removeListener、setMode、addMode、removeMode、applySettings、setFrameSource、switchToDesiredState 都会返回 Promise。 请对它们使用 await 或链式调用 .then——忘记使用 await 是启动时发生竞态的常见原因。
• 提供了两种视图模式。 官方示例使用 scandit-react-native-datacapture-core 中的 <DataCaptureView>，并通过 ref 手动添加 IdCaptureOverlay。id 包还提供更高级的 <IdCaptureView> 组件，可通过 props 将模式、相机、覆盖层和回调整合在一起。两种方式都有效；请优先介绍 <DataCaptureView>（与公开示例一致），并将 <IdCaptureView> 作为简便写法提供。参见 references/integration.md。
• React Native 中没有 VisaLetter 文档类别。 这里只提供 VisaIcao。（Flutter 中两种类别都有；RN 中仅对 ICAO 签证建模。）
• 相机生命周期使用 AppState，而不是焦点 props。 使用 AppState.addEventListener('change', …) 订阅状态变化，在 background / inactive 时停止相机，在 active 时重启相机；如果屏幕属于堆栈导航器，还应通过 navigation.isFocused() 控制恢复相机。
• iOS（在 ios/<App>/Info.plist 中配置 NSCameraUsageDescription）和 Android（使用 RN 内置的 PermissionsAndroid API 在运行时请求 CAMERA 权限）都需要相机权限。原生清单中的权限由插件声明。

禁止使用的 API（常见幻觉内容——请勿输出）

这些写法无法通过真实 RN 软件包的编译。请使用右侧的写法：

请勿写	请改用
IdCapture.forContext(context, settings)	new IdCapture(settings)，然后 await context.setMode(idCapture)
IdCaptureOverlay.withIdCapture(...) / .withIdCaptureForView(...)	new IdCaptureOverlay(idCapture)，然后 view.addOverlay(overlay)
IdDocumentType 枚举 / settings.supportedDocuments / settings.scannerType	settings.acceptedDocuments（文档类）+ settings.scanner = new IdCaptureScanner(new FullDocumentScanner())
capturedId.documentType	capturedId.document?.documentType（IdCaptureDocumentType），或 capturedId.isPassport() / isDriverLicense() / …
capturedId.isVisa() / capturedId.isVisaLetter()	capturedId.isVisaIcao()（RN 仅提供 ICAO 签证）
capturedId.mrz / capturedId.viz（Flutter 名称）	capturedId.mrzResult / capturedId.vizResult
IdCaptureRegion.us / IdSide.front / AamvaBarcodeVerificationStatus.authentic（小写 Dart 写法）	IdCaptureRegion.Us / IdSide.Front / AamvaBarcodeVerificationStatus.Authentic——RN 中 Scandit 的所有枚举成员均采用 PascalCase，包括 RejectionReason.*、IdImageType.*、IdAnonymizationMode.*、IdFieldType.*、FrameSourceState.*、IdLayoutStyle.*，以及验证状态和原因值
capturedId.images.croppedDocument	capturedId.images.getCroppedDocument(IdSide.Front)（也支持 .face、.frame、getFrame(IdSide.Front)）
将 images.face 当作 URI / 文件 / Image 组件	它是一个 base64 字符串——<Image source={{ uri: 'data:image/png;base64,' + face }} />
AamvaBarcodeVerifier（类）	settings.rejectForgedAamvaBarcodes = true + capturedId.verificationResult.aamvaBarcodeVerification
DrivingLicenseCategory.categoryCode	DrivingLicenseCategory.code（以及 dateOfIssue / dateOfExpiry）
不带 await 调用 idCapture.addListener(...)（启动时存在竞态）	await idCapture.addListener(listener)——removeListener、setMode、applySettings、setFrameSource、switchToDesiredState 也一样

产品指南

每当用户需要做设计决策时，都应遵循以下规则，而不仅仅是在回答 API 问题时。

• 只接受实际需要的文档。 范围较窄的 acceptedDocuments 列表（例如仅 new DriverLicense(IdCaptureRegion.Us)）比使用 IdCaptureRegion.Any 接受所有文档类型更快、更准确。不要默认选择“全部”，应先询问用户需要哪些文档和地区。
• 选择与所需数据相匹配的扫描器。 new FullDocumentScanner() 会自动读取正反面（适用于大多数 ID/DL 用例）。new SingleSideScanner(barcode, machineReadableZone, visualInspectionZone) 会读取启用区域所在的一面——仅需要美国 DL 背面的 PDF417 条码，或仅需要护照的 MRZ 时，可使用此扫描器。对于移动驾驶执照 / mDL，请使用 MobileDocumentScanner。
• 处理 didRejectId，不要只处理 didCaptureId。 拒绝原因（RejectionReason.Timeout、NotAcceptedDocumentType、DocumentExpired、DocumentVoided、ForgedAamvaBarcode 等）能让用户了解扫描未成功的原因。生产环境集成必须向用户显示相关消息。
• 如果不需要所有字段，默认进行匿名化。 IdCaptureSettings.anonymizationMode 和针对每个字段的 addAnonymizedField 可确保受监管的数据（例如文档图像、敏感字段）不会出现在结果中，除非你选择加入。建议仅保留满足用例所需的最少信息。
• 非 ID-Capture 问题请转交给 data-capture-sdk skill。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、Label Capture 等），或询问如何在产品之间进行选择，请改为交由 data-capture-sdk skill 处理，不要猜测。

意图路由

根据用户的请求，在作答前加载适当的参考文件：

• 从零开始集成 ID Capture（例如“为我的 RN 应用添加 ID 扫描”“扫描护照／驾照”“读取 MRZ”“提取持证人的姓名和出生日期”）→ 阅读 references/integration.md 并遵循其中的说明。
• 某项附加／高级功能（“拒绝已作废／已取消的证件”“检测有冲孔／已作废的驾照”“解码欧洲驾照背面的信息”“读取车辆类别”“验证 AAMVA 条码／检测伪造的美国驾照”“拒绝不一致的数据／数据一致性验证”“扫描移动驾照／mDL／ISO 18013-5 移动证件”）→ 阅读 references/supplementary-modules.md。
• 迁移或升级现有的 ID Capture 集成（“将 ID Capture 升级到最新 SDK”“从 v7 迁移到 v8”“我的 scannerType 代码无法通过编译了”“AamvaBarcodeVerifier 不见了”“不同版本的 ID Capture 有哪些变化”）→ 阅读 references/migration.md。
• React Navigation 路由生命周期、Expo／dev-client 设置，或 SDK 句柄的存放位置（“离开页面后相机不会停止”“页面获得／失去焦点时暂停相机”“useFocusEffect”“我在用 Expo／Expo Go／Expo Router”“我需要自定义 dev client 吗？”“expo-camera 的权限”“我应该把 IdCapture 放在 Redux／Zustand 中吗？”）→ 阅读 references/framework-recipes.md。Scandit 代码本身与 references/integration.md 中的代码一致；此文件介绍 React Navigation／Expo／状态管理的衔接方式。

API 使用政策

仅使用下方 Scandit 参考资料中明确记载的 API。不要编造或猜测方法签名、参数、属性名称或导入项。如果不确定某个 API 是否存在或如何调用，或者遇到 TypeScript 编译器／运行时错误，请先获取相关参考页面，再作答。不要让用户自行查阅文档。作答后，始终附上相关链接，方便用户进一步了解。

切勿拼接或猜测文档 URL。 需要特定类或属性的 API 页面时：

1. 先检查已获取的页面中是否有指向该页面的直接超链接——主题页面会直接链接到相关 API 符号。获取内容时，务必一并请求链接。
2. 如果没有找到直接链接，则获取 API 索引（参见下表中的 完整 API 参考），从中提取实际链接并访问。

URL 结构会因 SDK 版本和软件包路径而异，猜测 URL 会导致 404 错误。

框架变体政策

references/integration.md 中的示例使用函数组件 + React Hooks（useEffect、useRef、AppState），因为官方的 IdCaptureSimpleSample 就是这样编写的。如果项目也使用 React Navigation、Expo，或需要在多个屏幕间共享上下文，请参阅 references/framework-recipes.md——Scandit 调用保持不变，区别仅在导航生命周期、Expo 构建流程以及 ref 与状态存储的使用指导。不要仅为 ID Capture 引入新的状态管理库。

示例使用 TypeScript（官方示例为 .tsx）。建议使用 React Native >=0.74。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 native，许可证平台为 ios 和 android。

按以下顺序操作 — 绝不要让用户等待 MCP：

1. Scandit MCP 服务已连接 — 调用 ensure_scanner_setup，指定产品 native、平台 ios 和 android、app_identifier（应用的 bundle ID 或 application ID；对于 Web，应填写其生产域名，绝不能填写 localhost）以及环境变量 SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用该结果中的密钥 ID，或从 list_license_keys 获取密钥 ID，调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征得用户同意再获取。聊天中最多显示打码后的预览；绝不要输出完整密钥。

2. 未连接 — 告知用户一次：他们可以在 MCP 客户端中连接远程 Scandit MCP 服务 https://ssl.scandit.com/mcp，然后继续执行第 1 步。不要自行编辑 MCP 客户端配置。

   身份验证通过浏览器进行，因此不支持无头模式或 CI。该服务只提供试用密钥；绝不会创建、撤销或修改生产许可证。

3. 用户拒绝，或没有 MCP 客户端 — 请他们自行前往 https://ssl.scandit.com 生成密钥（尚无账户？请访问 https://ssl.scandit.com/dashboard/sign-up?p=test），然后粘贴密钥。

然后将密钥写入代码：在许可证密钥调用中，用密钥替换占位符 — 可以使用 get_license_key 返回的密钥，也可以使用用户粘贴或提供的密钥 — 聊天中仍只显示打码后的预览。不要在项目、文件或环境中搜索密钥。

参考资料

根据用户的问题，引导他们查看相应资源：

主题	资源
React Native 集成	入门 · 示例 (IdCaptureSimpleSample)
高级主题（匿名化、验证、扫描器、覆盖层）	高级配置
在主要 SDK 版本之间迁移	7 → 8
完整 API 参考	ID Capture API