---
id: ios-widget-extension
title: iOS Widget — WidgetKit + Timeline
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [ios, widget, widgetkit, vibe-coding]
tech_stack: { language: "Swift / WidgetKit / SwiftUI", applicable_to: ["iOS 14+", "macOS"] }
applied_in: []
aliases: [Home Screen Widget, Lock Screen, Timeline, Provider]
---

# iOS Widget (WidgetKit)

> 홈 / 잠금 화면에 표시. **Timeline 기반** — provider 가 시점별 entry list 반환 → OS 가 시간에 맞춰 표시. 메모리 / 실행시간 엄격 제한.

## 📖 핵심 개념
- Widget = Extension target.
- TimelineProvider 가 entries 반환.
- 각 entry = 표시할 시점 + view data.
- OS 가 timeline 끝나면 새로 요청.

## 💻 코드 패턴

### Widget 정의
```swift
import WidgetKit
import SwiftUI

struct StockEntry: TimelineEntry {
    let date: Date
    let symbol: String
    let price: Double
}

struct StockProvider: TimelineProvider {
    func placeholder(in: Context) -> StockEntry {
        StockEntry(date: .now, symbol: "AAPL", price: 0)
    }
    func getSnapshot(in: Context, completion: @escaping (StockEntry) -> Void) {
        completion(.init(date: .now, symbol: "AAPL", price: 175.0))
    }
    func getTimeline(in: Context, completion: @escaping (Timeline<StockEntry>) -> Void) {
        Task {
            let prices = try await fetchHourlyPrices()
            let entries = prices.map { StockEntry(date: $0.time, symbol: "AAPL", price: $0.price) }
            // 다음 fetch 는 1시간 후
            completion(Timeline(entries: entries, policy: .after(.now.addingTimeInterval(3600))))
        }
    }
}

struct StockWidgetView: View {
    let entry: StockEntry
    var body: some View {
        VStack(alignment: .leading) {
            Text(entry.symbol).font(.headline)
            Text("$\(entry.price, specifier: "%.2f")").font(.title)
            Text(entry.date, style: .time).font(.caption)
        }
        .containerBackground(.fill, for: .widget) // iOS 17+
    }
}

@main
struct StockWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(kind: "StockWidget", provider: StockProvider()) { entry in
            StockWidgetView(entry: entry)
        }
        .configurationDisplayName("주가")
        .description("실시간 주가 표시")
        .supportedFamilies([.systemSmall, .systemMedium, .accessoryRectangular])
    }
}
```

### App Group — 메인 앱과 데이터 공유
```swift
let defaults = UserDefaults(suiteName: "group.com.example.app")
defaults?.set(token, forKey: "shared_token")
// Widget extension 에서도 같은 group 접근
```

### Widget refresh trigger
```swift
// 메인 앱에서 데이터 변경 후
WidgetCenter.shared.reloadTimelines(ofKind: "StockWidget")
```

### Interactive widget (iOS 17+)
```swift
struct CounterWidget: View {
    let entry: CounterEntry
    var body: some View {
        VStack {
            Text("\(entry.count)")
            Button(intent: IncrementIntent()) { Image(systemName: "plus") }
        }
    }
}

struct IncrementIntent: AppIntent {
    static var title: LocalizedStringResource = "Increment"
    func perform() async throws -> some IntentResult {
        await Counter.shared.increment()
        return .result()
    }
}
```

## 🤔 의사결정 기준
| 표시 | family |
|---|---|
| 단일 정보 | systemSmall |
| 차트 / list | systemMedium / Large |
| 잠금 화면 (iOS 16+) | accessoryRectangular / accessoryCircular |
| Live Activity | 별도 (ActivityKit) |
| 사용자 설정 가능 (intent) | IntentConfiguration |

## ❌ 안티패턴
- **Widget 안에서 무거운 fetch 동기 호출**: 시간 초과 → 빈 표시.
- **timeline policy `.never`**: 영원히 안 갱신. `.atEnd` 또는 `.after`.
- **너무 잦은 reload**: OS 가 budget 제한. 의미 있는 변화만.
- **App Group 미설정**: 메인 앱 데이터 못 봄.
- **deep link URL handler 없음**: 위젯 탭 시 메인 앱 못 열림. widgetURL.
- **거대 image**: 메모리 한계. 작게 + caching.
- **dark/light mode 무시**: 한쪽만 보임. SwiftUI 자동.

## 🤖 LLM 활용 힌트
- App Group + WidgetCenter.reloadTimelines + intent 권장.
- iOS 17+ interactive widget 는 AppIntent.

## 🔗 관련 문서
- [[iOS_Live_Activities]]
- [[iOS_Background_Tasks]]