WidgetKit foundations
System Services 入门 20m

WidgetKit 基础知识

WidgetKit foundations

2026年6月10日

在 Apple 官方观看视频

一句话判断

别指望看到颠覆性的 Widget 新玩法，这是一场给新手打底、给老手查漏补缺的“规范课”，最大的干货是明确了 Tinted/Clear 模式的适配边界和刷新预算的潜规则。

这场 Session 讲了什么

这场 Session 最值得关注的一件事，是 Apple 终于把 Widget 在 Tinted (着色) 和 Clear (透明) 模式下的适配规则讲透了，顺便带了个新的 systemExtraLargePortrait (超大竖屏) 尺寸。

如果你已经写过 Widget，这 20 分钟可以快速倍速过一遍。Apple 把 Widget 的设计哲学浓缩成了三个词：Glanceable (一目了然)、Relevant (相关)、Personalizable (可个性化)。整个 Session 就是围绕怎么用 Widget Extension (小组件扩展) 和 Timeline (时间线) 把这三点落地。对于新手，它手把手教你怎么写 StaticConfiguration 和配置 Reload Policy (重新加载策略)；对于老手，它重点强调了别滥用刷新预算，以及如何用 .widgetAccentedRenderingMode 抢救被系统自动“反色”毁掉的 UI。

值得深挖的点

Timeline 刷新策略与“预算”潜规则

Apple 在 Session 里把 Reload Policy (重新加载策略) 分成了 atEnd、afterDate 和 never 三种。表面上看是 API 选择，背后其实是系统对电池续航的妥协。Widget 不是后台常驻进程，系统给每个 Widget 分配了“刷新预算”。

如果你用 atEnd，系统会在 Timeline (时间线) 耗尽时自动唤醒 Extension；用 afterDate，你可以指定一个绝对时间（比如午夜）来刷新。最容易被忽略的是 never，很多开发者觉得不用就不写，但对于那些只依赖用户交互（比如点击打卡）或 App 前台状态变化才需要更新的 Widget，显式声明 never 并通过 WidgetCenter.reloadTimelines 或推送来触发，是保住刷新预算的最佳姿势。系统在分配预算时，会根据用户的查看频率动态调整，如果你在前台疯狂触发刷新，预算耗尽后系统就会直接无视你的请求。

Tinted/Clear 模式下的 UI 抢救指南

iOS 和 macOS 现在支持 Tinted (着色) 和 Clear (透明) 外观模式。默认情况下，SwiftUI 会自作聪明地把你的 Widget UI 转换成单色或半透明效果。这对于纯文本或简单图标很好，但如果你有个精美的书籍封面或品牌 Logo，系统自动处理后的效果简直是灾难。

Apple 给出了 .widgetAccentedRenderingMode(.fullColor) 这个救命稻草。把它加在特定 View 上，就能告诉系统“这块区域保持全彩，别动它”。这里的 Trade-off 很明确：系统希望 Widget 融入桌面壁纸，而你希望展示品牌特色。滥用 .fullColor 会让 Widget 在 Tinted 模式下显得极其突兀，正确的做法是只给核心视觉元素（如头像、封面）保留全彩，背景和其他辅助元素依然跟随系统 Tint 变化。同时，务必使用 .containerBackground(for: .widget) 来声明背景，这样系统在 Clear 模式下才能正确地把你的背景替换成玻璃材质。

代码片段

1. 声明背景与抢救全彩 UI

场景：在 Tinted/Clear 模式下，保持书籍封面全彩，同时让背景正确适配系统的玻璃材质。

struct DailyReadingGoalView: View {
    let book: Book
    
    var body: some View {
        ZStack {
            // 核心视觉元素保持全彩，避免被系统强制反色
            Image(book.coverName)
                .resizable()
                .widgetAccentedRenderingMode(.fullColor)
            
            VStack {
                Text(book.title)
                Text("今日目标: 20页")
            }
        }
        // 必须使用 containerBackground，系统才能在 Clear 模式下正确替换为玻璃材质
        .containerBackground(for: .widget) {
            BackgroundGradient()
        }
    }
}

坑：如果不写 .containerBackground，在 iPadOS 或 macOS 的某些放置场景下，Widget 会直接丢失背景变成纯黑或纯白。

2. 配置 afterDate 刷新策略

场景：阅读日程 Widget 需要在每天午夜准时刷新，计算第二天的阅读计划。

struct ReadingScheduleProvider: TimelineProvider {
    // 生成占位视图，必须是同步且轻量的
    func placeholder(in context: Context) -> ReadingEntry {
        ReadingEntry(date: Date(), chapter: "加载中...")
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<ReadingEntry>) -> ()) {
        let entries = [ReadingEntry(date: Date(), chapter: "第三章")]
        
        // 计算明天午夜的日期
        let tomorrow = Calendar.current.startOfDay(for: Date().addingTimeInterval(86400))
        
        // 指定 afterDate 策略，让系统在明天午夜唤醒 Extension 重新请求时间线
        let timeline = Timeline(entries: entries, policy: .after(tomorrow))
        completion(timeline)
    }
}

坑：placeholder 方法里千万别写网络请求或读取数据库，它必须是瞬间返回的，否则系统在小组件库预览时会卡死。

最佳实践

  • 老项目迁移：全局搜索你的 Widget 代码，把所有硬编码的背景色替换为 .containerBackground(for: .widget)。检查所有包含图片或复杂渐变的 View，评估是否需要加上 .widgetAccentedRenderingMode(.fullColor) 以防在 Tinted 模式下“毁容”。
  • 新项目建议：一开始就支持尽可能多的 Widget Family (尺寸)，特别是新增的 systemExtraLargePortrait。数据模型设计时，把“核心指标”和“详细列表”拆开，方便在不同尺寸下复用同一个 TimelineProvider。
  • 避坑指南：别在 App 进入后台时盲目调用 WidgetCenter.reloadAllTimelines()。系统对频繁刷新有严格的预算限制，只在数据确实发生变化，且用户极有可能看到 Widget 时才触发刷新。如果是体育赛事的实时比分，请直接去做 Live Activities (实时活动)，别用 Widget 硬扛。

还有什么值得关注

  • 新增超大竖屏尺寸：systemExtraLargePortrait 正式登陆 macOS、iOS 和 iPadOS 27，给信息流类 Widget 提供了更大的展示空间。
  • App Intents 深度绑定：可配置 Widget 和交互按钮现在全面依赖 App Intents，老式的 IntentConfiguration 建议尽早迁移。
  • Deep Link 规范化：使用 .widgetURL 传递 URL Scheme 时，确保 App 端的 Router 能正确处理并高亮对应的 UI 状态，保持上下文连贯。
WidgetKit SwiftUI App Intents Timeline