matrixscan-ar-flutter

MatrixScan AR Flutter 技能

重要：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。BarcodeAr API 会随 SDK 主版本变化而变化——类名、构造函数签名、提供方接口和 Flutter 插件导入路径都经历过演变。

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

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

• 在 main() 中调用 runApp(...) 之前，必须调用并等待 ScanditFlutterDataCaptureBarcode.initialize()，且要在 WidgetsFlutterBinding.ensureInitialized() 之后调用。忘记这一步会导致平台通道错误，而且错误看起来可能与初始化无关。
• BarcodeArView 是一个 Flutter StatefulWidget。应在 initState() 中创建一次（不要在 build() 中创建），将其存储为字段，并嵌入 Widget 树中。在 build() 中创建它会导致每次重建时原生视图都被拆除并重新创建。
• 高亮和注释提供方（BarcodeArHighlightProvider、BarcodeArAnnotationProvider）分别返回 Future<BarcodeArHighlight?> 和 Future<BarcodeArAnnotation?>。这些回调是异步的——不要返回普通值。
• BarcodeArCustomHighlight 和 BarcodeArCustomAnnotation 使用 Flutter Widget 子级，并将其序列化为快照。动画 Widget 会在渲染时被捕获为静态帧——它们不会在 AR 覆盖层中播放动画。
• BLoC（或同等控制器）负责管理 DataCaptureContext、BarcodeAr 和摄像头生命周期。State 类持有 BarcodeArView 并实现提供方接口。
• iOS（在 ios/Runner/Info.plist 中设置 NSCameraUsageDescription）和 Android（通过 permission_handler 在运行时请求权限——插件会自动声明清单权限）都需要摄像头权限。
• Barcode AR 的导入路径是 scandit_flutter_datacapture_barcode_ar——这是与主导入路径 scandit_flutter_datacapture_barcode 分开的独立入口文件。
• Dart 中的 Symbology 枚举值使用小驼峰命名法：Symbology.code128、Symbology.ean13Upca、Symbology.code39、Symbology.qr、Symbology.dataMatrix。不要写成 Symbology.Code128 / Symbology.EAN13UPCA——那是 JS/TS 的写法，无法通过 Dart 编译。

意图路由

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

• 从头开始集成 BarcodeAr（例如“将 MatrixScan AR 添加到我的应用中”“设置条码 AR 扫描”“如何在 Flutter 中使用 BarcodeAr”“如何在跟踪的条码上显示高亮”“如何显示信息注释”）→ 阅读 references/integration.md，并遵循其中的说明。

• 从 BarcodeBatch / BarcodeTracking 迁移到 BarcodeAr（例如“从 BarcodeBatch 迁移”“将 BarcodeBatch 转换为 BarcodeAr”“从 MatrixScan 转到 MatrixScan AR”“用 BarcodeAr 替换 BarcodeTracking”“将旧的 MatrixScan 代码升级到 AR”）→ 阅读 references/migration.md，并遵循其中的 10 步迁移指南。

API 使用政策

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

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

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

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

框架变体政策

Flutter 应用使用多种状态管理模式（StatefulWidget、BLoC、Provider、Riverpod）。本技能中的示例使用 BLoC 模式，因为它与官方的 MatrixScanARSimpleSample 一致，能让扫描流程与 Widget 树清晰分离，并且易于与相机生命周期配合。如果目标项目已经使用其他模式（Provider、Riverpod、GetX、普通 StatefulWidget），请保持 BarcodeAr 的接线概念不变（由一个所有者持有 DataCaptureContext、BarcodeAr，并向 UI 暴露会话数据），同时将代码片段移植到项目现有的约定中——不要重写项目的状态管理。

许可证密钥

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

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

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，产品设为 native，平台设为 ios 和 android，app_identifier 使用应用的 bundle 或 application ID（对于 Web，使用其生产域名，绝不要使用 localhost），env_var 使用 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 集成	开始使用 · 示例
完整 API 参考	BarcodeAr API