matrixscan-batch-rn

MatrixScan Batch React Native 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit SDK API。BarcodeBatch* API 的表面会随 SDK 主版本变化而变化——构造函数签名、叠加层构造函数和监听器结构都已发生过变化。

编写或建议代码前，务必根据此技能提供的参考资料核实 API。 不要依赖记忆中的方法签名、参数、插件名称或属性名称。

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

• 必须在使用任何其他 Scandit API 之前，恰好调用一次 DataCaptureContext.initialize(licenseKey)。此调用会设置 DataCaptureContext.sharedInstance。不要构造多个上下文。
• dataCaptureContext.setMode(barcodeBatch) 用于在上下文中注册模式（所有 RN 示例均已确认）。这会替换之前处于活动状态的模式。
• dataCaptureContext.removeMode(barcodeBatch) 是清理调用——在 useEffect 清理函数中使用。
• 从 react-native=7.6 开始，可使用不带上下文参数的 new BarcodeBatch(settings)、new BarcodeBatchBasicOverlay(mode, style) 和 new BarcodeBatchAdvancedOverlay(mode) 构造函数。
• 从 react-native=7.6 开始，可使用 BarcodeBatch.createRecommendedCameraSettings()。
• 必须在 DataCaptureView 的 ref 回调中，通过 view.addOverlay(overlay) 将叠加层添加到 DataCaptureView。
• 在 iOS 上，每次安装或升级 Scandit 软件包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接。
• Metro 打包器缓存经常会掩盖 Scandit 软件包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• iOS（ios/<App>/Info.plist 中的 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求）都需要摄像头权限。
• 新架构注意事项（react-native ≥ 0.79，iOS）：使用新的 React Native 架构（Fabric / TurboModules）时，若要使用 BarcodeBatchAdvancedOverlay，iOS 应用的 AppDelegate 必须实现核心模块提供的 ScanditReactNativeFactoryContainer 协议。详情请参阅 integration.md。
• 需要 MatrixScan AR 附加组件：BarcodeBatchAdvancedOverlay、BarcodeBatchBasicOverlayListener.brushForTrackedBarcode 和 BarcodeBatchBasicOverlay.setBrushForTrackedBarcode 均需要获得许可的 MatrixScan AR 附加组件。

意图路由

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

• 从头开始集成 MatrixScan Batch（例如“将 MatrixScan 添加到我的应用中”“设置 BarcodeBatch”“同时跟踪多个条形码”“读取已跟踪条形码的数据 / 标识符 / 位置”“处理对高亮区域或 AR 视图的点击”“在检测到新条形码时发出反馈 / 蜂鸣声”“显示 AR 叠加层”“为每个条形码设置画笔”“生命周期或清理”“摄像头权限”）→ 阅读 references/integration.md，并遵循其中的说明。
• 用 MatrixScan Batch 替换第三方多条形码扫描器（例如“用 MatrixScan Batch 替换我的 react-native-vision-camera useCodeScanner”“从 VisionCamera 多条形码扫描迁移到 Scandit”“从 RNCamera / ML Kit 批量扫描切换到 BarcodeBatch”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

仅使用以下 Scandit 参考资料中明确记载的 API。不要臆造或猜测方法签名、参数、属性名称或导入项。如果不确定某个 API 是否存在或如何调用，请先获取相关参考页面，然后再作答。不要让用户自行查阅文档。回答后，务必附上相关链接，方便用户进一步了解。

绝不要构造或猜测文档 URL。 需要查找特定类或属性的 API 页面时：

1. 先检查已获取的页面中是否有指向该页面的直接链接。
2. 如果没有找到直接链接，请获取 API 索引，从中提取实际链接并访问。

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

框架变体政策

React Native 应用可以使用类组件或函数组件编写。本技能中的示例使用带 Hooks 的函数组件，因为它们符合当前的 React Native 约定。编写新的 BarcodeBatch 集成代码时，请使用函数组件——使用 useRef、useEffect、useCallback。

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

许可证密钥

扫描需要 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。不要运行它返回的命令。然后，使用该结果或 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 入门	开始使用
React Native AR 叠加层	添加 AR 叠加层
完整 API 参考	BarcodeBatch API