barcode-capture-flutter

BarcodeCapture Flutter 技能

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

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeCapture API 在不同主版本 SDK 之间变化很大：属性可能会重命名、移除或重新组织，Flutter 插件接口（导入、插件初始化、pub 包）也一直在演进。

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

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

• 在 main() 中调用 runApp(...) 之前，必须调用并等待 ScanditFlutterDataCaptureBarcode.initialize()；调用前还需先执行 WidgetsFlutterBinding.ensureInitialized()。如果遗漏，可能会产生看似与初始化无关的平台通道错误。
• 一个 DataCaptureContext 必须同时拥有 BarcodeCapture 模式和 DataCaptureView。不要为每个页面或每个 MaterialApp 构建多个 context；持有 context 的 BLoC / 控制器的生命周期应长于任何单个 State。
• DataCaptureView 是通过 DataCaptureView.forContext(context) 返回的 Flutter Widget，你必须通过 view.addOverlay(...) 显式向其添加 BarcodeCaptureOverlay。与 SparkScan 不同，它没有预构建的扫描 UI；覆盖层是唯一能在相机预览画面上显示已识别条码的组件。
• BarcodeCaptureListener.didScan(...) 会阻塞识别管线，直到该回调返回。在回调中执行任何实质性工作之前，先禁用该模式（barcodeCapture.isEnabled = false），并在处理完成后重新启用它（或停止相机），否则会触发重复或不需要的扫描事件。
• Flutter 监听器上的 getFrameData 参数类型为 Future<FrameData?> Function()，帧数据采用延迟获取方式。只有确实需要帧数据时才调用，因为这会跨越平台通道。
• 每次更改软件包版本后，都必须运行 flutter pub get。在 iOS 上，Podfile 会传递解析依赖项；除非用户使用自定义配置，否则无需手动安装 pod。
• iOS（在 ios/Runner/Info.plist 中配置 NSCameraUsageDescription）和 Android（通过 permission_handler 在运行时请求权限）都需要相机权限；插件会自动声明 Android 清单权限。
• 热重载不会重新运行 main()，因此热重载后相机生命周期（以及 ScanditFlutterDataCaptureBarcode.initialize() 调用）会保留。需要完整重启才能再次触发插件初始化。通过 WidgetsBindingObserver.didChangeAppLifecycleState 调用 camera.switchToDesiredState(...)，以便相机在 paused 时关闭，并在 resumed 时重新开启。

意图路由

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

• 从头集成 BarcodeCapture（例如“将 BarcodeCapture 添加到我的应用”“设置条码扫描”“如何在 Flutter 中使用 BarcodeCapture”“如何在 BarcodeCapture 中处理相机”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 BarcodeCapture 集成（例如“从 v6 升级到 v7”“迁移我的 BarcodeCapture”“将 Scandit 软件包升级到 v8”“SDK 版本之间有哪些变化”）→ 阅读 references/migration.md，并遵循其中的说明。
• 用 BarcodeCapture 替换第三方扫描器（例如“从 mobile_scanner 迁移”“用 Scandit 替换 google_mlkit_barcode_scanning”“将现有条码插件换成 Scandit”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用策略

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

编写或迁移代码后，运行 dart analyze（或 flutter analyze），并在回答前修复所有错误和警告。

切勿构造或猜测文档 URL。 需要查找某个类或属性的 API 页面时：

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

URL 结构因 SDK 版本和包路径而异（例如 api/ui/ 子目录），猜测 URL 会导致 404 错误。

框架变体策略

Flutter 应用采用多种状态管理模式（StatefulWidget、BLoC、Provider、Riverpod）。此技能中的示例使用 BLoC 模式，因为它与官方 Scandit Flutter 示例一致，能让扫描流程与 Widget 树清晰分离，并且能很好地配合相机生命周期。如果目标项目已使用其他模式（Provider、Riverpod、GetX、普通 StatefulWidget），则在概念上保持 BarcodeCapture 的接线方式不变（由一个所有者持有 DataCaptureContext、BarcodeCapture 和 Camera，并向 UI 提供扫描事件），并将代码片段移植到项目现有的惯例中——不要重写项目的状态管理。

许可证密钥

扫描需要 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 返回的密钥，或用户粘贴或提供的密钥——聊天中仍只显示经过遮蔽的预览。不要在项目、其文件或环境中搜索密钥。

参考资料

根据用户的问题，为其指引到合适的资源：

主题	资源
Flutter 集成	开始使用 · 示例
高级主题（自定义反馈、取景器、位置选择、扫描意图、复合码）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeCapture API