虽然 Widget 不能像主 App 那样随时发起网络请求但在 Timeline 构建阶段getTimeline/timeline你仍然可以进行网络请求来获取最新数据。合理设计网络加载策略是实现时效性要求较高的 Widget如天气、新闻、股价等的关键。本篇将系统介绍 Widget 中网络数据加载的方法、缓存策略和最佳实践。1. Widget 网络请求的时机与限制时机✅getTimeline(in:completion:)/timeline(for:in:)— 系统调用 Timeline 构建时✅getSnapshot(in:completion:)/snapshot(for:in:)— 但不建议做真实网络请求❌ Widget 视图渲染后 — 不可再发起请求❌ Widget Extension 后台 — 没有后台运行权限限制限制说明执行时间~5 秒超时后 Widget 会使用旧 Timeline 或空白内存预算~30MB无 URLSession 后台模式不能使用 background configuration系统调度刷新时机由系统控制非开发者完全可控2. 基础网络请求模式URLSession 回调式兼容 iOS 14funcgetTimeline(incontext:Context,completion:escaping(TimelineWeatherEntry)-Void){leturlURL(string:https://api.weather.com/forecast)!lettaskURLSession.shared.dataTask(with:url){data,response,errorinletentry:WeatherEntryifletdatadata,letweathertry?JSONDecoder().decode(WeatherResponse.self,from:data){entryWeatherEntry(date:Date(),temperature:\(weather.temp)℃,icon:weather.icon)}else{// 网络失败使用缓存或空数据entryWeatherEntry(date:Date(),temperature:--,icon:questionmark)}letnextRefreshCalendar.current.date(byAdding:.minute,value:30,to:Date())!lettimelineTimeline(entries:[entry],policy:.after(nextRefresh))completion(timeline)}task.resume()}async/await 式iOS 17functimeline(forconfiguration:Intent,incontext:Context)async-TimelineWeatherEntry{letentry:WeatherEntrydo{letweathertryawaitfetchWeather()entryWeatherEntry(date:Date(),temperature:\(weather.temp)℃,icon:weather.icon)saveToCache(weather)}catch{entryloadFromCache()??WeatherEntry(date:Date(),temperature:--,icon:questionmark)}letnextRefreshCalendar.current.date(byAdding:.minute,value:30,to:Date())!returnTimeline(entries:[entry],policy:.after(nextRefresh))}3. 缓存策略设计缓存是 Widget 网络加载的核心保障——确保即使网络不可用或超时Widget 也能展示有意义的内容。三级缓存架构Level 1: 内存缓存无Widget 每次重建 Level 2: App Group 共享容器主 App 写入 Widget 读取 Level 3: 硬编码默认值最终的兜底实现主 App 侧写入推荐主 App 具有完整的网络权限可以在前台定时拉取数据写入共享容器// 在主 App 中classWidgetDataManager{staticletsharedWidgetDataManager()privateletcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)funcsyncWeatherData(){Task{do{letweathertryawaitWeatherAPI.fetch()letcacheURLcontainerURL?.appendingPathComponent(weather_cache.json)letdatatryJSONEncoder().encode(weather)trydata.write(to:cacheURL!)// 刷新 WidgetWidgetCenter.shared.reloadTimelines(ofKind:WeatherWidget)}catch{print(Weather sync failed:\(error))}}}}// 在 SceneDelegate 或 App 入口中调用funcsceneDidBecomeActive(_scene:UIScene){WidgetDataManager.shared.syncWeatherData()}Widget 侧读取funcloadWeatherFromCache()-WeatherResponse?{guardletcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)else{returnnil}letcacheURLcontainerURL.appendingPathComponent(weather_cache.json)guardletdatatry?Data(contentsOf:cacheURL),letweathertry?JSONDecoder().decode(WeatherResponse.self,from:data)else{returnnil}returnweather}带过期时间的缓存structCachedDataT:Codable:Codable{letdata:Tlettimestamp:DateletexpiresAt:DatevarisExpired:Bool{Date()expiresAt}}funcsaveToCacheT:Codable(_data:T,ttl:TimeInterval1800){letcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)letcachedCachedData(data:data,timestamp:Date(),expiresAt:Date().addingTimeInterval(ttl))ifleturlcontainerURL?.appendingPathComponent(widget_cache.json),letencodedtry?JSONEncoder().encode(cached){try?encoded.write(to:url)}}funcloadFromCacheT:Codable(_type:T.Type)-T?{letcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)guardleturlcontainerURL?.appendingPathComponent(widget_cache.json),letdatatry?Data(contentsOf:url),letcachedtry?JSONDecoder().decode(CachedDataT.self,from:data),!cached.isExpiredelse{returnnil}returncached.data}4. 网络请求超时和重试funcfetchWithTimeout(timeout:TimeInterval3.0)asyncthrows-WeatherResponse{tryawaitwithThrowingTaskGroup(of:WeatherResponse.self){groupingroup.addTask{letsessionURLSession.sharedletrequestURLRequest(url:weatherURL,cachePolicy:.reloadIgnoringLocalCacheData,timeoutInterval:timeout)let(data,_)tryawaitsession.data(for:request)returntryJSONDecoder().decode(WeatherResponse.self,from:data)}group.addTask{tryawaitTask.sleep(for:.seconds(timeout))throwURLError(.timedOut)}letresulttryawaitgroup.next()!group.cancelAll()returnresult}}5. 错误降级策略functimeline(forconfiguration:Intent,incontext:Context)async-TimelineWeatherEntry{letnowDate()// 优先尝试从网络获取ifletfreshDatatry?awaitfetchWeatherWithTimeout(){saveToCache(freshData)letentryWeatherEntry(date:now,weather:freshData,state:.success)letnextCalendar.current.date(byAdding:.minute,value:30,to:now)!returnTimeline(entries:[entry],policy:.after(next))}// 降级 1使用缓存ifletcachedloadFromCache(WeatherResponse.self){letentryWeatherEntry(date:now,weather:cached,state:.cached)letnextCalendar.current.date(byAdding:.minute,value:10,to:now)!// 缓存过期后更快重试returnTimeline(entries:[entry],policy:.after(next))}// 降级 2展示默认占位内容letplaceholderWeatherEntry(date:now,weather:nil,state:.error(无法加载数据))letnextCalendar.current.date(byAdding:.minute,value:5,to:now)!returnTimeline(entries:[placeholder],policy:.after(next))}6. 最佳实践主 App 优先加载网络请求尽量在主 App 中完成写入共享缓存Widget 只做读取缓存带上时间戳设置合理的 TTL让 Widget 知道何时数据已过期超时设置Widget 中网络请求 timeout 建议设为 3 秒以内灰度降级网络 → 缓存 → 默认值逐级降级不重试Widget 环境下做请求重试意义不大时间限制失败就使用缓存避免重复请求在 Timeline 间隔内不必每次都请求优先使用有效期内的缓存使用后台任务在主 App 中使用BGTaskScheduler定期拉取数据更新缓存// 后台定期更新funcscheduleBackgroundRefresh(){letrequestBGAppRefreshTaskRequest(identifier:com.yourapp.widgetRefresh)request.earliestBeginDateDate(timeIntervalSinceNow:15*60)try?BGTaskScheduler.shared.submit(request)}小结Widget 可以在 Timeline 构建期间发起网络请求但受 5 秒超时限制推荐使用主 App 拉取 → 写缓存 → Widget 读取模式实现三级降级策略网络 → 缓存 → 默认值设置合理的请求超时2-3 秒和缓存 TTL上一篇iOS Widget 开发-15Widget 性能优化指南下一篇iOS Widget 开发-17Widget 错误处理与空状态设计
iOS Widget 开发-16：Widget 网络数据加载策略
虽然 Widget 不能像主 App 那样随时发起网络请求但在 Timeline 构建阶段getTimeline/timeline你仍然可以进行网络请求来获取最新数据。合理设计网络加载策略是实现时效性要求较高的 Widget如天气、新闻、股价等的关键。本篇将系统介绍 Widget 中网络数据加载的方法、缓存策略和最佳实践。1. Widget 网络请求的时机与限制时机✅getTimeline(in:completion:)/timeline(for:in:)— 系统调用 Timeline 构建时✅getSnapshot(in:completion:)/snapshot(for:in:)— 但不建议做真实网络请求❌ Widget 视图渲染后 — 不可再发起请求❌ Widget Extension 后台 — 没有后台运行权限限制限制说明执行时间~5 秒超时后 Widget 会使用旧 Timeline 或空白内存预算~30MB无 URLSession 后台模式不能使用 background configuration系统调度刷新时机由系统控制非开发者完全可控2. 基础网络请求模式URLSession 回调式兼容 iOS 14funcgetTimeline(incontext:Context,completion:escaping(TimelineWeatherEntry)-Void){leturlURL(string:https://api.weather.com/forecast)!lettaskURLSession.shared.dataTask(with:url){data,response,errorinletentry:WeatherEntryifletdatadata,letweathertry?JSONDecoder().decode(WeatherResponse.self,from:data){entryWeatherEntry(date:Date(),temperature:\(weather.temp)℃,icon:weather.icon)}else{// 网络失败使用缓存或空数据entryWeatherEntry(date:Date(),temperature:--,icon:questionmark)}letnextRefreshCalendar.current.date(byAdding:.minute,value:30,to:Date())!lettimelineTimeline(entries:[entry],policy:.after(nextRefresh))completion(timeline)}task.resume()}async/await 式iOS 17functimeline(forconfiguration:Intent,incontext:Context)async-TimelineWeatherEntry{letentry:WeatherEntrydo{letweathertryawaitfetchWeather()entryWeatherEntry(date:Date(),temperature:\(weather.temp)℃,icon:weather.icon)saveToCache(weather)}catch{entryloadFromCache()??WeatherEntry(date:Date(),temperature:--,icon:questionmark)}letnextRefreshCalendar.current.date(byAdding:.minute,value:30,to:Date())!returnTimeline(entries:[entry],policy:.after(nextRefresh))}3. 缓存策略设计缓存是 Widget 网络加载的核心保障——确保即使网络不可用或超时Widget 也能展示有意义的内容。三级缓存架构Level 1: 内存缓存无Widget 每次重建 Level 2: App Group 共享容器主 App 写入 Widget 读取 Level 3: 硬编码默认值最终的兜底实现主 App 侧写入推荐主 App 具有完整的网络权限可以在前台定时拉取数据写入共享容器// 在主 App 中classWidgetDataManager{staticletsharedWidgetDataManager()privateletcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)funcsyncWeatherData(){Task{do{letweathertryawaitWeatherAPI.fetch()letcacheURLcontainerURL?.appendingPathComponent(weather_cache.json)letdatatryJSONEncoder().encode(weather)trydata.write(to:cacheURL!)// 刷新 WidgetWidgetCenter.shared.reloadTimelines(ofKind:WeatherWidget)}catch{print(Weather sync failed:\(error))}}}}// 在 SceneDelegate 或 App 入口中调用funcsceneDidBecomeActive(_scene:UIScene){WidgetDataManager.shared.syncWeatherData()}Widget 侧读取funcloadWeatherFromCache()-WeatherResponse?{guardletcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)else{returnnil}letcacheURLcontainerURL.appendingPathComponent(weather_cache.json)guardletdatatry?Data(contentsOf:cacheURL),letweathertry?JSONDecoder().decode(WeatherResponse.self,from:data)else{returnnil}returnweather}带过期时间的缓存structCachedDataT:Codable:Codable{letdata:Tlettimestamp:DateletexpiresAt:DatevarisExpired:Bool{Date()expiresAt}}funcsaveToCacheT:Codable(_data:T,ttl:TimeInterval1800){letcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)letcachedCachedData(data:data,timestamp:Date(),expiresAt:Date().addingTimeInterval(ttl))ifleturlcontainerURL?.appendingPathComponent(widget_cache.json),letencodedtry?JSONEncoder().encode(cached){try?encoded.write(to:url)}}funcloadFromCacheT:Codable(_type:T.Type)-T?{letcontainerURLFileManager.default.containerURL(forSecurityApplicationGroupIdentifier:group.com.yourapp.widget)guardleturlcontainerURL?.appendingPathComponent(widget_cache.json),letdatatry?Data(contentsOf:url),letcachedtry?JSONDecoder().decode(CachedDataT.self,from:data),!cached.isExpiredelse{returnnil}returncached.data}4. 网络请求超时和重试funcfetchWithTimeout(timeout:TimeInterval3.0)asyncthrows-WeatherResponse{tryawaitwithThrowingTaskGroup(of:WeatherResponse.self){groupingroup.addTask{letsessionURLSession.sharedletrequestURLRequest(url:weatherURL,cachePolicy:.reloadIgnoringLocalCacheData,timeoutInterval:timeout)let(data,_)tryawaitsession.data(for:request)returntryJSONDecoder().decode(WeatherResponse.self,from:data)}group.addTask{tryawaitTask.sleep(for:.seconds(timeout))throwURLError(.timedOut)}letresulttryawaitgroup.next()!group.cancelAll()returnresult}}5. 错误降级策略functimeline(forconfiguration:Intent,incontext:Context)async-TimelineWeatherEntry{letnowDate()// 优先尝试从网络获取ifletfreshDatatry?awaitfetchWeatherWithTimeout(){saveToCache(freshData)letentryWeatherEntry(date:now,weather:freshData,state:.success)letnextCalendar.current.date(byAdding:.minute,value:30,to:now)!returnTimeline(entries:[entry],policy:.after(next))}// 降级 1使用缓存ifletcachedloadFromCache(WeatherResponse.self){letentryWeatherEntry(date:now,weather:cached,state:.cached)letnextCalendar.current.date(byAdding:.minute,value:10,to:now)!// 缓存过期后更快重试returnTimeline(entries:[entry],policy:.after(next))}// 降级 2展示默认占位内容letplaceholderWeatherEntry(date:now,weather:nil,state:.error(无法加载数据))letnextCalendar.current.date(byAdding:.minute,value:5,to:now)!returnTimeline(entries:[placeholder],policy:.after(next))}6. 最佳实践主 App 优先加载网络请求尽量在主 App 中完成写入共享缓存Widget 只做读取缓存带上时间戳设置合理的 TTL让 Widget 知道何时数据已过期超时设置Widget 中网络请求 timeout 建议设为 3 秒以内灰度降级网络 → 缓存 → 默认值逐级降级不重试Widget 环境下做请求重试意义不大时间限制失败就使用缓存避免重复请求在 Timeline 间隔内不必每次都请求优先使用有效期内的缓存使用后台任务在主 App 中使用BGTaskScheduler定期拉取数据更新缓存// 后台定期更新funcscheduleBackgroundRefresh(){letrequestBGAppRefreshTaskRequest(identifier:com.yourapp.widgetRefresh)request.earliestBeginDateDate(timeIntervalSinceNow:15*60)try?BGTaskScheduler.shared.submit(request)}小结Widget 可以在 Timeline 构建期间发起网络请求但受 5 秒超时限制推荐使用主 App 拉取 → 写缓存 → Widget 读取模式实现三级降级策略网络 → 缓存 → 默认值设置合理的请求超时2-3 秒和缓存 TTL上一篇iOS Widget 开发-15Widget 性能优化指南下一篇iOS Widget 开发-17Widget 错误处理与空状态设计
