[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,139 @@
+---
+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]]