iOS 小组件开发问题合集

小组件在 iOS 14 和 macOS 11 及更高的版本上才可用，且只支持Swift和SwiftUI。

尺寸

iPhone 小组件支持设置基础的三个尺寸，即：小、中、大。

从 iOS 15 开始，支持 systemExtraLarge 超大型号的组件，专门在 iPad 上使用的。

从 iOS 16 开始，支持 accessoryCircular 、 accessoryRectangular 和 accessoryInline 类型，这几种小部件可以用在手表中，也可以出现在 iOS 的锁定屏幕上。

Timeline

Widget 刷新时间由系统统一决定，如果需要强制刷新Widget，可以在 App 中使用 WidgetCenter 来重新加载所有时间线：WidgetCenter.shared.reloadAllTimelines()， 实际开发过程中， Widget 刷新的最短时间是5分钟，苹果推荐的是15分钟。

• Keeping a widget up to date | Apple Developer Documentation

小部件的预算适用于 24 小时期间。WidgetKit 根据用户的日常使用模式调整 24 小时窗口，这意味着每日预算不一定会在午夜重置。对于用户经常查看的小部件，每日预算通常包括 40 到 70 次刷新。该速率大致相当于每 15 到 60 分钟重新加载一次小部件，但由于涉及的许多因素，这些间隔通常会有所不同。

WidgetKit 不将重新加载次数计入您的小部件预算的情况包括：

• 小部件的包含应用程序位于前台。
• 小部件的包含应用程序具有活动的音频或导航会话。
• 小部件执行应用程序意图，例如当用户点击按钮或切换开关时。
• 小部件执行动画。
• 系统区域设置发生变化。
• 动态类型或辅助功能设置发生变化。

对于系统外观更改或系统区域设置更改等情况，请勿请求从应用程序重新加载时间线。系统会自动更新您的小部件。在待机状态下，系统会按照系统定义的速率刷新小部件的显示，该速率不计入其预算。

WidgetKit 有时会重新加载您的小部件以帮助保持其内容新鲜。一些常见的场景包括：

• 如果某个小部件位于用户很少访问的主屏幕页面上，则 WidgetKit 可能会降低该小部件的重新加载频率。稍后，当用户查看页面时，WidgetKit 可能会在小部件变得可见时重新加载该小部件。
• 对于使用位置服务的小部件，WidgetKit 会在发生重大位置更改后重新加载它们。有关使用位置服务的小部件重新加载的更多信息，请参阅访问小部件中的位置信息。

如何调试？

Xcode iOS 14 WidgetKit 并不总是附加到调试器 - 代码日志

Preview

Ensure that you have called the containerBackground(for: .widget) {…} modifier in your widget view.

这属于 iOS 17 的问题，将 iPhone 15 Pro 切换为低于 iOS 17 的版本可以解决。

下面文章对我无效：

• 调整应用程序的小部件以使用 .containerBackground(for:)

Missing ‘previewContext’ modifier

Target Membership 需要同事包含 iOSWidgetDemo 和 YoLinkWidgetExtension

Build service could not create build operation: unknown error while handling message: MsgHandlingError(message: “unable to initiate PIF transfer session (operation in progress?)”)

ios - Xcode 14.3 build error "unable to initiate PIF transfer session (operation in progress?)" - Stack Overflow

重启 Xcode 对我有用。

This app or an app that it contains has a Siri Intents app extension that is missing the IntentsSupported array in the NSExtensionAttributes dictionary in the NSExtension dictionary in its Info.plist.

Intents Extentsion 缺少如下红框中配置。

ios14 - IntentHandler for project that contains both Siri & Widget - Stack Overflow

SendProcessControlEvent:toPid: encountered an error: Error Domain=com.apple.dt.deviceprocesscontrolservice Code=8 “Failed to show Widget ‘com.ganzhixiog.ios-demo.MyWidget’ error: E…

降低 Minimum Deployments 到不高于手机系统版本。

Please specify the widget kind in the scheme’s Environment Variables using the key ‘_XCWidgetKind’ to be one of: ‘ThsWidget’, ‘YoLinkWidget’

当删除此 App 后，再次 Build，就会报这个错误。

@main
struct YoLinkWidgetBundle: WidgetBundle {
    var body: some Widget {
        YoLinkWidget()
        ThsWidget()
    }
}

通过将 body 下的 Widget 只保留一个，不再报错。

Cycle inside Runner; building could produce unreliable results.

Showing All Errors Only
Cycle inside Runner; building could produce unreliable results.
Cycle details:
→ Target 'Runner': ExtractAppIntentsMetadata
○ Target 'Runner' has copy command from '/Users/gan/Library/Developer/Xcode/DerivedData/Runner-djqhtrdgutewujghuzpngrhrkbck/Build/Products/Debug-iphoneos/YoLinkWidgetExtension.appex' to '/Users/gan/Library/Developer/Xcode/DerivedData/Runner-djqhtrdgutewujghuzpngrhrkbck/Build/Products/Debug-iphoneos/Runner.app/PlugIns/YoLinkWidgetExtension.appex'
○ That command depends on command in Target 'Runner': script phase “Thin Binary”
○ Target 'Runner' has process command with output '/Users/gan/Library/Developer/Xcode/DerivedData/Runner-djqhtrdgutewujghuzpngrhrkbck/Build/Products/Debug-iphoneos/Runner.app/Info.plist'
○ Target 'Runner' has copy command from '/Users/gan/Library/Developer/Xcode/DerivedData/Runner-djqhtrdgutewujghuzpngrhrkbck/Build/Products/Debug-iphoneos/YoLinkWidgetExtension.appex' to '/Users/gan/Library/Developer/Xcode/DerivedData/Runner-djqhtrdgutewujghuzpngrhrkbck/Build/Products/Debug-iphoneos/Runner.app/PlugIns/YoLinkWidgetExtension.appex'

Flutter iOS 存档错误：错误（Xcode）：在 Runner 内循环； 建筑可能会产生不可靠的结果 - Thinbug

Cannot find ‘XXWidget’ in scope

原因就是文件没有添加到小组件所在的 Target 导致。

解决

1. 移除添加到错误 Target 的 Build Phases 中的 Compile Sources 中的 XXWidget 文件。
2. 将 XXWidget 文件添加到小组件 Target 的 Build Phases 中 Complie Sources 中。

参考

• iOS 小组件开发第一篇：基础介绍 - 知乎