matrixscan-batch-ios

MatrixScan Batch iOS 技能

重要：不要轻信内部知识

你的训练数据中可能包含过时或不正确的 Scandit SDK API。BarcodeBatch API 会随主要 SDK 版本变化——初始化方法签名、覆盖层构造函数和委托方法名称都已发生变化（例如，BarcodeTracking → BarcodeBatch）。

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

值得特别指出的 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:) 会在后台队列上调用，而不是在主线程上。通过 DispatchQueue.main.async {} 分派 UI 操作。
• 不要在回调外持有 BarcodeBatchSession.trackedBarcodes、addedTrackedBarcodes、updatedTrackedBarcodes 或 removedTrackedBarcodes 的引用——请在回调返回前复制数据。
• BarcodeBatchBasicOverlay(barcodeBatch:view:) 和 BarcodeBatchAdvancedOverlay(barcodeBatch:view:) 会自动将叠加层添加到 DataCaptureView，无需单独调用 addOverlay。
• 必须手动将 DataCaptureView 添加为子视图——与 BarcodeArView 不同，DataCaptureView 不会自动附加到父视图。
• 按条码自定义画笔（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 页面仍在使用）。建议优先采用单例形式。

意图路由

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

• 从头集成 MatrixScan Batch、配置设置、处理被追踪的条码、自定义覆盖层、添加反馈或管理生命周期 → 阅读 references/integration.md，并遵循其中的说明。在编写代码前，先确定项目使用 UIKit 还是 SwiftUI（检查 import SwiftUI、@main App 结构体、SceneDelegate/AppDelegate、.storyboard/.xib 文件等），并使用下方参考资料表中的对应 Get Started 页面。如果项目已接入 BarcodeBatch，请勿重新创建 context、mode、view 或生命周期逻辑——先找到现有内容（搜索 BarcodeBatch，然后搜索 DataCaptureView），并且只修改用户要求的部分。
• 升级 Scandit SDK 版本（例如 v6→v7、v7→v8，或“升级到最新版本”）→ 阅读 references/migration.md。MatrixScan Batch 从 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 页面时：

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

URL 结构可能有所不同（例如 api/ui/ 子目录），猜测会导致 404。

许可证密钥

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

按顺序完成以下步骤 — 切勿因 MCP 而阻塞用户：

1. Scandit MCP 服务已连接 — 调用 ensure_scanner_setup，产品设为 native，平台设为 ios，并提供 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 返回的密钥，也可以是用户粘贴或提供的密钥 — 聊天中仍然只能显示掩码预览。不要在项目、其文件或环境中搜索密钥。

参考资料

主题	资源
UIKit 集成	入门（UIKit） · 示例
SwiftUI 集成	入门（SwiftUI）
AR 叠加层（BasicOverlay 画笔、AdvancedOverlay 视图）	添加 AR 叠加层
版本迁移（v6→v7→v8）	从 6 迁移到 7 · 从 7 迁移到 8
完整 API 参考	BarcodeBatch API