iOS 小组件

基本知识

时间轴

小组件通过AppIntentTimelineProvider进行 UI 刷新

struct Provider: AppIntentTimelineProvider {func placeholder(in context: Context) -> SimpleEntry {// 添加占位的（选择添加的时候使用）// todo}func snapshot(for configuration: WidgetCfgIntent, in context: Context) async -> SimpleEntry {// 添加预览的时候会调用, 建议这里进行和timeline方法一样的数据处理。// todo}func timeline(for configuration: WidgetCfgIntent, in context: Context) async -> Timeline<SimpleEntry> {// 返回每个时间点的数据。var entries: [SimpleEntry] = []// 按需添加自己的时间片段// entries.append(entry)let nextTimeMin = 20let nextUpDate = Calendar.current.date(byAdding: .minute, value:nextTimeMin, to: .now) ?? Date(timeIntervalSince1970: Date().timeIntervalSince1970 + Double(nextTimeMin*60)) // 16-50分钟刷新一次, 不能设置时间太小，太小会被系统忽略return Timeline(entries: entries, policy: .after(nextUpDate))}// 推荐配置。func recommendations() -> [AppIntentRecommendation<WidgetCfgIntent>] {// todo}}

数据共享

与其他扩展一样，小组件可以通过Group 的UserDefault 共享数据。 还可以通过 SwiftData 共享数据。

交互

widgetURL：所有区域

Link: 不同元素

具有交互性的 Tog 或 Button(iOS 16)：需要基于 AppIntent (与系统通用的 Intent 共用)参考https://developer.apple.com/documentation/widgetkit/adding-interactivity-to-widgets-and-live-activities

AppIntet 理解

Intent: 提供的一个小功能（通过入参、实现某个功能、返回什么结果），比如打开什么、记录什么

Entity：用来表示 App的内容，提供给 Intent 使用（对这个小功能的抽象数据）。

AppShortcut：用来包装 Intent,使之能被系统或者调用方发现。

APPIntent 如何返回数据

func perform() async throws -> some IntentResult & ReturnsValue<Int> {// 如果需要返回其他类型，在 Int 处替换。​		let returnValue: Int = 1​		//在这里添加你要执行的代码​		return .result(value: returnValue)​	}

APPIntent 的参数通常用@Parameter标记, 支持基本常用值， 也可以继承AppEntity或AppEnum–枚举进行自定义类型。

实现了 AppIntent 的功能默认自动提供给快捷指令使用。注意多语言和相关测试

小组件更新

主 APP 内：通过WidgetCenter刷新

// 通过 kind 刷新某个类型小组件
WidgetCenter.shared.reloadTimelines(ofKind: "com.mygame.gamestatus")
// 刷新所有小组件
WidgetCenter.shared.reloadAllTimelines()

系统刷新：

• 通过时间轴刷新（15~50分钟一次，设置时间小了，系统也会忽略）
• 执行交互型 Intent 后会触发刷新

支持小组件类型

struct DemoWidget: Widget {var body: some WidgetConfiguration {// AppIntentConfiguration 为可以配置的小组件AppIntentConfiguration(kind: kind, intent: WidgetCfgIntent.self, provider: Provider()) { entry inSwiftUIWidgetEntryView(entry: entry).widgetBackground(Color.container) // 添加自定义背景色（扩展方法），注意小组件最底层始终有一个底色。 无法做到像 Apple Home 那样的半透明背景效果(据说是只有系统才能用的 API)}.configurationDisplayName("展示名字").description("描述").supportedFamilies(supportFamilies) // 支持小组件类型。.disableContentMarginsIfNeeded() // 忽略边距（扩展方法）}private var supportFamilies:[WidgetFamily] {return [.systemSmall, .systemMedium, .systemLarge]}private var kind: String {return "com.xxxx.Widget"}
}

小组件配置

通过继承WidgetConfigurationIntent 实现。探索 App Intents 的功能更新 – 小专栏

一组一组配置

相关接口：https://developer.apple.com/documentation/appintents/intentitemcollection

struct DeviceDefaultProvider:DynamicOptionsProvider
// 注意这里需要返回 IntentItemCollection， 即分组显示
func results() async throws -> IntentItemCollection<DeviceEntity>  {
//        return ItemCollection(promptLabel: "----collection") {
//            ItemSection("title1", subtitle: "subtitle1", image: DisplayRepresentation.Image(named: "pic_xxxx")) {
//                DeviceEntity(deviceID: "111", name: "device111")
//                DeviceEntity(deviceID: "112", name: "device112")
//            }
//            ItemSection("title2", subtitle: "subtitle2", image: DisplayRepresentation.Image(named: "pic_em0xxxx")) {
//                DeviceEntity(deviceID: "211", name: "device211")
//                DeviceEntity(deviceID: "212", name: "device212")
//            }
//        }
}

效果图

小组件扩展

import WidgetKit
import SwiftUIextension View {/// 统一设置备件@ViewBuilderfunc widgetBackground(_ backgroundView: some View) -> some View {if Bundle.main.bundlePath.hasSuffix(".appex"){ // 小组件才生效if #available(iOS 17.0, *) {containerBackground(for: .widget) {backgroundView}} else {background(backgroundView)}} else {background(backgroundView)}}
}extension WidgetConfiguration {func disableContentMarginsIfNeeded() -> some WidgetConfiguration {if #available(iOSApplicationExtension 17.0, *) {// 禁用边距return self.contentMarginsDisabled()} else {return self}}
}

小组件刷新失败

entities 查询返回数据空

背景：我在主 APP 修改了小组件显示数据源， 同时调用了WidgetCenter.shared.reloadAllTimelines刷新，但是回到小组件，数据依然没有变化，通过调试，控制台打印如下：

Error getting AppIntent from LNAction: AppIntent has missing parameter value for 'xxxx'. You may need to set a default value in the initializer of your @Parameter, or using the default method on your Query.
No AppIntent in timeline(for:with:)

上面这种情况属于 APP 内主动刷新失效， 但是系统的时间轴刷新有效。

通过反复测试发现，在桌面小组件自定义配置后才发生。

我的配置参数是基于 AppEntity 实现的自定义类型。

发现每次在调用 EntityQuery 的entities(for)方法，内部返回空数组，都会打印上面的错误。

struct DeviceEntityQuery: EntityQuery, Sendable {// 通过 ID 查询的会调用， （比如通过配置匹配，提供数据源等）func entities(for identifiers: [DeviceEntity.ID]) async throws -> [DeviceEntity] {//具体逻辑：通过 ID 过滤数据。 如果没匹配到，就返回空。}
}

APP主动刷新小组件 -> 通过自定义配置在 EntityQuery 方法中查询 -> 查询到，触发刷新小组件的生命周期方法，（没查询，比如返回空数组，则不会刷新小组件生命周期方法）

结论：在entities(for)的返回结果时，不要返回空数组，否则可能无法刷新。

解决方法：如果没有匹配到，不返回空数组，构建对应的 Entity 返回。

其他问题

widgetURL配置

现象：通过 WidgtURL装饰器配置的 URL 跳转异常。

原因：我在最底层配置得了 WidgetURL, 在子视图也配置了 Widget,导致跳转异常. 根据官网文档解释,如果有多层View 使用了 WidgetURL， 状态和跳转将是不可预料的（在 iOS18.0上，多数情况下都响应最底层的 WidgetURL）

解决方案：通过 Link 或者 Button（AppIntent 交互）处理连接。

Link(destination: URL(string: "xxxxx" ) {
// your view           
}

Summery 怎么多语言化

使用新的多语言文件 xcstrings

使用占位模式

Get the daylight duration on ${date} in ${location}

使用示例

Summary("Switch \(\.$device) \(\.$isOn)")// 可选, table: "Localizable1")

注意：变量名要一致

Next

将 App 控制扩展到系统级别: 将功能扩展到系统控制，通过类型小组件 AppIntent 的方式。

资料参考

Apple 官方指导：https://developer.apple.com/cn/documentation/widgetkit/

iOS 小组件系列教程：https://juejin.cn/post/7297513663435210771?searchId=2024082914404396F94C65488FE5528F7E

WidgetExamples – github

SwiftUI 控件 Demo – github

SwiftUI 细节学习参考 --肘子的记事本： 各种SwiftUI 控件、布局理解。