label-capture-cordova

Label Capture Cordova 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或不正确的 Scandit Label Capture API。Cordova 插件接口（全局 Scandit.* 命名空间、deviceready 门控、插件安装、平台准备）与 Web、React Native、Flutter 和 Capacitor SDK 不同。

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

值得注意的 Cordova 特有问题：

• 所有 Scandit 代码都必须在 deviceready 之后运行。 在此之前，全局 Scandit.* 命名空间尚未填充。请使用 document.addEventListener('deviceready', () => {...}, false); 包装初始化代码。
• Cordova 上的监听器方法名称采用 iOS 风格。 Validation Flow 监听器使用 didCaptureLabelWithFields(fields) 和 didSubmitManualInputForField(field, oldValue, newValue)——而非 Web 对应的方法 onValidationFlowLabelCaptured / onManualInput。
• 基于类的字段 API，与 RN/Capacitor 相同（与 Flutter 相反）。使用 Scandit.CustomBarcode.initWithNameAndSymbologies(name, [...])、new Scandit.ExpiryDateText(name)、field.optional = false、Scandit.LabelCaptureSettings.settingsFromLabelDefinitions([...], {})。这里没有 LabelCaptureSettingsBuilder / LabelDefinitionBuilder，也没有 v8.5 的工厂函数语法糖——这些仅适用于 Web。
• 执行 cordova plugin add / 提升版本后，运行 cordova prepare ios（以及 cordova prepare android）以同步原生依赖。iOS 还需要在 platforms/ios/ 中重新运行 pod install。
• 相机权限：iOS 要求在应用的 Info.plist 中配置 NSCameraUsageDescription（或通过 config.xml 中的 <config-file> 配置）；Android 的 CAMERA 权限由插件自动声明，如果你的 minSdkVersion 面向 API 23 或更高版本，则必须在运行时请求该权限。
• Scandit.DataCaptureContext.initialize(licenseKey) 会返回单例上下文；不要创建多个上下文。

产品指导

只要用户在做设计决策（而不只是询问 API），就应用以下规则。这些规则体现了 Scandit 对 Label Capture 集成方式的建议。

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

意图路由

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

• 从零开始集成 Label Capture（例如“将 Label Capture 添加到我的应用”“扫描包含条码和到期日期的价格标签”“如何使用 Smart 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 页面时：

1. 先检查已获取的页面（例如“高级配置”页面）是否包含指向该页面的直接链接。
2. 如果没有找到直接链接，请获取 API 索引（见下表中的完整 API 参考），从中提取实际链接并访问。

URL 结构会因 SDK 版本和包路径而异，猜测链接会导致 404 错误。

框架变体政策

本技能中的示例使用纯 JavaScript（ES6+），因为这是 Cordova 模板和官方 LabelCaptureSimpleSample 的默认写法。如果目标项目使用 TypeScript（部分 Cordova 项目会使用），请保留相同的导入和结构，并按需添加类型注解——不要更改全局 Scandit.* 访问方式，不要改用 ES 模块导入，也不要假设存在打包工具功能。

许可证密钥

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

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

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

参考资料

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