matrixscan-ar-net-ios

MatrixScan AR .NET for iOS 技能

关键：请勿相信内部知识

你的训练数据可能包含过时或错误的 Scandit SDK API。BarcodeAr API 相对较新（在 dotnet.ios 7.2 中引入），并且在多个方面与 Swift 原生 SDK 不同：提供程序基于 async/Task，而非基于委托；高亮和注释构造函数仅接受 Barcode（没有 context 参数）；监听器接口只有一个方法；BarcodeArView 是 IDisposable，而不是 UIView 子类；.NET 绑定使用 PascalCase，使用 TimeSpan 而非 TimeInterval，等等。

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

值得指出的 .NET-iOS 特定注意事项：

• 此技能适用于非 MAUI .NET for iOS 工作负载（项目使用 <TargetFramework>net10.0-ios</TargetFramework> 或类似设置，且没有 <UseMaui> 标志）。对于 MAUI 应用，请改用面向 MAUI 的技能——BarcodeArView 在 MAUI 中的托管方式截然不同（XAML / Microsoft.Maui.Controls.View）。
• BarcodeAr 使用接收上下文的 new 构造函数：new BarcodeAr(dataCaptureContext, settings)。在 .NET 中没有 BarcodeAr.Create(...) / BarcodeAr.ForDataCaptureContext(...) 工厂方法。BarcodeArSettings 也使用普通的 new。（DataCaptureContext.ForLicenseKey(key) 仍使用工厂形式——它属于 Core。）
• BarcodeArView.Create(parentView, barcodeAr, dataCaptureContext, viewSettings, cameraSettings) 是工厂方法（与 BarcodeAr 本身不同）。cameraSettings 参数可为空——传入 null 即可使用 BarcodeAr.RecommendedCameraSettings。parentView 是 UIView（通常是宿主视图控制器的 this.View，或专用的容器 UIView outlet）。BarcodeArView 会自动将自身附加到 parentView——不要对它调用 this.View.AddSubview(...)。
• BarcodeArView 实现了 IDisposable，不是 UIView 子类。该类声明了 public static implicit operator View(BarcodeArView view)，可在需要时将其转换为 UIKit.UIView（例如用于原生互操作，因为在 iOS 上 View 通过 global using View = UIKit.UIView; 别名指向 UIView），但你无需自行将其添加到视图层级中——Create 工厂方法会自动将它附加到 parentView。
• iOS 上的 .NET BarcodeArView 没有 OnResume() / OnPause()。这些方法仅适用于 Android（在绑定中由 #if __ANDROID__ 保护）。在 iOS 上，生命周期处理方式是在 ViewWillAppear 中调用 barcodeArView.Start()，并在 ViewWillDisappear 中调用 barcodeArView.Stop()——这与官方 MatrixScanARSimpleSample 一致。在 .NET iOS 视图控制器中调用 barcodeArView.OnResume() 会导致编译错误。
• BarcodeArView.Dispose() 会执行清理。BarcodeArView 没有 OnDestroy() 方法（这是 Android Java/Kotlin 的惯用方式）。请在视图控制器的 Dispose(bool) 重写方法中调用 Dispose()，或者在实例生命周期较短且由你管理时使用 using 语义。
• 仅 iOS 提供的视图控件。ShouldShowMacroModeControl（bool）和 MacroModeControlPosition（Anchor）仅适用于 iOS（Android 不提供这些控件）。它们与跨平台的 ShouldShowTorchControl / ShouldShowZoomControl / ShouldShowCameraSwitchControl 及对应的 *Position 属性并列。用户询问 iOS 上的控件时，请提及它们。
• IBarcodeArListener 只有一个方法：OnSessionUpdated(BarcodeAr, BarcodeArSession, IFrameData)。在 dotnet.ios 中，它没有类似 Swift BarcodeArListener 协议的 OnObservationStarted / OnObservationStopped 回调。声明这些方法会导致编译错误——该接口中根本没有它们。
• 在惯用的 C# 写法中，优先使用事件 API（barcodeAr.SessionUpdated += handler），而不是侦听器接口。处理程序接收包含 BarcodeAr、Session 和 FrameData 的 BarcodeArEventArgs。为与其他平台保持一致，AddListener(IBarcodeArListener) 仍然可用。
• **OnSessionUpdated / SessionUpdated 在后台识别队列上运行。**任何 UI 更新都应通过 DispatchQueue.MainQueue.DispatchAsync(() => { … })（来自 CoreFoundation）进行调度。不要使用 InvokeOnMainThread——虽然可用，但 Scandit 官方 .NET iOS 示例始终使用 DispatchQueue.MainQueue.DispatchAsync。
• 提供程序接口使用异步方法，而不是基于委托的方式。IBarcodeArHighlightProvider.HighlightForBarcodeAsync(Barcode) 返回 Task<IBarcodeArHighlight?>，IBarcodeArAnnotationProvider.AnnotationForBarcodeAsync(Barcode) 返回 Task<IBarcodeArAnnotation?>。不要查找委托 / completionHandler 参数——.NET 绑定中不存在这些参数。对于给定条码，返回 Task.FromResult<IBarcodeArHighlight?>(null)（或在 async 方法中返回 null），即可停用对应的高亮 / 标注。
• 高亮和标注的构造函数只接收 Barcode——不接收 context 参数。请使用 new BarcodeArRectangleHighlight(barcode)、new BarcodeArCircleHighlight(barcode, BarcodeArCircleHighlightPreset.Dot)、new BarcodeArInfoAnnotation(barcode)、new BarcodeArStatusIconAnnotation(barcode)、new BarcodeArPopoverAnnotation(barcode, buttons)。传入 UIViewController 或 UIView 会导致编译错误。
• 对称名称使用 C# PascalCase：Symbology.Ean13Upca、Symbology.Ean8、Symbology.Code128、Symbology.Code39、Symbology.Qr、Symbology.DataMatrix、Symbology.InterleavedTwoOfFive。它们不采用 Swift 的驼峰命名形式（.ean13UPCA、.qr）。
• BarcodeArSettings 没有 Enabled 开关——BarcodeAr 本身也没有 Enabled 属性。要暂停 / 恢复扫描，请使用 barcodeArView.Pause() / barcodeArView.Start()。
• **.NET 中的 BarcodeArViewSettings 仅包含少量设置。**它只有三个属性：SoundEnabled、HapticEnabled、DefaultCameraPosition。不要臆造 TriggerButtonCollapseTimeout、InactiveStateTimeout、ToastSettings 或 DefaultMiniPreviewSize 等属性——这些属于 SparkScan，而非 BarcodeAr。
• BarcodeArFeedback 位于 Scandit.DataCapture.Barcode.Ar.Feedback，包含两个类型为 Core.Common.Feedback.Feedback 的属性：Scanned 和 Tapped。空构造函数 new BarcodeArFeedback() 会生成一个两个事件都静默的反馈对象——将其赋给 barcodeAr.Feedback 会禁用默认的提示音 / 振动。要恢复默认设置，请使用静态属性 BarcodeArFeedback.DefaultFeedback。（注意：它在 .NET 中是静态属性，而不是 Swift 的 BarcodeArFeedback.default() 方法。）
• 高亮上的点击交互通过 BarcodeArView 上的 HighlightForBarcodeTapped 事件（EventHandler<HighlightForBarcodeTappedEventArgs>）公开。.NET 的 BarcodeArView 上没有 UiListener / UIDelegate 属性——Swift 的 BarcodeArViewUIDelegate 在 C# 中通过事件提供。事件参数公开了 BarcodeAr、Barcode 和 Highlight。
• barcodeAr.Feedback 是一个属性（可读写）；ApplySettingsAsync(BarcodeArSettings) 返回 Task。BarcodeAr.RecommendedCameraSettings 是一个静态属性，不是方法（Swift SDK 将 BarcodeAr.recommendedCameraSettings 公开为类变量——在 .NET 中它是一个 getter；dotnet.ios 上没有 BarcodeAr.CreateRecommendedCameraSettings() 方法）。
• **.NET API 树中没有 BarcodeArFilter / SetBarcodeFilter。**Swift 的 setBarcodeFilter(...) 方法（在 8.1 中添加）目前未在 dotnet.ios 中公开。不要尝试使用它。
• 视图控制器构造函数取决于 VC 的实例化方式。如果 VC 由 storyboard / XIB 加载（当项目的 Info.plist 中设置了 UIMainStoryboardFile，且项目包含 Main.storyboard 时很常见），请保留 public MyVC(IntPtr handle) : base(handle) { } 构造函数——运行时会传入真实的原生句柄。对于以编程方式实例化的 VC（没有 Main.storyboard，从 SceneDelegate.WillConnect 或 AppDelegate 设置根视图控制器），应声明无参数构造函数 public MyVC() : base() { }，并使用 new MyVC() 实例化。不要向 (IntPtr) 构造函数传入 IntPtr.Zero——这会导致原生对等对象未初始化，且 ViewDidLoad 可能永远不会触发，表现为黑屏、没有相机预览且无法扫描。
• **SDK 8.0+ 要求显式初始化。**在任何 Scandit 代码运行之前，请于 AppDelegate.FinishedLaunching（或者项目没有 AppDelegate 时，在 SceneDelegate.WillConnect 的最开头）调用 ScanditCaptureCore.Initialize() + ScanditBarcodeCapture.Initialize()。否则，首次调用 new BarcodeAr(...) / BarcodeArView.Create(...) 时会因 DI 容器中没有注册项而在启动时崩溃。**6.x / 7.x 不需要此操作。**完整的 AppDelegate.cs 模板请参见 references/integration.md。
• NuGet 包为 Scandit.DataCapture.Core 和 Scandit.DataCapture.Barcode。这里没有单独的 *.Maui 包——那些仅适用于 MAUI 项目。不要根据训练数据猜测版本——固定版本前，请通过 WebFetch 从 https://www.nuget.org/packages/Scandit.DataCapture.Barcode/ 获取最新的稳定版。编造一个不存在的版本（例如只发布了 8.4.0，却使用 8.13.0）会导致 dotnet restore 失败，并显示 Unable to find package Scandit.DataCapture.Core with version (>= …)。完整流程请参见 references/integration.md 的步骤 0。
• **iOS 的 SupportedOSPlatformVersion 必须 ≥ 15.0。**请在 .csproj 中设置。Scandit 官方 iOS 示例的 Info.plist 中 MinimumOSVersion 为 15.0，且项目的 <SupportedOSPlatformVersion> 与之相符。
• 必需的 Info.plist 键是 NSCameraUsageDescription（Privacy - Camera Usage Description）。缺少此项会导致应用首次访问相机时崩溃。iOS 会在相机首次打开时自动提示用户；无需调用单独的运行时请求 API（没有 Android 风格的 RequestPermissions）。这是 .NET Android 技能的一项关键区别，后者要求手动处理权限流程。

意图路由

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

• 从头开始集成 BarcodeAr、配置设置、自定义高亮或注释、处理会话更新、自定义反馈或接入点按交互（例如“将 MatrixScan AR 添加到我的 .NET iOS 应用中”“在 C# 中设置条码 AR 扫描”“为每个跟踪到的条码显示矩形高亮”“显示包含条码数据的信息注释”“关闭提示音”“响应高亮点按”“切换为圆形高亮”“显示宏模式开关”）→ 阅读 references/integration.md，并遵循其中的说明。
• 迁移或升级现有的 MatrixScan AR 集成（例如“从 v7 升级到 v8”“将 Scandit .NET SDK 升级到 v8”“BarcodeAr 的 SDK 版本之间有哪些变化”“升级到 8.x 时是否需要更改 BarcodeAr 代码”）→ 阅读 references/migration.md，并遵循其中的说明。

API 使用政策

仅使用下方 Scandit 参考资料中明确记录的 API。不要编造或猜测方法签名、参数或属性名称。如果不确定某个 API 是否存在或如何调用，或者发生编译错误，请先获取相关参考页面，再进行回复。不要让用户自行查阅文档。回复后，始终附上相关链接，方便用户进一步了解。

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

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

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

许可证密钥

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

请按以下顺序操作，切勿让用户等待 MCP：

1. Scandit MCP 服务已连接 — 调用 ensure_scanner_setup，指定产品 native 和平台 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 中，应用本身不会自动获取该密钥。.NET 不会自动加载 .env，因此请使用以下最简单的方法。在任何平台上，最简单的方法都是读取 .env 并直接将密钥填入许可证密钥调用中，同时在聊天中仅显示掩码预览。

参考资料

根据用户的问题，引导他们查看相应的资源：

主题	资源
入门	入门（.NET for iOS）
高级主题（自定义高亮、自定义注释、点击交互、弹出层、筛选）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeAr API（.NET iOS）

此技能涵盖的 API 范围

官方 RST 文档（docs/source/barcode-capture/api/barcode-ar*.rst 和 api/ui/barcode-ar-*.rst）中所有标注了 :available: dotnet.ios 的类，均在 references/integration.md 中介绍：

• BarcodeAr — new BarcodeAr(DataCaptureContext?, BarcodeArSettings), Feedback (get/set), ApplySettingsAsync(BarcodeArSettings) → Task, AddListener(IBarcodeArListener) / RemoveListener(IBarcodeArListener), event EventHandler<BarcodeArEventArgs> SessionUpdated, static RecommendedCameraSettings, Dispose。
• BarcodeArSettings — new BarcodeArSettings(), EnableSymbology(Symbology, bool), EnableSymbologies(ICollection<Symbology>), GetSymbologySettings(Symbology), EnabledSymbologies (get), ExpectsOnlyUniqueBarcodes (get/set), SetProperty / GetProperty<T> / TryGetProperty<T>, Dispose。
• IBarcodeArListener — 仅有一个方法：OnSessionUpdated(BarcodeAr, BarcodeArSession, IFrameData)。（没有 OnObservation* 回调。）
• BarcodeArSession — AddedTrackedBarcodes（IReadOnlyList<TrackedBarcode>）、RemovedTrackedBarcodes（IReadOnlyList<int>）、TrackedBarcodes（IReadOnlyDictionary<int, TrackedBarcode>）、Reset()。
• BarcodeArEventArgs — BarcodeAr、Session、FrameData。
• BarcodeArFeedback — new BarcodeArFeedback()（静音）、静态 DefaultFeedback（默认值）、Scanned / Tapped（Core.Common.Feedback.Feedback）、Dispose。
• BarcodeArView — static Create(UIView parentView, BarcodeAr, DataCaptureContext, BarcodeArViewSettings, CameraSettings?)、HighlightProvider（get/set IBarcodeArHighlightProvider?）、AnnotationProvider（get/set IBarcodeArAnnotationProvider?）、ShouldShowTorchControl / ShouldShowZoomControl / ShouldShowCameraSwitchControl / ShouldShowMacroModeControl（仅限 iOS）、TorchControlPosition / ZoomControlPosition / CameraSwitchControlPosition / MacroModeControlPosition（仅限 iOS）（Anchor）、Start()、Stop()、Pause()、Reset()、GetNotificationPresenter()、event EventHandler<HighlightForBarcodeTappedEventArgs> HighlightForBarcodeTapped、隐式转换为 UIKit.UIView、Dispose。iOS 上没有 OnResume() / OnPause()——这些仅适用于 Android。
• BarcodeArViewSettings — SoundEnabled（默认值为 true）、HapticEnabled（默认值为 true）、DefaultCameraPosition（默认值为 WorldFacing）。
• HighlightForBarcodeTappedEventArgs — BarcodeAr、Barcode、Highlight（IBarcodeArHighlight）。
• 高亮：IBarcodeArHighlight : IDisposable、IBarcodeArHighlightProvider.HighlightForBarcodeAsync(Barcode) → Task<IBarcodeArHighlight?>、BarcodeArRectangleHighlight(Barcode)，包含 Barcode / Brush / Icon、BarcodeArCircleHighlight(Barcode, BarcodeArCircleHighlightPreset)，包含 Barcode / Brush / Icon / Size、BarcodeArCircleHighlightPreset 枚举（Dot、Icon）。
• 注释：IBarcodeArAnnotation : IDisposable（声明 AnnotationTrigger）、IBarcodeArAnnotationProvider.AnnotationForBarcodeAsync(Barcode) → Task<IBarcodeArAnnotation?>。
  • BarcodeArStatusIconAnnotation(Barcode) — AnnotationTrigger、HasTip、Icon、Text、TextColor、BackgroundColor。
  • BarcodeArInfoAnnotation(Barcode) — HasTip、EntireAnnotationTappable、Anchor（BarcodeArInfoAnnotationAnchor）、AnnotationTrigger、Width（BarcodeArInfoAnnotationWidthPreset）、Body（IReadOnlyCollection<BarcodeArInfoAnnotationBodyComponent>）、Header（BarcodeArInfoAnnotationHeader?）、Footer（BarcodeArInfoAnnotationFooter?）、BackgroundColor、Listener（IBarcodeArInfoAnnotationListener?）。
  • BarcodeArPopoverAnnotation(Barcode, IList<BarcodeArPopoverAnnotationButton>) — AnnotationTrigger、EntirePopoverTappable、Listener（IBarcodeArPopoverAnnotationListener?）、Buttons。
  • BarcodeArPopoverAnnotationButton(ScanditIcon, string) — Text、TextSize、Typeface、TextColor、Enabled、Icon。
  • BarcodeArAnnotationTrigger 枚举：HighlightTapAndBarcodeScan、HighlightTap。
• 信息注释子包（Scandit.DataCapture.Barcode.Ar.UI.Annotations.Info）：BarcodeArInfoAnnotationBodyComponent（Text、TextColor、TextSize、Typeface、StyledTextFormatted、LeftIcon、RightIcon、LeftIconTappable、RightIconTappable、TextAlignment）、BarcodeArInfoAnnotationHeader（Text、TextSize、Typeface、TextColor、Icon、BackgroundColor）、BarcodeArInfoAnnotationFooter（Text、TextSize、Typeface、TextColor、Icon、BackgroundColor）、BarcodeArInfoAnnotationAnchor 枚举（Left、Right、Bottom、Top）、BarcodeArInfoAnnotationWidthPreset 枚举（Small、Medium、Large）、IBarcodeArInfoAnnotationListener（OnInfoAnnotationHeaderTapped、OnInfoAnnotationFooterTapped、OnInfoAnnotationLeftIconTapped、OnInfoAnnotationRightIconTapped、OnInfoAnnotationTapped）。
• IBarcodeArPopoverAnnotationListener — OnPopoverButtonTapped、OnPopoverTapped。
• TrackedBarcode（位于 Scandit.DataCapture.Barcode.Batch.Data 中）— Barcode、Identifier、Location。