feat: 小组件

Author: OHeroJ

docs/.vuepress/config/sidebarConf.js

@@ -75,7 +75,8 @@ module.exports = {
         {
             title: "iOS",
             collapsable: false,
-            children: ["", "t1-pod-webp", "t2-youhua", "pod-wechat", "ios-build-cers", "XCFramework", "ios-webkit", "widgetkit-1"],
+            children: ["", "t1-pod-webp", "t2-youhua", "pod-wechat", "ios-build-cers", "XCFramework", 
+                "ios-webkit", "widgetkit-1", "widgetkit-2"],
         },
     ],
     "/swift/better/": [

docs/swift/ios/widgetkit-2.md

@@ -0,0 +1,107 @@
+---
+sitemap:
+  exclude: false
+  changefreq: hourly
+title: 'iOS 小组件开发之核心方法调用时机'
+date: 2024-10-22
+tags:
+- swift
+- ios
+- widgetkit
+---
+
+在开发 **iOS 小组件 (Widget)** 时，`placeholder`、`getSnapshot` 和 `getTimeline` 是 **WidgetKit** 的核心方法，它们的调用时机关系到组件的**加载状态**和**数据刷新**流程。下面是详细说明它们的调用时机及作用：
+
+---
+
+## **1. placeholder 的调用时机**  
+`placeholder` 方法用于**占位内容**，即小组件在加载完成前展示的默认视图。
+
+- **什么时候调用？**  
+  - 在小组件刚添加到主屏幕时。
+  - 系统或 Widget 需要**快速展示**内容（通常在数据尚未加载时）。
+  - 在 **Widget 预览模式**（如用户在添加小组件时浏览不同尺寸的预览）。
+
+- **适用场景：**
+  - 使用占位符数据来显示小组件的基本布局，不需要实际数据。
+
+**示例代码：**
+```swift
+func placeholder(in context: Context) -> SimpleEntry {
+    SimpleEntry(date: Date(), message: "加载中...")
+}
+```
+
+---
+
+## **2. getSnapshot 的调用时机**  
+`getSnapshot` 方法用于生成**静态快照**，即当系统需要**快速加载和展示**当前视图时使用。  
+- **什么时候调用？**  
+  - 当用户**查看小组件的预览**（例如在主屏幕上长按时）。
+  - 当系统**无法立即获取完整数据**，需要快速显示快照。
+
+- **特点：**  
+  - 该方法的执行速度需要尽量**快**，通常返回**最近一次的缓存数据**。
+  - 在一些静态内容的小组件中，`getSnapshot` 可能会频繁调用。
+
+**示例代码：**
+```swift
+func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> Void) {
+    let entry = SimpleEntry(date: Date(), message: "快照数据")
+    completion(entry)
+}
+```
+
+---
+
+## **3. getTimeline 的调用时机**  
+`getTimeline` 是**核心数据更新方法**，用于生成一系列的时间条目 (`TimelineEntry`)，并决定小组件**何时刷新**。
+
+- **什么时候调用？**  
+  - **首次加载**小组件时。
+  - **定时刷新**，由你通过时间表或策略 (`Timeline`) 控制刷新频率。
+  - 在**用户交互或系统事件触发**刷新时。
+
+- **特点：**
+  - 你可以通过设置**刷新策略**（如固定时间间隔、到期后刷新等）来控制更新频率。
+  - 合理控制刷新时间非常重要，频繁更新会影响性能和耗电量。
+
+**示例代码：**
+```swift
+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`    | 数据刷新或系统定时触发时                            | 生成时间表并决定何时刷新数据            |
+
+---
+
+通过合理使用这三个方法，你可以确保小组件**快速加载、平滑更新**，并在**性能与电量**之间取得良好平衡。