barcode-capture-rn

BarcodeCapture React Native 技能

关键：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeCapture API 会随主要 SDK 版本变化——属性可能会重命名、移除或重新组织，React Native 插件接口（导入、原生链接、pod install、软件包名称）也经历了演变。

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

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

• 在调用任何其他 Scandit API 之前，必须且只能调用一次 DataCaptureContext.initialize(licenseKey)。它会设置 DataCaptureContext.sharedInstance，这是其他所有对象读取的单例。不要构造多个 context。
• 绝不要调用 dataCaptureContext.dispose()。 context 是进程级单例——释放它会破坏应用中的所有 Scandit 屏幕，而不只是正在卸载的屏幕。屏幕卸载时，调用 dataCaptureContext.removeMode(barcodeCapture)，移除 overlay，移除 listener，并将相机切换到 FrameSourceState.Off。这就是完整的清理流程；不要添加 dispose()。
• 在 iOS 上，每次安装或升级 Scandit 软件包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接——无需手动操作。
• Metro 打包器缓存经常会掩盖 Scandit 软件包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• BarcodeCapture 不是独立的视图组件。你必须渲染一个带有 context 的 <DataCaptureView>，通过 DataCaptureView.addOverlay(...) 将 BarcodeCaptureOverlay 附加到该视图，并自行驱动相机，使用 Camera.default、dataCaptureContext.setFrameSource(camera) 和 camera.switchToDesiredState(FrameSourceState.On)。卸载时拆除所有这些内容是集成者的责任。在 SDK 8.7+ 中，根级 ScanditProvider 内的 BarcodeCaptureAioView 是独立组件的替代方案；请参阅 references/third-party-migration.md 中的 SDK 8.7+: BarcodeCaptureAioView 部分。
• 在 didScan 内部，在执行任何单次扫描相关操作（导航、网络、UI 更新）之前，将 barcodeCapture.isEnabled = false，并在准备好接收下一个代码时重新启用。listener 回调会阻塞帧处理；若未禁用该模式，处理程序返回前就可能重复调用 didScan。
• iOS（在 ios/<App>/Info.plist 中设置 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求）都需要相机权限——插件会自动声明 Android 清单权限。

意图路由

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

• 从头集成 BarcodeCapture（例如“将 BarcodeCapture 添加到我的应用”“设置条码扫描”“如何在 React Native 中使用 BarcodeCapture”“如何添加取景器”）→ 阅读 references/integration.md 并遵循其中的说明。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit 软件包升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md 并遵循其中的说明。
• 用 BarcodeCapture 替换第三方扫描器（例如“用 Scandit 替换 react-native-vision-camera useCodeScanner”“从 vision-camera v5 / expo-camera CameraView 迁移到 Scandit”“从我的条码扫描库切换到 BarcodeCapture”）→ 阅读 references/third-party-migration.md 并遵循其中的说明。

API 使用政策

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

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

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

不同 SDK 版本和软件包路径的 URL 结构各不相同（例如 api/ui/ 子目录），猜测会导致 404 错误。

框架变体政策

React Native 应用可以使用类组件或函数组件编写。本技能中的示例采用带有钩子的函数组件，因为它们与官方 React Native 示例一致，也符合当前 React Native 惯例。即使目标项目其他部分仍使用旧式类组件，也应将新的 BarcodeCapture 代码写成函数组件——不要改写应用其余部分的组件风格，但 BarcodeCapture 集成应使用当前惯用写法（useRef、useEffect、useFocusEffect、useMemo）。

示例使用 TypeScript（.tsx）。如果目标项目使用纯 JavaScript（.js／.jsx），请移除类型注解，并保留相同的导入和结构。

许可证密钥

扫描需要 Scandit 许可证密钥。本技能使用的许可证产品为 native，许可证平台为 ios 和 android。

按以下顺序处理——绝不要因为 MCP 而阻止用户继续操作：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，指定产品 native 和平台 ios、android，并提供 app_identifier（应用的 bundle 或 application ID；对于 Web，应使用生产域名，绝不能使用 localhost）以及 env_var SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用密钥 ID 调用 get_license_key，该 ID 可从此结果或 list_license_keys 中获取；如果 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 集成	开始使用 · 示例
高级主题（自定义取景器、位置选择、扫描意图、复合码、反馈）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API