matrixscan-batch-web

MatrixScan 批次 Web 技能

关键：不要相信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeBatch Web API 会在主要 SDK 版本之间发生变化——构造函数签名、叠加层工厂名称、异步模式和初始化方式都已演变。

编写或建议代码前，务必根据此技能提供的参考资料核实 API。 不要依赖记忆中的方法签名、参数或导入路径。如果在提供的参考资料中找不到某个 API，请先获取相关文档页面，再作答。

值得特别指出的 Web 专属注意事项：

• BarcodeBatch.forContext(context, settings) 是异步的——务必使用 await。不要使用 new BarcodeBatch(settings)（这是 React Native ≥7.6 中的形式）。
• barcodeBatch.setEnabled(true/false) 是异步的——务必使用 await。
• BarcodeBatchBasicOverlay.withBarcodeBatchForView(barcodeBatch, view) 和 BarcodeBatchBasicOverlay.withBarcodeBatchForViewWithStyle(barcodeBatch, view, style) 是异步工厂方法——务必使用 await。不会隐式创建叠加层。
• BarcodeBatchAdvancedOverlay.withBarcodeBatchForView(barcodeBatch, view) 是异步的——务必使用 await。
• BarcodeBatchAdvancedOverlay 上的 setAnchorForTrackedBarcode 和 setOffsetForTrackedBarcode 是同步的（返回 void）——不要使用 await。
• BarcodeBatchAdvancedOverlay 上的 clearTrackedBarcodeViews() 也是同步的（返回 void）。
• BarcodeBatch.recommendedCameraSettings 是一个静态属性，不是方法调用。
• 模块加载器是 barcodeCaptureLoader()（来自 @scandit/web-datacapture-barcode）——没有单独的 barcodeBatchLoader。BarcodeCapture 和 BarcodeBatch 使用相同的加载器。
• BarcodeBatch 必须启用多线程。 如果没有 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp（可自托管）或 credentialless（CDN），SDK 会退回到单线程模式，批次跟踪速度将慢到无法使用。
• Web 上的 AR 视图使用普通 HTML 元素——TrackedBarcodeView.withHTMLElement(element, options) 会返回一个 Promise<TrackedBarcodeView>。直接将此 Promise 传给 setViewForTrackedBarcode，或从 viewForTrackedBarcode 返回它——两者都接受 Promise。这不是子类模式。
• session.removedTrackedBarcodes 返回 string[]（序列化为字符串的标识符）——与 TrackedBarcode.identifier（类型为 number）比较时，使用 Number.parseInt(id, 10)。
• 可以在上下文初始化前创建 DataCaptureView：new DataCaptureView() → connectToElement(element) → await view.setContext(context)。这样可以在 SDK 加载期间显示进度条。另一种方式 await DataCaptureView.forContext(context) 同样有效。
• 传给 view.connectToElement() 的 DOM 元素必须具有已定义的尺寸和已设置的 position（例如 fixed 或 absolute）——尺寸为零或未设置定位的容器无法渲染相机预览。
• 相机需要手动管理：调用 await context.frameSource?.switchToDesiredState(FrameSourceState.On) 来启动，调用 FrameSourceState.Off 来停止。页面失去焦点时，相机不会自动停止。

意图路由

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

• 从头集成 MatrixScan Batch（例如“将 MatrixScan 添加到我的 Web 应用”“设置 BarcodeBatch”“同时追踪多个条码”“在条码上显示 AR 覆盖层”“为每个条码设置画笔颜色”“生命周期或清理”）→ 阅读 references/integration.md 并遵循其中的说明。
• 迁移或升级现有的 MatrixScan Batch 集成（例如“从 v6 升级到 v7”“将 BarcodeTracking 迁移到 BarcodeBatch”“将 Scandit SDK 升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md 并遵循其中的说明。
• 用 MatrixScan Batch 替换第三方多条码扫描器（例如“将 ZXing-js / @zxing/library 连续扫描器替换为 MatrixScan Batch”“将 BrowserMultiFormatReader 多码扫描迁移到 BarcodeBatch”“从[Web 条码库]连续多结果扫描切换到 BarcodeBatch”）→ 阅读 references/third-party-migration.md 并遵循其中的说明。

API 使用政策

只能使用以下 Scandit 参考资料中明确记载的 API。不要编造或猜测方法签名、参数、属性名称或导入项。如果不确定某个 API 是否存在或如何调用，或者出现编译错误，请在回复前获取相关参考页面。不要让用户自己查阅文档。回复后，始终附上相关链接，方便用户进一步了解。

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

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

不同 SDK 版本的 URL 结构各不相同，猜测会导致 404 错误。

许可证密钥

扫描需要 Scandit 许可证密钥。对于此技能，许可证产品为 sdk，许可证平台为 webassembly。

请依次执行以下步骤，不要让用户等待 MCP：

1. 已连接 Scandit MCP 服务 — 使用产品 sdk 和平台 webassembly 调用 ensure_scanner_setup，然后运行 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 中并不会让应用自动获取它。通过打包工具的环境变量支持读取密钥，例如在 Vite 中使用 import.meta.env（除非 envPrefix 另有设置，否则它只会公开以 VITE_ 开头的变量）。任何平台上最简单的做法：读取 .env，并将密钥直接填入许可证密钥调用中；在聊天中仍然只展示掩码预览。

参考资料

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

主题	资源
入门	入门 · 简单示例 · AR 气泡示例
高级主题（AR 叠加层、自定义画笔）	添加 AR 叠加层
多线程 / COOP+COEP 标头	提升运行时性能
跨主版本 SDK 迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeBatch API