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 14+）

func getTimeline(in context: Context, completion: @escaping (Timeline<WeatherEntry>) -> Void) {
    let url = URL(string: "https://api.weather.com/forecast")!

    let task = URLSession.shared.dataTask(with: url) { data, response, error in
        let entry: WeatherEntry

        if let data = data, let weather = try? JSONDecoder().decode(WeatherResponse.self, from: data) {
            entry = WeatherEntry(date: Date(), temperature: "\(weather.temp)℃", icon: weather.icon)
        } else {
            // 网络失败，使用缓存或空数据
            entry = WeatherEntry(date: Date(), temperature: "--", icon: "questionmark")
        }

        let nextRefresh = Calendar.current.date(byAdding: .minute, value: 30, to: Date())!
        let timeline = Timeline(entries: [entry], policy: .after(nextRefresh))
        completion(timeline)
    }
    task.resume()
}

async/await 式（iOS 17+）

func timeline(for configuration: Intent, in context: Context) async -> Timeline<WeatherEntry> {
    let entry: WeatherEntry

    do {
        let weather = try await fetchWeather()
        entry = WeatherEntry(date: Date(), temperature: "\(weather.temp)℃", icon: weather.icon)
        saveToCache(weather)
    } catch {
        entry = loadFromCache() ?? WeatherEntry(date: Date(), temperature: "--", icon: "questionmark")
    }

    let nextRefresh = Calendar.current.date(byAdding: .minute, value: 30, to: Date())!
    return Timeline(entries: [entry], policy: .after(nextRefresh))
}

---

3. 缓存策略设计

缓存是 Widget 网络加载的核心保障------确保即使网络不可用或超时，Widget 也能展示有意义的内容。

三级缓存架构

Level 1: 内存缓存（无，Widget 每次重建）
 
Level 2: App Group 共享容器（主 App 写入 + Widget 读取）
 
Level 3: 硬编码默认值（最终的兜底）

实现主 App 侧写入（推荐）

主 App 具有完整的网络权限，可以在前台定时拉取数据写入共享容器：

// 在主 App 中
class WidgetDataManager {
    static let shared = WidgetDataManager()

    private let containerURL = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.yourapp.widget"
    )

    func syncWeatherData() {
        Task {
            do {
                let weather = try await WeatherAPI.fetch()
                let cacheURL = containerURL?.appendingPathComponent("weather_cache.json")
                let data = try JSONEncoder().encode(weather)
                try data.write(to: cacheURL!)

                // 刷新 Widget
                WidgetCenter.shared.reloadTimelines(ofKind: "WeatherWidget")
            } catch {
                print("Weather sync failed: \(error)")
            }
        }
    }
}

// 在 SceneDelegate 或 App 入口中调用
func sceneDidBecomeActive(_ scene: UIScene) {
    WidgetDataManager.shared.syncWeatherData()
}

Widget 侧读取

func loadWeatherFromCache() -> WeatherResponse? {
    guard let containerURL = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.yourapp.widget"
    ) else { return nil }

    let cacheURL = containerURL.appendingPathComponent("weather_cache.json")
    guard let data = try? Data(contentsOf: cacheURL),
          let weather = try? JSONDecoder().decode(WeatherResponse.self, from: data) else {
        return nil
    }
    return weather
}

带过期时间的缓存

struct CachedData<T: Codable>: Codable {
    let data: T
    let timestamp: Date
    let expiresAt: Date

    var isExpired: Bool { Date() > expiresAt }
}

func saveToCache<T: Codable>(_ data: T, ttl: TimeInterval = 1800) {
    let containerURL = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.yourapp.widget"
    )
    let cached = CachedData(data: data, timestamp: Date(), expiresAt: Date().addingTimeInterval(ttl))
    if let url = containerURL?.appendingPathComponent("widget_cache.json"),
       let encoded = try? JSONEncoder().encode(cached) {
        try? encoded.write(to: url)
    }
}

func loadFromCache<T: Codable>(_ type: T.Type) -> T? {
    let containerURL = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.yourapp.widget"
    )
    guard let url = containerURL?.appendingPathComponent("widget_cache.json"),
          let data = try? Data(contentsOf: url),
          let cached = try? JSONDecoder().decode(CachedData<T>.self, from: data),
          !cached.isExpired else {
        return nil
    }
    return cached.data
}

---

4. 网络请求超时和重试

func fetchWithTimeout(timeout: TimeInterval = 3.0) async throws -> WeatherResponse {
    try await withThrowingTaskGroup(of: WeatherResponse.self) { group in
        group.addTask {
            let session = URLSession.shared
            let request = URLRequest(url: weatherURL, cachePolicy: .reloadIgnoringLocalCacheData, timeoutInterval: timeout)
            let (data, _) = try await session.data(for: request)
            return try JSONDecoder().decode(WeatherResponse.self, from: data)
        }

        group.addTask {
            try await Task.sleep(for: .seconds(timeout))
            throw URLError(.timedOut)
        }

        let result = try await group.next()!
        group.cancelAll()
        return result
    }
}

---

5. 错误降级策略

func timeline(for configuration: Intent, in context: Context) async -> Timeline<WeatherEntry> {
    let now = Date()

    // 优先尝试从网络获取
    if let freshData = try? await fetchWeatherWithTimeout() {
        saveToCache(freshData)
        let entry = WeatherEntry(date: now, weather: freshData, state: .success)
        let next = Calendar.current.date(byAdding: .minute, value: 30, to: now)!
        return Timeline(entries: [entry], policy: .after(next))
    }

    // 降级 1：使用缓存
    if let cached = loadFromCache(WeatherResponse.self) {
        let entry = WeatherEntry(date: now, weather: cached, state: .cached)
        let next = Calendar.current.date(byAdding: .minute, value: 10, to: now)!  // 缓存过期后更快重试
        return Timeline(entries: [entry], policy: .after(next))
    }

    // 降级 2：展示默认占位内容
    let placeholder = WeatherEntry(date: now, weather: nil, state: .error("无法加载数据"))
    let next = Calendar.current.date(byAdding: .minute, value: 5, to: now)!
    return Timeline(entries: [placeholder], policy: .after(next))
}

---

6. 最佳实践

1. 主 App 优先加载：网络请求尽量在主 App 中完成，写入共享缓存，Widget 只做读取
2. 缓存带上时间戳：设置合理的 TTL，让 Widget 知道何时数据已过期
3. 超时设置：Widget 中网络请求 timeout 建议设为 3 秒以内
4. 灰度降级：网络 → 缓存 → 默认值，逐级降级
5. 不重试：Widget 环境下做请求重试意义不大（时间限制），失败就使用缓存
6. 避免重复请求：在 Timeline 间隔内不必每次都请求，优先使用有效期内的缓存
7. 使用后台任务 ：在主 App 中使用 BGTaskScheduler 定期拉取数据更新缓存

// 后台定期更新
func scheduleBackgroundRefresh() {
    let request = BGAppRefreshTaskRequest(identifier: "com.yourapp.widgetRefresh")
    request.earliestBeginDate = Date(timeIntervalSinceNow: 15 * 60)
    try? BGTaskScheduler.shared.submit(request)
}

---

小结

• Widget 可以在 Timeline 构建期间发起网络请求，但受 5 秒超时限制
• 推荐使用"主 App 拉取 → 写缓存 → Widget 读取"模式
• 实现三级降级策略：网络 → 缓存 → 默认值
• 设置合理的请求超时（2-3 秒）和缓存 TTL

---

上一篇 ：iOS Widget 开发-15：Widget 性能优化指南
下一篇 ：iOS Widget 开发-17：Widget 错误处理与空状态设计