Antigravity Agent
140 lines
4.3 KiB
Markdown
140 lines
4.3 KiB
Markdown
---
|
|
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]]
|