简介：一份面向iOS开发者的灵动岛动画小组件实战源码包，定位解决“灵动岛区域小组件如何播放动画”的实际问题，适合了解SwiftUI语法、希望进阶WidgetKit动画开发的读者，也可作为课程设计或面试作品参考。资源以WidgetKit与SwiftUI为核心，提供完整Xcode工程，覆盖小组件扩展创建、动画API编写、数据源绑定、更新频率控制，以及与系统通知动画协调等关键实现；案例中更包含动图素材与音频演示工程，并梳理了小组件属性与AppIntent交互入口，方便逐项对照验证动画效果。包内共64个文件，以swift源码、json配置文件、plist属性列表、png图片和gif动图素材为主，压缩后总大小仅847KB，结构清晰，便于按需检索与复用。当前已有388人学习下载；借助这份工程可以快速掌握灵动岛组件的动画搭建思路，改造示例并迁移到自己的设计中。

1. 灵动岛动画不是“播放视频”：先想清楚你要哪种“动”

做灵动岛动画小组件，最常翻车的不是代码写不出来，而是概念一开始就错了。很多人以为“动画”= 放一个 GIF、播放一段 Lottie、或者像 App 里那样UIView.animate无限循环——这套思维放到灵动岛上，第一天就会被系统按在地上摩擦。灵动岛上的“小组件”实际是 Live Activity（实时活动），它的渲染机制不是视频播放器，而是“状态机”：你提供给系统的不是一个动画文件，而是一连串带时间戳的视图状态，系统按自己的调度节奏把这些状态渲染出来。所以你要回答的第一个问题不是“用什么动画库”，而是“我这个动画，到底是要进度数字蹦一蹦，还是圆圈转起来，还是文本跑马灯”。想清楚这件事，再去谈 WidgetKit 和 ActivityKit 的配置，你才不会在“动画为什么不动”的排查里耗掉一整天。这篇文章按我做灵动岛动画的真实流程来：先讲机制，再讲最小代码，接着给参数，最后把最常见的坑一次说完。

2. 灵动岛动画的底层机制：为什么它是“状态机”而不是“播放器”

2.1 灵动岛上的“小组件”其实是 Live Activity，不是普通 Widget

先纠正一个高频误解：普通的 WidgetKit 小组件（Widget）是无法上灵动岛的。灵动岛展示的是通过 ActivityKit 启动的 Live Activity，它在锁屏和灵动岛上各有三种展示形态。你用 Widget Extension 写了个Text("hello")，然后跑到灵动岛上找它——找不到的，这是很多新手第一天的真实体验。

我一般这样理解：普通 Widget 是“定时器驱动的快照”，系统觉得该刷新就生成一张新视图；Live Activity 则是“活动驱动的状态流”，它有一个Attributes（静态信息）和一个ContentState（动态状态），App 通过Activity.request启动，之后可以在合适时机update它的状态。灵动岛动画小组件的“动画”，本质上就是ContentState里的值发生变化时，SwiftUI 在两次渲染之间做的过渡。

这就带出一个关键结论：你不应该在灵动岛里做“持续播放 10 秒的动画”，而应该做“随状态变化而平滑过渡的视觉效果”。想要进度条从 10% 走到 80%，不是播放一段进度条动画，而是构造 70 个不同progress值的 timeline 条目，排好时间让系统依次渲染。

2.2 三种展示形态：compact、minimal、expanded 对动画的约束

Live Activity 在灵动岛上有三种形态，动画设计的第一件事就是搞清楚你的小组件会以哪种形态出现：

你写DynamicIsland的 builder 时，系统会要求你分别实现compactLeading、compactTrailing、minimal、expanded这几个分支。很多人的动画动不了，是因为把动画代码只写在expanded分支里，但用户默认看到的是 compact 形态。我习惯先把核心信息放到 compactLeading 和 compactTrailing，比如左侧显示“快递”“外卖”这类活动名，右侧显示数字进度；把真正的“大动画”（进度条 + 百分比）放到 expanded 分支。这样用户不展开也能看到数字在跳，展开后有完整的动画体验。

2.3 系统节流：灵动岛动画为什么做不到 60fps

这是最容易让 App 开发者心态爆炸的一点：灵动岛动画不保证 60fps。普通 App 里withAnimation一写，Core Animation 自己跑完整个过渡，流畅顺滑；但 Live Activity 的渲染是由系统的“预算机制”控制的。iOS 会根据 App 是否在前台、设备状态、用户是否在锁屏等条件，决定你这份 Timeline 能被多大程度地密集渲染。简单说：你想让它每秒更新 30 帧，系统可能只允许它在关键状态变化时更新几次。

官方给的 Live Activity 更新频率限制很明确，常规场景下你的 App 发起update的间隔是有限制的，用户没有买会员也不会给你发推送的优先通道。内置的NSSupportsLiveActivitiesFrequentUpdates键可以在 Info.plist 里声明你的活动需要高频更新（比如体育比分、计时器），但声明了也不是 60fps，只是系统会用更积极的调度策略。

所以做灵动岛动画的正确预期是：动画是“断点续传”式的。你把状态 A 和状态 B 给到系统，系统在 A 到 B 之间用 SwiftUI 的过渡做一次动画，整个过程可能只有几百毫秒，但看起来是连续的。如果你想做无限循环动画（比如一个不停转圈的加载图标），那就是和系统预算对着干，结果就是发热、掉电、被系统挂起，甚至审核被拒。

3. 最小可复现：用 SwiftUI 给灵动岛做一个“数字变化动画”

3.1 目标设定：做一个外卖配送进度小组件

我拿一个最常见的需求来讲：外卖配送进度。灵动岛左侧显示“外卖”，右侧显示“距离 800m”，展开后显示一条进度线加百分比数字。这不只是一个示例，它几乎覆盖了你做灵动岛动画要用到的所有动作：文本增删、数字跳动、进度条宽度变化。

假设我们已有一个 Xcode 工程，第一步是新建 Widget Extension Target。这一步我不展开 UI 操作，但有一个必查的配置：在 Widget Extension 的 Info.plist 里加上NSSupportsLiveActivities为YES。如果后面你还要做更频繁的状态更新，例如外卖距离每 5 秒跳一次，就再加NSSupportsLiveActivitiesFrequentUpdates为YES。没有这个键，你的小组件可能根本不亮出来。

3.2 代码一：定义 Activity 的 Attributes 与 ContentState

Live Activity 有两条核心数据：Attributes保存不变的信息，比如外卖商家名；ContentState保存随时间变化的信息，比如剩余距离、配送进度。

import ActivityKit import SwiftUI import WidgetKit // Attributes：启动 Live Activity 时传入，之后基本不修改 struct DeliveryAttributes: ActivityAttributes { public struct ContentState: Codable, Hashable { // 对外显示的距离文本 var remainingDistance: String // 配送进度，0.0 ~ 1.0，动画的核心驱动值 var progress: Double } // 固定信息 var restaurantName: String var orderNumber: String }

这段代码定义了数据契约。注意ContentState必须遵循Codable和Hashable，因为系统要把状态存下来并跨进程传给 Widget Extension 去渲染。progress是驱动动画的关键值，动画是否生效，取决于每次更新时这个值是否真的有变化。

3.3 代码二：Widget 的 ViewBuilder 与动画过渡

接下来写小组件的 SwiftUI 视图。这里的关键不是布局，而是动画修饰符怎么挂。

struct DeliveryActivityView: View { let context: ActivityViewContext<DeliveryAttributes> var body: some View { let state = context.state DynamicIsland { // 展开态：完整的进度条 + 数字 DynamicIslandExpandedRegion(.leading) { Label { Text(context.attributes.restaurantName) .font(.caption) } icon: { Image(systemName: "fork.knife") } } DynamicIslandExpandedRegion(.trailing) { Text("\(Int(state.progress * 100))%") .font(.headline) .contentTransition(.numericText()) .animation(.spring(response: 0.35, dampingFraction: 0.8), value: state.progress) } DynamicIslandExpandedRegion(.center) { ProgressView(value: state.progress) .progressViewStyle(.linear) .tint(.green) .animation(.linear(duration: 0.3), value: state.progress) } } compactLeading: { Text("外卖") .font(.caption2) } compactTrailing: { Text("\(Int(state.progress * 100))%") .font(.caption2) .contentTransition(.numericText()) .animation(.easeInOut(duration: 0.2), value: state.progress) } minimal: { Image(systemName: "fork.knife") } } }

代码里两个最关键的东西，一个是.contentTransition(.numericText())，一个是.animation(_:value:)。.contentTransition让数字从 12% 变到 13% 时不是生硬地替换文本，而是像计算器一样滚动跳变；.animation(value:)指定 SwiftUI 在progress变化时，对视图渐变做多长的动画过渡。

参数这里先记住：duration不是“动画总时长”，而是“状态 A 到状态 B 的过渡时长”。你 timeline 里相邻两条数据的间隔是 5 秒，那动画过渡时长写 0.3 和写 4 秒的效果完全不同——前者在状态切换后很快稳定，后者则像慢动作。后面专门讲参数。

3.4 代码三：TimelineProvider 构造“动画骨架”

现在到最核心的一步：构造 Timeline。你要理解 WidgetKit 是“按时间线喂数据”的，每个 TimelineEntry 都有一个date和一个state，系统到点就用最新的 state 渲染一次。动画的本质，就是 Timeline 里相邻 entry 的 state 存在差异，加上 SwiftUI 的 animation 后，过渡就产生了。

struct DeliveryTimelineProvider: TimelineProvider { func placeholder(in context: Context) -> DeliveryEntry { return DeliveryEntry(date: Date(), state: DeliveryAttributes.ContentState(remainingDistance: "800m", progress: 0.2)) } func getSnapshot(in context: Context, completion: @escaping (DeliveryEntry) -> Void) { let state = DeliveryAttributes.ContentState(remainingDistance: "800m", progress: 0.2) completion(DeliveryEntry(date: Date(), state: state)) } func getTimeline(in context: Context, completion: @escaping (Timeline<DeliveryEntry>) -> Void) { var entries: [DeliveryEntry] = [] let startDate = Date() // 构造未来 40 秒的 40 个状态，每隔 1 秒 progress 增加 0.025 for second in 0..<40 { let progress = min(Double(second) * 0.025, 1.0) let state = DeliveryAttributes.ContentState( remainingDistance: "\(Int((1.0 - progress) * 800))m", progress: progress ) let entryDate = startDate.addingTimeInterval(TimeInterval(second)) entries.append(DeliveryEntry(date: entryDate, state: state)) } let timeline = Timeline(entries: entries, policy: .atEnd) completion(timeline) } } struct DeliveryEntry: TimelineEntry { let date: Date let state: DeliveryAttributes.ContentState }

这段代码的逻辑很直白：生成 40 个 entry，每个 entry 间隔 1 秒，progress从 0 平滑增加到 1。系统每秒钟换一个 entry，视图里的ProgressView和数字就会因为animation(value:)而平滑过渡。

这时的行为像什么？它像你把一个 40 帧的动画拆成 40 张关键帧，按每秒一帧的节奏播放。看起来是动画，实际上全是状态切换。

3.5 代码四：从 App 发起 Live Activity 并更新状态

TimelineProvider 只是 Widget 侧的“渲染蓝图”，真正让动画动起来的是 App 侧调用 ActivityKit 更新状态。新手最常犯的错误是只写了 TimelineProvider，但压根没在 App 里启动 Activity，灵动岛自然什么都没有。

import ActivityKit // 启动 Live Activity func startDeliveryActivity() { let attributes = DeliveryAttributes(restaurantName: "老王牛肉面", orderNumber: "A1024") let initialState = DeliveryAttributes.ContentState(remainingDistance: "800m", progress: 0.0) do { let activity = try Activity.request( attributes: attributes, contentState: initialState, pushType: nil ) print("Activity started: \(activity.id)") } catch { print("启动失败：\(error)") } } // 模拟配送进度更新，每次调用都会触发灵动岛动画 func updateDeliveryProgress(newProgress: Double) { let updatedState = DeliveryAttributes.ContentState( remainingDistance: "\(Int((1.0 - newProgress) * 800))m", progress: newProgress ) Task { // 拿到当前活动的列表，把最新状态推给它 for activity in Activity<DeliveryAttributes>.activities { await activity.update(using: updatedState) } } }

pushType: nil表示当前不做远程推送，只靠 App 在前台时手动update。注意Activity.request必须在主线程调用，否则低版本系统可能直接抛异常。Activity.activities拿到的是当前 App 启动的所有同类型活动，遍历更新即可。

到这里，一套完整的“灵动岛动画小组件”最小闭环已经跑通了：App 请求一个 Activity → Widget 用 TimelineProvider 描述未来状态的骨架 → App 持续 update → SwiftUI 在状态间过渡出动画。

4. 灵动岛动画的 5 个必调参数：从“能动”到“动得好看”

4.1 动画 duration：值不是越大越好，要和 Timeline 间隔匹配

animation(_:value:)里的 duration 参数，很多人第一反应是“动画持续 2 秒”，实际它是 SwiftUI 在检测到值变化后，从旧视图渐变到新视图的时间。这里有个隐性关系：Timeline 相邻 entry 的时间间隔，决定了系统多久喂一个新状态；如果你的 entry 间隔是 5 秒，而 duration 写了 4 秒，那么动画刚播完差不多系统就更新下一帧了，观感是“一顿一顿地慢放”；如果 entry 间隔是 0.5 秒，duration 写了 4 秒，那动画压根没走完就被新状态打断，看上去像抖动。

我常用的匹配关系：条目间隔 1 秒时，过渡 duration 用 0.2～0.35 秒；条目间隔 5 秒时，过渡可以拉长到 0.8 秒，让状态变化有“从容展开”的感觉，不会被下一次更新打断。这个参数没有标准答案，取决于你的信息密度——数字每秒变一次，过渡短一点更利落；进度条每分钟才变一次，过渡慢一点更像“生长”而不是“跳变”。

4.2 spring 与 linear：曲线决定灵动岛动画的性格

SwiftUI 动画曲线的选择会影响灵动岛动画的“精气神”。默认的.linear(duration:)用于进度条最稳妥，因为它匀速推进，不会让用户觉得速度不稳。数字跳变我更喜欢.spring(response:dampingFraction:)，response 控制弹簧响应时间，dampingFraction 控制回弹强度，取值 0.8 左右会有轻微过冲，让数字变化带一点“校准感”；取值 1 则完全没有回弹。

注意.spring在低帧率环境下会显得“粘滞”，因为系统更新不连续，弹簧曲线按真实时间计算，两个状态之间隔了 1 秒，动画会拉得很长。如果你在真机上发现数字像橡皮糖一样来回甩，把 dampingFraction 调到 1，或者干脆改回.easeOut(duration: 0.25)。

4.3 更新频率：FrequentUpdates 键不是万能钥匙

Info.plist 里的NSSupportsLiveActivitiesFrequentUpdates键很多人一上来就加，以为能解锁 60fps。我实测下来，它确实能提高系统调度优先级，但代价是更高的电量消耗和更严格的审核备注。iOS 文档里对“Frequent Updates”的定义是“至少每分钟一次”级别的场景，比如体育比赛比分、计时器秒数变化。如果你做的是外卖距离这种 30 秒更新一次的应用，不需要开这个键；开了反而容易在低电量模式下被系统强制挂起。

再强调一次：灵动岛永远不是你 App 里那种“每秒 60 帧渲染”。系统会尽量把 Live Activity 的渲染控制在每秒 1～2 次，极端情况下可能十几秒都不更新（比如锁屏后一段时间）。所以你的动画设计必须容忍“缺失中间帧”——用户看到的是 12% 跳到 15%，不要指望中间那 13%、14% 一定出现。

4.4 布局参数：compact 形态下别放超过两个元素

灵动岛的物理空间有限，这是布局参数真正的约束。compactLeading 和 compactTrailing 的高度大概就是一条细长矩形的空间，宽度你不能直接指定，系统按内容自适应，但它会截断超宽内容。所以我在 compact 形态里只放不超过两个元素：比如左侧“外卖”，右侧“1200m”。icon + 文本是最稳定的组合，别放两个文本，也别放一个长文本加一个图标，否则系统会压缩到你认不出。

expanded 形态才有真正的布局自由，但有个细节：DynamicIslandExpandedRegion的.center区域宽度受限，两个文本之间如果靠得太近，动画时会重叠。我一般把动态内容（数字、进度）放在.trailing，把静态标签（外卖、快递）放在.leading，避免动画中文字交叠。

4.5 颜色与安全区域：黑底不是纯黑，透明区域别乱放内容

灵动岛在深色模式下是纯黑背景，但注意灵动岛旁边的区域不是你的画布。很多人在 expanded 布局里把内容铺满，结果系统会把左右两侧的传感器区域也计算进去，出现奇怪的遮挡变色。安全做法是：只用系统给定的 region，不要用 geometry 自作主张偏移；浅色模式下灵动岛整体会变成深色胶囊，这时候如果你的文本颜色用了白色，iOS 会自动调整为系统默认的标签色，但自定义配色（比如品牌黄、品牌绿）可能需要你在动态岛上做一次反色适配，否则用户会觉得你的小组件在“发灰”。

颜色这块我有个血泪经验：在灵动岛动画里，不要尝试用.foregroundStyle(.primary)以外的自定义颜色做大量渐变。灵动岛动画的核心信息本身就在变化，颜色再一闪，观感非常发虚。老老实实把品牌色用在图标或进度条上，文本保持系统语义色。

5. 灵动岛动画常见问题与避坑：从“不动”到“被截断”

5.1 模拟器上看不到灵动岛动画

现象：在 Xcode 模拟器里启动 App，Live Activity 调用成功，但模拟器灵动岛区域毫无反应。

原因：Live Activity 在模拟器上的支持一直不完整。模拟器虽然能显示灵动岛轮廓，但 Activity 的调度和 true 度渲染在模拟器上经常失效，尤其是 iOS 16 初期版本，Activity.request可能直接返回错误。

解决：别在模拟器上耗时间。我是用真机调试的，iPhone 14 Pro 及以上机型，系统 iOS 16.1+。真机上如果还是看不到，去“设置 → 灵动岛与实时活动”检查是不是给这个 App 关闭了权限，或者开了“省电模式”，后者会大幅度降低 Live Activity 的刷新频率，动画表现就像被阉割了。

5.2 灵动岛动画完全不动，只有文本跳变

现象：Text 会更新，从“800m”变“750m”，但 ProgressView 没有过渡，进度条直接以存 5% 的宽度跳过去。

原因：这是动画失效的经典案例。检查你的.animation(_:value:)的 value 是不是progress。很多人直接把.animation(.linear(duration: 0.3))挂在容器上，没有指定 value，SwiftUI 就把白色动画应用到了所有属性上，如果视图树里某个状态更新没有变化，动画就会被整体忽略。

解决：把.animation从容器级下放到具体视图上，比如只挂给ProgressView和数字文本。并且确保ContentState里progress变量参与绘制，而不是在 body 里用let state = context.state后取了个中间值又算了一份新值——如果计算后的值相同，animation(value:)会判定没有变化，不会触发过渡。

5.3 灵动岛内容被截断，文字左右跑不全

现象：compact 形态下，文本“剩余 1200.0m”写不进去，左右两边直接没了；或者 expanded 形态下，右边数字部分被系统时间遮挡。

原因：你让每个 container 都塞太多内容了。灵动岛的 compact 形态宽度是系统控制的，它会根据你的内容宽度做截断，而不是自动换行。带小数点的数字会比整数宽很多，再加上一个“m”单位后缀，经常踩中宽度上限。

解决：文本格式化优先级高。把"剩余 1200.0m"在ContentState里就处理成整数字符串，比如"1200m"；不要放“剩余”“距离”这类冗余前缀。我的习惯是：动态数字永远格式化到最简形式，单位直接拼在数字后面，避免系统 locale 给你加千分位逗号而触发宽度变化。

5.4 动画执行一半被“掐断”

现象：数字从 20% 往 30% 过渡的时候，突然跳回 20%，过一秒又跳到 30%。

原因：Timeline 里出现了倒序 entry。WidgetKit 要求 Timeline 的 entry 按时间递增排列，但如果你手动在 App 侧 update 了一个早于当前时间线的状态，系统会丢掉旧 entry 并回退到最新合法状态，导致动画倒带。

解决：更新 Activity 前，先对比Activity.activities里状态的更新时间，只update时间戳大于当前 timeline 的状态。我通常在updateDeliveryProgress(newProgress:)里加一个判断：如果newProgress小于等于最后一次写入的值，直接忽略。

5.5 灵动岛动画常驻不掉，审核被拒

现象：审核员反馈 App 的 Live Activity 动画一直转个不停，涉嫌误导用户或过度消耗资源。App 用户在小部件上看到一个永不停止的循环动画，比如旋转图标、加载进度条，系统其实不支持这种持续动画，你的方案是每隔 1 秒提交一个新 entry，把 spinner 角度 +10°，本质上是用 Timeline 循环“伪造”动画。

原因：Live Activity 的审核政策对“本质上是无限动画”的实时活动非常严格。你可能觉得它就是个小动画，但系统认为它占用了灵动岛的展示资源，却没给用户带来实时信息。

解决：把动画和真实信息绑定。我接手过 2 个被拒的项目，最后都是把“无限加载转圈”改成“真实进度百分比+状态文本”。如果确实要展示等待状态，就显示“预计 5 分钟”，而不是让一个圆转下去。审核视角下，灵动岛动画必须服务信息，服务视觉效果本身是会被打回的。

6. 进阶技巧：用“时间线映射”做无法停下来的循环动画

很多玩灵动岛的人都遇到过这个需求：做一个计时器，一秒一秒倒计时。数字变化本身不是问题，问题是如果你用 TimelineProvider 按秒生成 entry，系统在锁屏后可能调度变慢，计时器会“漏秒”。我这里的进阶技巧，是把动画播放从“更新驱动”转成“时间驱动”：在 Timeline entry 里放下关键时间戳，由 SwiftUI 的TimelineView或Text(timerInterval:)来自动推进渲染。

思路是这样的：Timeline 里只放一个 entry，它的 date 是倒计时结束时间。视图里用Text(startDate, style: .timer)来渲染剩余时间，这样 SwiftUI 会在本地每秒重新渲染一次，不需要系统再喂新的 entry，避开了 Live Activity 的更新预算限制。这个模式特别适合做“距离外卖还有 10 分钟”这种持续性倒计时动画。

DynamicIslandExpandedRegion(.center) { ViewThatFits { // 关键在于用 timerInterval 让系统自己每秒重绘 Text(timerInterval: entry.state.startDate...entry.state.endDate) .font(.title) .monospacedDigit() } }

.monospacedDigit()是另一个小技巧，它可以强制数字等宽，避免倒计时从“9”变“10”时文本宽度跳动，引发动画抖动。这个方案里，你 App 侧的 update 只需要在活动开始和结束时调用，中间的每一秒都交给系统去渲染——这既抵消了部分系统节流，又让动画流畅度提升了一个档次。我做过 40 多个 Live Activity 相关的项目，这套“时间戳 + 系统重绘”的组合是目前在灵动岛上做低功耗动画最可靠的路子。

最后提一个验证习惯：每次改完动画参数，先在真机锁屏状态下观察 2 分钟，再解锁看灵动岛，最后切到别的 App 看后台表现。三种环境下的动画节奏可能完全不同，不亲眼看完，你永远不会知道用户实际看到的“动画”和你预览器里差多远。希望这些从机制到参数的细节，能让你少走几段我踩过的弯路。

本文还有配套的精品资源，点击获取