matrixscan-batch-cordova

MatrixScan Batch Cordova 技能

重要：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeBatch* API 表面在不同主要 SDK 版本之间会发生变化——构造函数签名、Overlay 构造函数和监听器形式都已经演变。

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

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

• 全局命名空间：Scandit SDK 通过 window.Scandit 暴露。运行时请使用 Scandit.BarcodeBatch、Scandit.DataCaptureView 等。npm 包（scandit-cordova-datacapture-*）是插件清单，不是 ES 模块。不要在 WebView 中运行的用户代码里写 import { ... } from 'scandit-cordova-datacapture-*'。只有使用打包器的 TypeScript 项目才能在编译时导入类型。
• deviceready 门控：所有 Scandit API 都必须在 document.addEventListener('deviceready', ...) 之后调用。绝不要在模块加载时调用。
• context.setMode(barcodeBatch)：这是 Cordova 用于向 context 注册 mode 的方法。它会替换任何先前激活的 mode。两份 Cordova 示例均已确认此行为。
• 现代构造函数要求 SDK 7.6+：new Scandit.BarcodeBatch(settings)、new Scandit.BarcodeBatchBasicOverlay(mode, style)、new Scandit.BarcodeBatchAdvancedOverlay(mode) 和 Scandit.BarcodeBatch.createRecommendedCameraSettings() 均从 cordova=7.6 起可用。
• AdvancedOverlay 使用序列化视图：在 Cordova 上，setViewForTrackedBarcode 接受 view: Promise<TrackedBarcodeView?>——这是序列化的 TrackedBarcodeView，不是原生 UI 实例。请使用 Scandit.TrackedBarcodeView.withHTMLElement(domElement, options) 来构造。其形式与 Capacitor 相同。确切用法请参阅 Bubbles 示例。
• 需要 MatrixScan AR 附加组件：BarcodeBatchAdvancedOverlay、IBarcodeBatchBasicOverlayListener.brushForTrackedBarcode 和 setBrushForTrackedBarcode 均要求获得 MatrixScan AR 附加组件许可。
• 相机权限会由插件在 iOS 和 Android 上自动配置。
• DataCaptureView.forContext(context) 是 Cordova 工厂方法。然后调用 view.connectToElement(htmlElement) 将其附加到 DOM。
• TrackedObject（Cordova 8.2+）：从 SDK 8.2 起，引入了 TrackedObject 基类，TrackedBarcode 会继承该类。无需额外处理——你日常使用的 TrackedBarcode API 保持不变。

意图路由

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

• 从头集成 MatrixScan Batch（例如“将 MatrixScan 添加到我的应用”“设置 BarcodeBatch”“同时追踪多个条码”“显示 AR Overlay”“按条码设置画笔”“点击处理”“已移除的条码”“反馈 / 蜂鸣 / 振动”“生命周期或清理”“相机权限”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 MatrixScan 集成（例如“从 v6 升级到 v7/v8”“将 BarcodeTracking 迁移到 BarcodeBatch”“BarcodeTracking 和 BarcodeBatch 是一样的吗？”“升级 Scandit 插件”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
• 替换第三方多条码扫描器（例如“用 MatrixScan Batch 替换 phonegap-plugin-barcodescanner”“从 Cordova ML Kit 条码插件迁移”“我们会循环使用扫描器来读取所有条码，请帮我们切换到 Scandit”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

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

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

框架变体政策

Cordova 是基于 WebView 的框架。本技能中的示例使用纯 JavaScript（可选用 JSDoc 类型提示）。同一 API 也适用于 TypeScript——添加 global.d.ts 声明文件并使用 TypeScript 语法。本技能默认不假设项目使用 TypeScript。如果目标项目显然使用 TypeScript（包含 .ts 文件或 tsconfig.json），则将最终输出调整为 TypeScript；否则使用纯 JS。

许可证密钥

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

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

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，产品设为 native，平台设为 ios 和 android，然后运行 get_license_env_command 返回的命令，将密钥写入项目的 .env。在聊天中最多只显示掩码预览；绝不要打印完整密钥。

2. 尚未连接——先提出连接一次，然后从第 1 步继续：

   • Claude Code：claude mcp add --transport http scandit https://ssl.scandit.com/mcp
   • Cursor：将 {"mcpServers": {"scandit": {"url": "https://ssl.scandit.com/mcp"}}} 添加到 ~/.cursor/mcp.json
   • VS Code：将 {"servers": {"scandit": {"type": "http", "url": "https://ssl.scandit.com/mcp"}}} 添加到 MCP 用户配置中

   身份验证通过浏览器进行，因此不支持无头环境或 CI。该服务仅提供试用密钥；不会创建、撤销或修改生产许可证。

3. 用户拒绝连接或没有 MCP 客户端——让用户自行在 https://ssl.scandit.com 生成密钥（尚无账户时访问 https://ssl.scandit.com/dashboard/sign-up?p=test），然后粘贴密钥。

然后将密钥填入代码，替换占位符；密钥仅放在 .env 中并不会自动传入应用。Cordova 不会自行加载 .env，因此请使用以下最简单的方法。任何平台上最简单的方法：读取 .env，并将密钥直接填入许可证密钥调用中；在聊天中仍只显示掩码预览。

参考资料

根据用户的问题，将其引导至相应资源：

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