matrixscan-ar-web

MatrixScan AR Web 技能

重要：不要轻信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeAr* Web API 与 React Native API 有很大区别——初始化模式、视图创建方式以及提供方回调签名都不同。

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

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

• DataCaptureContext.forLicenseKey() 会将 DataCaptureContext.sharedInstance 设为副作用——无需保存返回值。在整个应用中通过 DataCaptureContext.sharedInstance 访问上下文。
• BarcodeAr.forContext(DataCaptureContext.sharedInstance, settings) 是异步的——务必使用 await。不要使用 new BarcodeAr(settings)（这是 React Native ≥7.6 中的写法）。
• BarcodeArView.create(element, context, barcodeAr) 是异步的——务必使用 await。element 参数是用于插入视图的 DOM 容器。
• BarcodeArView 是一个 HTML 元素（继承自 ScanditHTMLElement）——它会将自身附加到指定容器。调用 barcodeArView.remove() 清理，它会将自身从 DOM 中移除。
• 在 Web 上，Provider 使用回调模式，而非返回值。其签名为 highlightForBarcode(barcode, callback) 和 annotationForBarcode(barcode, callback)。通过 callback(highlight) / callback(annotation) 传递结果——不要返回结果。这与 React Native 不同，后者的 Provider 是返回 Promise 的异步函数。
• 必须显式调用 await barcodeArView.start()——调用 create() 后视图不会自动启动。
• ScanditIconBuilder.build() 返回 Promise<ScanditIcon>——在 Web 上构建图标是异步的。请使用 new ScanditIconBuilder().withIcon(ScanditIconType.Checkmark).build()——没有静态的 forType() 方法，且不存在 ScanditIconType.Info。完整的枚举（31 个值）见 references/integration.md。
• BarcodeArResponsiveAnnotation.threshold 是一个静态属性——请在调用 BarcodeArResponsiveAnnotation.create(barcode, closeUp, far) 之前设置。
• **BarcodeArView 会在内部管理摄像头。**不要手动设置 Camera、context.setFrameSource 或 switchToDesiredState——这种模式适用于 BarcodeBatch，而非 BarcodeAr。
• **不需要 DataCaptureView。**对于 MatrixScan AR，BarcodeArView.create() 完全取代了 DataCaptureView。
• 模块加载器是 barcodeCaptureLoader()（来自 @scandit/web-datacapture-barcode）——BarcodeAr 没有单独的加载器。
• 自定义高亮和标注元素必须实现 BarcodeArHighlight / BarcodeArAnnotation，并作为 Web Component 继承 HTMLElement。它们必须设置 position: absolute、will-change: transform，并实现 updatePosition(point, transformOrigin, rotationAngle)，SDK 会在每一帧调用此方法。添加 [hidden] { display: none }，以支持 SDK 管理可见性。使用 if (!customElements.get(tag)) 作为保护条件，确保只注册一次 customElements.define。
• session.addedTrackedBarcodes 返回的是 Record<string, TrackedBarcode>（字典），而非数组——请使用 Object.values(session.addedTrackedBarcodes) 进行迭代。session.allTrackedBarcodes 也一样。
• **必须启用多线程。**设置 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp；即使 SDK 来自 jsDelivr CDN，也必须设置。不要建议使用 credentialless。如果没有这些响应头，SDK 会退回单线程模式，而这对 AR 跟踪来说速度太慢。在页面代码中，先启动 BrowserHelper.checkMultithreadingSupport()（来自 @scandit/web-datacapture-core），不要等待它完成，然后再调用 await DataCaptureContext.forLicenseKey()，这样两者会并行运行，且初始化不会等待检查完成。如果结果为 false，且用户未选择以单线程模式运行，则显示多线程对话框：从 references/integration.md 中的 multithreading-warning 辅助模块导入 showMultithreadingWarning；该模块不需要页面标记。在 React 中，应通过组件状态渲染同一对话框，而不是导入此辅助模块。每次页面加载最多显示一次对话框，并遵从“本次会话不再显示”复选框。COEP credentialless 并不表示要以单线程模式运行：Safari 不支持它，因此仍会显示对话框。
• 从 CDN 加载 SDK 时，必须在每个 URL 中指定一个确切版本（例如 @8.6.1），包括导入映射和 libraryLocation。使用浮动版本 @8 会导致 JavaScript 和引擎解析到不同的发行版本，从而使启动失败。
• 不要添加 visibilitychange 处理程序：页面隐藏时，视图已会停止摄像头；页面重新可见时，视图会恢复摄像头。
• DataCaptureContext.forLicenseKey() 是幂等的，因此可以安全地再次调用。调用 context.dispose() 后，请再次调用 forLicenseKey()，并重新设置 BarcodeAr 和 BarcodeArView，然后再调用 start()：单独调用 start() 不会重启已释放的上下文。

意图路由

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

• 从头集成 MatrixScan AR（例如“将 MatrixScan AR 添加到我的 Web 应用”“设置 BarcodeAr”“在条码上显示 AR 高亮”“显示信息注释”“如何在 Web 上使用 BarcodeArView”“生命周期或清理”）→ 阅读 references/integration.md，并遵循其中的说明。
• 从 BarcodeBatch / BarcodeTracking 迁移到 BarcodeAr（例如“从 BarcodeBatch 迁移到 BarcodeAr”“将 MatrixScan Batch 转换为 MatrixScan AR”“用 BarcodeAr 替换 BarcodeTracking”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

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

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

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

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

许可证密钥

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

请按以下顺序操作，绝不要让用户等待 MCP：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，传入产品 sdk、平台 webassembly、app_identifier（应用的 bundle 或 application id；对于 Web 应用，应填写其生产域名，绝不能填写 localhost）和环境变量 SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用该结果或 list_license_keys 中的密钥 ID 调用 get_license_key；如果 list_license_keys 显示该密钥不是试用密钥，请先征求用户同意，再获取密钥。在聊天中最多显示经过遮蔽的预览；绝不要输出完整密钥。

2. 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 返回的密钥，或用户粘贴或提供的密钥，替换占位符；在聊天中仍只显示经过遮蔽的预览。不要在项目、文件或环境中搜索密钥。

参考资料

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

主题	资源
入门	开始使用 · 简单示例
多线程 / COOP+COEP 标头	提升运行时性能
完整 API 参考	BarcodeAr API