label-capture-web

Label Capture Web 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不准确的 Scandit Label Capture API 信息。Label Capture 在近期的 SDK 版本中不断演进：

• 在 v7→v8 大版本升级（v7.6 → v8.0）中，LabelFieldDefinition 的正则表达式属性更名了（pattern→valueRegex、patterns→valueRegexes、dataTypePattern→anchorRegex、dataTypePatterns→anchorRegexes）。
• 在 v8.2 中，Validation Flow UI 经过重新设计，三个自定义属性已弃用。
• 在 v8.5 中，构建器新增了便捷的简写形式。

ARE（Adaptive Recognition Engine） 是 Scandit 基于云的 OCR 后备方案，可通过标签定义中的 AdaptiveRecognitionMode.Auto 启用。目前它处于 Beta 阶段，仅适用于 Validation Flow 覆盖层，并且需要启用了 ARE 功能标志的许可证密钥。可申请试用密钥进行评估；生产密钥需要联系 [email protected]。默认情况下不要启用它。

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

Web 特有注意事项

• 从 CDN 加载 SDK 时，请在每个 URL 中固定一个确切版本（例如 @8.6.1）：包括导入映射和 libraryLocation。使用浮动版本 @8 会导致 JavaScript 和引擎解析到不同版本，从而无法启动。
• 即使 SDK 来自 jsDelivr CDN，也需要跨源隔离设置 Cross-Origin-Opener-Policy: same-origin 和 Cross-Origin-Embedder-Policy: require-corp。不要为 SDK 推荐 credentialless。在页面代码中，应在 await DataCaptureContext.forLicenseKey() 之前启动 BrowserHelper.checkMultithreadingSupport()（来自 @scandit/web-datacapture-core），不要等待其完成，这样两者可以并行运行，初始化也不会等待检查结果。如果检查结果为 false，除非用户要求使用单线程，否则应显示多线程对话框：从参考资料中的 references/integration.md 所述 multithreading-warning 辅助模块导入 showMultithreadingWarning，无需页面标记。在 React 中，应通过组件状态渲染相同的对话框，而不是导入辅助模块。每次页面加载最多显示一次对话框，并遵循“不再显示本次会话”的复选框设置。COEP credentialless 并不表示要使用单线程：Safari 不支持它，因此仍会显示对话框。

意图路由

根据用户的请求，先加载相应的参考文件再作答：

• 关于其他 Scandit 产品或扫描模式的问题（例如 SparkScan、Barcode Capture、MatrixScan、ID Capture，或与 Label Capture 无关的常规 SDK 设置问题）→ 转交给 data-capture-sdk 技能。不要凭记忆尝试回答有关其他采集模式的问题——专用技能包含正确且最新的参考资料。

• 从头集成 Label Capture（例如“将 Label Capture 添加到我的应用”“扫描包含条码和到期日期的价签”“如何使用 Smart Label Capture”“如何启用 Validation Flow”“我想构建一个标签扫描应用”“应该使用哪个覆盖层”“什么是 ARE”“如何提高 OCR 准确率”）→ 阅读 references/integration.md 并遵循其中的说明。如果用户没有现有项目，指南会提示你优先提供预构建示例。

• 迁移或升级现有的 Label Capture 集成（例如“将我的 Label Capture 升级到最新 SDK”“从 v8.1 迁移到 v8.2”“Label Capture 的 SDK 版本之间有哪些变化”）→ 阅读 references/migration.md 并遵循其中的说明。

API 使用政策

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

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

1. 先检查已获取的页面（例如 Advanced Configurations 页面）是否包含指向该页面的直接链接——主题页面会直接链接到相关 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。不要运行该调用返回的命令。然后使用该结果或 list_license_keys 返回的密钥 ID 调用 get_license_key；如果 list_license_keys 显示密钥不是试用密钥，获取该密钥前先询问用户。聊天中最多显示部分遮蔽的预览；绝不要输出完整密钥。

2. 未连接 — 告知用户一次，他们可以在 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 的返回结果，也可以由用户粘贴或提供。聊天中仍只能显示部分遮蔽的预览。不要在项目、其文件或环境中搜索密钥。

参考资料

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

主题	资源
基本集成	入门 · 示例（LabelCaptureSimpleSample）
标签定义（字段、正则表达式、预设）	标签定义
高级主题（验证流程自定义、自适应识别、自定义叠加层）	高级配置
完整 API 参考	标签捕获 API