label-capture-capacitor

Label Capture Capacitor 技能

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

你的训练数据中可能包含过时或错误的 Scandit Label Capture API。Capacitor 插件接口（ES 模块导入、initializePlugins()、webViewContentOnTop 开关）与 Web、React Native、Flutter 和 Cordova SDK 不同。

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

值得特别指出的 Capacitor 注意事项：

• 必须先初始化插件。 在调用 DataCaptureContext.initialize(licenseKey) 之前，先调用 await ScanditCaptureCorePlugin.initializePlugins();。跳过此步骤会导致运行时出现插件桥接错误。
• webViewContentOnTop 开关。 原生扫描视图位于 WebView 后方。扫描时，将 view.webViewContentOnTop = false，以便原生叠加界面接收触摸事件。要在上方显示基于 DOM 的界面（例如结果弹窗），请切换回 view.webViewContentOnTop = true。忘记切换是导致“扫描时弹窗／按钮无法使用”或“扫描界面不可见”的最常见原因。
• Capacitor 上的监听器方法名称采用 iOS 风格。 Validation Flow 监听器使用 didCaptureLabelWithFields(fields)、didSubmitManualInputForField(field, oldValue, newValue)、didUpdateValidationFlowResult(...)。Web 上的名称（onValidationFlowLabelCaptured、onManualInput）在 Capacitor 上不存在。
• 基于类的字段 API，与 RN／Cordova 相同（与 Flutter 相反）。CustomBarcode.initWithNameAndSymbologies(...)、new ExpiryDateText(...)、field.optional = false、LabelCaptureSettings.settingsFromLabelDefinitions([...], {})。没有 LabelCaptureSettingsBuilder／LabelDefinitionBuilder，也没有 v8.5 的工厂函数简写——这些仅适用于 Web。
• 安装或升级 Scandit 软件包后，请运行 npx cap sync（iOS 还需运行 cd ios/App && pod install）。
• 相机权限：iOS 要求在 ios/App/App/Info.plist 中设置 NSCameraUsageDescription。Android：插件会自动声明权限；如果 minSdkVersion >= 23，请通过 @capacitor/camera 或 @capgo/permission 在运行时请求权限。

产品指导

每当用户做出设计决策时，都应遵循这些规则，而不仅仅是在回答 API 问题时。这些规则体现了 Scandit 对 Label Capture 集成方式的建议。

• 默认使用 Validation Flow。 新集成应使用 LabelCaptureValidationFlowOverlay，而不是 LabelCaptureBasicOverlay。只有当客户明确需要实时 AR 覆盖层，或需要 Validation Flow 固定布局无法实现的 UI 时，才建议使用基础／高级覆盖层方案。请参阅 references/validation-flow.md。
• Validation Flow 必须以全屏方式呈现。 不要将其放在卡片、半屏面板、模态切片或部分高度的小组件中——其布局假定具有全屏高度，以容纳字段清单、手动输入面板和键盘。
• 优先使用预制标签，其次使用预制字段，最后才考虑自定义。 按以下顺序尝试：(1) 预制标签定义是否满足使用场景？— LabelDefinition.createVinLabelDefinition(name)、LabelDefinition.createPriceCaptureDefinition(name)、LabelDefinition.createSevenSegmentDisplayLabelDefinition(name)。(2) 标签能否由预制字段构成？— ExpiryDateText、PackingDateText、DateText、WeightText、UnitPriceText、TotalPriceText、SerialNumberBarcode、PartNumberBarcode、ImeiOneBarcode、ImeiTwoBarcode。(3) 只有在最后不得已时，才使用 CustomText / CustomBarcode。
• 从零开始集成时，先使用示例应用。 如果用户要从头开始，请建议克隆 LabelCaptureSimpleSample（链接见 References 表格），并在此基础上进行调整。
• 非 Label Capture 问题请转交给 data-capture-sdk skill。 如果用户询问其他 Scandit 产品（Barcode Capture、SparkScan、MatrixScan、ID Capture 等），或询问如何在产品之间进行选择，请转交给 data-capture-sdk skill，而不要猜测。

意图路由

• 从零开始集成 Label Capture → 阅读 references/integration.md。默认情况下，应集成 Validation Flow（集成指南会优先介绍它）。
• Validation Flow 相关问题（“如何自定义它”“哪些内容可以更改”“为什么这样实现”“如何响应手动编辑”“能否更改颜色”）→ 阅读 references/validation-flow.md。
• 超出 Validation Flow 范围的视觉自定义（“实时 AR 覆盖层”“在每个捕获的字段旁绘制标签”“扫描时获取相机帧”）→ 阅读 references/customization.md。
• Adaptive Recognition Engine／云回退／收据扫描（“如何启用 ARE”“使用云识别”“扫描收据”“AdaptiveRecognitionMode”“ARE 是否可在生产环境中使用”）→ 阅读 references/adaptive-recognition.md。
• 迁移或升级现有 Label Capture 集成 → 阅读 references/migration.md。

API 使用政策

只能使用以下 Scandit 参考资料中明确记载的 API。不要杜撰或猜测方法签名、参数、属性名称或导入项。如果不确定某个 API 是否存在，或发生运行时错误，请先获取相关参考页面，再作答。不要让用户自行查阅文档。回答后务必附上相关链接。

切勿构造或猜测文档 URL。 只能跟随已获取页面中的超链接，或获取 API 索引并从中跟随链接。

框架变体策略

此技能中的示例使用原生 JavaScript 和 ES 模块导入，因为这是 Capacitor 模板和官方 LabelCaptureSimpleSample 的默认配置。如果目标项目使用框架（React、Vue、Angular、Ionic），请将 Scandit 初始化和设置放在组件树之外（例如放在一个导出单例上下文的小型模块中），并从框架组件中调用它。不要仅为了 Label Capture 引入状态管理库。

许可证密钥

扫描需要 Scandit 许可证密钥。此技能使用的许可证产品为 native，许可证平台为 ios 和 android。

请按以下顺序操作，切勿让用户等待 MCP：

1. Scandit MCP 服务已连接——使用产品 native、平台 ios 和 android、app_identifier（应用的 bundle 或 application id；对于 Web，使用其生产域名，绝不要使用 localhost）以及环境变量 SCANDIT_LICENSE_KEY 调用 ensure_scanner_setup。不要运行它返回的命令。然后使用该结果或 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 返回的，也可以是用户粘贴或提供的。聊天中仍然只能显示脱敏预览。不要在项目、文件或环境中搜索密钥。

参考资料

主题	资源
Capacitor 集成	开始使用 · 示例（LabelCaptureSimpleSample）
标签定义（字段、正则表达式、预设）	标签定义
高级主题（验证流程自定义、自适应识别、自定义叠加层）	高级配置
完整 API 参考	Label Capture API