matrixscan-count-flutter

MatrixScan Count Flutter 技能

重要：不要相信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeCount API 会在主要 SDK 版本之间发生变化——类名、构造函数签名、监听器接口和 Flutter 插件导入路径都已演变。

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

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

• 在 main() 中调用 runApp(...) 之前，必须调用并等待 ScanditFlutterDataCaptureBarcode.initialize() 完成；调用前需先执行 WidgetsFlutterBinding.ensureInitialized()。如果忘记这一步，会产生平台通道错误，看起来可能与初始化无关。
• BarcodeCountView 是 Flutter StatefulWidget。示例在 build() 中内联创建它，并使用级联运算符 ..uiListener = _bloc ..listener = _bloc——对于 BarcodeCount，这样做是正确的，因为该视图不会像 BarcodeArView 那样在重建时被销毁。不过，为了清晰起见，也可以将它存为 initState() 中的字段。
• BarcodeCount(settings) 是 Flutter ≥7.6 中可用的无上下文构造函数。在较旧的 SDK（Flutter 6.17–7.5）中，必须使用 BarcodeCount.forDataCaptureContext(context, settings)，该方法会返回一个 Future<BarcodeCount>——添加监听器之前必须先等待其完成。对于 ≥7.6，在使用无上下文构造函数时，需显式调用 dataCaptureContext.setMode(barcodeCount)。
• BLoC 负责管理 DataCaptureContext、BarcodeCount 和摄像头生命周期。BLoC 还实现了 BarcodeCountListener、BarcodeCountViewListener 和 BarcodeCountViewUiListener。
• BarcodeCount 的导入汇总库为 scandit_flutter_datacapture_barcode_count——与 scandit_flutter_datacapture_barcode 是不同的汇总库。务必同时导入两者。
• Dart 中的 Symbology 枚举值使用小驼峰命名法：Symbology.code128、Symbology.ean13Upca、Symbology.code39。不要写 Symbology.Code128 / Symbology.EAN13UPCA——那是 JS/TS 的形式，在 Dart 中无法编译。
• 仅适用于 Flutter 的监听器方法：Flutter ≥8.3 中的 BarcodeCountListener 扩展了 IBarcodeCountExtendedListener 接口，新增 didUpdateSession。Flutter ≥8.3 中的 BarcodeCountCaptureListListener 扩展了 IBarcodeCountCaptureListExtendedListener 接口，新增 didCompleteCaptureList。这些都是 Flutter 专有的扩展。
• 根据 SDK 文档，BarcodeCountView 必须全屏显示。
• iOS（ios/Runner/Info.plist 中的 NSCameraUsageDescription）和 Android（通过 permission_handler 在运行时请求）都需要摄像头权限。
• 最低 SDK 版本说明：BarcodeCount Flutter 6.17；无上下文构造函数 7.6；Status 模式 7.0（Flutter 上的最低版本）；Mapping 工作流 8.3；列表外操作设置 8.3；TextForBarcodesNotInListDetectedHint 8.3；TextForClusteringGestureHint 8.3；shouldDisableModeOnExitButtonTapped 8.3。
• License 占位符必须准确写为：'-- ENTER YOUR SCANDIT LICENSE KEY HERE --'

意图路由

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

• 从零开始集成 BarcodeCount（例如“将 MatrixScan Count 添加到我的应用”“设置条码计数”“如何在 Flutter 中使用 BarcodeCount”“如何计数条码”“根据列表扫描”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从旧版 BarcodeCount 构造函数迁移或添加较新的功能（例如“从 forDataCaptureContext 迁移”“更新 BarcodeCount 构造函数”“添加 Status 模式”“添加 Mapping 工作流”“列表外操作”）→ 阅读 references/migration.md，并遵循其中的指南。

API 使用政策

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

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

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

框架变体政策

Flutter 应用会使用多种状态管理模式（StatefulWidget、BLoC、Provider、Riverpod）。本技能中的示例使用 BLoC 模式，因为它与官方的 MatrixScanCountSimpleSample 一致，能让扫描流程与 Widget 树清晰分离，并且能很好地适配相机生命周期。如果目标项目已采用其他模式，则保持 BarcodeCount 的接线思路不变（一处统一管理 DataCaptureContext 和 BarcodeCount，并向 UI 暴露会话数据），再将代码片段迁移到项目现有的惯用模式中。

许可证密钥

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

按以下顺序操作，切勿让用户因 MCP 而受阻：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，传入产品 native 和平台 ios、android，然后运行 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 集成	开始使用 · 示例
完整 API 参考	BarcodeCount API