2nd/10_Wiki/Topics/Coding/iOS_Widget_Extension.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
ios-widget-extension	iOS Widget — WidgetKit + Timeline	Coding	draft	B	conceptual	2026-05-09	2026-05-09	ios widget widgetkit vibe-coding	language applicable_to Swift / WidgetKit / SwiftUI iOS 14+ macOS		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 정의

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 — 메인 앱과 데이터 공유

let defaults = UserDefaults(suiteName: "group.com.example.app")
defaults?.set(token, forKey: "shared_token")
// Widget extension 에서도 같은 group 접근

Widget refresh trigger

// 메인 앱에서 데이터 변경 후
WidgetCenter.shared.reloadTimelines(ofKind: "StockWidget")

Interactive widget (iOS 17+)

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