label-capture-flutter

Label Capture Flutter 技能

重要：不要相信内部知识

你的训练数据可能包含过时或错误的 Scandit Label Capture API。Flutter 插件的接口（包名、构建器 API、插件初始化、Widget 生命周期）与 Web、React Native、Cordova 和 Capacitor SDK 不同。

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

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

• 必须先初始化插件，再调用任何 Scandit API。 在 DataCaptureContext.initialize(licenseKey); 之前调用 await ScanditFlutterDataCaptureLabel.initialize();（以及 await ScanditFlutterDataCaptureBarcode.initialize();）。跳过插件的 initialize() 会导致运行时出现难以判断原因的 MethodChannel 错误。
• Flutter 上的监听器方法名称采用 iOS 风格。 Validation Flow 使用 didCaptureLabelWithFields(fields)、didSubmitManualInputForField(field, oldValue, newValue) 和 didUpdateValidationFlowResult(...)。Web 中的名称（onValidationFlowLabelCaptured、onManualInput）在 Flutter 上不存在。
• 存在两种监听器接口。 LabelCaptureValidationFlowListener 只声明 didCaptureLabelWithFields。要处理手动输入提交或逐帧结果更新，请实现 LabelCaptureValidationFlowExtendedListener（它在基础监听器的基础上扩展了 didSubmitManualInputForField 和 didUpdateValidationFlowResult）。
• Flutter 上的构建器 API。 字段定义使用构建器：CustomBarcodeBuilder().setSymbologies([...]).isOptional(false).build(name)、LabelDefinitionBuilder().addCustomBarcode(...).addExpiryDateText(...).build(name)、LabelCaptureSettings([labelDefinition])。这与 RN/Cordova/Capacitor（基于类的 API）相反，不要混淆。
• iOS（ios/Runner/Info.plist 中的 NSCameraUsageDescription）和 Android 均需要相机权限（Android 会自动声明；请在运行时使用 permission_handler 包请求权限）。
• DataCaptureView 是一个 Flutter Widget，其生命周期与 Widget 树绑定。通过 WidgetsBindingObserver 在 didChangeAppLifecycleState 中暂停相机，并在 State 的 dispose() 中释放监听器。

产品指导

每当用户在做设计决策时，都应用以下规则，而不只是回答 API 问题。这些规则体现了 Scandit 推荐的 Label Capture 集成方式。

• 默认使用 Validation Flow。 新集成应使用 LabelCaptureValidationFlowOverlay，而不是 LabelCaptureBasicOverlay。只有当客户明确需要实时 AR 覆盖层，或需要 Validation Flow 的固定布局无法实现的 UI 时，才推荐使用基础／高级覆盖层方案。请参阅 references/validation-flow.md。
• Validation Flow 必须全屏渲染。 不要将其放入卡片、半屏面板、局部模态视图或非全高小部件中——其布局假设可用于字段清单、手动输入面板和键盘的高度为全屏高度。
• 优先使用预制标签，其次是预制字段，最后才考虑自定义。 按以下顺序尝试：（1）预制标签定义是否满足使用场景？— LabelDefinition.vinLabelDefinitionWithName(name)、LabelDefinition.priceCaptureDefinitionWithName(name)、LabelDefinition.sevenSegmentDisplayLabelDefinitionWithName(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。
• 自适应识别引擎／云端回退／收据扫描（“如何启用 ARE”“使用云端识别”“扫描收据”“AdaptiveRecognitionMode”“ARE 是否可用于生产环境”）→ 阅读 references/adaptive-recognition.md。
• 迁移或升级现有的 Label Capture 集成 → 阅读 references/migration.md。

API 使用政策

仅使用下方 Scandit 参考资料中明确记录的 API。不要臆造或猜测方法签名、参数、属性名称或导入语句。如果不确定某个 API 是否存在或如何调用，或者出现 Dart 编译器／运行时错误，请先获取相关参考页面，再作答。不要让用户自行查阅文档。回答后，始终附上相关链接，供用户进一步了解。

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

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

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

框架变体政策

此技能中的示例使用 StatefulWidget + WidgetsBindingObserver，因为官方的 LabelCaptureSimpleSample 和其他 Flutter Scandit 示例都采用这种方式。如果目标项目使用状态管理库（BLoC、Riverpod、Provider），则应将监听器和生命周期接入相应模式，但保持相同的插件初始化和字段／构建器代码。不要仅为 Label Capture 引入新的状态管理库。

示例使用 Dart（健全的空安全）。需要 Flutter >=3.10 和 Dart >=3.0。

许可证密钥

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

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

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，并设置产品为 native、平台为 ios 和 android，设置 app_identifier（应用的 bundle 或 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 返回的密钥，或用户粘贴或提供的密钥，替换许可证密钥调用中的占位符——聊天中仍然只能显示经过遮蔽的预览。不要在项目、文件或环境中搜索密钥。

参考资料

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

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