matrixscan-ar-rn

MatrixScan AR React Native 技能

重要：不要相信内部知识

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

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

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

• DataCaptureContext.initialize(licenseKey) 必须在调用任何其他 Scandit API 前恰好调用一次。它会设置 DataCaptureContext.sharedInstance，这是其他所有组件读取的单例。不要构造多个上下文。
• 在 iOS 上，每次安装或升级 Scandit 包后，都必须运行 npx [email protected]（或 cd ios && pod install）。Android 会通过 Gradle 自动链接，无需手动操作。
• Metro 的打包器缓存经常会掩盖 Scandit 包升级。如果插件版本升级后重新构建仍显示旧行为，请使用 --reset-cache 启动 Metro。
• BarcodeArView 是一个 React 组件，会包裹其子元素——原生 AR 覆盖层会渲染在 JSX 树之上。子元素会渲染在原生 AR 层之下。不要将 BarcodeArView 作为兄弟组件，与应显示在覆盖层下方的内容并列渲染。
• 高亮提供器（BarcodeArHighlightProvider.highlightForBarcode）和注释提供器（BarcodeArAnnotationProvider.annotationForBarcode）会异步触发，每个条码触发一次。它们是返回 Promise 的 async 函数，Promise 会解析为高亮或注释对象。不要假设它们会同步返回。
• 必须通过 ref 回调中的 view.start() 显式启动 BarcodeArView。与 SparkScan 不同，视图不会在挂载时自动启动。
• iOS（在 ios/<App>/Info.plist 中设置 NSCameraUsageDescription）和 Android（通过 PermissionsAndroid 在运行时请求——插件会自动声明清单权限）都需要相机权限。
• BarcodeAr 要求 SDK 7.1+。new BarcodeAr(settings) 构造函数（不带上下文参数）从 react-native=7.6 起可用。使用 dataCaptureContext.addMode(barcodeAr) 将模式附加到上下文。
• BarcodeArCustomHighlight 要求 SDK 8.0+。BarcodeArCustomAnnotation 要求 SDK 8.1+。BarcodeArResponsiveAnnotation 要求 SDK 8.2+。

意图路由

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

• 从头集成 MatrixScan AR（例如“将 MatrixScan AR 添加到我的应用”“设置 Barcode AR”“如何在 React Native 中使用 BarcodeArView”“如何在条码上显示 AR 覆盖层”“添加或更改高亮或注释”“生命周期、清理或会话处理”）→ 阅读 references/integration.md，并遵循其中的说明。
• 从 BarcodeBatch 迁移到 BarcodeAr（例如“从 BarcodeBatch 迁移”“将 BarcodeBatch 转换为 BarcodeAr”“从 MatrixScan 转到 MatrixScan AR”“用 BarcodeAr 替换 BarcodeTracking”“将我的旧 MatrixScan 代码升级为 AR”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

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

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

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

URL 结构会因 SDK 版本和程序包路径而异（例如 api/ui/ 子目录），猜测 URL 会导致 404 错误。

框架变体政策

React Native 应用可以使用类组件或函数组件编写。本技能中的示例使用带 hooks 的函数组件，因为这符合当前的 React Native 惯例。即使目标项目其他位置仍有旧式类组件，也应将新的 MatrixScan AR 代码编写为函数组件——不要重写应用其余部分的组件风格，但 BarcodeAr* 集成本身应保持使用当前惯用方式（useRef、useEffect、useMemo）。

示例使用 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），并将 env_var 设为 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 集成	入门指南
完整 API 参考	BarcodeAr API