在开发 iOS 小组件 (Widget) 时，placeholder、getSnapshot 和 getTimeline 是 WidgetKit 的核心方法，它们的调用时机关系到组件的加载状态和数据刷新流程。下面是详细说明它们的调用时机及作用：

---

1. placeholder 的调用时机

placeholder 方法用于占位内容，即小组件在加载完成前展示的默认视图。

• 什么时候调用？

  • 在小组件刚添加到主屏幕时。
  • 系统或 Widget 需要快速展示内容（通常在数据尚未加载时）。
  • 在 Widget 预览模式（如用户在添加小组件时浏览不同尺寸的预览）。

• 适用场景：

  • 使用占位符数据来显示小组件的基本布局，不需要实际数据。

示例代码：

func placeholder(in context: Context) -> SimpleEntry {
    SimpleEntry(date: Date(), message: "加载中...")
}

---

2. getSnapshot 的调用时机

getSnapshot 方法用于生成静态快照，即当系统需要快速加载和展示当前视图时使用。

• 什么时候调用？

  • 当用户查看小组件的预览（例如在主屏幕上长按时）。
  • 当系统无法立即获取完整数据，需要快速显示快照。

• 特点：

  • 该方法的执行速度需要尽量快，通常返回最近一次的缓存数据。
  • 在一些静态内容的小组件中，getSnapshot 可能会频繁调用。

示例代码：

func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> Void) {
    let entry = SimpleEntry(date: Date(), message: "快照数据")
    completion(entry)
}

---

3. getTimeline 的调用时机

getTimeline 是核心数据更新方法，用于生成一系列的时间条目 (TimelineEntry)，并决定小组件何时刷新。

• 什么时候调用？

  • 首次加载小组件时。
  • 定时刷新，由你通过时间表或策略 (Timeline) 控制刷新频率。
  • 在用户交互或系统事件触发刷新时。

• 特点：

  • 你可以通过设置刷新策略（如固定时间间隔、到期后刷新等）来控制更新频率。
  • 合理控制刷新时间非常重要，频繁更新会影响性能和耗电量。

示例代码：

func getTimeline(in context: Context, completion: @escaping (Timeline<SimpleEntry>) -> Void) {
    let currentDate = Date()
    let nextUpdate = Calendar.current.date(byAdding: .minute, value: 15, to: currentDate)!
    
    let entry = SimpleEntry(date: currentDate, message: "最新数据")
    let timeline = Timeline(entries: [entry], policy: .after(nextUpdate))
    
    completion(timeline)
}

---

调用顺序与流程图

1. 首次加载小组件：

   • 调用 placeholder 显示占位内容 → 调用 getSnapshot 展示快照 → 调用 getTimeline 获取完整数据并更新。

2. 用户查看预览或长按：

   • 调用 getSnapshot 快速加载当前状态。

3. 定时或事件触发更新：

   • 调用 getTimeline 更新数据并生成新的时间表。

---

总结

方法	调用时机	作用
placeholder	小组件加载或预览时	展示基本布局的占位符，不含实际数据
getSnapshot	预览模式或需要快速展示内容时	提供当前状态的快照，速度快，使用缓存数据
getTimeline	数据刷新或系统定时触发时	生成时间表并决定何时刷新数据

---

通过合理使用这三个方法，你可以确保小组件快速加载、平滑更新，并在性能与电量之间取得良好平衡。

贡献者: laijihua