.NET MAUI 接入 iOS Widget：原生扩展 + MAUI 宿主的工程实践

如果你是一个 .NET MAUI 开发者，想给自己的 iOS 应用补上一个主屏幕小部件，你很快会发现一个让人难受的事实：Visual Studio 的新建项目面板里找不到 iOS Widget 模板，dotnet new 同样没有现成的 MAUI Widget 模板。这并不代表这件事做不了，而是说它需要一种更务实的姿态：iOS 小部件是 WidgetKit 的地盘，而 WidgetKit 只能以原生扩展的形式跑在苹果的独立进程里；.NET MAUI 负责的是 App 本体的业务逻辑、界面和数据存储。平时我们说的“用 .NET MAUI 构建 iOS 小部件”，真正拆开来看，目标是：把原生 Widget Extension 和 MAUI 宿主应用装进同一个 App 安装包，并把两边的数据链路填平。这篇文章就是按这条真实可行的路线来拆解，适合已经跑通过一个 MAUI iOS 应用、想在应用列表上加小部件入口的开发者阅读。

1. 先想清楚：“用 MAUI 做 iOS 小部件”到底指什么

1.1 主屏幕小部件的真实面目

苹果在 iOS 14 推出的主屏幕 Widget，不是过去那种可以随便放控件、随便跑逻辑的桌面挂件。它的运行机制非常克制：Widget 渲染在系统进程管理的“时间线”上，展示内容由 WidgetKit 根据你提供的 Timeline 数据生成。换句话说，Widget 不是 App 的某个页面缩小了挤进主屏幕，而是独立的“只读展示单元”。

这种设计的原因很简单：主屏幕是系统最容易卡顿和耗电的地方之一。苹果不希望每一个 Widget 背后都常驻一个完整 App。所以在 iOS 的架构里，Widget 是以 App Extension 形式存在的，名字后缀是 .appex，被单独签名、单独运行，也不能随便访问主 App 的沙盒目录。开发语言目前看是完全绑定 SwiftUI 的，Widget 的 View 必须写 SwiftUI，不能塞一个 UIView，也不能直接放 MAUI 控件。

这一点很多人一开始会踩坑。他们以为可以用 MAUI 的 ContentView 画一个小卡片，然后直接把 UI 渲染进 Widget。现实是，Widget 无法继承主 App 的 UI 渲染栈，你不可能在小部件里启动 MAUI 的 Application，也不可能在扩展进程里加载 XAML。WidgetKit 从设计上就只认 SwiftUI 描述。这意味着“用 MAUI 写 Widget UI”这条路目前并不存在。

1.2 MAUI 自身能承担和不能承担的

先看清边界，后面做工程才不会白费力气。

MAUI 在这类需求里能承担的部分包括：作为宿主 App，负责鉴权、拉数据、让用户设置内容；在用户操作后，把最新状态写入 App Group 共享容器；甚至通过远程推送驱动的 WidgetCenter 重载逻辑间接刷新 Widget。从 iOS 13 开始系统支持 URL Scheme，到了 iOS 14 Widget 也能通过 widgetURL 把点击事件带回 App，所以宿主内的跳转也可以完全交由 MAUI 的 OpenUrl 处理。

MAUI 不能承担的部分则很明确：小部件本身的扩展 Target、Widget 的 SwiftUI 视图、Timeline 的生成策略。目前你只能在 Xcode 里新建 Widget Extension，用 Swift 写 UI 渲染，然后把编译好的 .appex 嵌进 MAUI 生成的 .app 包里。

这里我多说一句：如果你搜到一些号称“纯 MAUI 写 Widget”的 NuGet 包，要警惕它们的真实程度。有的包是在 MAUI 层封装了“日历、提醒事项”之类的系统视图来实现显示，不是真正的主屏幕 Widget；有的包只是把 Swift 生成的代码做成绑定库，并没有绕开 SwiftUI。真正的 iOS Widget，从系统角度看必须是一个原生 WidgetKit Extension。

1.3 当前最值得采用的工程路线

既然 Widget 必须原生，那我们能选择的就是“原生扩展 + MAUI 宿主”的组合。具体分两条落地方案，我分别说。

第一种是“Xcode 负责扩展、MAUI 负责宿主”的工程分离。你维护两个仓库：WidgetExtension 用 Xcode 单独管理，主 App 用 Visual Studio 跑 MAUI。最终产物把 .appex 拷到 MAUI App 的 PlugIns 目录下，手动签好名再发布。优点是两个工程互不干扰，调试 Widget UI 很方便；缺点是多了一个工程，CI 流程要处理两套构建。

第二种是“扩展嵌入 MAUI 单工程”。你把 Widget Extension 的 Xcode 工程放在 MAUI 解决方案里，通过自定义 MSBuild Target 在 MAUI 构建结束后，把 .appex 复制进 App Bundle。这样开发者可以只点一下 Visual Studio 的 Run，出的是带 Widget 的完整 App。缺点是需要折腾签名顺序，否则真机会出现“Extension 无效”的安装报错。

以我接触过的项目来说，团队规模小、Widget 复杂度不高的时候，第二条最省心，只要把签名脚本维护稳定，后续迭代非常快。下面的实操我会以这条路线为主展开。

2. 动手前必须理解的三个底层机制：Timeline、App Group、交互入口

2.1 Timeline Provider 是怎么决定 Widget 内容的

Widget 不是“页面随时刷新”的模式，它使用时间线模型。你在 Widget Extension 里要实现一个 TimelineProvider，只要数据更新了、时间到了，系统就来向你的 Provider 询问未来某段时间内要显示什么。Provider 会返回一个 Timeline，里面塞一个或多个 TimelineEntry。

每个 TimelineEntry 都包含一个时间点以及一份数据。系统到了某个 Entry 的时间点时，就会渲染对应视图。比如你在早上 8 点创建一个Entry，附上“距离会议开始还有 2 小时”的数据，等到 10 点这个 Entry 过期后，系统就会向 Provider 重新请求下一条 Entry，或者使用你在 Timeline 里预留的下一条。

为了节约资源，WidgetKit 重载 Timeline 的频率是有限制的。如果你每次都返回一条“当前时间 + 当前数据”的 Entry，系统会认为这个 Widget 不需要频繁更新，可能几小时才刷新一次。反过来，如果你想做“每 5 分钟显示一次倒计时”，必须把未来半小时的 6 个 Entry 一次性准备好。

这点很关键：MAUI 宿主 App 不能在后台无限刷新 Widget，它只能通过 WidgetCenter.shared.reloadAllTimelines() 主动告诉系统“我有新数据了”。具体什么时候重新拉 Timeline，由系统决定。所以从架构上说，Widget 必须能在“没有宿主 App 参与”的情况下，独立地根据时间推断出应该显示的内容。

2.2 宿主 App 与 Widget 之间靠什么交换数据

Widget 运行在独立的扩展进程里，它和宿主 App 的沙盒不互通。为了让两边共享设置项和业务数据，最常用的是 App Group。你在苹果开发者后台为宿主 App 和 Extension 同时开启同一个 App Group，然后系统会分配一个两边都能访问的共享容器目录。

常见的读写方式有两种。第一种是用 UserDefaults(suiteName: "group.com.example.app")，适合保存设置项或轻量状态。第二种是直接通过 FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.com.example.app") 访问共享目录，适合放图片缓存或较大的 JSON 文件。

数据不是实时同步的。宿主 App 写入后，Widget 进程不知道；Widget 更新时，宿主 App 进程也不知情。如果宿主 App 改了配置，需要写入 App Group 后调用 WidgetCenter.shared.reloadAllTimelines()。同理，如果 Widget 想改变宿主 App 的状态，一般只能通过点击跳到 App 内页面，由用户去操作。

这里有个值得注意的业务细节：在 Widget 首次安装、首次添加时，系统可能直接访问 Extension 进程，而此时宿主 App 并未运行，共享容器里可能是空的。你的 Widget 需要有“默认占位内容”的逻辑，不能依赖宿主 App 一定先写入过数据。否则用户添加 Widget 后只能看到一片空白，体验非常差。

2.3 Widget 点击后如何拉起 MAUI App

主屏幕 Widget 允许用户点击后打开宿主 App。小尺寸 Widget 可以使用 widgetURL(_:) 为整个组件设置一个 URL；中尺寸和大尺寸 Widget 里，Link 控件可以让不同区域点击跳转到不同 URL。

这些 URL 会传给宿主 App。MAUI iOS 工程中，常见的处理是自定义 AppDelegate，重写 OpenUrl 方法，或者使用 UrlScheme 将 URL 映射到某个页面。例如 Widget 上显示“打开订单详情”，URL 定义为 mymauiapp://order?id=12345，MAUI 宿主里解析 id 后，用深链接库跳到对应详情页。

需要注意，Widget 点击并不能在系统里调用任意 Objective-C 方法，你一定要注册 URL Scheme。否则系统会提示“无法打开App”，用户点几次就会觉得小部件坏了。

3. 从零到一：Xcode 创建 Widget Target，再挂到 MAUI 宿主

3.1 在 Xcode 中新建 Widget Extension

我这里假设你已经有一个能跑起来的 MAUI iOS 工程，至少跑过一遍真机或模拟器。接下来打开 .sln 同级目录，用 Xcode 新建一个空工程，或者直接新建一个 Swift Package 工程，然后把 Widget Target 放进去。

我的习惯是建一个纯空工程，名字叫 YourAppWidgets。然后在 Xcode 里选择 File -> New -> Target -> Widget Extension。需要注意四个细节：

• Product Name 要跟宿主 App 的 Bundle ID 相关联，一般使用 com.example.app.WidgetExtension。
• 语言一定选 SwiftUI。
• 如果你不需要用户配置，可以不勾选 “Include Configuration App Intent” 之类的选项，单 target 工程越简单越容易排查问题。
• 部署目标建议设成 iOS 15 或更高。虽然 iOS 14 就能跑 Widget，但 iOS 15 以后提供了更稳定的 AccessoryWidget 和实时活动支持，Api 也友好一些。

新建完成后，Xcode 会生成一个文件夹，里面包含 WidgetBundle、View、TimelineProvider 三个主要文件。你可以先用默认模板跑一次，确认 Widget 能在模拟器上被添加。如果这一步没走通，后面所有嵌入工作都没必要继续。

有一点我必须提醒：Xcode 生成的 .appex 产物，默认路径在 Xcode 的 DerivedData 里，不是随便一个 bin 目录。你在做 MAUI 集成时，最好在 Xcode 的 Build Settings 中把 Build Products Path 改成一个固定的项目内目录，比如 $(SRCROOT)/Output/$(CONFIGURATION)/$(SDK_NAME)。这样 MAUI 的 MSBuild 脚本才能稳定地找到 .appex 文件。

3.2 把 .appex 打包进 MAUI 生成的 .app

苹果要求扩展必须放在主 App 包的 PlugIns 目录下。Xcode 原生工程能识别 Embed App Extensions 这个构建阶段，把子 target 的 .appex 自动复制进去并签名。但 MAUI 的 msbuild 链路并不认识我们的 Widget Extension Target，所以得通过自定义 Target 手动复制。

我实际用的是下面这种 MSBuild 配置：

xml复制<PropertyGroup>
  <WidgetAppex>$(MSBuildThisFileDirectory)..\YourAppWidgets\Output\Release-iphoneos\YourAppWidgets.appex</WidgetAppex>
</PropertyGroup>

<Target Name="EmbedWidgetExtension" AfterTargets="_CopyFilesToContent">
  <ItemGroup>
    <_WidgetAppex Include="$(WidgetAppex)" />
  </ItemGroup>
  <Copy SourceFiles="@(_WidgetAppex)"
        DestinationFolder="$(AppBundleDir)\PlugIns"
        SkipUnchangedFiles="false" />
</Target>

这段 Target 是在 MAUI iOS 构建拷贝完了主 App 内容之后再触发。$(AppBundleDir) 是 MAUI 构建过程中已经定义好的路径，指向最终生成的 .app 包。复制完 .appex 后，我们会在下一步对它单独签名。

这里有个隐藏陷阱：AfterTargets 挂构建阶段不能挂得太早。如果挂到 AfterBuild，很可能 MAUI 已经执行完了主 App 签名流程，这时你才把未签名的 .appex 塞进 PlugIns，整个过程还需要重新签一次主 App。我踩过几次坑之后总结的经验是：最好直接复制完成后再写一个 Target 对整个 .app 做后签名处理，不要依赖 MAUI 默认的签名步骤。

写完后，你可以在命令行跑 dotnet build -f net8.0-ios -p:RuntimeIdentifier=ios-arm64 -c Release，然后检查生成的 .app 目录。如果看到 PlugIns/YourAppWidgets.appex 出现在里面，说明复制动作生效了。

3.3 签名与 Entitlements 配置

很多人做完复制，掏出真机一装，发现提示“无法安装 App，此 App 包含的扩展无效”。这类问题九成出在签名上。

在原生 Xcode 工程里，Widget Extension 需要独立签名，并且要配置自己的 Entitlements。你在 Apple Developer 后台至少需要准备两套能力：

• App Group：宿主 App 和 Extension 都启用同一个 Group ID，才能共享容器。
• 签名证书：宿主 App 用一个 Distribution Certificate，扩展不能随便用同一套 Provisioning Profile，它要使用包含了 App Group 能力的对应 Profile。

在 MAUI 端，先把宿主 App 的 Entitlements.plist 内容补全：

xml复制<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.application-groups</key>
    <array>
        <string>group.com.example.app</string>
    </array>
</dict>
</plist>

然后在 MAUI 的 csproj 里把 Entitlements 路径指向这个文件：

xml复制<PropertyGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
    <CodesignEntitlements>Entitlements.plist</CodesignEntitlements>
</PropertyGroup>

对于 Widget Extension 本身，不能只使用宿主 App 的 Entitlements。我的做法是在原生的 Widget Target 里建一个独立的 Entitlements-Widget.plist，内容同样声明 App Group。然后在 MAUI 的签名 Target 里，使用 codesign 单独给 .appex 签名：

bash复制codesign --force --sign "iPhone Distribution: Your Company" \
  --entitlements YourAppWidgets/Entitlements-Widget.plist \
  "$(AppBundleDir)/PlugIns/YourAppWidgets.appex"

签完扩展后再对主 App 重新签名，否则主 App 的签名校验会不通过。顺序上不要反过来。如果你嫌命令行麻烦，也可以把 Widget Extension 作为 Xcode 工程单独 Archive，生成一个已签名好的 .appex，再在 MAUI 的 Target 里只做复制。但这种方式每次更新 Widget 都要先去 Xcode 按一次 Archive，迭代效率低，我一般只用它做最终发布包。

3.4 从 MAUI C# 侧刷新 Widget

Widget 的数据如果想跟着 App 内操作即时变化，宿主侧要写一段刷新代码。核心就两件事：先把数据写进共享的 App Group，然后调 WidgetCenter 让系统请 Timeline。

C# 侧没有直接可用的 WidgetCenter API，所以需要调用 iOS 原生方法。你可以通过绑定或自定义 UIDevice 层调用，但更轻量的是在 MAUI 中写一个 WidgetCenterHelper，通过 JavaScript Bridge 不用去弄，直接写 native Binding 类：

csharp复制public static class WidgetCenterHelper
{
    private const string AppGroupId = "group.com.example.app";

    public static void SaveDataToSharedDefaults(string json)
    {
        var userDefaults = new NSUserDefaults(AppGroupId, NSUserDefaultsType.SuiteName);
        userDefaults.SetString(json, "widget_data");
        userDefaults.Synchronize();
    }

    public static void ReloadWidget()
    {
        var selector = new ObjCRuntime.Selector("reloadAllTimelines");
        // 这里需要绑定 WidgetCenter 类，或使用原生调用
    }
}

WidgetCenter 的显式绑定并不复杂，但如果你不想引入额外库，还可以用运行时消息发送，只是可读性差一些。实际项目中我更推荐先用 Xcode 写好一个很小的 Swift 工具类，比如：

swift复制@objc public class WidgetCenterHelper: NSObject {
    @objc public static func reload() {
        WidgetCenter.shared.reloadAllTimelines()
    }
}

然后在 MAUI 工程里把这个 Swift 类编成 framework，通过绑定库方式调用 WidgetCenterHelper.Reload()。这样写的好处是 Swift 侧代码非常薄，跨语言桥接不易出错，后面的刷新逻辑都在 C# 里维护即可。

4. 把 Widget 的真实内容做出来：一个“下一场会议倒计时”案例

4.1 TimelineProvider 三个方法的功能切分

我拿一个最常见也最有代表性的例子讲：App 里维护了一份会议列表，Widget 在主屏幕显示“下一场会议还有多久开始”。这在日历、会议、提醒类应用里非常典型，因为倒计时类内容必须在没有宿主 App 运行时也能自己演变。

WidgetKit 的 TimelineProvider 主要实现三个方法。placeholder 是系统在小部件预览和过渡时使用的占位数据，通常给一个默认了假字段的对象；getSnapshot 是给系统在 Widget Gallery 展示预览用的，要立刻返回一条当前快照，不需要大量延迟；getTimeline 才是真实场景下不断提供时间线的入口。

以会议倒计时为例，我在 Swift 代码里这样设计数据模型：

swift复制struct MeetingEntry: TimelineEntry {
    let date: Date
    let meetingTitle: String
    let startTime: Date
    var isPast: Bool {
        startTime < date
    }
}

Entry 不是业务模型，它是“在某个时间点要渲染的数据快照”。我建议不要把 App 里的完整会议对象直接塞进 Entry，因为系统会缓存 Timeline，里面包含了 Entry 的数据。如果数据全塞进去，可能造成内存或磁盘问题。

4.2 怎么生成有条理的 Timeline

我做倒计时 Widget 时，通常会把未来 30 分钟切成每 5 分钟一个 Entry。每一条 Entry 都附带当前时刻和会议开始时间，SwiftUI 视图在渲染时计算“还剩 xx 分钟”。为什么不是直接计算一次然后固定显示“还剩 30 分钟”？因为 WidgetKit 需要在 Entry 刷新时重新渲染，如果你只返回一条 Entry，时间永远不会变。

另一种做法是根据会议的开始时间，只生成一个 Entry 对应“会议开始时”的临界点，然后让视图用 Text(timerInterval:) 这种系统支持的计时控件自动倒计时。这个方法在锁屏和实时活动里可用，但在主屏幕 Widget 里偶尔会出现刷新延迟，不如生成多条 Entry 来得可靠。

生成代码大致如下：

swift复制func getTimeline(for request: INIntent, completion: @escaping (Timeline<MeetingEntry>) -> Void) {
    Task {
        let meetings = await loadMeetingsFromSharedContainer()
        guard let next = meetings
            .filter({ $0.startTime > Date() })
            .sorted(by: { $0.startTime < $1.startTime })
            .first
        else {
            let entry = MeetingEntry(date: Date(), meetingTitle: "暂无会议", startTime: Date())
            let timeline = Timeline(entries: [entry], policy: .after(.now.addingTimeInterval(60 * 60)))
            completion(timeline)
            return
        }

        var entries: [MeetingEntry] = []
        let now = Date()
        let step: TimeInterval = 5 * 60
        var cursor = now
        for _ in 0..<6 {
            entries.append(MeetingEntry(date: cursor, meetingTitle: next.title, startTime: next.startTime))
            cursor.addTimeInterval(step)
        }
        let timeline = Timeline(entries: entries, policy: .after(cursor))
        completion(timeline)
    }
}

Timeline 的 policy 参数决定系统在 Timeline 用完后怎么处理。可以选 .never，意思是“除非宿主 App 主动 reload，否则不再来请求”；也可以选 .after(date)，意思是“过了这个时间点后，要再走一次 Provider”。对于倒计时类，我建议用 .after(cursor)，也就是把预生成的 6 条 Entry 用完后马上请求下一批。

4.3 SwiftUI 视图怎么写才能适配不同尺寸

Widget 的 View 必须要兼容系统提供的三种尺寸：systemSmall、systemMedium、systemLarge，以及在 iOS 16 之后出现的 Accessory 系列（锁屏和灵动岛周边）。如果你只按一个小尺寸写死，系统在用户拖拽中尺寸时会拉伸或者裁切，观感很差。

我一般用 @Environment(\.widgetFamily) 判断当前尺寸：

swift复制@Environment(\.widgetFamily) private var family

var body: some View {
    switch family {
    case .systemMedium:
        HStack {
            Text("\(meetingTitle)")
            Spacer()
            Text("\(nextStartText)")
        }
        .padding()
    default:
        VStack(alignment: .leading) {
            Text("下一场会议")
            Text("\(nextStartText)")
                .font(.title2.bold())
        }
        .padding()
    }
}

这里不需要写特别复杂的设计，重点是保证内容和边界留白正确。Widget 的背景会在主屏幕以圆角卡片展示，你不必自己画很重的圆角或背景色，直接把 SwiftUI 的 containerBackground 应用到最新 API 就好。在 iOS 17 的 Widget 里，如果没设置背景，系统会使用一个默认的透明背景，在某些壁纸上文字会看不清。最简单的兜底办法是给文字加一层半透明背景或使用系统材质。

4.4 从 MAUI 侧把会议数据写进共享容器

SwiftUI 端只负责读和使用，不能发起网络请求去拿会议列表。合理的做法是宿主 App 在打开时、切后台时、或会议列表变更时，把会议 JSON 写到 App Group 共享目录。

这部分我在 C# 里直接用 Foundation.NSUserDefaults 实现。注意命名空间和套件名要完全对齐 Swift 端使用的 group.com.example.app。数据格式我建议统一用 JSON 字符串，不要分别存一堆 string 字段，否则后面加一个字段就要同步改两端。

csharp复制var defaults = new NSUserDefaults("group.com.example.app", NSUserDefaultsType.SuiteName);
var meetingData = new List<Meeting>
{
    new Meeting { Title = "产品周会", StartTime = DateTime.Now.AddMinutes(25) }
};
var json = JsonSerializer.Serialize(meetingData);
defaults.SetString(json, "meetings");
defaults.Synchronize();

写完数据后，调用扩展刷新方法。这里要注意：Synchronize 不能保证 Widget 进程立即看到数据，它只是把数据同步到磁盘。真正让 Widget 更新 UI，必须依赖 WidgetCenter.shared.reloadAllTimelines()。用完这个调用后，系统会在下一次方便的时候询问 TimelineProvider，App 侧不必期待毫秒级同步。

5. 实战中经常遇到的坑和排查方法

5.1 Widget 在模拟器能看到，真机一装就报错

这种问题基本是签名配置不一致。先检查宿主 App 和 Widget Extension 的 Bundle ID 是不是以同一个 Team ID 的 Prefix 开头；再检查两边的 Provisioning Profile 是否都包含 App Group 能力。很多开发者只给主工程开了 App Group，忘了给 Extension 单独生成描述文件，结果主 App 装上了，但系统校验扩展时发现没有写权限，直接导致整个 App 安装失败。

排查时可以在 Xcode 里单独跑一下 Widget Target，看真机能不能装上这个附录包。或者使用命令对 .appex 做一次签名检查：

bash复制codesign -d --entitlements - path/to/YourAppWidgets.appex

如果输出里没有 com.apple.security.application-groups，基本就是扩展侧缺少该能力。

5.2 Widget 一直显示占位数据，不更新成真实数据

数据链路没问题但界面不刷新，大概率是 App Group 写错了 ID。宿主 App 用 group.com.example.app，扩展里却写成了 group.com.example.app.Widget，两边看起来相关，其实完全不是同一个容器。我建议先在 Swift 端临时加一个日志，读取 UserDefaults(suiteName:) 里有没有值。如果读不到，就先检查 ID；如果读到了，再检查 TimelineProvider 的读取逻辑。

另一个常见原因是宿主写入完成后调用了 Synchronize()，但没调 reloadAllTimelines()。Synchronize() 只是保证当前进程的数据落盘，系统并不监听这个事件。写入后请务必触发一次刷新。

5.3 Widget 不能做到实时倒计时

这是开发周期里被问得最多的问题。由于 WidgetKit 的时间线机制，一个 Widget 显示的剩余时间不可能每秒钟跳一次，除非你使用系统计时器支持的区间显示组件，并且该组件在对应 Widget family 上可用。系统的 Text(timerInterval:pauseTime:countsDown:) 可以在显示上做秒级倒计时，但它只在少数场景下能稳定工作，而且仍受 Timeline 限制。

如果你的业务允许，最好在 Widget 文案上模糊时间精度，写成“还有 25 分钟”，而不是“还有 25:36”。前者在 5 分钟一刷的时间线下也不会觉得奇怪，后者一旦没刷新就会露馅。

5.4 中尺寸 Widget 里存在多个可点击区域，点击后跳转不准确

中尺寸和大尺寸 Widget 支持 Link，你可以在 SwiftUI 的视图中写多个链接，为不同区域设置不同的 URL。但你需要确认宿主 App 的 OpenUrl 处理函数已经正确解析路径参数。很多 MAUI 开发者只在 App 启动时处理 URL，没有在 App 从后台回到前台时处理 URL，导致用户已经装好 Widget 后再次点击时，只能打开 App 首页。

处理方式是保证 AppDelegate 的 OpenUrl 方法覆盖如下情况：App 尚未启动、App 在后台、App 已经在前台。一种稳定写法是在该方法中把 URL 转发给当前 Shell 页面，然后在页面 OnAppearing 里执行跳转逻辑。具体页面耦合不强，但一定要有统一的路由表。

5.5 Widget 卡片上出现难看的系统材质或半透明背景

如果你没有为 Widget 提供背景，iOS 17 后的系统会把 Widget 默认背景改成跟主屏幕壁纸一致的透明样式。这不是错误，但文字颜色如果没有对比度设计，可读性会下降。最简单的处理是在最外层给一个明确的 containerBackground(.fill.secondary, for: .widget)，或者使用系统材质把内容浮起来。不要试图做透明背景配白色文字，这类组合在浅色壁纸上基本看不清。

6. 我的实际体验与几条避坑建议

用 .NET MAUI 做 iOS Widget 这件事，如果只站在 C# 工程师的角度去操作，初期一定会有一点抵触心理，觉得为什么苹果不提供一个 XAML 标签，非要写 SwiftUI。但换个角度看，Widget 本身的形态非常简单，UI 代码通常不超过 100 行，用 SwiftUI 写一个纯展示卡片，难度远低于维护一整套 MAUI 页面生命周期。真正费时间的不是 SwiftUI，而是构建集成、签名和跨进程数据同步。

我这里想特别建议：第一个 Widget 版本，不要把数据链路设计得太复杂。先做一个最简单的静态文案 Widget，走通“生成原生 Extension - 嵌入 appex - 真机安装确认”这条路，再迭代到动态数据。我见过好几个项目一上来就想做“实时天气 + 股票 + 待办”的复杂 Widget，最后被时间线和进程限制卡了一周。Widget 的交互边界很清楚：它适合做摘要、快捷入口和基于时间的连续性信息，不适合承载完整的业务流程。

另外，团队合作时一定要在代码库里把两套工程的分工文档写清楚。Xcode 里产生的签名配置、目录路径、.appex 产物路径，是 Visual Studio 构建流程每次都要依赖的“外部件”。如果开发者 A 更新了 Widget 代码，却没有把新产物放到共享目录，开发者 B 在 VS 里构建时可能拿到的是一个四天前的旧 .appex，这时候排查起来非常痛苦。

最后一个技巧是给 CI 流程加一道产物检查。每次构建完成后，直接写一个很小的检测脚本，检查 .app/PlugIns 下是否存在改动的 Widget 包。这一步能拦住我遇到过至少四次“忘记复制新 appex”的人为失误。

从目前情况看，MAUI 官方直接集成 WidgetKit 的日期还很遥远，但“原生扩展 + MAUI 宿主”这条路已经足够支撑真实产品。你把数据层和时间线设计想清楚后，后续维护成本并不高，至少比每次单独维护一套纯原生 App 加一套 MAUI App 要省事得多。