Flutter+Android/ios 桌面小组件

Flutter+Android/iOS 桌面组件开发指南

核心要点：

Android和iOS桌面小组件需要原生开发绘制组件和更新数据，Flutter层可通过MethodChannel与原生通信控制数据更新。用户需手动添加/删除小组件，应用无法主动控制。
小组件支持显示文字、图片、列表、虚拟时钟、勾选框、进度条等原生视图，不支持自定义绘制的视图。
iOS负一屏支持自定义编辑添加小组件，Android原生负一屏目前仅支持新闻feed流，但国内厂商（小米、华为等）将负一屏与桌面组件整合，需要适配不同厂商系统。

开发工具推荐

在iOS开发过程中，推荐使用Appuploader这款iOS开发助手工具。它可以帮助开发者快速完成证书管理、描述文件配置和App Store上传等工作，特别适合需要频繁调试和更新小组件的开发场景。Appuploader的图形化界面让复杂的配置过程变得简单直观，大大提升了开发效率。

官方文档参考：

Android小组件：Android开发者文档
iOS小组件：Apple开发者文档
小米小部件：小米开发者平台
华为荣耀小组件：华为开发者平台

开发实践

使用Flutter插件：home_widget

插件地址：pub.dev/packages/ho...

iOS平台配置

添加Widget Extension

在Xcode中通过File > New > Target > Widget Extension添加小组件扩展
配置App Group

需要Apple开发者账号，在开发者中心创建App Group并添加到应用和小组件扩展的Signing & Capabilities中
版本同步（可选）

在Runner目标的Build Phases中添加Run Script同步版本号：

bash 复制代码

generatedPath="$SRCROOT/Flutter/Generated.xcconfig"
versionNumber=$(grep FLUTTER_BUILD_NAME "$generatedPath" | cut -d '=' -f2 | xargs)
buildNumber=$(grep FLUTTER_BUILD_NUMBER "$generatedPath" | cut -d '=' -f2 | xargs)
infoPlistPath="$SRCROOT/WidgetExtension/Info.plist"

/usr/libexec/PlistBuddy -c "Set :CFBundleVersion $buildNumber" "$infoPlistPath"
/usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $versionNumber" "$infoPlistPath"

Android平台配置

添加Jetpack Glance依赖
在app的build.gradle中添加：

gradle 复制代码

implementation 'androidx.glance:glance-appwidget:1.0.0'

创建Widget配置
在res/xml中创建widget配置：

xml 复制代码

<appwidget-provider 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:resizeMode="horizontal|vertical"
    android:updatePeriodMillis="10000">
</appwidget-provider>

功能实现

数据交互

初始化设置
iOS需要设置App Group ID：

dart 复制代码

HomeWidget.setAppGroupId('YOUR_GROUP_ID');

保存数据
使用Appuploader配置好证书后，可以更方便地测试数据共享功能：

dart 复制代码

HomeWidget.saveWidgetData<String>('key', 'value');

更新小组件
强制刷新小组件：

dart 复制代码

HomeWidget.updateWidget(
    name: 'WidgetProvider',
    androidName: 'WidgetProvider',
    iOSName: 'WidgetExtension'
);

高级功能

交互式小组件
iOS 17+和Android支持交互式元素：

dart 复制代码

@pragma("vm:entry-point")
void backgroundCallback(Uri data) {
    // 处理交互
}

HomeWidget.registerInteractivityCallback(backgroundCallback);

Flutter组件转图片
将Flutter组件渲染为图片供原生小组件使用：

dart 复制代码

var path = await HomeWidget.renderFlutterWidget(
    CustomWidget(),
    key: 'widgetPreview',
    logicalSize: Size(400, 400)
);

后台更新
结合后台任务插件实现定时更新：

dart 复制代码

Workmanager().executeTask((task, inputData) async {
    await HomeWidget.updateWidget(...);
    return true;
});

开发建议

使用Appuploader管理开发证书和描述文件，避免配置错误导致的小组件调试问题
小组件资源要轻量化，确保快速加载
测试不同尺寸的小组件布局适配
注意各平台的数据更新频率限制
合理设计用户交互路径，提升用户体验

通过合理利用Appuploader等开发工具，可以显著提升Flutter小组件的开发效率和质量。建议在开发过程中持续测试不同设备和系统版本的兼容性，确保小组件在各种环境下都能稳定运行。