widget-live-activity

Widget / Live Activity / 动态岛

架构概览

特性	最低版本	框架	运行环境
主屏幕 Widget	iOS 14+	WidgetKit	独立进程
锁屏 Widget	iOS 16+	WidgetKit	独立进程
Live Activity	iOS 16.1+	ActivityKit	主 App 进程
Dynamic Island	iOS 16.1+	ActivityKit	主 App 进程

核心区别：

• Widget 是独立 Extension 进程，与主 App 不共享内存
• Live Activity / Dynamic Island 运行在主 App 进程内
• Widget 必须用 SwiftUI，不支持 UIKit
• Live Activity 的 UI 也必须用 SwiftUI

---

Widget 开发

创建 Widget Extension

• Xcode → File → New → Target → Widget Extension
• 勾选 "Include Live Activity" 可同时生成 Live Activity 模板
• Widget Extension 有独立 Bundle ID：com.app.WidgetExtension

目录结构

WidgetExtension/
├── WidgetExtension.swift        # 入口 + Provider + Widget View
├── WidgetExtensionBundle.swift  # Bundle（多个 Widget 时）
├── Assets.xcassets
└── Info.plist

基本结构

import WidgetKit
import SwiftUI

struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), title: "示例标题", value: "示例值")
    }

    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> Void) {
        completion(SimpleEntry(date: Date(), title: "快照标题", value: "快照值"))
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<SimpleEntry>) -> Void) {
        let currentDate = Date()
        let entry = SimpleEntry(date: currentDate, title: "实时标题", value: "实时值")

        let nextUpdate = Calendar.current.date(byAdding: .minute, value: 30, to: currentDate)!
        let timeline = Timeline(entries: [entry], policy: .after(nextUpdate))
        completion(timeline)
    }
}

struct SimpleEntry: TimelineEntry {
    let date: Date
    let title: String
    let value: String
}

struct WidgetEntryView: View {
    let entry: SimpleEntry

    var body: some View {
        VStack(alignment: .leading, spacing: 4) {
            Text(entry.title)
                .font(.headline)
            Text(entry.value)
                .font(.subheadline)
                .foregroundColor(.secondary)
        }
        .padding()
    }
}

struct AppWidget: Widget {
    let kind: String = "AppWidget"

    var body: some WidgetConfiguration {
        StaticConfiguration(kind: kind, provider: Provider()) { entry in
            WidgetEntryView(entry: entry)
        }
        .configurationDisplayName("我的小组件")
        .description("显示最新数据")
        .supportedFamilies([.systemSmall, .systemMedium])
    }
}