barcode-capture-web

条码捕获 Web 技能

关键提示：不要相信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeCapture Web API 在不同主要 SDK 版本之间变化显著：方法会更名，异步模式会改变，且上下文初始化在 v8 中经过了重新设计。

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

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

• DataCaptureContext.forLicenseKey() 必须使用 await — 它是异步的，并会设置 DataCaptureContext.sharedInstance。不要接收其返回值；应始终使用 DataCaptureContext.sharedInstance。
• BarcodeCapture.forContext(context, settings) 是异步的 — 始终使用 await。
• DataCaptureView.forContext(context) 是异步的 — 始终使用 await。
• BarcodeCaptureOverlay.withBarcodeCaptureForView(barcodeCapture, view) 是异步的 — 始终使用 await。
• barcodeCapture.setEnabled(false/true) 是异步的 — 在 didScan 中执行其他操作前，先使用 await，以防重复扫描。
• 监听器回调是 didScan — 不是 onBarcodeScanned（那是 Android 中的名称）。
• 在 Web 上，codeDuplicateFilter 是以毫秒为单位的数字（例如 500）— 不是类似 Android 中的 TimeInterval 对象。
• BarcodeCapture.recommendedCameraSettings 是静态属性，不是方法调用。
• 传递给 view.connectToElement() 的 DOM 元素必须定义尺寸和定位方式 — 尺寸为零或未设置定位的元素无法渲染相机预览。
• 使用 context.frameSource.switchToDesiredState(FrameSourceState.On) 开启相机，使用 FrameSourceState.Off 关闭相机。不要添加 visibilitychange 处理器：页面隐藏时，DataCaptureView 已会停止相机，并在页面再次显示时恢复相机；添加第二个处理器会与 SDK 自身的处理逻辑发生竞争。
• 从 CDN 加载 SDK 时，每个 URL 都要固定到同一个确切版本（例如 @8.6.1）：包括导入映射和 libraryLocation。使用浮动版本 @8 会导致 JavaScript 和引擎解析到不同的发行版，从而无法启动。
• 在 await DataCaptureContext.forLicenseKey() 之前启动 BrowserHelper.checkMultithreadingSupport()（来自 @scandit/web-datacapture-core），但不要等待它完成，这样两者可以并行运行，初始化也不会等待检查完成。如果结果为 false，除非用户选择以单线程运行，否则应显示多线程对话框：从 references/integration.md 中的 multithreading-warning 辅助模块导入 showMultithreadingWarning，无需页面标记。在 React 中，应改为根据组件状态渲染同一对话框，而不是导入该辅助模块。每次页面加载最多显示一次该对话框，并遵循“本次会话不再显示”复选框。COEP credentialless 并不意味着要以单线程运行：Safari 不支持它，因此仍会显示该对话框。
• DataCaptureContext.forLicenseKey() 具有幂等性，因此再次调用是安全的。dispose() 会释放上下文、引擎和相机：释放后要继续扫描，必须再次调用 forLicenseKey()。

意图路由

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

• 从零开始集成 BarcodeCapture、配置设置、自定义反馈或覆盖层、添加取景器、处理扫描结果，或在扫描后执行异步操作（例如“将 BarcodeCapture 添加到我的应用”“设置条码扫描”“如何在 Web 中使用 BarcodeCapture”“过滤重复扫描”“关闭提示音”“添加取景器”“查询条码时禁用扫描”）→ 阅读 references/integration.md，并按照其中的说明操作。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit SDK 升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并按照其中的说明操作。

API 使用政策

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

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

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

URL 结构可能有所不同（例如 api/ui/ 子目录），猜测 URL 会导致 404 错误。

许可证密钥

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

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

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，设置产品 sdk、平台 webassembly、app_identifier（应用的 bundle 或 application ID；对于 Web，使用其生产域名，绝不要使用 localhost）和环境变量 SCANDIT_LICENSE_KEY。不要运行它返回的命令。然后使用该结果中的密钥 ID 或从 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 返回的密钥，或用户粘贴或提供的密钥，填入许可证密钥调用处，替换占位符——聊天中仍然只显示经过遮罩处理的预览。不要搜索项目、文件或环境中的密钥。

参考资料

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

主题	资源
快速入门	快速入门 · 示例
高级主题（取景器、位置选择、反馈、重复项过滤、复合码）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API