【译】 如何使用 .NET MAUI 构建 Android 小部件

▲点击上方“DotNet NB”关注公众号回复“1”获取开发者路线图学习分享丨作者 / 郑 子 铭这是DotNet NB 公众号的第239篇原创文章原文 | Toine de Boer翻译 | 郑子铭这是Toine de Boer的客座博文。这篇博客将探讨上一篇关于iOS 小部件的博客中创建的交互式小部件的 Android 版本。Android 通常限制较少也更容易上手您可以在 Visual Studio 的 .NET MAUI 项目中直接构建所有内容。其复杂性在于完成任务的选项众多以及需要考虑较旧的 Android 版本。与 iOS 小部件博客一样本文并非循序渐进的教程。相反它将按照构建 Android 小部件时通常会遇到的障碍顺序重点介绍最重要、最关键的部分。文章从创建一个简单的静态小部件开始逐步构建一个可配置、完全交互式的小部件。GitHub 上有一个完整的小部件示例Maui.WidgetExample。先决条件对于 Android 小部件来说并没有什么真正的先决条件。虽然 .NET MAUI 没有适用于 Android 小部件的组件但我们可以使用原生 Android 方法自行构建。好处是所有操作都可以在 Visual Studio 中完成当然您也可以选择使用 Android Studio 及其可视化编辑器和预览工具来设计布局。由于我过去曾大量使用过 Android XML 布局并且本博客侧重于功能而非外观因此我将在 Copilot 的辅助下手动创建 XML 布局。如果我想要更精致的界面我会切换到 Android Studio用 XML 创建布局。具体操作是创建一个虚拟的 Android 项目添加一个组件例如通过“文件”“新建”“组件”然后开始设计 XML 布局。这样可以充分利用实时预览工具和属性面板查看并编辑每个视图的所有可用选项。当您将 Android 特有的资源文件按照类似于原生 Android 应用的文件夹结构进行组织时.NET MAUI 可以很好地处理这些资源文件./Platforms/Resources。因此创建小部件无需对项目文件进行任何更改.csproj——项目文件保持不变。我通常在 Visual Studio 之外创建或复制文件和文件夹以防止 Visual Studio 修改项目文件.csproj。对于 iOS 小部件我已经创建了一个 .NET MAUI 项目来演示如何与小部件通信我将在 Android 中复用该项目。大部分现有代码保持不变。所有新增的 Android 小部件代码都将放在相应的./Platforms/Android文件夹中。创建小部件Android 小部件并非像应用中的普通视图但它们确实存在于 .NET MAUI 应用中。小部件仅限于 RemoteViews 提供的 Android 视图集不支持自定义视图。您仍然可以对它们进行相当不错的样式设置但需要巧妙地运用形状、矢量图形和其他可绘制对象。Android 小部件的起点是divAppWidgetProvider。它可以使用div根据 ID 为小部件AppWidgetManager提供视图。Android使用div来显示来自其他进程的视图它们使用与普通 Android 视图相同的 XML 布局样式但它们被加载到一个div对象中。RemoteViewsRemoteViewsRemoteViews[BroadcastReceiver(Label My Widget)] [MetaData(AppWidgetManager.MetaDataAppwidgetProvider, Resource xml/mywidget_provider_info)] publicclassMyWidgetProvider : AppWidgetProvider { publicoverridevoidOnUpdate(Context? context, AppWidgetManager? appWidgetManager, int[]? appWidgetIds) { if (context null || appWidgetIds null || appWidgetManager null) { return; } foreach (var appWidgetId in appWidgetIds) { var views new RemoteViews(context.PackageName, Resource.Layout.mywidget); views.SetTextViewText(Resource.Id.widgetText, Count:5 (static)); appWidgetManager.UpdateAppWidget(appWidgetId, views); } } }该功能AppWidgetProvider依赖于位于文件夹中的配置文件并通过字段中的属性Resources/xml引用该文件。此文件允许您配置小部件设置例如预览图像、尺寸、调整大小限制和功能。MetaDataResource!-- Resources/xml/mywidget_provider_info.xml -- ?xml version1.0 encodingutf-8? appwidget-providerxmlns:androidhttp://schemas.android.com/apk/res/android android:minWidth120dp android:minHeight80dp android:maxResizeWidth140dp android:updatePeriodMillis0 android:initialLayoutlayout/mywidget android:resizeModehorizontal|vertical android:widgetCategoryhome_screen android:configurewidgetexample.WidgetConfigurationActivity android:widgetFeaturesreconfigurable android:previewImagedrawable/mywidget_preview_image /其中最重要的条目之一是android:initialLayout它指的是位于中的视图布局Resources/layout。此布局被加载到中RemoteView!-- Resources/layout/mywidget.xml -- ?xml version1.0 encodingutf-8? LinearLayout xmlns:androidhttp://schemas.android.com/apk/res/android android:orientationhorizontal android:layout_widthmatch_parent android:layout_heightwrap_content TextView android:idid/widgetText android:textStatic widget android:textSize16sp android:layout_widthwrap_content android:layout_heightwrap_content / /LinearLayout与普通 Android 视图的一个主要区别RemoteView在于您无法直接从代码中操作视图。每个视图仅允许更新有限的属性集所有更改都必须通过RemoteViews对象及其辅助方法进行。例如您可以传入要更新的视图的资源 IDviews.SetTextViewText(Resource.Id.widgetText, Hello World);此时您可以构建应用程序并且应该可以在手机的小部件库中看到该小部件。应用与小部件之间的数据共享在 Android 系统中应用和组件之间的数据共享比 iOS 系统更简单因为组件内部可以使用 C# .NET MAUI 代码。虽然由于生命周期问题这种方式可能不太可靠但您甚至可以在一定程度上在组件和应用之间共享内存数据。因此我们建议采用持久化存储方案。由于我们已经为 iOS 组件设置了共享数据存储SharedPreferences为了确保跨平台一致性我们在 Android 系统上继续沿用现有的机制。// example how to store data in .NET MAUI (Preferences) Preferences.Set(MyDataKey, my data to share, group.com.enbyin.WidgetExample); // example how to store data on Android, on the same location (SharedPreferences) var preferences context.GetSharedPreferences(group.com.enbyin.WidgetExample, Context.MODE_PRIVATE); var value preferences.GetString(MyDataKey, null);笔记存储键区分大小写请保持键名简洁且全部小写以避免出现问题。应用与小部件之间的通信与 iOS 类似Android 小部件无法感知应用何时更新数据应用也无法自动感知小部件何时更新数据。在 Android 系统中应用和小部件之间有多种通信方式你甚至可以在应用运行时更新小部件视图。最可靠的机制是使用Intents……原理很简单创建一个对象Intent并为其指定一个操作字符串。Intent然后可以在需要时广播该对象例如在后台进程完成后或用户按下控件上的按钮时。// Broadcast an Intent with action ‘ActionAppwidgetUpdate’ var intent new Android.Content.Intent(AppWidgetManager.ActionAppwidgetUpdate); Android.App.Application.Context.SendBroadcast(intent);需要接收操作的组件Intent声明相同的操作字符串。在 .NET MAUI 中Intent使用Occeptable属性可以轻松订阅操作[IntentFilter]。如果组件需要Intent从其自身应用程序外部接收操作则需要设置OcceptableExported true属性。控件需要这样做因为它们实际上存在于应用程序之外。// Subscribing your AppWidgetProvider to listen to Intents [BroadcastReceiver(Label My Widget, Exported true)] [IntentFilter(new[] { AppWidgetManager.ActionAppwidgetUpdate })] [MetaData(AppWidgetManager.MetaDataAppwidgetProvider, Resource xml/mywidget_provider_info)] publicclassMyWidgetProvider : AppWidgetProvider { publicoverridevoidOnReceive(Context? context, Intent? intent) { var myIntent Intent; // ... } }// Subscribing a Service to listen to Intents [Service(Exported true)] [IntentFilter(new[] { AppWidgetManager.ActionAppwidgetUpdate })] publicclassWidgetListenerService : Service { publicoverride StartCommandResult OnStartCommand(Intent intent, StartCommandFlags flags, int startId) { var myIntent intent; return StartCommandResult.NotSticky; } }// Subscribing an Activity to listen to Intents [IntentFilter(new[] { Intent.ActionView })] publicclassMyActivity : Activity { protectedoverridevoidOnCreate(Bundle savedInstanceState) { base.OnCreate(savedInstanceState); var myIntent Intent; } }手动刷新小部件AppWidgetProvider默认情况下该组件会监听Intent带有内置操作的事件AppWidgetManager.ActionAppwidgetUpdate。当Intent收到此类事件时通常会触发组件刷新。您可以通过将事件作用域限定Intent在您的包中并包含特定的组件 ID 来限制哪些组件响应。// Refreshing all Widgets of a specific AppWidgetProvider public staticvoid RefreshWidget(Context context) { var appWidgetManager AppWidgetManager.GetInstance(context); var componentName new ComponentName(context, Java.Lang.Class.FromType(typeof(MyWidgetProvider))); var appWidgetIds appWidgetManager?.GetAppWidgetIds(componentName); var intent new Intent(AppWidgetManager.ActionAppwidgetUpdate); intent.SetPackage(context.PackageName); intent.PutExtra(AppWidgetManager.ExtraAppwidgetIds, appWidgetIds); context.SendBroadcast(intent); }// Handling incoming Intent on an AppWidgetProvider [BroadcastReceiver(Label My Widget, Exported true)] [IntentFilter(new[]{ AppWidgetManager.ActionAppwidgetUpdate})] [MetaData(AppWidgetManager.MetaDataAppwidgetProvider, Resource xml/mywidget_provider_info)] publicclassMyWidgetProvider : AppWidgetProvider { publicoverridevoidOnUpdate(Context? context, AppWidgetManager? appWidgetManager, int[]? appWidgetIds) { if (context null || appWidgetManager null || appWidgetIds null) { return; } foreach (var appWidgetId in appWidgetIds) { var views BuildRemoteViews(context, appWidgetId); appWidgetManager.UpdateAppWidget(appWidgetId, views); } } publicoverridevoidOnReceive(Context? context, Intent? intent) { base.OnReceive(context, intent); } }按计划刷新小部件Android 提供了多种安排小部件更新的方法这些方法可以结合使用updatePeriodMillis设置在appwidget-providerXML 配置文件中定义。最简单的选项是使用固定的更新间隔最短 30 分钟。AlarmManager能够重复广播警报Intent最小间隔约为 60 秒可能受到限制。设备重启后警报不会恢复。WorkManager可靠性高设备重启后仍能正常工作支持多种配置选项。最小重复间隔为15分钟。使小部件具有交互性小部件允许用户执行一些简单的操作例如按下按钮。这些操作通过Intent事件触发并且必须用div标签包裹PendingIntent以便在小部件及其视图创建很久之后仍然可以执行。PendingIntent事件是可重用的请保持其requestCode唯一性以避免覆盖它们。// Attach Intent to the increment button var incrementIntent new Intent(context, typeof(MyWidgetProvider)); incrementIntent.SetAction(com.enbyin.WidgetExample.INCREMENT_COUNTER); var incrementPendingIntent PendingIntent.GetBroadcast( context, 101, incrementIntent, PendingIntentFlags.UpdateCurrent | (Build.VERSION.SdkInt BuildVersionCodes.S ? PendingIntentFlags.Mutable : 0) ); views.SetOnClickPendingIntent(Resource.Id.widgetIncrementButton, incrementPendingIntent);通过监听自定义操作来处理按钮交互AppWidgetProvider[BroadcastReceiver(Label My Widget, Exported true)] [IntentFilter(new[] { AppWidgetManager.ActionAppwidgetUpdate, com.enbyin.WidgetExample.INCREMENT_COUNTER })] [MetaData(AppWidgetManager.MetaDataAppwidgetProvider, Resource xml/mywidget_provider_info)] publicclassMyWidgetProvider : AppWidgetProvider { publicoverridevoidOnReceive(Context? context, Intent? intent) { if (intent null || context null) { base.OnReceive(context, intent); return; } switch (intent.Action) { casecom.enbyin.WidgetExample.INCREMENT_COUNTER: { var currentCount Preferences.Get(MainPage.SharedStorageAppIncomingDataKey, 0); currentCount; Preferences.Set(MainPage.SharedStorageAppIncomingDataKey, currentCount); UpdateAllWidgets(context); return; } } base.OnReceive(context, intent); } }从组件到应用程序的通信所有触发器、数据传输以及其他与小部件之间的通信都通过消息流 (S) 处理Intent。诸如 BroadcastReceiver、Service、AppWidgetProvider 和 Activity 之类的组件可以指定Intent它们监听的消息流类型也可以广播任何消息流Intent供其他组件接收。以下简要概述了数据流展示了这些组件如何通过Intent消息流进行通信以管理交互式小部件。您还可以使用 ActivityIntent来启动您的应用。无需Intent在后台广播 Activity而是Activity使用onBroadcast直接将其发送到 Activity PendingIntent.GetActivity()。与任何 Activity 一样Intent您可以向 Activity 附加数据。使用 Activity 启动应用时一种常见的方法是使用深度链接URL将结构化数据传递到应用中。然后您可以在onBroadcast用于冷启动或onBroadcast当 Activity 已运行时Intent中检索传入的数据。OnCreate()OnNewIntent()// Example of making a PendingIntent using Deep Link / URL var openAppIntent newIntent(Intent.ActionView); openAppIntent.SetData(global::Android.Net.Uri.Parse(${App.UrlScheme}://{App.UrlHost}?counter{currentCount})); openAppIntent.SetFlags(ActivityFlags.NewTask | ActivityFlags.ClearTop); var openAppPendingIntent PendingIntent.GetActivity( context, 103, openAppIntent, PendingIntentFlags.UpdateCurrent | (Build.VERSION.SdkInt BuildVersionCodes.S ? PendingIntentFlags.Immutable : 0) ); views.SetOnClickPendingIntent(Resource.Id.widgetText, openAppPendingIntent);[Activity] [IntentFilter(new[] { Intent.ActionView }, Categories new[] { Intent.CategoryDefault, Intent.CategoryBrowsable }, DataScheme App.UrlScheme, DataHost App.UrlHost)] publicclassMainActivity : MauiAppCompatActivity { protectedoverridevoidOnCreate(Bundle? savedInstanceState) { base.OnCreate(savedInstanceState); HandleIntent(Intent); } protectedoverridevoidOnNewIntent(Intent? intent) { base.OnNewIntent(intent); HandleIntent(intent); } privatestaticvoidHandleIntent(Intent? intent) { if (intent?.Data ! null) { var url intent.Data.ToString(); // handle the URL as needed } } }与 iOS 小部件相比Android 小部件可以直接访问 C# 组件。IServiceProvider由于MauiProgram.CreateMauiApp()其调用方式与在应用程序中完全相同因此也同样可用。请将小部件视为独立于应用程序之外的组件将业务逻辑放在小部件之外AppWidgetProvider。如果您希望小部件Intent首先通过AppWidgetProviderC# 组件进行 UI 更新请Intent从 C# 组件触发一个新的 C# 事件并将其广播到应用程序以执行业务逻辑。publicoverridevoidOnReceive(Context? context, Intent? intent) { if (intent null || context null) { base.OnReceive(context, intent); return; } switch (intent.Action) { casecom.enbyin.WidgetExample.INCREMENT_COUNTER: { var currentCount Preferences.Get(MainPage.SharedStorageAppIncomingDataKey, 0); currentCount; // Send silent trigger to app for background work var silentIntent new Intent(context, typeof(WidgetSilentReceiver)); silentIntent.SetAction(WidgetToAppSilentIntentAction); silentIntent.PutExtra(WidgetToAppSilentExtraValueField, currentCount); silentIntent.SetPackage(context.PackageName); context.SendBroadcast(silentIntent); UpdateAllWidgets(context); return; } } base.OnReceive(context, intent); }当您需要响应事件执行短暂操作时Intent标准接收器BroadcastReceiver非常适用。接收器只能短暂运行之后会被 Android 系统自动停止。如果您需要更多时间请使用后台接收器Service。[BroadcastReceiver(Exported true)] [IntentFilter([ MyWidgetProvider.WidgetToAppSilentIntentAction ])] publicclassWidgetSilentReceiver : BroadcastReceiver { publicoverridevoidOnReceive(Context? context, Intent? intent) { if (context null || intent null || intent.Action ! MyWidgetProvider.WidgetToAppSilentIntentAction) { return; } var counterValue intent.GetIntExtra(MyWidgetProvider.WidgetToAppSilentExtraValueField, int.MinValue); if (counterValue ! int.MinValue) { Preferences.Set(MainPage.SharedStorageAppIncomingDataKey, counterValue); } MainPage.RefreshWidget(); } }创建可配置的小部件在小部件配置文件中可以指定一个Activity作为小部件的用户配置屏幕。这样的小部件配置活动应该是一个小型活动能够立即保存配置更改。关闭此屏幕后小部件将自动更新一次。!-- Resources/xml/mywidget_provider_info.xml -- ?xml version1.0 encodingutf-8 ? appwidget-provider xmlns:androidhttp://schemas.android.com/apk/res/android android:widgetFeaturesreconfigurable android:configurewidgetexample.WidgetConfigurationActivity !-- other widget settings -- /appwidget-provider该字段android:configure必须引用其Activity自身Name指定的值Activity。请注意该Name值。[Activity(Label Configure Widget, Exported true, Name widgetexample.WidgetConfigurationActivity, Theme android:style/Theme.Material.Light.Dialog, ConfigurationChanges ConfigChanges.UiMode)] [IntentFilter([AppWidgetManager.ActionAppwidgetConfigure])] publicclassWidgetConfigurationActivity : Activity { protectedoverridevoidOnCreate(Bundle? savedInstanceState) { base.OnCreate(savedInstanceState); SetResult(Result.Canceled); var extras Intent?.Extras; if (extras ! null) { _appWidgetId extras.GetInt(AppWidgetManager.ExtraAppwidgetId, AppWidgetManager.InvalidAppwidgetId); } // Build the configuration View // The views used are NOT special widget views, so you can use event handlers // to store configuration changes SetContentView(layout); } }配置活动是一个标准的 Android 活动Activity这意味着它使用常规的 Android 视图而不是RemoteView。您可以使用完整的 .NET MAUI 框架构建这些屏幕但为了这篇博客我使用了基本的 XML 布局和一个标准的非 .NET MAUI Activity。利用上下文关键在于使用正确的 Android 上下文Context。虽然总是使用容易访问的上下文很诱人Android.App.Application.Context但在使用小部件时这个上下文在很多情况下可能为空。当小部件触发后台服务时这一点尤为重要因为使用错误的上下文可能会导致服务静默崩溃。请使用 Android 提供给后台服务的上下文如果该上下文不可用至少要检查是否Platform.CurrentActivity可访问。性能考量每个 Android 应用只能有一个Application实例。WidgetsAppWidgetProviders和 BroadcastReceiver 会自动在应用所在的同一应用程序内运行。使用它们会加载整个 .NET MAUI 堆栈包括对AppWidgetProviders的调用MauiProgram.CreateMauiApp()。这可能会导致几秒钟的初始延迟例如当首次按下小部件按钮时。您可以通过避免不必要的 UI 相关工作来减少这种延迟。一个简单的方法是创建一个最小化的 .NET MAUI 应用程序版本该版本仅初始化小部件所需的基本要素。例如publicstaticclassMauiProgram { publicstatic MauiApp CreateMauiApp() { var builder MauiApp.CreateBuilder(); builder .UseMauiAppApp() .ConfigureFonts(fonts { fonts.AddFont(OpenSans-Regular.ttf, OpenSansRegular); fonts.AddFont(OpenSans-Semibold.ttf, OpenSansSemibold); }); #if DEBUG builder.Logging.AddDebug(); #endif return builder.Build(); } publicstatic MauiApp CreateMinimalMauiApp() { var builder MauiApp.CreateBuilder(); builder.UseMauiAppApp(); return builder.Build(); } }为了充分利用最小化设置的优势需要检测应用程序是作为小部件启动还是作为完整应用程序启动。在 Android 系统中MauiApplication这可以通过检查ProcessInfo当前正在运行的应用程序进程来实现。[Application] publicclassMainApplication : MauiApplication { publicMainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership) { } protectedoverride MauiApp CreateMauiApp() { bool isBackgroundOnly IsBackgroundExecution(); return isBackgroundOnly ? MauiProgram.CreateMinimalMauiApp() : MauiProgram.CreateMauiApp(); } privateboolIsBackgroundExecution() { try { var activityManager (ActivityManager?)GetSystemService(ActivityService); if (activityManager null) { returnfalse; } var runningAppProcesses activityManager.RunningAppProcesses; if (runningAppProcesses null) { returnfalse; } foreach (var processInfo in runningAppProcesses) { if (processInfo.Pid Process.MyPid()) { bool isBackground (int)processInfo.Importance (int)Importance.Visible; return isBackground; } } } catch { // ignore errors and assume foreground } returnfalse; } }在 iOS 上您可以采用类似的方法AppDelegate检查应用程序是否因静默推送通知而启动如果是则初始化一个最小的 .NET MAUI 应用程序。笔记Process :widget_process在 Android 上您可以使用属性在单独的进程中运行小部件BroadcastReceiver但这会绕过 .NET MAUI 框架从而阻止访问共享首选项和其他基本内容。最后想说的话与 iOS 小部件不同Android 小部件提供了更多选项并允许直接访问您的 C# 代码。因此请谨慎对待并实现一个能够在各种设备上可靠运行的解决方案尤其是在跨平台场景下。一些 Android 设备制造商会限制或更改小部件的使用体验本文主要讨论标准的 Android 小部件。最后还有几点建议在新版 Android 设备和至少一台运行最低支持版本的设备上测试您的组件。始终使用 AndroidContext提供的AppWidgetProvider上下文BroadcastReceiver服务应使用自己的上下文。避免使用过于复杂的 UI 结构来构建控件优先选择简单的布局而不是基于适配器的视图以防止闪烁。原文链接How to Build Android Widgets with .NET MAUI推荐阅读【译】 GitHub Copilot Testing for .NET 将 AI 驱动的单元测试引入 Visual Studio 2026Maomi.MQ 功能强大的 .NET RabbitMQ 消息队列通讯模型框架来了推荐一个开源的 .NET 工作流引擎和审批流项目推荐一个基于 .NET 10 开源的 RBAC权限体系的通用后台管理系统推荐一个基于 .NET 开发的功能强大的权限可视化流程管理系统YY-Admin 一个基于 WPF 的现代后端管理系统通用框架点击下方卡片关注DotNet NB一起交流学习▲点击上方卡片关注DotNet NB一起交流学习请在公众号后台回复【路线图】获取.NET 2024开发者路线回复【原创内容】获取公众号原创内容回复【峰会视频】获取.NET Conf大会视频回复【个人简介】获取作者个人简介回复【年终总结】获取作者年终回顾回复【加群】加入DotNet NB 交流学习群长按识别下方二维码或点击阅读原文。和我一起交流学习分享心得。