WidgetKit 基础知识

WidgetKit 基础知识

小组件可在系统各处突出显示你 App 中最重要的内容，让用户有更多机会与你的 App 交互。探索不同类型的小组件，以及令人印象深刻的小组件需要具备的特质。了解如何创建小组件、让小组件保持最新状态，并利用 App Intents 和动态样式为用户提供自定义小组件的选项。

章节
- 0:01 - Introduction
- 1:03 - Fundamentals
- 13:15 - Integrate with your app
- 17:04 - Adapt with the system
资源
- - 高清视频
  - 标清视频
相关视频

WWDC26
- 实时活动基础知识
WWDC25
- 小组件的新功能
WWDC23
- 如何让小组件更加生动
- 探索 App Intents 的增强功能
WWDC21
- 优秀小组件的原则
你好我是Jonathan Long 系统体验团队的工程师大家都喜欢使用小组件你的小组件能在用户最常访问的地方提供相关内容小组件适用于多个Apple平台包括iOS iPadOS watchOS visionOS和macOS 你的小组件能扩展App 在整个系统中的覆盖范围为用户提供更多体验你优秀App的机会接下来我们深入探讨小组件了解WidgetKit的基础知识如何构建你的第一个小组件以及如何保持更新今天我将介绍小组件基础知识以及如何构建第一个小组件 WidgetKit提供的功能助力整合App与小组件体验以及如何确保小组件适应系统环境的变化例如切换到着色环境首先是基础知识从什么是小组件说起让小组件令人难忘有三个特质小组件要一目了然用户应能通过快速浏览了解你的小组件例如天气小组件会显示恰好足够的天气预报信息帮助我为新的一天做准备小组件要具有相关性小组件内容应符合时间个人习惯和位置预期日历小组件显示当前时间的下一个日程并持续更新全天不断更新小组件可个性化定制可以配置为对你而言重要的内容例如这个照片回忆小组件展示我在家庭露营的美好回忆与我的女儿们在一起借助WidgetKit和SwiftUI 你可以提供出色的一目了然相关且可个性化定制的App小组件
我正在为读书俱乐部开发一款App 以鼓励自己多读书这款App让我追踪阅读进度以及已读完的书目并制定计划帮我在下次读书会前读完一本书我还创建了一些小组件可直接在主屏幕查看数据第一个是阅读目标小组件全天鼓励我坚持阅读第二个是阅读日志小组件帮助我追踪当前的阅读进度第三个小组件为我制定计划帮助我按时读完一本书在整个讲座中我将介绍每个小组件的关键决策为你创建小组件提供参考首先介绍App如何向系统提供小组件无论App使用SwiftUI 还是UIKit构建都可以拥有小组件而小组件将以SwiftUI构建你的App通过小组件扩展向系统提供小组件该扩展作为独立进程运行与App相互分离由于小组件扩展作为独立进程运行你需要使用共享容器通过App Group将数据从App传递给小组件扩展例如共享数据库或User Defaults 小组件扩展专注于小组件本身系统和WidgetKit与扩展交互获取小组件所需的数据 WidgetKit向扩展请求内容这些内容称为时间线
时间线由多个时间线条目组成 WidgetKit将这些条目作为数据提供给小组件的视图生成的视图将被归档系统在相应时间显示这些视图 Widget Extension将小组件暴露给系统并提供时间线内容时间线是一系列条目每个条目携带所需数据用于在特定时间点渲染小组件视图接下来看看阅读目标小组件的代码将这些部分整合在一起
当你为小组件扩展创建新Target时 Xcode会为你生成一个小组件对于简单的小组件这个实现已包含很多所需内容从提供WidgetConfiguration 的body开始
小组件有两种配置类型 AppIntentConfiguration 和StaticConfiguration AppIntentConfiguration适用于可由用户配置的小组件我的小组件会根据当前阅读的书自动配置所以我使用最简单的 StaticConfiguration StaticConfiguration需要几个参数 Kind 即该类小组件的唯一标识符时间线Provider负责为小组件生成时间线条目以及一个闭包接收时间线条目并返回View 在闭包中你为提供的时间线条目返回SwiftUI视图由于我的读书俱乐部App 使用SwiftUI构建已有现成视图 DailyReadingGoalView 正是小组件所需的视图为了指定背景我使用了containerBackground修饰符该修饰符标识了小组件的背景视图
当用户为设备设置彩色或透明着色效果时系统可以将指定的背景视图替换为玻璃材质视图阅读目标小组件的视图部分已实现接下来深入了解时间线Provider的职责以及时间线如何保持小组件的相关性
时间线Provider提供条目代表小组件的三种独立状态 Snapshot Placeholder 和Timeline
Snapshot是小组件的真实预览这是用户在小组件库中看到的内容这是小组件给用户留下深刻第一印象的机会在用户开始使用前App没有数据所以我展示了一本热门书籍 Atomic Habits 并附上默认消息让用户想象小组件最佳状态下的样子在将其添加到主屏幕之前 Placeholder是小组件暂无内容时系统显示的占位视图尚没有内容可显示时例如首次加载时间线时由于占位视图需立即显示获取它必须是同步操作因此请提供无需从磁盘或网络获取数据的占位视图
对于阅读目标小组件我使用了SwiftUI的redacted修饰符它会创建我的View 的简化版本
时间线条目是小组件在特定时刻显示的内容可以是当下也可以是未来的任意时刻时间线Provider会生成一组这样的条目系统在各自对应的时间渲染每个条目
阅读目标小组件的时间线条目包含小组件所需的全部信息以渲染此视图包括励志消息已读页数书名和封面名称
这个小组件的大部分数据都保持不变除了励志消息该消息会在全天各个时间更新在讲解时间线时我只展示会随时间变化的消息它会随时间的推移而变化时间线对于保持小组件内容更新至关重要每个时间线条目提供渲染小组件视图所需的数据此时间线当前显示两个条目一个在上午9时另一个在上午11时30分
阅读目标小组件所需的核心数据是全天更新的励志消息随WidgetKit推进时间线而更新
这些时间线条目被提供给小组件以生成相关视图在特定时间展示该条目的内容通过新鲜内容保持小组件的相关性
在某个时刻你的时间线需要刷新以获取更多条目这称为重新加载时间线时间线通过重新加载策略指定其重新加载行为重新加载策略有三种选项 atEnd afterDate和never 我们来讨论每种策略及其适用场景
atEnd策略表示时间线应在耗尽后重新加载当所有时间线条目全部显示完毕时
全天将渲染新的时间线条目
当下午1时最后一个条目显示完毕后系统会触发重新加载向小组件扩展请求更多内容
你的小组件扩展将提供包含更多条目的新时间线阅读目标小组件会在不同时间更新励志消息全天不断更新 atEnd策略适合此场景因为该小组件提供一系列条目结束时间不是固定的且需要在时间线耗尽时重新加载
afterDate策略允许你为小组件指定具体的重新加载日期以请求重新加载以下是驱动阅读日程小组件的不同时间线条目我已隐去完整数据集只保留随时间变化的章节信息随时间推移而变化阅读日程小组件提供两个时间线条目指示所需阅读的内容包括今天和明天需要阅读的内容该小组件需要在当天结束时重新加载以重新计算后续日程它使用afterDate重新加载策略指定当天结束时的日期
当前时间到达该日期时我的扩展将被重新加载并被要求提供新的时间线
新时间线提供周二和周三的条目包含重新计算的日程 afterDate策略非常适合像阅读日程小组件这样的场景当你明确知道小组件需要重新加载的具体时间时
最后是never重新加载策略顾名思义小组件不会自动重新加载当自动重新加载不适用时可选择此策略阅读日志小组件就是一个好例子它只需在用户与App 或小组件交互时才刷新当需要重新加载时你可以通过显式调用来实现调用WidgetCenter的重新加载API 或发送推送通知如需深入了解重新加载策略请观看WWDC21的《Principles of great widgets》
以下是几个值得牢记的最佳实践在构建和重新加载时间线时
尽可能提供多个时间线条目确保系统始终有内容可供你的小组件显示
WidgetKit在设计时考虑了全天续航因此每个小组件都有更新预算预算受用户查看习惯的显著影响并会全天持续更新更新频率可能有所不同系统足够智能能够合理地为你的小组件调整重新加载请注意 App在前台时频繁重新加载可能会受到限制如果小组件数据可能已更新在App进入后台时最后调用一次重新加载通常是好方法某些内容是短暂的有明确的开始和结束日期需要更频繁地更新并需要提醒功能例如体育赛事如果符合上述情况建议考虑构建实时活动你可以在《Live Activities essentials》中了解更多关于实时活动的内容来自WWDC 26
目前我所有小组件的尺寸相同均为system medium家族但现在我的Widget Extension 和时间线Provider已连接好我可以使用多种其他小组件家族小组件有各种不同的形状和尺寸建议支持尽可能多的尺寸让使用你小组件的用户在放置时有更多选择
System extra large portrait家族已在visionOS 26中推出 macOS iOS和iPadOS 27的新增功能 System extra large portrait家族现已可用这个新家族让使用你小组件的用户能够更充分地展示你App的内容读书俱乐部的阅读日程小组件可以复用medium小组件的相同数据我们已经实现的数据更大的尺寸让我可以了解自己的阅读进度在接下来几天应完成多少内容
并非所有小组件家族都适合你的小组件从少数几个家族开始是最简单的做法
这是我正在构建的每日阅读目标小组件我可以使用.supportedFamilies修饰符列出我的小组件支持的所有家族
添加新的小组件家族时我可以复用相同的小组件和时间线Provider 并构建适合新家族形状和尺寸的SwiftUI视图我刚介绍了构建第一个小组件所需的基本步骤使用专注于小组件的 Widget Extension来构建小组件你通过由时间线条目组成的时间线向小组件提供内容选择适合你使用场景的时间线重新加载策略
我的App现已拥有出色的iOS小组件帮助我把握读书俱乐部的进度我的小组件实际上也在其他地方可用我的iOS小组件在CarPlay上可用也可作为macOS上的远程小组件我们刚介绍了构建小组件所需做的事情接下来讨论WidgetKit提供的更多选项以便更好地整合你的App内容与小组件
你可以通过Deep Link 将小组件与App更好地整合使小组件可配置以及为小组件添加交互元素小组件的默认交互是打开App 这是一个很好的起点如果小组件显示App中的特定内容小组件可以提供Deep Link 直接跳转到该内容让我们回到阅读目标小组件的代码了解如何实现阅读目标小组件显示我正在阅读的书籍我将提供一个Deep Link到书籍详情页这样点击小组件就能直接跳转到用户预期的位置我将使用widgetURL修饰符为App指定Deep Link URL 以便在启动时处理该URL编码了书籍ID 让App直接跳转到书籍详情页
Deep Link是将小组件与App整合的绝佳方式在用户切换时保持情境连贯可配置小组件是将小组件与App整合的另一种绝佳方式使小组件可配置让用户个性化定制小组件使用App中的特定内容
天气小组件是一个很好的例子用户可以配置此小组件来显示天气状况来自他们关心的位置我喜欢关注优胜美地的天气以便随时规划一次说走就走的旅行
读书俱乐部App中的阅读日志小组件是可配置小组件的另一个例子使用我App的用户可以配置此小组件来追踪特定书籍的阅读记录可配置小组件可以在其放置的任何位置进行配置例如从iOS主屏幕这是我阅读日志小组件的配置界面只有一个参数该界面让用户选择他们想要追踪的书籍我将最近阅读的书设为默认选项这样用户无需手动选择可配置小组件还允许用户添加具有不同配置的多个小组件我的主屏幕有三个阅读日志小组件分别追踪我正在阅读的三本书在考虑可配置小组件时有几点需要牢记考虑小组件内容是否应根据使用者的不同而变化保持配置简洁— 通常一两个参数就足够了不要预先要求配置提供合理的默认值让用户日后可以按需调整要了解更多使用App Intents 使小组件可配置的内容请观看 WWDC23的讲座《Explore enhancements to App Intents》
可配置小组件让用户有更多选择个性化设备使设备更贴近个人需求小组件还可以通过交互元素与你的App整合按钮和开关让用户可以直接在小组件中执行操作提醒事项是交互式小组件的绝佳示例完成一项任务后我可以直接在小组件中将其标记完成获得那份继续一天所需的成就感在考虑交互元素时有几点需要牢记小组件可以将交互元素呈现为开关或按钮思考App中最重要的操作并在小组件中展示出来例如阅读日志小组件上的完成章节按钮小组件视图由系统归档和渲染因此代码并非一直运行当小组件显示在屏幕上时按钮和开关使用App Intent 系统可代你执行当用户与元素交互时要了解更多关于交互式小组件的内容请观看WWDC23的《Bring widgets to life》小组件是你App的延伸 Deep Link 可配置小组件和交互元素都是很好的方式统一App与小组件之间的体验使用你小组件的用户还可以自定义系统体验小组件的设计考虑了对这些系统变化的适应能力在iOS上系统可以自定义为特定颜色的着色或透明着色使用任一自定义选项时系统都会通过玻璃材质渲染小组件为内容添加色调并用自适应玻璃效果替换背景这让主屏幕上的每个小组件都保持视觉统一 SwiftUI完成了大量繁重工作但测试仍然很重要测试小组件以确保外观出色
在我开始测试阅读目标小组件时发现全彩色渲染效果非常出色完成前我想通过着色自定义来测试并确认小组件渲染结果符合预期我将在设备上运行并自定义主屏幕来测试当我将iPhone切换到透明模式时小组件的渲染效果不正确书籍封面显示为一个大白色矩形这不是预期效果这是我的BookCoverImage视图在视图的body中图像针对这本书进行渲染来自资源目录在着色渲染模式下系统无法适当地为图像添加着色我可以为此图像指定要使用的渲染模式使用widgetAccentedRenderingMode修饰符有了这个选项我的小组件现在以全彩色渲染书籍封面我使用全彩色选项以便书籍封面渲染时保持原有颜色不变经过此更改我的小组件在着色渲染模式下效果出色务必在每种显示环境中测试小组件从本地设备开始在全彩色着色模式下测试小组件以及透明模式以确保渲染符合预期请记住你的iOS小组件也会以远程小组件的形式出现在macOS上请花时间测试交互效果在Mac上是否仍然流畅当用户在Mac上使用时借助SwiftUI预览快速迭代
在Xcode右侧的SwiftUI画布中你可以检查不同家族配色方案和渲染模式无需离开Xcode 在测试时开启 WidgetKit开发者模式以解除重新加载预算等限制让你能更快地迭代小组件要了解更多关于小组件适应系统自定义的内容请观看WWDC25的《What's new in widgets》
今天我介绍了很多内容在结束之前请记住以下几点希望你受到启发去构建出色的小组件! 考虑如何扩展和个性化你的小组件体验通过与App整合务必测试并让小组件适应所有自定义环境每个平台提供的环境小组件让我的iPhone 充满个人特色和趣味我迫不及待想使用你创建的出色小组件!

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"
    
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
        }
    }
}

12:25 - Supported Families

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
        }
        .supportedFamilies([.systemMedium])
    }
}

14:03 - Adding deep links

struct DailyReadingGoalWidget: Widget {
    let kind = "DailyReadingGoalWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: kind,
            provider: DailyReadingGoalProvider()
        ) { entry in
            DailyReadingGoalView(book: entry.book,
                                 message: entry.message,
                                 timeOfDay: entry.timeOfDay)
            .environment(\.colorScheme, .dark)
            .containerBackground(for: .widget) {
                Background()
            }
            .widgetURL(URL(string: "bookclub://reading/\(book.bookID)"))
        }
        .supportedFamilies([.systemMedium])
    }
}

18:17 - Accented rendering mode

struct BookCoverImage: View {
    let imageName: String

    var body: some View {
        Image(imageName: bundle: .main)
            .widgetAccentedRenderingMode(.fullColor)
    }
}

- 0:01 - Introduction
- Widgets highlight your app's most important content across the system. The best widgets are glanceable, relevant, and personalizable. Learn how to build your first widget and keep it up to date, extending the reach of your app across platforms with WidgetKit and SwiftUI.
- 1:03 - Fundamentals
- Widgets should be glanceable, relevant, and personalizable. They are built by creating a widget extension that exposes a timeline of TimelineEntry values. Each TimelineEntry provides the data to render a SwiftUI view at a particular moment in time. Learn how to define a widget with a StaticConfiguration or AppIntentConfiguration, build a quality TimelineProvider, and select a timeline reload policy to keep your widget up to date. Discover the various sizes and placements for widgets with .supportedFamilies — including the new systemExtraLargePortrait family coming to macOS, iOS, and iPadOS 27.
- 13:15 - Integrate with your app
- WidgetKit offers three key integration points to tighten the connection between a widget and your app. Deep links route taps directly to specific content in your app. Configurable widgets let people personalize widget content. Interactive elements that let people perform the most important actions from within your app using App Intents.
- 17:04 - Adapt with the system
- Widgets are dynamic and adapt with the system appearance modes like full color, tinted, and clear. SwiftUI handles most of the adaptation automatically, though you can customize the behavior of particular Views with the .widgetAccentedRenderingMode(.fullColor) modifier. Learn techniques to test your widgets for considerations with appearance modes and budgeted reloads.

探索“入门汇总”

及时了解最新动态

探索“平台”

精选

探索“技术”

精选

探索“社区”

精选

探索“文档”

发布说明

探索“下载”

精选

探索“支持”

精选

快速链接

章节

资源

相关视频

WWDC26

WWDC25

WWDC23

WWDC21