matrixscan-batch-capacitor

MatrixScan Batch Capacitor 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit SDK API。BarcodeBatch* API 的表面会随 SDK 主版本变化而变化——构造函数签名、覆盖层构造函数和监听器形式都经历过演变。

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

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

• 必须先调用（并等待）ScanditCaptureCorePlugin.initializePlugins()，才能使用任何其他 Scandit API——包括 DataCaptureContext.initialize。忘记调用会产生看似与初始化无关的运行时错误。
• 每次更改插件版本后，都必须运行 npx cap sync，将原生资源同步到 iOS/Android。跳过此步骤会导致运行时出现 Web/原生版本不匹配。
• 在 Capacitor 中，通过 context.setMode(barcodeBatch) 将模式注册到上下文中（两个示例均已确认）。这会替换任何之前处于活动状态的模式。
• DataCaptureView.forContext(context) 是创建捕获视图的 Capacitor 工厂方法。然后调用 view.connectToElement(htmlElement) 将其附加到 DOM。
• 现代构造函数要求 SDK 7.6+：new BarcodeBatch(settings)、new BarcodeBatchBasicOverlay(mode, style)、new BarcodeBatchAdvancedOverlay(mode) 和 BarcodeBatch.createRecommendedCameraSettings() 均从 capacitor=7.6 起可用。
• AdvancedOverlay 使用序列化视图：在 Capacitor 上，setViewForTrackedBarcode 接受 view: Promise<TrackedBarcodeView?>——这是序列化的 TrackedBarcodeView，而非原生 UI 实例。使用 scandit-capacitor-datacapture-barcode 中的 TrackedBarcodeView.withHTMLElement(domElement, options)。将其包装在 Promise 中，或直接传入——示例直接传入实例（API 会在内部进行包装）。
• 需要 MatrixScan AR 附加组件：BarcodeBatchAdvancedOverlay、IBarcodeBatchBasicOverlayListener.brushForTrackedBarcode 和 setBrushForTrackedBarcode 均需要 MatrixScan AR 附加组件许可证。
• 相机权限：iOS 要求在 Info.plist 中设置 NSCameraUsageDescription。Android 由插件自动处理。
• TrackedObject（Capacitor 8.2+）：在 SDK 8.2+ 中引入了 TrackedObject 基类，TrackedBarcode 继承自该类。对此无需特别处理——日常使用的 TrackedBarcode API 保持不变。

意图路由

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

• 从头开始集成 MatrixScan Batch（例如“将 MatrixScan 添加到我的应用”“设置 BarcodeBatch”“同时跟踪多个条码”“显示 AR 覆盖层”“每个条码使用不同的画笔”“点击处理”“覆盖层样式（边框/圆点）”“扫描反馈/蜂鸣/振动”“生命周期或清理”“相机权限”）→ 阅读 references/integration.md，并遵循其中的说明。
• 升级 Scandit SDK 版本（例如“从 v6/v7 迁移到 v8”“BarcodeTracking 已不存在”“将 BarcodeTracking 重命名为 BarcodeBatch”“找不到 DataCaptureContext.forLicenseKey”）→ 阅读 references/migration.md，并遵循其中的说明。
• 替换第三方多条码扫描器（例如“从 @capacitor-mlkit/barcode-scanning / ML Kit 切换到 MatrixScan Batch”“用 Scandit 替换 BarcodeScanner.startScan 和 barcodesScanned”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

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

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

框架变体政策

Capacitor 是基于 WebView 的框架。本技能中的示例使用纯 JavaScript（ES 模块）。TypeScript 项目可以原样使用相同的导入语句和 API，只需添加类型即可；但本技能默认不假设项目使用 TypeScript。如果目标项目显然使用 TypeScript（包含 .ts 文件或 tsconfig.json），请将最终输出调整为 TypeScript 语法；否则使用纯 JS。

许可证密钥

扫描需要 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. Scandit MCP 服务未连接——只告知用户一次，他们可以在 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 的返回结果，也可以由用户粘贴或提供；聊天中仍然只能显示经过掩码处理的预览。不要在项目、其文件或环境中搜索密钥。

参考资料

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

主题	资源
Capacitor 入门	开始使用
Capacitor AR 叠加层	添加 AR 叠加层
Bubbles 示例	MatrixScanBubblesSample
完整 API 参考	BarcodeBatch API