matrixscan-count-rn

MatrixScan Count React Native 技能

重要：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeCount* API 的表面会在主要 SDK 版本之间发生显著变化——构造函数签名会改变、会添加新属性，React Native 插件的接口（导入、原生链接、pod install、软件包名称）也会不断演变。

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

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

• 在调用任何其他 Scandit API 之前，必须且只能调用一次 DataCaptureContext.initialize(licenseKey)。它会设置 DataCaptureContext.sharedInstance，其他所有内容都会读取这个单例。不要构造多个上下文。
• 在 iOS 上，每次安装或升级 Scandit 软件包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接，无需手动操作。
• Metro 的打包器缓存经常会掩盖 Scandit 软件包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• BarcodeCountView 是一个 React 组件（以 JSX 渲染）。将 barcodeCount 和 context 作为属性传入。不要手动将视图附加到上下文——这些属性会处理此事。此视图不需要显式调用 start()（与 BarcodeArView 不同）。
• BarcodeCountView 上的 listener 和 uiListener 通过 ref 回调以命令式方式设置：view.listener = ... 和 view.uiListener = ...。
• iOS（ios/<App>/Info.plist 中的 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求——插件会自动声明清单权限）都需要相机权限。
• new BarcodeCount(settings) 构造函数（不带上下文参数）从 react-native=7.6 起可用。较早的集成使用 BarcodeCount.forDataCaptureContext(context, settings)。如果目标项目使用较旧的插件，请使用工厂方法。使用 ≥7.6 版本的构造函数时，通过 dataCaptureContext.addMode(barcodeCount) 附加该模式。
• BarcodeCountStatusProvider、setStatusProvider、shouldShowStatusModeButton、shouldShowStatusIconsOnScan、TextForBarcodesNotInListDetectedHint、TextForScreenCleanedUpHint、TextForClusteringGestureHint、StatusModeButtonAccessibilityLabel/Hint、StatusModeButtonContentDescription：均要求 react-native=8.3+。
• BarcodeCountNotInListActionSettings 和 BarcodeCountView 上的 barcodeNotInListActionSettings：要求 react-native=7.1+。
• tapToUncountEnabled：要求 react-native=7.0+。
• Android 上的 enableHardwareTrigger(keyCode)：要求 react-native=7.1+，设备 API 级别 ≥28。
• hardwareTriggerEnabled（iOS 音量按钮触发）：要求 react-native=7.1+。
• BarcodeCountStatusProvider.onStatusRequested(barcodes, callback) 基于回调——不要对其使用 await。调用 callback.onStatusReady(result) 传递结果。从平台的角度来看，此回调模式是异步的。
• BarcodeCountSettings.clusteringMode 要求 react-native=8.3+。
• BarcodeCountSettings.disableModeWhenCaptureListCompleted 要求 react-native=8.3+。
• BarcodeCountSession.recognizedBarcodes（数组 API）要求 react-native=7.0+。BarcodeCountListener 中的 didScan 回调会提供该会话。
• BarcodeCount.createRecommendedCameraSettings() 要求 react-native=7.6+。

意图路由

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

• 从头集成 MatrixScan Count（例如：“将 MatrixScan Count 添加到我的应用中”“设置 BarcodeCount”“如何在 React Native 中使用 BarcodeCountView”“如何扫描并统计多个条码”“对照列表进行扫描”“自定义计数视图”“添加状态叠加层”“生命周期或清理”）→ 阅读 references/integration.md，并遵循其中的说明。
• 从旧版 forDataCaptureContext 工厂迁移到新构造函数，或采用 Status/MappingFlow/NotInList API（例如：“从 forDataCaptureContext 迁移”“升级 BarcodeCount 构造函数”“添加状态模式”“采用映射流”“启用不在列表中的操作”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用策略

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

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

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

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

框架变体策略

React Native 应用可以使用类组件或函数组件编写。本技能中的示例使用带 Hooks 的函数组件，因为它们符合当前 React Native 的惯例。即使目标项目的其他部分仍包含旧式类组件，也应将新的 MatrixScan Count 代码写为函数组件——不要重写应用其余部分的组件风格，但 BarcodeCount* 集成本身应使用当前惯用写法（useRef、useEffect、useCallback）。

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

许可证密钥

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

请按顺序执行以下步骤——绝不要因为 MCP 而阻止用户：

1. Scandit MCP 服务已连接——使用产品 native、平台 ios 和 android、app_identifier（应用的 bundle ID 或 application ID；对于 Web，使用其生产域名，绝不要使用 localhost）以及环境变量 SCANDIT_LICENSE_KEY 调用 ensure_scanner_setup。不要运行它返回的命令。然后使用密钥 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 集成	入门
完整 API 参考	BarcodeCount API