SuperAPI AI 工具集

avalonia-mobile

编程与开发

查看项目

更新于 11-03 17:15

技能介绍

用途

该技能用于在构建或修复 Avalonia 应用的 Android 或 iOS(以及 Mac Catalyst)端时提供指导,重点是“应用层”问题:项目头部结构、启动入口、生命周期、平台 UI 适配等。打包、签名以及 APK/IPA 发布不属于本技能范围,应参考 avalonia-deployment;版本标签说明参考 avalonia-versions。

版本与目标框架

  • 11.x:使用 net*-android / net*-ios(pre-net10)目标框架。
  • 12.0 / 12.1:需要 net10.0-android / net10.0-ios(要求 net10.0)。
  • Mac Catalyst:11.x 不支持;12.0+ 通过 Avalonia.iOS 包使用 net10.0-maccatalyst。
  • 包:Android 使用 Avalonia.Android,iOS 使用 Avalonia.iOS,包版本必须与核心 Avalonia 版本一致。

标准解决方案布局来自 avalonia-dotnet-templates 的 xplat 模板:共享 App 项目 + *.Android 头项目 + *.iOS 头项目(以及 Desktop/Browser)。模板默认值:Android SupportedOSPlatformVersion 23,iOS 13.0,并引用 AndroidX SplashScreen 包。

Android 启动

12.0+ 采用 Application 类加 Activity 的结构:初始化从 activity 移到 [Application] 标记的 AvaloniaAndroidApplication<TApp> 子类中,在 CustomizeAppBuilder 中做 builder 定制;MainActivity 为非泛型 AvaloniaMainActivity。App.axaml.cs 中使用 IActivityApplicationLifetime 的 MainViewFactory(Func<Control>)设置主视图;Android 不再使用 ISingleViewApplicationLifetime,该分支保留给 iOS/Browser。MainViewFactory 每个 activity 实例调用一次,应使用工厂创建新视图而不是共享实例。

11.x 使用泛型 AvaloniaMainActivity<TApp>,在 activity 中重写 CustomizeAppBuilder,并在 App 中通过 ISingleViewApplicationLifetime.MainView 设置视图。

一个进程内可能有多个主 activity 实例(通知点击、从其他应用返回)。12.0 起后续 activity 可使用项目的 Application 类。在 Android 12 上不要设置 ISingleViewApplicationLifetime.MainView,否则第二个 activity 会显示空白。额外(非主)activity 继承 AvaloniaActivity 并设置 Content;AvaloniaActivity 还提供 ActivityResult、RequestPermissionsResult、BackRequested 事件以及 OnBackPressed()/OnBackInvoked()。

渲染模式

在 Android 的 CustomizeAppBuilder 中通过 AndroidPlatformOptions 设置 RenderingMode 数组,可选 Egl(默认 GPU)、Vulkan、Software。第一个成功初始化的模式生效;空列表或全部失败会抛 InvalidOperationException,建议保留 Software 作为回退。iOS 在 AppDelegate 的 CustomizeAppBuilder 中通过 iOSPlatformOptions 设置 RenderingMode(如 Metal、OpenGl),并可设置 EnableHighRefreshRate。

iOS / Mac Catalyst 启动

iOS 使用 AvaloniaAppDelegate<App> 子类和 CustomizeAppBuilder,主视图通过 ISingleViewApplicationLifetime.MainView 设置(所有版本一致)。12.0+ 使用场景(scene)生命周期,scene delegate 由框架内部管理,大多数应用无需改动;AvaloniaAppDelegate.Window 在启动后为 null,若需访问 UIWindow 可重写 AvaloniaView.MovedToWindow。Mac Catalyst 12.0+ 的 TargetFrameworks 中包含 net10.0-maccatalyst,需安装 maccatalyst workload 并以对应框架运行。嵌入场景可使用 Avalonia.iOS.AvaloniaView(UIKit 视图)和 Avalonia.Android.AvaloniaView。

安全区域与边到边

通过 TopLevel.GetTopLevel(...)?.InsetsManager 获取 IInsetsManager:DisplayEdgeToEdgePreference 请求边到边显示(替代已移除的 DisplayEdgeToEdge),DisplaysEdgeToEdge 反映实际状态,SafeAreaPadding 和 SafeAreaChanged 提供安全区域内边距及变更事件,IsSystemBarVisible 和 SystemBarColor 控制系统栏。TopLevel 上还有附加属性 SystemBarColor 及 GetAutoSafeAreaPadding/SetAutoSafeAreaPadding。开启边到边后应对根布局应用 SafeAreaPadding(或在 SafeAreaChanged 中重新应用),避免内容被刘海或 Home 指示条遮挡。

软键盘

通过 TopLevel.InputPane 获取 IInputPane,订阅 StateChanged,根据 e.NewState(Open/Closed)和 e.EndRect 调整底部占位或滚动,OccludedRect 给出当前键盘区域。Closed 也表示键盘浮动/覆盖且不计入 insets。12 中 TextInputMethodClient.ShowInputPanel 已移除,客户端改为触发 InputPaneActivationRequested,由平台决定是否显示;不要自行调用显示方法,聚焦 TextBox 即可。

返回键与方向

TopLevel.BackRequested 事件响应物理返回键或返回导航请求,可设置 e.Handled 阻止默认行为。Android 12.0+ 中 AvaloniaActivity 另有 BackRequested(AndroidBackRequestedEventArgs 含 Handled)及 OnBackPressed()/OnBackInvoked()。处理后应设置 Handled = true,否则应用会退出而不是返回。

方向:Android 可在 activity 上通过 ScreenOrientation 锁定,并保留 ConfigurationChanges = Orientation | ScreenSize | UiMode 以避免旋转重建;iOS 在 Info.plist 的 UISupportedInterfaceOrientations 中设置。运行时可通过 TopLevel.Screens?.Primary?.CurrentOrientation 读取,并响应布局尺寸变化。

生命周期

通过 Application.Current?.TryGetFeature<IActivatableLifetime>() 获取生命周期,订阅 Activated/Deactivated,依据 ActivationKind(Background、File、OpenUri、Reopen)处理事件;12 中替代了已移除的 IActivatableApplicationLifetime / IApplicationPlatformEvents,11.x 使用 (ApplicationLifetime as IActivatableApplicationLifetime)。应在 Deactivated(进入后台)时保存状态,因为移动系统可能直接终止进程。Android 可通过 activity 上的 IntentFilter 注册文件/URI 意图;iOS 的协议/通用链接以 ProtocolActivatedEventArgs(Kind == OpenUri)传递。

反馈、主题与触摸

PlatformFeedback(12.1+)用于触觉与声音:通过 SetFeedbackType 让控件加入(自定义控件默认为 None,可选 None/Auto/Sound/Haptic),调用 PerformFeedback(FeedbackAction.Click/Hold),也可在 XAML 中用 PlatformFeedback.FeedbackType 设置。12.0/11.x 不可用。

系统主题:12.1 起 Android 可在运行时检测系统深浅主题变化,此前版本仅启动时读取。应保持 RequestedThemeVariant = Default 以跟随系统,并处理 activity 的 ConfigChanges.UiMode。

触摸输入:12.0+ 中触摸/笔的选中与聚焦发生在指针释放时而非按下;ListBoxItem/TreeViewItem 自行处理选中。手势事件(如 Pinch)直接位于 InputElement 上,XAML 中无需 Gestures 前缀。触摸场景下 :pointerover 样式无意义,应使用 :pressed。点击目标建议至少约 44x44 dp。

存储、权限与启动器

使用 TopLevel.StorageProvider.OpenFilePickerAsync 选择文件,并通过 OpenReadAsync/OpenWriteAsync 流式读写;移动端文件路径不可靠,不要使用 LocalPath。使用 TopLevel.Launcher.LaunchUriAsync 打开 URI。Android 运行时权限需在 AndroidManifest.xml 声明,并通过 Android API 请求,AvaloniaActivity 的 RequestPermissionsResult/ActivityResult 回调可接收结果,另有 IActivityResultHandler。iOS 需在 Info.plist 添加用途描述(如 NSCameraUsageDescription)。

页面导航

12.0 新增 Page、ContentPage、DrawerPage、CarouselPage 等移动风格导航页面,页面生命周期事件在过渡完成后触发;11.x 不支持,需使用 ContentControl + ViewModel 导航。可将 TopLevel.BackRequested 与页面栈连接,模板可生成基于页面的主视图。

常见错误

包括:Android 12.x 误用泛型 AvaloniaMainActivity<TApp> 或 ISingleViewApplicationLifetime;在 activity 上重写 CustomizeAppBuilder(12.x 已移除);AvaloniaAndroidApplication<TApp> 子类缺少 [Application] 特性;目标框架错误;使用已移除 API;开启边到边后未应用安全区域;键盘遮挡输入框;过早访问 InsetsManager/InputPane;返回处理未设置 Handled;在 12.0 使用 PlatformFeedback;假设触摸按下即选中;使用选择器返回的文件路径;移除 ConfigChanges 导致旋转/主题变化时重建;在 iOS 12 读取 AvaloniaAppDelegate.Window。