SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场matrixscan-batch-ios

matrixscan-batch-ios

编程与开发

查看项目

更新于 10-16 03:29

技能介绍

用途

MatrixScan Batch iOS 技能面向需要在 iOS 应用中同时识别多个条码的场景，基于 Scandit SDK 的 BarcodeBatch 模式（旧称 BarcodeTracking）。它帮助开发者完成从零集成、配置、处理被跟踪条码、自定义覆盖层、添加反馈以及生命周期管理等工作。

主要能力

  • 同时跟踪和扫描多个条码。
  • 支持 UIKit 与 SwiftUI 项目集成。
  • 支持 BasicOverlay 与 AdvancedOverlay 两种 AR 覆盖层。
  • 支持版本迁移（v6→v7→v8）。
  • 支持从第三方多码扫描方案迁移，例如 AVFoundation 的 AVCaptureMetadataOutput、VisionKit 的 DataScannerViewController 或其他第三方多码 SDK。

使用方式

技能强调不要信任内部记忆中的 Scandit SDK API，因为 BarcodeBatch 的初始化器签名、覆盖层构造器和委托方法名在不同大版本间会变化（例如 BarcodeTracking 改名为 BarcodeBatch）。编写或建议代码前，必须对照技能提供的参考文档核实 API。

根据用户请求加载对应参考文件：

  • 从零集成、配置设置、处理被跟踪条码、自定义覆盖层、添加反馈或管理生命周期 → 阅读 references/integration.md。写代码前先判断项目使用 UIKit 还是 SwiftUI（检查 import SwiftUI、@main App 结构、SceneDelegate/AppDelegate、.storyboard/.xib 文件等），并使用匹配的 Get Started 页面。如果项目已接入 BarcodeBatch，不要重新创建 context、mode、view 或生命周期，先定位现有实现（grep BarcodeBatch，再查 DataCaptureView），只修改用户要求的部分。
  • 升级 Scandit SDK 版本（如 v6→v7、v7→v8 或升级到最新）→ 阅读 references/migration.md。v6→v7 的主要变化是 BarcodeTracking 改名为 BarcodeBatch，指南也涵盖 context/camera 的现代化。询问用户前先从 Package.resolved / Podfile.lock 检测已安装版本。
  • 用 MatrixScan Batch 替换其他条码扫描器（AVFoundation AVCaptureMetadataOutput、VisionKit DataScannerViewController 或其他第三方多码 SDK）→ 阅读 references/third-party-migration.md，然后按 references/integration.md 进行 BarcodeBatch 集成。

API 使用策略：只使用 Scandit 参考文档中明确记录的 API，不要臆造或猜测方法签名、参数或属性名。如果不确定 API 是否存在或如何调用，或出现编译错误，先获取相关参考页面再回复。不要让用户自己去查文档。回答后始终附上相关链接。不要构造或猜测文档 URL：先检查已获取页面是否包含直接超链接；如果没有，获取 API 索引，从中提取实际链接再跟进。

许可证密钥：扫描需要 Scandit 许可证密钥。本技能的许可证产品为 native，许可证平台为 ios。按顺序处理，不要因 MCP 阻塞用户：

  1. Scandit MCP 服务器已连接 → 调用 ensure_scanner_setup，参数 product 为 native、platforms 为 ios，然后运行 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 中的密钥不会自动到达应用。可通过 .xcconfig 文件映射到 Info.plist，再用 Bundle.main.object(forInfoDictionaryKey:) 读取。任何平台上最简单的做法：读取 .env 并直接将密钥放入许可证密钥调用中，聊天中仍只显示掩码预览。

iOS 特有注意事项

  • BarcodeBatch(context: context, settings: settings) 是直接的便利初始化器，不是 Android 的 BarcodeBatch.forDataCaptureContext(...) 那样的工厂方法。传入非 nil 的 context 会自动将模式附加到 context。
  • 相机设置是手动的：获取 Camera.default，调用 context.setFrameSource(camera, completionHandler: nil)，然后 camera?.apply(BarcodeBatch.recommendedCameraSettings, completionHandler: nil)。在 viewWillAppear / viewWillDisappear 中驱动相机。
  • BarcodeBatchListener.barcodeBatch(_:didUpdate:frameData:) 在后台队列调用，不是主线程。UI 工作需通过 DispatchQueue.main.async {} 派发。
  • 不要在回调外持有 BarcodeBatchSession.trackedBarcodes、addedTrackedBarcodes、updatedTrackedBarcodes 或 removedTrackedBarcodes 的引用——在回调返回前复制数据。
  • BarcodeBatchBasicOverlay(barcodeBatch:view:) 和 BarcodeBatchAdvancedOverlay(barcodeBatch:view:) 会自动将覆盖层添加到 DataCaptureView，无需单独调用 addOverlay。
  • DataCaptureView 必须手动 addSubview，不像 BarcodeArView 会自动附加到父视图。
  • 逐条码画笔自定义（barcodeBatchBasicOverlay(:brushFor:)、setBrush(:for:)）需要 MatrixScan AR 附加许可证。统一的默认画笔（无委托）不需要。
  • BarcodeBatchAdvancedOverlay 需要 MatrixScan AR 附加许可证。
  • 没有内置反馈——BarcodeBatch 不会自行播放声音或振动（不同于 BarcodeCapture / SparkScan）。需在监听器回调内（派发到主线程）用 Feedback.default.emit() 手动发出反馈，并以 session.addedTrackedBarcodes 为条件，避免每帧都响。
  • session.removedTrackedBarcodes 是跟踪标识符的 [Int]（离开画面的条码），不是 TrackedBarcode 对象。addedTrackedBarcodes / updatedTrackedBarcodes 是 [TrackedBarcode]。
  • iOS 符号类型是 camelCase：.ean13UPCA、.code128、.qr，不是 Android 的 EAN13_UPCA / CODE128 / QR。
  • iOS 委托方法使用 Swift 命名：barcodeBatchBasicOverlay(:didTap:)（不是 Android 的 onTrackedBarcodeTapped），barcodeBatchAdvancedOverlay(:viewFor:)（不是 viewForTrackedBarcode）。
  • BarcodeBatchAdvancedOverlayDelegate 使用 UIView，不是 Android View 或 SwiftUI 视图。
  • SwiftUI：DataCaptureView 是 UIView，不能直接放入 SwiftUI。需将 UIKit 视图控制器包装在 UIViewControllerRepresentable 中，并将所有 BarcodeBatch API 保留在该视图控制器内。
  • 清理：BarcodeBatchListener 以弱引用持有，漏掉 removeListener 不会泄漏——但应在 deinit 中调用 barcodeBatch.removeListener(self) 使生命周期明确。使用共享单例（DataCaptureContext.shared）时，模式在应用生命周期内保持附加——无需调用 removeCurrentMode() 或 dispose()。如果需要显式拆除，DataCaptureContext 上确实存在这些方法。
  • DataCaptureContext 暴露两个有效初始化器：DataCaptureContext.initialize(licenseKey:) + .shared（7.1.0/7.6.0 新增——现代单例模式，本技能使用的方式）和较旧的 DataCaptureContext(licenseKey:) 便利初始化器（仍未弃用，docs.scandit.com 上的 UIKit Get Started 页面仍展示）。优先使用单例形式。

适用场景

  • 在 iOS 应用中从零集成 MatrixScan Batch。
  • 配置设置、处理被跟踪条码、自定义覆盖层、添加反馈、管理生命周期。
  • 升级 Scandit SDK 版本（v6→v7→v8）。
  • 用 MatrixScan Batch 替换其他条码扫描器。

限制

  • 扫描需要 Scandit 许可证密钥。
  • 逐条码画笔自定义和 BarcodeBatchAdvancedOverlay 需要 MatrixScan AR 附加许可证。
  • MCP 认证基于浏览器，不支持无头或 CI 环境；服务器仅提供试用密钥，不会创建、撤销或修改生产许可证。
  • 只能使用参考文档中明确记录的 API，不得臆造或猜测。

参考资源

  • UIKit 集成：Get Started (UIKit) · Sample
  • SwiftUI 集成：Get Started (SwiftUI)
  • AR 覆盖层（BasicOverlay 画笔、AdvancedOverlay 视图）：Adding AR Overlays
  • 版本迁移（v6→v7→v8）：Migrate 6→7 · Migrate 7→8
  • 完整 API 参考：BarcodeBatch API