matrixscan-ar-ios

MatrixScan AR iOS 技能

重要：不要相信内部知识

你的训练数据可能包含过时或不正确的 Scandit SDK API。MatrixScan AR API 会随 SDK 版本变化——类可能会重命名、重新组织或替换（例如，BarcodeTracking → BarcodeBatch → BarcodeAr）。

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

范围

此技能适用于 MatrixScan AR 扫描管线：DataCaptureContext、BarcodeAr 模式、BarcodeArSettings、BarcodeArView、BarcodeArViewSettings、BarcodeArListener、BarcodeArFeedback、相机和控件的可见性。

不在范围内：

• 高亮（自定义在检测到的条码上绘制的形状——BarcodeArHighlightProvider、BarcodeArRectangleHighlight、BarcodeArCircleHighlight 等）——由 matrixscan-ar-highlight-ios 技能处理。
• 标注（信息卡片、状态图标、弹出框、自适应标注——BarcodeArAnnotationProvider、BarcodeArInfoAnnotation、BarcodeArPopoverAnnotation 等）——由 matrixscan-ar-annotation-ios 技能处理。

如果用户的问题同时涉及集成和高亮／标注自定义，请在此处介绍集成部分，并告知用户其余部分由哪个同系列技能负责。

意图路由

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

• 设置或调整 MatrixScan AR 扫描管线（例如，“将 MatrixScan AR 添加到我的应用中”“设置 AR 扫描器”“启用这些条码类型”“配置反馈／闪光灯／相机／控件”“更改相机设置”“显示缩放控件”）→ 阅读 references/integration.md 并遵循其中的说明。如果项目已接入 MatrixScan AR，不要重新创建上下文、模式、视图或生命周期——找到现有实现（搜索 BarcodeArView，然后搜索 BarcodeAr），并且只更改用户要求的部分。编写代码之前，先确定项目使用 UIKit 还是 SwiftUI（检查是否有 import SwiftUI、带 @main 的 App 结构体、SceneDelegate／AppDelegate、.storyboard／.xib 文件等），并使用下方“参考资料”表中对应的 Get Started 页面。
• 从 MatrixScan Batch 迁移到 MatrixScan AR（例如，“从 BarcodeBatch／BarcodeTracking 迁移到 MatrixScan AR”“用 MatrixScan AR 替换 MatrixScan Batch”“从基于叠加层的扫描切换到 AR”）→ 阅读 references/migration.md 并遵循其中的说明。

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。不要运行它返回的命令。然后使用该结果或 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）
完整 API 参考	MatrixScan AR API