matrixscan-batch-flutter

MatrixScan Batch Flutter 技能

重要：切勿相信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeBatch* API 的接口会随 SDK 主版本变化——构造函数签名、叠加层构造函数、监听器结构以及 Flutter 专属类名都曾发生变化。

编写或建议代码前，务必依据此技能提供的参考资料核实 API。 不要依赖记忆中的方法签名、参数、插件名称或属性名称。

值得特别注意的 Flutter 问题：

• 在 main() 中，必须在调用 WidgetsFlutterBinding.ensureInitialized() 之后、调用 runApp(...) 之前调用并等待 await ScanditFlutterDataCaptureBarcode.initialize()。Bubbles 示例还会在 main() 中调用 await DataCaptureContext.initialize(licenseKey)，然后使用 DataCaptureContext.sharedInstance；Simple 示例则会将 context 传递给屏幕。这两种模式都有效——请根据项目结构选择。
• BarcodeBatch(settings) 是无需 context 的构造函数（Flutter ≥7.6）。构造完成后，显式调用 dataCaptureContext.setMode(barcodeBatch)。旧版 SDK 请使用接受 context 的工厂构造函数。
• Flutter ≥7.6 提供 BarcodeBatch.createRecommendedCameraSettings()。
• Flutter 上的高级叠加层方法名称与其他平台不同：
  • 设置 widget：setWidgetForTrackedBarcode(BarcodeBatchAdvancedOverlayWidget? widget, TrackedBarcode trackedBarcode)（而不是 setViewForTrackedBarcode）
  • 清除所有 widget：clearTrackedBarcodeWidgets()（而不是 clearTrackedBarcodeViews）
• 自定义 AR 标注 = BarcodeBatchAdvancedOverlayWidget 的子类（仅限 Flutter 的基类）。widget 状态必须扩展 BarcodeBatchAdvancedOverlayWidgetState<T>，并重写 build()，返回 BarcodeBatchAdvancedOverlayContainer。
• 使用 BarcodeBatchAdvancedOverlay 需要 MatrixScan AR 附加组件。 在 BarcodeBatchBasicOverlay 上使用 brushForTrackedBarcode 和 setBrushForTrackedBarcode 同样需要 MatrixScan AR 附加组件。
• Flutter 上的 BarcodeBatchAdvancedOverlay 提供 view getter（仅限 Flutter；其他平台不提供）。
• 在 Flutter 上，offsetForTrackedBarcode 是 BarcodeBatchAdvancedOverlayListener 的成员（根据 RST 中的 @dart@ 注解）。Flutter 上提供此成员；无需额外接口。
• TrackedObject（Flutter ≥7.3+）：SDK 7.3 引入了 TrackedObject 基类，TrackedBarcode 会扩展该类。对此无需编写操作指南——日常使用的 TrackedBarcode API 保持不变。
• BarcodeBatch 类的导入总入口为 scandit_flutter_datacapture_barcode_batch——它与 scandit_flutter_datacapture_barcode 是不同的导入总入口。始终同时导入这两个入口。
• Dart 中的 Symbology 枚举值使用 小驼峰命名法：Symbology.code128、Symbology.ean13Upca、Symbology.code39。不要写 Symbology.Code128 或 Symbology.EAN13UPCA。
• Dart 中，session.trackedBarcodes 是 Map<int, TrackedBarcode>（以整数标识符而非字符串为键）。
• Dart 中，session.removedTrackedBarcodes 是 List<int>（整数标识符）。
• 生命周期清理：调用 _barcodeBatch.removeListener(this)，将 _barcodeBatch.isEnabled 设为 false，关闭相机，并调用 dataCaptureContext.removeAllModes()（如果使用单例模式，则调用 removeCurrentMode()）。
• 许可证占位符必须完全一致：'-- ENTER YOUR SCANDIT LICENSE KEY HERE --'

意图路由

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

• 从头集成 MatrixScan Batch（例如“将 MatrixScan 添加到我的 Flutter 应用中”“设置 BarcodeBatch”“同时跟踪多个条码”“显示 AR 覆盖层”“逐条码画笔”“扫描反馈／蜂鸣／振动”“生命周期或清理”“相机权限”）→ 阅读 references/integration.md，并遵循其中的说明。
• 跨 SDK 版本升级现有的 MatrixScan 集成（例如“从 v6 迁移到 v7”“升级到 SDK 8”“我的代码使用 BarcodeTracking”“将 BarcodeTracking 重命名为 BarcodeBatch”）→ 阅读 references/migration.md，并遵循其中的说明。
• 用 MatrixScan Batch 替换第三方扫描器（例如“从 mobile_scanner 迁移”“我们使用 ML Kit / google_mlkit_barcode_scanning，想要跟踪多个条码”“将现有条码插件替换为 Scandit MatrixScan”）→ 阅读 references/third-party-migration.md，并遵循其中的说明。

API 使用政策

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

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

1. 首先检查已获取的页面中是否有指向该页面的直接链接。
2. 如果没有找到直接链接，请获取 API 索引并从中提取实际链接。

框架变体政策

Flutter 应用会使用多种状态管理模式（StatefulWidget、BLoC、Provider、Riverpod）。本技能中的示例使用 StatefulWidget 和 WidgetsBindingObserver，因为这与官方示例（MatrixScanSimpleSample、MatrixScanBubblesSample）一致，并能让扫描流程保持简洁。如果目标项目使用不同的模式，请保持 BarcodeBatch 的接线方式在概念上不变——由一个所有者持有 DataCaptureContext、BarcodeBatch、相机和覆盖层——并将代码片段移植到项目现有的约定中。

许可证密钥

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

按顺序完成以下步骤 — 不要因 MCP 而阻碍用户：

1. Scandit MCP 服务已连接 — 使用产品 native 和平台 ios、android 调用 ensure_scanner_setup，然后运行 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 中并不会自动传入应用。构建时通过 --dart-define-from-file=.env 传入，并使用 String.fromEnvironment 读取。适用于任何平台的最简单方式：读取 .env，并直接将密钥填入许可证密钥调用；在聊天中仍然只显示掩码预览。

参考资料

根据用户的问题，为其提供对应的资源：

主题	资源
Flutter 入门	Get Started
Flutter AR 覆盖层	Adding AR Overlays
完整 API 参考	BarcodeBatch API