[Swift] D-Day 위젯 만들기 (1)

 

 

 

iOS에서 '위젯'이라는 개념은 생각보다 오래됐다.
다만 사용자에게 노출되는 모습과 개발자가 다루는 기술 스택은 크게 두 번 바뀌었다.

이번 글에서는 위젯의 흐름을 간단히 짚고, 왜 지금은 SwiftUI 기반의 WidgetKit으로 개발해야 하는지를 정리한 뒤,
예제로 D-Day 위젯을 구현하는 순서를 단계별로 살펴보려고 한다.

 

 

 

iOS 위젯의 변화와 WidgetKit의 등장

1. Today Extension 시절(iOS 8 ~ iOS 13)
초기 위젯은 Notification Center의 Today View에 존재했다.
이 때의 위젯은
- Today Extension 이라는 별도의 타깃으로 구현
- UIKit + AutoLayout + Storyboard 기반
- 앱과의 연동도 지금보다 제약이 많고, UI 자유도는 있었지만 시스템 통합 경험은 제한적

무엇보다, 홈 화면에 올려놓는 형태가 아니라 '알림센터 한 켠'에 있는 부가 기능 정도였다.

 

2. WidgetKit도입(iOS 14~)
iOS 14부터 애플은 위젯을 홈 화면의 First-class로 끌어올렸다.
- 홈 화면 어디든 배치 가능
- 다양한 사이즈(Small / Medium / Large, 이후 iOS 15+, 16+에서 더 확장)

이 시점에서 위젯 구현 방식도 완전히 바뀌게 됐다.
- UIKit 기반 Today Extension → SwiftUI 기반 WidgetKit
- UI는 전부 SwiftUI View로만 작성
- 업데이트는 이벤트 기반이 아니라 Timeline 기반의 '스냅샷 렌더링' 구조

이제 iOS에서 '위젯을 만든다'는 WidgetKit + SwiftUI로 개발한다는 의미다.

 

---

 

WidgetKit의 설계 철학: 왜 SwiftUI만 허용할까?

WidgetKit의 핵심은 아래 두 가지로 요약된다.

1. 정적이고 예측 가능한 UI
위젯은 사용자가 직접 상호작용하는 화면이라기 보다,
시스템이 정한 간격과 규칙에 따라 노출되는 '정보 카드'에 가깝다.
따라서 앱처럼 복잡한 뷰 계층, 애니메이션, 제스처가 주인공이 아니다.

2. Timeline 기반 렌더링
WidgetKit은 '언제, 어떤 데이터로 위젯을 업데이트할지'를 미리 정한 타임라인(Timeline)을 넘겨받고,
그 시점마다 SwiftUI View를 렌더링하여 화면에 그려준다.


이때 SwiftUI는
- 선언형 UI이기 때문에 현재 상태 → 뷰로 매핑하기 좋고
- 재렌더링 시 시스템이 비용을 예측하기 쉽고
- 사이드 이펙트가 통제되기 때문에

WidgetKit의 '스냅샷 기반 렌더링' 모델과 잘 맞는다.
반대로 UIKit은 라이프사이클과 상태가 복잡하기 때문에 위 구조와 맞지 않아 위젯에서는 아예 사용이 금지된다.

 

---

D-Day 위젯을 예제로 아키텍처잡기

간단하게 만들어 볼 위젯의 기능
① 사용자가 앱에서 '기념일 제목 + 날짜'를 설정
② 홈 화면에서
    - D-3, D-day, D+2와 같이 남은/지난 날짜 표시
    - 기념일 날짜, 제목 함께 노출
③ 자정이 지날 때마다 자동으로 D-Day 숫자가 바뀜
④ 위젯을 탭하면 앱의 D-Day 설정 화면으로 이동

개발 순서
① 기본 프로젝트 + Widget Extension 생성
② 공용 데이터 저장소(App Group + UserDefaults) 설계
③ D-Day 도메인 모델 및 날짜 계산 로직 구현
④ TimelineProvider / Entry 구현
⑤ SwiftUI로 위젯 UI 구성
⑥ 앱에서 설정 변경 시 위젯 갱신 연동(WidgetCenter)
⑦ 실기기/시뮬레이터에서 위젯 추가 및 동작 검증

---

1단계 – Widget Extension 생성

1. Xcode에서
- File > New > Target…
- iOS 탭에서 Widget Extension 선택

2. 이름 예: DDayWidget
3. SwiftUI + WidgetKit 기반 템플릿이 생성된다.

생성 후 프로젝트 구조:
- DDayWidget.swift (위젯 정의)
- DDayWidgetExtension 타깃
- 기본 Provider / Entry / View 코드

(여기서 기존 개발하던 프로젝트가 UIKit 기반이라도 상관없음! 타겟만 추가하면 됨)

(추가하면 이렇게 자동으로 예시 파일과 함께 생성됨)

2단계 - App Group + 공유 저장소 설계

앱과 위젯은 서로 다른 프로세스이기 때문에, 데이터를 직접 공유할 수 없다.
애플은 이를 위해 App Groups라는 공유 컨테이너를 제공하고 있다.


App Group 설정

1. 앱 타겟 → Signing & Capabilities → + Capability → App Groups 추가
2. Widget 타깃에도 동일하게 App Groups 추가
3. ex) group.com.yegrcompany.ddaywidget 생성 후, 두 타깃 모두 체크


공유 UserDefaults 래퍼

enum SharedStore {
    static let suiteName = "group.com.yegrcompany.ddaywidget"

    static var defaults: UserDefaults? {
        UserDefaults(suiteName: suiteName)
    }
}

struct DDayConfig: Codable {
    let title: String
    let targetDate: Date
}

extension SharedStore {
    private static let key = "dday_config"

    static func save(config: DDayConfig) {
        guard let data = try? JSONEncoder().encode(config) else { return }
        defaults?.set(data, forKey: key)
    }

    static func loadConfig() -> DDayConfig? {
        guard
            let data = defaults?.data(forKey: key),
            let config = try? JSONDecoder().decode(DDayConfig.self, from: data)
        else { return nil }

        return config
    }
}

- 앱에서는 D-Day 설정 화면에서 save(config:) 호출
- 위젯에서는 loadConfig()로 읽어서 화면에 반영

 

3단계 - D-Day 날짜 계산 로직

위젯의 핵심 도메인은 결국 '오늘과 목표일의 일(day) 단위 차이'이다.

- 날짜 차이 계산 로직

struct DDayInfo {
    let config: DDayConfig
    let dayDiff: Int   // 오늘 기준 날짜 차이
}

func calculateDDay(target: Date, now: Date = Date()) -> Int {
    let calendar = Calendar.current
    let startOfToday = calendar.startOfDay(for: now)
    let startOfTarget = calendar.startOfDay(for: target)

    // (오늘 → 타겟) 기준 차이
    let diff = calendar.dateComponents([.day], from: startOfToday, to: startOfTarget).day ?? 0
    return diff
}

func formattedDDayString(dayDiff: Int) -> String {
    switch dayDiff {
    case 0:
        return "D-Day"
    case let d where d > 0:
        return "D-\(d)"
    default:
        return "D+\(abs(dayDiff))"
    }
}

 

• diff > 0 → 타겟이 미래 → D-3
• diff == 0 → 오늘이 바로 그 날 → D-Day
• diff < 0 → 타겟이 과거 → D+2

 

4단계 - TimelineProvider & Entry 구현

WidgetKit은 타임라인에 따라 위젯을 갱신한다.
여기서 '자정마다 다시 계산해서 그려달라'는 타임라인을 넘겨주면 된다.

- Entry 정의

import WidgetKit
import SwiftUI

struct DDayEntry: TimelineEntry {
    let date: Date            // 위젯 상태 기준 시간
    let config: DDayConfig?   // 저장된 설정 (없을 수도 있음)
    let dayDiff: Int          // 계산된 날짜 차이
}

 

- Provider 구현

struct DDayProvider: TimelineProvider {
    func placeholder(in context: Context) -> DDayEntry {
        DDayEntry(
            date: Date(),
            config: DDayConfig(title: "기념일", targetDate: Date()),
            dayDiff: 0
        )
    }

    func getSnapshot(in context: Context, completion: @escaping (DDayEntry) -> Void) {
        let config = SharedStore.loadConfig()
        let target = config?.targetDate ?? Date()
        let diff = calculateDDay(target: target)

        let entry = DDayEntry(date: Date(), config: config, dayDiff: diff)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<DDayEntry>) -> Void) {
        let now = Date()
        let config = SharedStore.loadConfig()
        let target = config?.targetDate ?? now
        let diff = calculateDDay(target: target, now: now)

        let entry = DDayEntry(date: now, config: config, dayDiff: diff)

        // 다음 자정 시간 계산
        let calendar = Calendar.current
        let nextMidnight = calendar.nextDate(
            after: now,
            matching: DateComponents(hour: 0, minute: 0, second: 0),
            matchingPolicy: .nextTime
        )

        let timeline: Timeline<DDayEntry>
        if let next = nextMidnight {
            timeline = Timeline(entries: [entry], policy: .after(next))
        } 
        else {
            // 계산 실패 시 일단 고정
            timeline = Timeline(entries: [entry], policy: .never)
        }

        completion(timeline)
    }
}

여기서 포인트는
- 위젯이 '실시간'으로 돌아가는 것이 아니라, 
   '지금 상태를 나타내는 Entry를 하나 넘겨주고, 다음에 언제 다시 불러줄지(timeline policy)를 알려주는 구조'라는 것
- D-Day의 경우 날짜 단위로만 변하면 되므로, 자정마다 다시 호출되도록 타임라인을 구성한다는 점



5단계 - SwiftUI로 위젯 UI 구성

이제 Entry에 담긴 데이터를 바탕으로 SwiftUI로 UI를 그린다.

struct DDayWidgetView: View {
    var entry: DDayProvider.Entry

    var body: some View {
        ZStack {
            LinearGradient(
                gradient: Gradient(colors: [.blue.opacity(0.8), .purple]),
                startPoint: .topLeading,
                endPoint: .bottomTrailing
            )

            VStack(alignment: .leading, spacing: 4) {
                Text(entry.config?.title ?? "D-Day 미설정")
                    .font(.headline)
                    .foregroundColor(.white)

                Text(formattedDDayString(dayDiff: entry.dayDiff))
                    .font(.system(size: 32, weight: .bold))
                    .foregroundColor(.white)

                if let target = entry.config?.targetDate {
                    Text(target, style: .date)
                        .font(.caption)
                        .foregroundColor(.white.opacity(0.9))
                }
            }
            .padding()
        }
    }
}

 

위젯 정의

@main
struct DDayWidget: Widget {
    let kind: String = "DDayWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: DDayProvider()) { entry in
            DDayWidgetView(entry: entry)
        }
        .configurationDisplayName("D-Day 위젯")
        .description("중요한 날을 홈 화면에서 바로 확인하세요.")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}

 

 

 

6단계 - 앱과 위젯의 연동(WidgetCenter)

앱에서 사용자가 기념일을 바꿨다면, 위젯도 그 사실을 알아야 한다.

1. 앱에서 새로운 D-Day 설정 저장
2. App Group(UserDefaults)에 DDayConfig 저장
3. WidgetCenter를 통해 위젯 타임라인 리로드 요청

앱에서 연동

import WidgetKit

func updateDDay(title: String, date: Date) {
    let config = DDayConfig(title: title, targetDate: date)
    SharedStore.save(config: config)

    // 위젯 타임라인 새로고침 요청
    WidgetCenter.shared.reloadAllTimelines()
}

이게 위젯 입장에서는 다음 타임라인 요청 시점에 최신 설정을 읽어가게 되는 구조다.



7단계 - 실제 기기에서 위젯 테스트

1. 앱 + 위젯 타깃이 모두 포함된 스킴으로 빌드
2. 실기기 또는 시뮬레이터 홈 화면에서:
    - 홈 화면 길게 터치 → '위젯 추가'
    - DDayWidget 검색 후 추가
3. 앱에서 D-Day 설정 변경 → 홈 화면의 위젯이 정상적으로 갱신되는지 확인

자정 변화 테스트는 시간을 바꾸거나, 임시로 timeline policy를 짧게 설정해서 검증하고,
실제 배포 전에는 자정 기준으로 되돌리는 식으로 진행할 수 있다.

 

---

이번 글에서는 아래 흐름으로 iOS 위젯 개발을 정리해봤다.

- 왜 위젯은 이제 SwiftUI로만 개발이 되는가?
    - WidgetKit 도입 배경과 Today Extension과의 차이
- D-Day 위젯을 예제로 위젯 구조 설계
    - App Group 기반 데이터 공유
    - 날짜 계산 도메인 로직
    - TimelineProvider / Entry / SwiftUI View
- 앱과 위젯 연동까지 포함한 end-to-end 개발 순서

다음에는
- 여러 개의 D-Day를 관리하는 다중 위젯
- Intent 기반으로 사용자가 위젯마다 다른 기념일을 지정하는 구조
- 잠금 화면 위젯 / StandBy 모드 대응
- HealthKit 걸음 수 위젯

와 같은 주제로 정리해보려고 한다.