label-capture-android

Label Capture Android 技能

关键：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit Label Capture API。Label Capture 在最近几个 SDK 版本中不断演进：

• 在 v7→v8 重大版本升级中，LabelFieldDefinition 的正则表达式构建器方法更名了（setPattern→setValueRegex、setPatterns→setValueRegexes、setDataTypePattern→setAnchorRegex、setDataTypePatterns→setAnchorRegexes）。
• 在 v8.2 中，Validation Flow 2.0 为 LabelCaptureValidationFlowOverlay 引入了 shouldHandleKeyboardInsetsInternally，这与 Android 15 强制执行的 edge-to-edge 模式有关。
• Android 的符号体系名称使用下划线：Symbology.EAN13_UPCA，而不是 Symbology.EAN13UPCA。

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

Label Capture 的功能比看起来更丰富——养成两个习惯，避免大多数故障

Label Capture 提供丰富的预构建字段和完整的预构建标签定义，适用于人们实际扫描的数据，例如序列号、IMEI 1 和 2、有效期／包装日期、价格、重量、VIN、七段数码管显示内容。集成中最常见的两种错误，是忘了这些预构建项的存在，以及因缺少模型制品而在运行时崩溃。请养成以下两个习惯：

1. 优先使用预构建字段或预构建标签，不要一上来就自定义。 用户提到可识别的扫描目标时，例如“序列号”“IMEI”“有效期”“价格／货架标签”或“VIN”，几乎总有专用构建器或完整标签工厂，已针对这些目标调校好锚点和数值正则表达式。请使用它。对于已有预构建构建器的目标，仍用手写正则表达式创建自定义条码／文本字段，是导致集成出错的最大原因：你猜测的正则表达式不如经过调校的正则表达式适用于真实标签，而且这表明你不知道预构建项的存在。只有在没有合适的预构建项时，才使用 addCustomBarcode()／addCustomText()。完整目录及选择规则见 references/integration.md——请查阅，不要依赖记忆。

2. 使用任何预构建字段或定义时，都要随包包含正确的模型制品——模型配置错误是运行时故障的头号原因。 label-text-models 不只是文本字段需要的：序列号、IMEI 和零件号字段虽然属于“条码”字段，但运行时仍会加载模型。而且，单独使用 label-text-models 不足以支持完整标签预构建工厂——createPriceCaptureDefinition 还需要 com.scandit.datacapture:price-label。如果漏掉它，应用可以编译并启动，却始终无法扫描。references/integration.md 列出了各字段和工厂对应的制品规则；编写 Gradle 配置块之前，先将每个所用的预构建项对应到所需制品。

限制：Label Capture 不能与 Barcode Capture 同时运行

DataCaptureContext 一次只能运行一个活动模式，因此 Label Capture 和 Barcode Capture 不能同时处于活动状态——同时附加两者会导致上下文报错。如果用户想在扫描标签的“同时”读取独立条码，应将该条码建模为标签定义中的一个字段（使用 addCustomBarcode() 或预构建条码字段），而不是添加第二种模式——几乎所有情况下都应如此处理。（只有确实需要两个不同的扫描步骤时，才使用 setMode() 切换活动模式。）请参阅 references/integration.md。

意图路由

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

• 从头集成 Label Capture（例如：“将 Label Capture 添加到我的 Android 应用中”“扫描带有条形码和有效期的价签”“扫描手机包装盒上的序列号／IMEI”“读取 VIN”“如何使用 Smart Label Capture”）→ 阅读 references/integration.md，并遵循其中的说明。该文件包含完整的预构建字段目录和预构建整标签定义——在编写任何自定义字段或正则表达式之前，先查阅该文件。
• 启用或自定义 Validation Flow（例如：“如何启用 Validation Flow”“添加 Validation Flow 覆盖层”“自定义 Validation Flow 中的占位文本／按钮标签”“如何处理 Validation Flow 的结果”）→ 阅读 references/validation-flow.md，并遵循其中的说明。
• 自定义覆盖层、添加自定义 AR 视图、排查问题或使用云端 Adaptive Recognition（例如：“自定义字段高亮画笔／labelBrush”“字段正确时将价格字段设为绿色”“描出捕获的标签轮廓”“在字段上方显示勾选标记／徽章／图标”“使用 LabelCaptureBasicOverlayListener / brushForField / brushForLabel”“使用 Advanced Overlay 在字段上添加自定义 AR 视图”“viewForCapturedLabel(Field)”“扫描七段显示屏”“相机预览为黑屏”“构建标签时应用启动即崩溃”“启用云端回退／Adaptive Recognition Engine / ARE”“扫描收据”）→ 阅读 references/advanced.md（覆盖层自定义与组合、Advanced Overlay——包括按字段监听器无法获取标签上下文这一陷阱、七段显示屏、Adaptive Recognition 和收据扫描 beta）。问题排查症状请参阅 references/integration.md 末尾的内容。
• 迁移或升级现有的 Label Capture 集成（例如：“将我的 Label Capture 升级到最新 SDK”“从 v7 迁移到 v8”“Label Capture 的 SDK 版本之间有哪些变化”“升级后键盘遮挡了 Validation Flow 中的输入框”“将 Validation Flow 迁移到 2.0”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

仅使用下方 Scandit 参考资料中明确记载的 API。不要臆造或猜测方法签名、参数或构建器结构。如果不确定某个 API 是否存在或如何调用，或者遇到编译错误，请先获取相关参考页面。不要让用户自行查阅文档。回答后，务必附上相关链接，方便用户进一步了解。

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

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

URL 结构可能各不相同，猜测会导致 404 错误。

许可证密钥

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

按顺序完成以下步骤 — 绝不要让用户等待 MCP：

1. Scandit MCP 服务已连接 — 调用 ensure_scanner_setup，产品设为 native，平台设为 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 并不会让应用自动获取密钥。在 Gradle 中读取密钥，并将其公开为 BuildConfig 字段（这需要 buildFeatures { buildConfig = true }）。任何平台上最简单的做法：读取 .env，并直接将密钥传入许可证密钥调用，同时在聊天中仅显示掩码预览。

参考资料

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

主题	资源
基本集成	开始使用 · 示例（LabelCaptureSimpleSample）
标签定义（字段、正则表达式、预设）	标签定义
高级主题（覆盖层自定义 — 画笔、浮动 AR 视图 — 七段显示、Adaptive Recognition／Receipt Scanning 测试版）	references/advanced.md · 高级配置
完整 API 参考	Label Capture API