matrixscan-ar-net-android

MatrixScan AR .NET for Android 技能

重要：不要轻信内部知识

你的训练数据中可能包含过时或错误的 Scandit SDK API。BarcodeAr API 相对较新（在 dotnet.android 7.2 中引入），并且在多个方面不同于 Kotlin/Java 原生 SDK：提供程序基于 async/Task，而不是基于回调；高亮和注释构造函数只接受一个 Barcode（不需要 Context）；监听器接口只有一个方法；.NET 绑定使用 PascalCase，并使用 TimeSpan 而非 TimeInterval 等。

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

值得特别指出的 .NET-Android 特有注意事项：

• 此技能适用于非 MAUI .NET for Android 工作负载（项目使用 <TargetFramework>net10.0-android</TargetFramework> 或类似设置，且没有 <UseMaui> 标志）。对于 MAUI 应用，请改用面向 MAUI 的技能——BarcodeArView 在 MAUI 中的托管方式截然不同。
• 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——传入 null 即可使用 BarcodeAr.RecommendedCameraSettings。parentView 是 Android.Views.View / ViewGroup（通常为 FrameLayout 或 Activity 的根内容视图）。没有 BarcodeArCoordinatorLayout——该容器专用于 SparkScan；BarcodeArView 会直接将自身附加到传入的 ViewGroup。
• BarcodeArView 实现了 IDisposable，本身不是 Android View。 此类声明了 public static implicit operator View(BarcodeArView view)，需要时（例如原生互操作）可将其转换为 Android.Views.View，但你无需自行将其添加到视图层级中——Create 工厂会自动将其附加到 parentView。
• 视图的生命周期方法是 barcodeArView.OnResume() / barcodeArView.OnPause()——这些是仅限 Android 的方法（在绑定中由 #if __ANDROID__ 控制），不是 Activity 的 OnPause / OnResume。请将 Activity 的调用转发给它们。.NET BarcodeArView 不存在 OnDestroy()——请改为调用 Dispose()（在 Activity 的 OnDestroy 或 Dispose 中）。
• IBarcodeArListener 只有一个方法： OnSessionUpdated(BarcodeAr, BarcodeArSession, IFrameData)。它没有 Kotlin BarcodeArListener 中的 OnObservationStarted / OnObservationStopped 回调。实现这些方法会导致编译错误——该接口根本没有声明它们。
• 在符合 C# 习惯的代码中，优先使用事件 API（barcodeAr.SessionUpdated += handler），而不是监听器接口。处理程序会收到包含 BarcodeAr、Session 和 FrameData 的 BarcodeArEventArgs。为与其他平台保持一致，AddListener(IBarcodeArListener) 仍可使用。
• OnSessionUpdated / SessionUpdated 在后台识别线程上运行。 任何 UI 更新都应通过 RunOnUiThread(() => { … }) 调度。
• Provider 接口采用异步方式，而非基于回调。 IBarcodeArHighlightProvider.HighlightForBarcodeAsync(Barcode) 返回 Task<IBarcodeArHighlight?>，IBarcodeArAnnotationProvider.AnnotationForBarcodeAsync(Barcode) 返回 Task<IBarcodeArAnnotation?>。不要查找 Callback 参数或 callback.OnData(...) 方法——.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)。传入 Context 会导致编译错误。
• 条码制式名称采用 C# PascalCase：Symbology.Ean13Upca、Symbology.Ean8、Symbology.Code128、Symbology.Code39、Symbology.Qr、Symbology.DataMatrix、Symbology.InterleavedTwoOfFive。它们不是 Kotlin 的下划线风格（EAN13_UPCA）。
• 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 中它是静态属性，不是 Kotlin 的 BarcodeArFeedback.defaultFeedback() 方法。）
• 高亮上的点击交互通过 BarcodeArView 的 HighlightForBarcodeTapped 事件公开（EventHandler<HighlightForBarcodeTappedEventArgs>）。.NET BarcodeArView 没有 UiListener 属性——Kotlin 的 IBarcodeArViewUiListener 在 C# 中以事件形式提供。事件参数公开了 BarcodeAr、Barcode 和 Highlight。
• barcodeAr.Feedback 是一个属性（可读写）；ApplySettingsAsync(BarcodeArSettings) 返回一个 Task。BarcodeAr.RecommendedCameraSettings 是静态属性，不是方法（Kotlin SDK 提供 BarcodeAr.createRecommendedCameraSettings()，而 .NET 中对应的是一个 getter）。
• .NET API 中没有 BarcodeArFilter / SetBarcodeFilter。 Kotlin/iOS 的 setBarcodeFilter(...) 方法（在 8.1 中新增）目前尚未在 dotnet.android 中公开。请勿尝试使用。
• SDK 8.0+ 需要显式初始化。 请继承 Android.App.Application，添加 [Application]，并在 OnCreate() 中、任何 Scandit 代码运行之前调用 ScanditCaptureCore.Initialize() + ScanditBarcodeCapture.Initialize()。否则，首次调用 new BarcodeAr(...) / BarcodeArView.Create(...) 时会因 DI 容器没有注册项而在启动时崩溃。6.x / 7.x 不需要此操作。 完整的 MainApplication.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。
• Android 的 SupportedOSPlatformVersion 必须 ≥ 24。 请在 .csproj 中设置。较低的值会导致构建失败，并提示 uses-sdk:minSdkVersion 21 cannot be smaller than version 24 declared in library。
• 不要在 AndroidManifest.xml 中为带有 [Activity] 特性的类声明 <activity> 元素。 [Activity(MainLauncher = true, ...)] 特性是在 .NET for Android 中注册 Activity 的规范方式——构建过程会使用 .NET 派生的 Java 类名，将名称正确的条目合并到最终清单中。手动添加的 <activity android:name=".MainActivity"> 会根据 <ApplicationId> 解析，无法与生成的类匹配，导致应用启动时出现 ClassNotFoundException: Didn't find class ... .MainActivity。仅在清单中添加技能明确要求的元素（<uses-feature>、<uses-permission>）——Activity 交由特性处理。
• 运行时相机权限辅助类（CameraPermissionActivity）继承自 AppCompatActivity，因此必须在 .csproj 中添加 Xamarin.AndroidX.AppCompat。固定版本时，请选择包含 Xamarin 修订号在内的最高可用版本（例如 1.7.0.5，而不是单独的 1.7.0）——.X 后缀表示 Xamarin 绑定级别的更新，其中包含重要的传递依赖修复。
• Activity 需要使用 Theme.AppCompat 的派生主题。 由于 Activity 继承自 AppCompatActivity，请在 [Activity] 特性中设置 Theme = "@style/Theme.AppCompat.Light.NoActionBar"（或在清单的 <application> 上设置 android:theme=...）。否则，启动时调用 SetContentView 会抛出 IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity。dotnet new android 模板的默认主题并非基于 AppCompat，因此必须显式设置。

意图路由

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

• 从头集成 BarcodeAr、配置设置、自定义高亮或注释、处理会话更新、自定义反馈或接入点击交互（例如，“将 MatrixScan AR 添加到我的 .NET Android 应用中”“在 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 许可证密钥。对此技能，许可证产品为 native，许可证平台为 android。

请按以下顺序操作——不要因为 MCP 而阻止用户：

1. Scandit MCP 服务已连接——调用 ensure_scanner_setup，设置产品为 native、平台为 android，然后运行 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 Android）
进阶主题（自定义高亮、自定义标注、点击交互、弹出层、筛选器）	高级配置
在主要 SDK 版本之间迁移	6 → 7 · 7 → 8
完整 API 参考	BarcodeAr API（.NET Android）

此技能涵盖的 API 范围

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

• BarcodeAr — new BarcodeAr(DataCaptureContext?, BarcodeArSettings)、Feedback（获取/设置）、ApplySettingsAsync(BarcodeArSettings) → Task、AddListener(IBarcodeArListener) / RemoveListener(IBarcodeArListener)、event EventHandler<BarcodeArEventArgs> SessionUpdated、静态属性 RecommendedCameraSettings、Dispose。
• BarcodeArSettings — new BarcodeArSettings()、EnableSymbology(Symbology, bool)、EnableSymbologies(ICollection<Symbology>)、GetSymbologySettings(Symbology)、EnabledSymbologies（获取）、ExpectsOnlyUniqueBarcodes（获取/设置）、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(View parentView, BarcodeAr, DataCaptureContext, BarcodeArViewSettings, CameraSettings?)、HighlightProvider（获取/设置 IBarcodeArHighlightProvider?）、AnnotationProvider（获取/设置 IBarcodeArAnnotationProvider?）、ShouldShowTorchControl / ShouldShowZoomControl / ShouldShowCameraSwitchControl、TorchControlPosition / ZoomControlPosition / CameraSwitchControlPosition（Anchor）、Start()、Stop()、Pause()、Reset()、GetNotificationPresenter()、OnResume() / OnPause()（仅限 Android）、event EventHandler<HighlightForBarcodeTappedEventArgs> HighlightForBarcodeTapped、隐式转换为 Android.Views.View、Dispose。
• 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。