简介这套资源是围绕 iOS 灵动岛动画小组件开发的完整 Xcode 工程示例面向有一定 SwiftUI 基础、希望实现系统岛区域动态效果的 iOS 开发者也适合快速搭建灵动岛演示项目的场景。资源包共 64 个文件大小仅 847KB核心以 15 个 Swift 源码为主配合 Widget 扩展配置、JSON/plist 描述文件以及 Xcode 工程结构另含 PNG/GIF 图片素材便于替换动画帧已有 388 人浏览学习。通过工程内小组件入口、动画视图与灵动岛组件的搭配开发者可以直观理解 WidgetKit 如何驱动小组件动画、时间线刷新与锁屏/主屏幕动态展示流程同时学习到系统通知避让、更新频率控制和设计一致性等关键处理思路其中时间线刷新机制决定动画何时更新是保证灵动岛视觉连续性的关键。整体目录结构简洁主 App 与 Widget 扩展目标划分清晰适合作为从零搭建灵动岛动画小组件的参照便于后续二次修改与迁移。1. 灵动岛动画小组件的容器从来不是小组件而是实时活动不少团队接到“做一个会动的灵动岛小组件”的需求第一反应是打开 Widget Extension在主屏幕小组件里加个withAnimation循环结果发现系统根本不让你自由连续播放。真正的答案在 iOS 16.1 之后落到 Live Activity实时活动上灵动岛上那些跑动的进度条、计时秒数、播放波形本质上都是系统在锁屏界面和灵动岛区域内渲染一个 SwiftUI 视图而这个视图的更新由 ActivityKit 驱动。搞清楚这个边界才能回答“iOS灵动岛动画小组件怎么播放动画”这个问题。Live Activity 有紧凑、最小、展开三种外观动画也分成两类一类是你用 SwiftUI 状态变化驱动的视图动画另一类是系统在收起、展开灵动岛时自动执行的形变动画。前者决定内容动起来后者决定岛怎么开合。适合读这篇文章的人是正在做打车、外卖、播放器、计时器、运动记录这类有实时任务场景的客户端工程师或者想让灵动岛动效落地但还没理清更新机制的 iOS 开发。下面从创建、驱动、排错到进阶验证按真实可跑的路径走一遍。2. 创建会动的基础ActivityKit 的授权、启动、更新与结束2.1 先确认工程配置少一个开关就收不到灵动岛在写任何动画代码之前先确认 Target 的 Info.plist 里有没有NSSupportsLiveActivities这个布尔值。很多“灵动岛不出现”“小组件不更新”的问题第一步就死在这里没有声明支持实时活动ActivityKit 的request会直接抛错连岛都上不去。这个开关不是默认开启的Xcode 新建 Widget Extension 模板也不会自动帮你勾上。配置项所在位置值缺失时的表现NSSupportsLiveActivities主 App Target 的 Info.plistYES启动 Activity 失败日志出现“required string for key not found”之类错误签名与 Deployment Target主 App 与 Widget ExtensioniOS 16.1真机 iPhone 14 Pro 系列或 iPhone 15 Pro 系列模拟器上 Activity 存在但灵动岛区域不渲染动画Widget Extension 的 Info.plist与主 App 同 Target无需额外开关但需开启 App Group若要在主 App 和 Widget 间共享数据主 App 更新状态后 Widget 收不到注意灵动岛的硬件形态依赖原深感摄像头挖孔区域在普通刘海屏机型上Live Activity 只能以锁屏横幅形式出现不会显示成岛。调试动画时尽量用带灵动岛的真机模拟器也能跑但灵动岛的收起、展开形变是模拟渲染和真机的 OLED 显示效果差距很大。2.2 用 ActivityAttributes 定义动画状态模型Live Activity 的架构分两层ActivityAttributes里的静态属性描述这个任务是什么ContentState描述当前时刻的动态状态。动画要做的所有事情几乎都是围绕ContentState变化展开的。下面以播放器为例定义状态模型import ActivityKit struct PlayerActivityAttributes: ActivityAttributes { public struct ContentState: Codable, Hashable { /// 播放进度取值范围 0...1驱动进度条动画 var progress: Double /// 是否正在播放切换时触发图标动画 var isPlaying: Bool /// 显示在紧凑尾部的歌曲名建议不超过 8 个字符 var trackName: String /// 波形动画用记录当前音量高度模拟音频节奏 var audioLevel: Double } /// 静态属性在 Activity 生命周期内不变 var albumName: String }ContentState必须遵循Codable和Hashable因为系统会把状态序列化后交给 Widget 进程渲染。progress和audioLevel这两个字段就是驱动动画的数据源。每次你调用update时系统会把新的ContentState和旧状态做对比然后触发 SwiftUI 视图的 body 重新求值。如果这两个字段不变视图就不会刷新动画自然停住。2.3 启动、更新与结束动画状态推进的完整代码路径import ActivityKit // 启动 Live Activity let attributes PlayerActivityAttributes(albumName: 2025 播放列表) let initialState PlayerActivityAttributes.ContentState( progress: 0.0, isPlaying: true, trackName: 晴天, audioLevel: 0.3 ) do { let activity try ActivityPlayerActivityAttributes.request( attributes: attributes, contentState: initialState, pushType: .token ) // pushType 传 .token 表示允许通过 APNs 远程更新拿到 token 后给服务端 print(Activity 启动pushToken: \(activity.pushToken?.hexString ?? 暂无)) } catch { print(启动失败: \(error.localizedDescription)) } // 本地更新把进度从 0 推到 0.5界面上的进度条会随之动画变化 Task { let nextState PlayerActivityAttributes.ContentState( progress: 0.5, isPlaying: true, trackName: 晴天, audioLevel: 0.8 ) // 注意update 是 async 方法要在 Task 或 async 上下文里调用 await activity.update(using: nextState) } // 结束 ActivitydismissalPolicy 决定结束动画的样式 Task { await activity.end( using: PlayerActivityAttributes.ContentState( progress: 1.0, isPlaying: false, trackName: 晴天, audioLevel: 0.0 ), dismissalPolicy: .default ) // .default 会先展示结束状态再执行收起动画 // .immediate 则直接消失.after(date) 可以指定在未来某个时间消失 }request的pushType参数如果传nil表示只能本地更新不能远程推送。做动画时通常用本地更新因为动画频率高、延迟要求低走 APNs 的网络链路完全跟不上。只有打车、外卖这种低频状态变化才适合远程推送。dismissalPolicy决定结束时的灵动岛收起动画.default和.immediate会让收岛动画节奏不同建议在真机上对比感受不要偷懒只写.immediate。2.4 本地更新和远程推送的取舍更新方式延迟适合场景动画流畅度本地activity.update毫秒级播放进度、计时器、运动步数高可达到系统允许的最高刷新频率APNs 远程推送受网络影响通常 1~3 秒外卖状态、航班状态、快递进度低不适合连续动画本地预定时长 系统自动推进无倒计时、秒表最好系统在后台自己算不需要你更新做“灵动岛动画小组件”时原则上动画数据源应该在 App 进程内直接驱动。如果服务端也想控制动画比较稳妥的做法是服务端推送“目标值”和“动画时长”客户端收到后用update设置终态再配合第 3 章的Text(timerInterval:)或TimelineView让视觉效果连续推进而不是服务端每秒推一帧。3. 在灵动岛上播放动画三种形态与三种动画引擎3.1 从紧凑到展开动画边界由形态决定Live Activity 在灵动岛上有三种展示形态动画必须分形态设计否则会出现“动画显示不全”或“压缩变形”的问题。Apple 的DynamicIsland视图修饰器允许你分别注册 compactLeading、compactTrailing、minimal 和 expanded 区域。紧凑形态高度只有 37.33 pt宽度约 126 pt能放的内容非常有限展开形态会把灵动岛拉成一个约 160 pt 高的大矩形才有足够的空间放进度条、波形、大段文本。DynamicIsland { // 展开形态在灵动岛展开的矩形区域内显示 ExpandedView() } compactLeading: { // 紧凑形态左侧一般放 App 图标或小图标 Image(systemName: music.note) .foregroundStyle(.white) } compactTrailing: { // 紧凑形态右侧放置进度或播放状态 Text(timerInterval: startDate...endDate) .font(.caption2) .monospacedDigit() } minimal: { // 最小形态另一个岛上的独立小圆点 ProgressView() .tint(.white) }动画设计要和这三个区域绑定。比如播放器场景紧凑形态的动画应该放在右侧的圆形进度环上左侧保持静态图标展开形态则把进度条、封面、波形归入底部区域避免左侧空间被裁切。实际开发中我一般会把紧凑形态的动画做得更克制灵动岛本身很小高频率闪动反而让用户视觉疲劳。3.2 用 TimelineView 驱动旋转与闪烁动画如果只是让某个图标转起来、闪一下TimelineView(.animation)是首选。它会让闭包里的视图以系统调度的时间频率重新求值不需要你手动管理Timer也不需要更新ContentState因为驱动的数据源是时间本身DynamicIsland { Text(播放中) } compactLeading: { TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in let seconds context.date.timeIntervalSinceReferenceDate // 用时间的小数部分驱动旋转角度形成连续旋转动画 let angle seconds.truncatingRemainder(dividingBy: 1.0) * 360.0 Image(systemName: waveform) .rotationEffect(.degrees(angle)) .animation(.linear(duration: 0.03), value: angle) .foregroundStyle(.white) } } compactTrailing: { Text(00:42) }minimumInterval: 1.0 / 30.0表示“每 1/30 秒刷新一次”但系统不会真正保证每秒 30 次。在实时活动里更新会被节流实际频率可能只有 10~15 Hz。因为灵动岛区域小、元素轻量这个频率已经足够产生流畅错觉。注意rotationEffect和.animation(value:)只在value变化时触发过渡TimelineView 每次刷新都会给一个新的angle所以可以把 SwiftUI 的隐式动画用在时间驱动的场景里。3.3 让系统自己走时间Text 和 ProgressView 的 timerInterval 模式这是我认为最省心、最优雅的灵动岛动画方式不手动更新状态而是告诉系统“从哪开始、到哪结束”系统按照真实时间在后台自动推进 UI。倒计时、秒表、进度条这些场景都适用let startDate Date() // 任务开始时间 let endDate Date().addingTimeInterval(5 * 60) // 5 分钟后结束 DynamicIsland { VStack { // 展开形态显示剩余时间和一个自动填充的进度条 Text(timerInterval: startDate...endDate) .font(.title2) .monospacedDigit() ProgressView(timerInterval: startDate...endDate) .tint(.white) } .padding() } compactLeading: { Image(systemName: timer) .foregroundStyle(.white) } compactTrailing: { // 紧凑形态系统自动把剩余时间渲染成“4:59”的形式 Text(timerInterval: startDate...endDate) .font(.caption2) .monospacedDigit() } minimal: { ProgressView(timerInterval: startDate...endDate) .tint(.white) }这套 API 的底层由系统维护期间即使用户锁屏、App 退到后台、甚至进程被挂起UI 依然按真实时间走动。对比手动更新方案它不会因为进程被挂起而停在旧时间上。唯一的限制是Text(timerInterval:)默认显示的格式是“分钟:秒”如果要做“小时:分钟:秒”的样式需要自定义Text(_:style:)的DateStyle但灵动岛空间有限建议保持简单。3.4 用 Canvas 播帧序列做出“真正的动画”效果TimelineView 适合轻量状态动画但如果你要播放一组预生成好的帧比如火焰、波纹、音量律动就需要 Canvas 加帧序列的方式。把动画拆成一组 PNG 序列在 TimelineView 中按时间索引取帧struct FrameAnimationView: View { // 预加载的动画帧建议提前用 UIImage 缓存到内存 let frames: [UIImage] var body: some View { TimelineView(.animation(minimumInterval: 1.0 / 24.0)) { context in Canvas { context, size in let total frames.count // 通过时间计算当前帧索引循环播放 let seconds context.date.timeIntervalSinceReferenceDate let frameIndex Int(seconds * 24.0) % total guard frameIndex total else { return } if let cgImage frames[frameIndex].cgImage { // 把当前帧绘制到整个画布区域 context.draw(Image(decorative: cgImage, scale: 1.0), in: CGRect(origin: .zero, size: size)) } } .frame(width: 80, height: 80) .clipped() } } }这套方案是把“动画小组件”做到高帧率错觉的正解。但要注意预算Live Activity 的刷新频率受系统限制你就算把minimumInterval写到1.0 / 60.0也不一定能跑到 60 帧。因此帧序列设计时要克制帧数控制在 20~30 帧以内单帧尺寸按实际显示大小导出不要塞一张 1024 的大图进去否则同时触发解码开销和绘制开销。OLED 屏幕的特性也影响这个选择灵动岛区域本身是纯黑挖孔动画帧中大量高亮像素长时间停留会导致残影风险所以帧动画的高亮面积尽量缩小。3.5 三种动画引擎怎么选引擎适用场景更新频率预算消耗我的建议TimelineView(.animation)旋转、闪烁、波形、进度指示10~30 Hz低适合轻量图形大多数动画的首选Text(timerInterval:)ProgressView倒计时、秒表、剩余时间系统自动极低能不用手写更新就不用Canvas 帧序列逐帧动画、图片序列、特效自定义建议 15~24 Hz高需要控制帧图和大小只在真正需要时使用选型原则很简单能用系统时间驱动就不用ContentState能用 TimelineView 做轻量变换就不上 Canvas。灵动岛动画的美感来自克制和节奏感几十帧的连续动画在这种小尺寸区域里反而容易显得廉价。4. 动画不动、卡顿、显示不全预算与节流的排查路径4.1 修改了 ContentState界面却没有反应最常遇到的坑是代码里调用update了但灵动岛视图纹丝不动。排查顺序是先确认更新的是不是正确的Activity实例。如果同一个 Attributes 启动了多个 Live Activity而你把更新发给了其中一个已结束的实例系统会静默忽略。其次查看ContentState是否有 0 秒内的连续更新系统对更新次数有预算短时间频繁更新会触发节流后续更新被吞掉。另一个容易被忽略的点是Hashable一致性。如果ContentState里的progress从 0.0 改成 0.0000001在浮点比较时可能被系统认为是“无变化”从而跳过 UI 刷新。驱动动画的字段建议按明确的进度单位变化不要做无意义的小数抖动。// 错误的更新方式一次性把 0.0 到 1.0 按每秒 60 次连续推会被节流 for progress in stride(from: 0.0, through: 1.0, by: 0.016) { try? await Task.sleep(nanoseconds: 16_000_000) await activity.update(using: state) } // 正确的做法直接设置终态让视图用 TimelineView 或 timerInterval 自己过渡 let finalState PlayerActivityAttributes.ContentState( progress: 1.0, isPlaying: true, trackName: 晴天, audioLevel: 0.5 ) await activity.update(using: finalState)在真实项目中我一般只更新关键状态点播放、暂停、进度跳转、结束。持续的时间感交给时间驱动的 API而不是靠手刷ContentState。4.2 minimumInterval 不是帧率保证而是更新上限新手最常见误判是认为TimelineView(.animation(minimumInterval: 1.0/60.0))能保证 60 帧。实际上这个参数只是告诉 SwiftUI“不要更快地刷新”系统会根据当前的运行内存、CPU 占用和实时活动的整体预算来降频。如果视图里执行了昂贵的绘制比如 Canvas 里做大量离屏渲染、加载高清图片帧率会掉到个位数。观察实际刷新频率的办法很简单在视图 body 里打印时间戳TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in let timestamp context.date.timeIntervalSinceReferenceDate // 真机观察这个输出之间的间隔正常情况下在 0.03~0.1 秒之间波动 print(刷新: \(timestamp)) Image(systemName: sun.max) }如果两次打印间隔稳定在 0.1 秒附近说明系统已经把更新预算压低你需要简化视图层级或者降低minimumInterval期望值到 10 Hz。时钟类、计时器类的 UI 在 10 Hz 下依然可读但旋转动画看起来就会有点顿挫。4.3 动画显示不全展开态和紧凑态的空间差异“动画显示不全”是我的开发过程中被问得最多的问题。原因基本只有一个同一个动画在不同形态里用了固定 frame导致在紧凑形态下超出边界被裁切。灵动岛紧凑区域的高度限制很严格任何超过 44 pt 的视图都会被裁剪掉而且系统不会给你明显警告。解决方案分两层第一是在设计阶段就避免同一个视图直接复用紧凑形态只放简单图标和数字第二是在必要复用时加上.clipped()和.contentShape()并主动把尺寸压进安全边界。展开态内部也要留边距因为灵动岛展开区域的圆角和系统 UI 会有视觉重叠compactLeading: { Image(systemName: music.note) .frame(width: 16, height: 16) // 明确限制尺寸避免被压缩时变形 .clipped() } expanded: { VStack(spacing: 6) { Text(正在播放) // 展开态四周留 8 pt避免贴近圆角边缘 ProgressView(timerInterval: start...end) .padding(.horizontal, 8) } }4.4 模拟器和真机的动画表现完全不同用模拟器调动画时要格外小心模拟器没有真正地驱动 OLED 屏幕也没硬件渲染层级所以动画卡顿、掉帧、模糊的体验跟真机相差很大。反过来模拟器里看着流畅的动画在真机上可能会显得过于细碎或闪得刺眼。凡是跟灵动岛动画相关的效果一定要以真机为准。若手头只有刘海屏机器就借用一下支持灵动岛的设备或者退而求其次看锁屏横幅动画保证核心动画逻辑正确再接真机验证。4.5 减少僵尸任务防止灵动岛动画越跑越卡如果测试时不断启动新的 Activity而不结束旧的系统会同时维护多个实时活动实例每个实例的视图都在更新CPU 压力会叠加导致动画刷新率进一步下降。开发阶段用一个小工具来集中管理 Activity 实例enum LiveActivityManager { static var current: ActivityPlayerActivityAttributes? static func start() { // 启动前先结束旧实例避免多个 Activity 同时动画 Task { if let old current { await old.end(dismissalPolicy: .immediate) } current try? Activity.request(...) } } }这个管理类同时解决一个问题用户从 App 切出去再回来如果 Activity 还挂着动画却停在老状态那就需要根据当前场景重新update一次。避免让用户看到已经结束的任务还在岛上“播报”。5. 把动画能力做成小组件帧序列、状态保持与验证技巧5.1 抽一个通用的动画播放修饰器如果你要在多个功能里复用同样一套灵动岛动画建议把“时间驱动动画”封装成修饰器。这个修饰器接收一个动画引擎和一组参数内部用 TimelineView 统一驱动struct LiveActivityAnimationModifier: ViewModifier { let engine: AnimationEngine let frameCount: Int func body(content: Content) - some View { TimelineView(.animation(minimumInterval: engine.minimumInterval)) { context in content .environment(\.animationFrameIndex, engine.frameIndex(at: context.date)) } } } enum AnimationEngine { case rotation(speed: Double) case frameSequence(fps: Int) var minimumInterval: TimeInterval { switch self { case .rotation: return 1.0 / 30.0 case .frameSequence(let fps): return 1.0 / TimeInterval(fps) } } func frameIndex(at date: Date) - Int { switch self { case .rotation(let speed): return Int(date.timeIntervalSinceReferenceDate * speed * 30) % 360 case .frameSequence(let fps): return Int(date.timeIntervalSinceReferenceDate * Double(fps)) % 30 } } }这样做的好处是动画逻辑和视图解耦调试的时候可以只改AnimationEngine的枚举值而不用去每个视图里调整 TimelineView 参数。这其实就是不少团队在“动画工作流”里沉淀下来的做法把时间轴、帧率、帧索引封装成数据驱动的东西让设计师和开发共用一套参数描述。5.2 锁屏小组件和灵动岛共享一个动画状态如果 App 同时做了锁屏小组件和灵动岛要注意两个容器不是同一个进程不能直接共享内存。推荐做法是把动画状态写入 App Group 的共享 UserDefaults 或一个小型 JSON 文件锁屏小组件在刷新时读取。但这种机制的同步频率不高适合播放、暂停、当前进度等低频状态。高频动画数据不应该跨进程。比如音量波动这种需要每秒刷新数十次的数据只放在 Live Activity 的ContentState里实时更新。锁屏小组件就展示静态数据和最近一次快照不要试图同步每一帧。这是常见的误用场景两边都想要连续动画结果把跨进程通信的负载打满最后两边都掉帧。5.3 用 iOS 自动化做推送测试不打断动画状态机调试更新流程时我会用快捷指令配合服务端做一次远程通道测试。做法是在快捷指令里用“获取 URL 内容”向自己的服务端发一个 POST服务端再通过 APNs 向当前 Activity 的 pushToken 推一条更新。这样可以验证远程推送链路是否通畅同时不打断本地动画状态机的连续节奏。注意 pushToken 是Data类型需要转成十六进制字符串后才能发给 APNs。正常情况下 token 会在 Activity 启动后的几秒内回调。如果一直拿不到 token确认pushType是否传了.token以及 App 是否有远程通知权限。测试结束后记得把current实例调用end(dismissalPolicy: .immediate)避免残留 Activity 影响后续测试。5.4 验证动画是否流畅的三个手段第一个手段是拿秒表直接掐录一段灵动岛的屏幕视频把视频放到剪辑软件里逐帧拖看动画是不是均匀推进。这是最朴素的验证方法但效果最直接。第二个手段是把 Xcode 的os_signpost埋点放进 TimelineView 更新闭包里统计每秒实际刷新次数对比设计目标帧率。第三个手段是开 MeterKit 观测实时活动的 CPU 占用如果动画逻辑占用了过多 CPU系统会主动降频这时优先优化视图体量而不是继续堆动画帧数。// os_signpost 埋点示例用 Instruments 的 os_signpost 模板查看 import os.signpost let log OSLog(subsystem: com.example.player, category: LiveActivityAnimation) let spid OSSignpostID(log: log) TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in os_signpost(.event, log: log, name: FrameUpdate, signpostID: spid, fps: %d, Int(1.0 / max(context.date.timeIntervalSince(lastDate), 0.0001))) }看刷新间隔的分布如果大部分时间落在 30~40 ms 左右说明刷新率在 25~30 Hz对灵动岛动画来说已经够用。如果大量间隔超过 100 ms就要回第 4 章查视图重量和更新频率了。最后记住一条灵动岛动画的核心是“用系统时间代替手动推进”把握住这一点动画显示不全、卡顿、被节流的问题至少能少一半。本文还有配套的精品资源点击获取 iOS灵动岛动画小组件实战：Live Activity与TimelineView驱动
简介这套资源是围绕 iOS 灵动岛动画小组件开发的完整 Xcode 工程示例面向有一定 SwiftUI 基础、希望实现系统岛区域动态效果的 iOS 开发者也适合快速搭建灵动岛演示项目的场景。资源包共 64 个文件大小仅 847KB核心以 15 个 Swift 源码为主配合 Widget 扩展配置、JSON/plist 描述文件以及 Xcode 工程结构另含 PNG/GIF 图片素材便于替换动画帧已有 388 人浏览学习。通过工程内小组件入口、动画视图与灵动岛组件的搭配开发者可以直观理解 WidgetKit 如何驱动小组件动画、时间线刷新与锁屏/主屏幕动态展示流程同时学习到系统通知避让、更新频率控制和设计一致性等关键处理思路其中时间线刷新机制决定动画何时更新是保证灵动岛视觉连续性的关键。整体目录结构简洁主 App 与 Widget 扩展目标划分清晰适合作为从零搭建灵动岛动画小组件的参照便于后续二次修改与迁移。1. 灵动岛动画小组件的容器从来不是小组件而是实时活动不少团队接到“做一个会动的灵动岛小组件”的需求第一反应是打开 Widget Extension在主屏幕小组件里加个withAnimation循环结果发现系统根本不让你自由连续播放。真正的答案在 iOS 16.1 之后落到 Live Activity实时活动上灵动岛上那些跑动的进度条、计时秒数、播放波形本质上都是系统在锁屏界面和灵动岛区域内渲染一个 SwiftUI 视图而这个视图的更新由 ActivityKit 驱动。搞清楚这个边界才能回答“iOS灵动岛动画小组件怎么播放动画”这个问题。Live Activity 有紧凑、最小、展开三种外观动画也分成两类一类是你用 SwiftUI 状态变化驱动的视图动画另一类是系统在收起、展开灵动岛时自动执行的形变动画。前者决定内容动起来后者决定岛怎么开合。适合读这篇文章的人是正在做打车、外卖、播放器、计时器、运动记录这类有实时任务场景的客户端工程师或者想让灵动岛动效落地但还没理清更新机制的 iOS 开发。下面从创建、驱动、排错到进阶验证按真实可跑的路径走一遍。2. 创建会动的基础ActivityKit 的授权、启动、更新与结束2.1 先确认工程配置少一个开关就收不到灵动岛在写任何动画代码之前先确认 Target 的 Info.plist 里有没有NSSupportsLiveActivities这个布尔值。很多“灵动岛不出现”“小组件不更新”的问题第一步就死在这里没有声明支持实时活动ActivityKit 的request会直接抛错连岛都上不去。这个开关不是默认开启的Xcode 新建 Widget Extension 模板也不会自动帮你勾上。配置项所在位置值缺失时的表现NSSupportsLiveActivities主 App Target 的 Info.plistYES启动 Activity 失败日志出现“required string for key not found”之类错误签名与 Deployment Target主 App 与 Widget ExtensioniOS 16.1真机 iPhone 14 Pro 系列或 iPhone 15 Pro 系列模拟器上 Activity 存在但灵动岛区域不渲染动画Widget Extension 的 Info.plist与主 App 同 Target无需额外开关但需开启 App Group若要在主 App 和 Widget 间共享数据主 App 更新状态后 Widget 收不到注意灵动岛的硬件形态依赖原深感摄像头挖孔区域在普通刘海屏机型上Live Activity 只能以锁屏横幅形式出现不会显示成岛。调试动画时尽量用带灵动岛的真机模拟器也能跑但灵动岛的收起、展开形变是模拟渲染和真机的 OLED 显示效果差距很大。2.2 用 ActivityAttributes 定义动画状态模型Live Activity 的架构分两层ActivityAttributes里的静态属性描述这个任务是什么ContentState描述当前时刻的动态状态。动画要做的所有事情几乎都是围绕ContentState变化展开的。下面以播放器为例定义状态模型import ActivityKit struct PlayerActivityAttributes: ActivityAttributes { public struct ContentState: Codable, Hashable { /// 播放进度取值范围 0...1驱动进度条动画 var progress: Double /// 是否正在播放切换时触发图标动画 var isPlaying: Bool /// 显示在紧凑尾部的歌曲名建议不超过 8 个字符 var trackName: String /// 波形动画用记录当前音量高度模拟音频节奏 var audioLevel: Double } /// 静态属性在 Activity 生命周期内不变 var albumName: String }ContentState必须遵循Codable和Hashable因为系统会把状态序列化后交给 Widget 进程渲染。progress和audioLevel这两个字段就是驱动动画的数据源。每次你调用update时系统会把新的ContentState和旧状态做对比然后触发 SwiftUI 视图的 body 重新求值。如果这两个字段不变视图就不会刷新动画自然停住。2.3 启动、更新与结束动画状态推进的完整代码路径import ActivityKit // 启动 Live Activity let attributes PlayerActivityAttributes(albumName: 2025 播放列表) let initialState PlayerActivityAttributes.ContentState( progress: 0.0, isPlaying: true, trackName: 晴天, audioLevel: 0.3 ) do { let activity try ActivityPlayerActivityAttributes.request( attributes: attributes, contentState: initialState, pushType: .token ) // pushType 传 .token 表示允许通过 APNs 远程更新拿到 token 后给服务端 print(Activity 启动pushToken: \(activity.pushToken?.hexString ?? 暂无)) } catch { print(启动失败: \(error.localizedDescription)) } // 本地更新把进度从 0 推到 0.5界面上的进度条会随之动画变化 Task { let nextState PlayerActivityAttributes.ContentState( progress: 0.5, isPlaying: true, trackName: 晴天, audioLevel: 0.8 ) // 注意update 是 async 方法要在 Task 或 async 上下文里调用 await activity.update(using: nextState) } // 结束 ActivitydismissalPolicy 决定结束动画的样式 Task { await activity.end( using: PlayerActivityAttributes.ContentState( progress: 1.0, isPlaying: false, trackName: 晴天, audioLevel: 0.0 ), dismissalPolicy: .default ) // .default 会先展示结束状态再执行收起动画 // .immediate 则直接消失.after(date) 可以指定在未来某个时间消失 }request的pushType参数如果传nil表示只能本地更新不能远程推送。做动画时通常用本地更新因为动画频率高、延迟要求低走 APNs 的网络链路完全跟不上。只有打车、外卖这种低频状态变化才适合远程推送。dismissalPolicy决定结束时的灵动岛收起动画.default和.immediate会让收岛动画节奏不同建议在真机上对比感受不要偷懒只写.immediate。2.4 本地更新和远程推送的取舍更新方式延迟适合场景动画流畅度本地activity.update毫秒级播放进度、计时器、运动步数高可达到系统允许的最高刷新频率APNs 远程推送受网络影响通常 1~3 秒外卖状态、航班状态、快递进度低不适合连续动画本地预定时长 系统自动推进无倒计时、秒表最好系统在后台自己算不需要你更新做“灵动岛动画小组件”时原则上动画数据源应该在 App 进程内直接驱动。如果服务端也想控制动画比较稳妥的做法是服务端推送“目标值”和“动画时长”客户端收到后用update设置终态再配合第 3 章的Text(timerInterval:)或TimelineView让视觉效果连续推进而不是服务端每秒推一帧。3. 在灵动岛上播放动画三种形态与三种动画引擎3.1 从紧凑到展开动画边界由形态决定Live Activity 在灵动岛上有三种展示形态动画必须分形态设计否则会出现“动画显示不全”或“压缩变形”的问题。Apple 的DynamicIsland视图修饰器允许你分别注册 compactLeading、compactTrailing、minimal 和 expanded 区域。紧凑形态高度只有 37.33 pt宽度约 126 pt能放的内容非常有限展开形态会把灵动岛拉成一个约 160 pt 高的大矩形才有足够的空间放进度条、波形、大段文本。DynamicIsland { // 展开形态在灵动岛展开的矩形区域内显示 ExpandedView() } compactLeading: { // 紧凑形态左侧一般放 App 图标或小图标 Image(systemName: music.note) .foregroundStyle(.white) } compactTrailing: { // 紧凑形态右侧放置进度或播放状态 Text(timerInterval: startDate...endDate) .font(.caption2) .monospacedDigit() } minimal: { // 最小形态另一个岛上的独立小圆点 ProgressView() .tint(.white) }动画设计要和这三个区域绑定。比如播放器场景紧凑形态的动画应该放在右侧的圆形进度环上左侧保持静态图标展开形态则把进度条、封面、波形归入底部区域避免左侧空间被裁切。实际开发中我一般会把紧凑形态的动画做得更克制灵动岛本身很小高频率闪动反而让用户视觉疲劳。3.2 用 TimelineView 驱动旋转与闪烁动画如果只是让某个图标转起来、闪一下TimelineView(.animation)是首选。它会让闭包里的视图以系统调度的时间频率重新求值不需要你手动管理Timer也不需要更新ContentState因为驱动的数据源是时间本身DynamicIsland { Text(播放中) } compactLeading: { TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in let seconds context.date.timeIntervalSinceReferenceDate // 用时间的小数部分驱动旋转角度形成连续旋转动画 let angle seconds.truncatingRemainder(dividingBy: 1.0) * 360.0 Image(systemName: waveform) .rotationEffect(.degrees(angle)) .animation(.linear(duration: 0.03), value: angle) .foregroundStyle(.white) } } compactTrailing: { Text(00:42) }minimumInterval: 1.0 / 30.0表示“每 1/30 秒刷新一次”但系统不会真正保证每秒 30 次。在实时活动里更新会被节流实际频率可能只有 10~15 Hz。因为灵动岛区域小、元素轻量这个频率已经足够产生流畅错觉。注意rotationEffect和.animation(value:)只在value变化时触发过渡TimelineView 每次刷新都会给一个新的angle所以可以把 SwiftUI 的隐式动画用在时间驱动的场景里。3.3 让系统自己走时间Text 和 ProgressView 的 timerInterval 模式这是我认为最省心、最优雅的灵动岛动画方式不手动更新状态而是告诉系统“从哪开始、到哪结束”系统按照真实时间在后台自动推进 UI。倒计时、秒表、进度条这些场景都适用let startDate Date() // 任务开始时间 let endDate Date().addingTimeInterval(5 * 60) // 5 分钟后结束 DynamicIsland { VStack { // 展开形态显示剩余时间和一个自动填充的进度条 Text(timerInterval: startDate...endDate) .font(.title2) .monospacedDigit() ProgressView(timerInterval: startDate...endDate) .tint(.white) } .padding() } compactLeading: { Image(systemName: timer) .foregroundStyle(.white) } compactTrailing: { // 紧凑形态系统自动把剩余时间渲染成“4:59”的形式 Text(timerInterval: startDate...endDate) .font(.caption2) .monospacedDigit() } minimal: { ProgressView(timerInterval: startDate...endDate) .tint(.white) }这套 API 的底层由系统维护期间即使用户锁屏、App 退到后台、甚至进程被挂起UI 依然按真实时间走动。对比手动更新方案它不会因为进程被挂起而停在旧时间上。唯一的限制是Text(timerInterval:)默认显示的格式是“分钟:秒”如果要做“小时:分钟:秒”的样式需要自定义Text(_:style:)的DateStyle但灵动岛空间有限建议保持简单。3.4 用 Canvas 播帧序列做出“真正的动画”效果TimelineView 适合轻量状态动画但如果你要播放一组预生成好的帧比如火焰、波纹、音量律动就需要 Canvas 加帧序列的方式。把动画拆成一组 PNG 序列在 TimelineView 中按时间索引取帧struct FrameAnimationView: View { // 预加载的动画帧建议提前用 UIImage 缓存到内存 let frames: [UIImage] var body: some View { TimelineView(.animation(minimumInterval: 1.0 / 24.0)) { context in Canvas { context, size in let total frames.count // 通过时间计算当前帧索引循环播放 let seconds context.date.timeIntervalSinceReferenceDate let frameIndex Int(seconds * 24.0) % total guard frameIndex total else { return } if let cgImage frames[frameIndex].cgImage { // 把当前帧绘制到整个画布区域 context.draw(Image(decorative: cgImage, scale: 1.0), in: CGRect(origin: .zero, size: size)) } } .frame(width: 80, height: 80) .clipped() } } }这套方案是把“动画小组件”做到高帧率错觉的正解。但要注意预算Live Activity 的刷新频率受系统限制你就算把minimumInterval写到1.0 / 60.0也不一定能跑到 60 帧。因此帧序列设计时要克制帧数控制在 20~30 帧以内单帧尺寸按实际显示大小导出不要塞一张 1024 的大图进去否则同时触发解码开销和绘制开销。OLED 屏幕的特性也影响这个选择灵动岛区域本身是纯黑挖孔动画帧中大量高亮像素长时间停留会导致残影风险所以帧动画的高亮面积尽量缩小。3.5 三种动画引擎怎么选引擎适用场景更新频率预算消耗我的建议TimelineView(.animation)旋转、闪烁、波形、进度指示10~30 Hz低适合轻量图形大多数动画的首选Text(timerInterval:)ProgressView倒计时、秒表、剩余时间系统自动极低能不用手写更新就不用Canvas 帧序列逐帧动画、图片序列、特效自定义建议 15~24 Hz高需要控制帧图和大小只在真正需要时使用选型原则很简单能用系统时间驱动就不用ContentState能用 TimelineView 做轻量变换就不上 Canvas。灵动岛动画的美感来自克制和节奏感几十帧的连续动画在这种小尺寸区域里反而容易显得廉价。4. 动画不动、卡顿、显示不全预算与节流的排查路径4.1 修改了 ContentState界面却没有反应最常遇到的坑是代码里调用update了但灵动岛视图纹丝不动。排查顺序是先确认更新的是不是正确的Activity实例。如果同一个 Attributes 启动了多个 Live Activity而你把更新发给了其中一个已结束的实例系统会静默忽略。其次查看ContentState是否有 0 秒内的连续更新系统对更新次数有预算短时间频繁更新会触发节流后续更新被吞掉。另一个容易被忽略的点是Hashable一致性。如果ContentState里的progress从 0.0 改成 0.0000001在浮点比较时可能被系统认为是“无变化”从而跳过 UI 刷新。驱动动画的字段建议按明确的进度单位变化不要做无意义的小数抖动。// 错误的更新方式一次性把 0.0 到 1.0 按每秒 60 次连续推会被节流 for progress in stride(from: 0.0, through: 1.0, by: 0.016) { try? await Task.sleep(nanoseconds: 16_000_000) await activity.update(using: state) } // 正确的做法直接设置终态让视图用 TimelineView 或 timerInterval 自己过渡 let finalState PlayerActivityAttributes.ContentState( progress: 1.0, isPlaying: true, trackName: 晴天, audioLevel: 0.5 ) await activity.update(using: finalState)在真实项目中我一般只更新关键状态点播放、暂停、进度跳转、结束。持续的时间感交给时间驱动的 API而不是靠手刷ContentState。4.2 minimumInterval 不是帧率保证而是更新上限新手最常见误判是认为TimelineView(.animation(minimumInterval: 1.0/60.0))能保证 60 帧。实际上这个参数只是告诉 SwiftUI“不要更快地刷新”系统会根据当前的运行内存、CPU 占用和实时活动的整体预算来降频。如果视图里执行了昂贵的绘制比如 Canvas 里做大量离屏渲染、加载高清图片帧率会掉到个位数。观察实际刷新频率的办法很简单在视图 body 里打印时间戳TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in let timestamp context.date.timeIntervalSinceReferenceDate // 真机观察这个输出之间的间隔正常情况下在 0.03~0.1 秒之间波动 print(刷新: \(timestamp)) Image(systemName: sun.max) }如果两次打印间隔稳定在 0.1 秒附近说明系统已经把更新预算压低你需要简化视图层级或者降低minimumInterval期望值到 10 Hz。时钟类、计时器类的 UI 在 10 Hz 下依然可读但旋转动画看起来就会有点顿挫。4.3 动画显示不全展开态和紧凑态的空间差异“动画显示不全”是我的开发过程中被问得最多的问题。原因基本只有一个同一个动画在不同形态里用了固定 frame导致在紧凑形态下超出边界被裁切。灵动岛紧凑区域的高度限制很严格任何超过 44 pt 的视图都会被裁剪掉而且系统不会给你明显警告。解决方案分两层第一是在设计阶段就避免同一个视图直接复用紧凑形态只放简单图标和数字第二是在必要复用时加上.clipped()和.contentShape()并主动把尺寸压进安全边界。展开态内部也要留边距因为灵动岛展开区域的圆角和系统 UI 会有视觉重叠compactLeading: { Image(systemName: music.note) .frame(width: 16, height: 16) // 明确限制尺寸避免被压缩时变形 .clipped() } expanded: { VStack(spacing: 6) { Text(正在播放) // 展开态四周留 8 pt避免贴近圆角边缘 ProgressView(timerInterval: start...end) .padding(.horizontal, 8) } }4.4 模拟器和真机的动画表现完全不同用模拟器调动画时要格外小心模拟器没有真正地驱动 OLED 屏幕也没硬件渲染层级所以动画卡顿、掉帧、模糊的体验跟真机相差很大。反过来模拟器里看着流畅的动画在真机上可能会显得过于细碎或闪得刺眼。凡是跟灵动岛动画相关的效果一定要以真机为准。若手头只有刘海屏机器就借用一下支持灵动岛的设备或者退而求其次看锁屏横幅动画保证核心动画逻辑正确再接真机验证。4.5 减少僵尸任务防止灵动岛动画越跑越卡如果测试时不断启动新的 Activity而不结束旧的系统会同时维护多个实时活动实例每个实例的视图都在更新CPU 压力会叠加导致动画刷新率进一步下降。开发阶段用一个小工具来集中管理 Activity 实例enum LiveActivityManager { static var current: ActivityPlayerActivityAttributes? static func start() { // 启动前先结束旧实例避免多个 Activity 同时动画 Task { if let old current { await old.end(dismissalPolicy: .immediate) } current try? Activity.request(...) } } }这个管理类同时解决一个问题用户从 App 切出去再回来如果 Activity 还挂着动画却停在老状态那就需要根据当前场景重新update一次。避免让用户看到已经结束的任务还在岛上“播报”。5. 把动画能力做成小组件帧序列、状态保持与验证技巧5.1 抽一个通用的动画播放修饰器如果你要在多个功能里复用同样一套灵动岛动画建议把“时间驱动动画”封装成修饰器。这个修饰器接收一个动画引擎和一组参数内部用 TimelineView 统一驱动struct LiveActivityAnimationModifier: ViewModifier { let engine: AnimationEngine let frameCount: Int func body(content: Content) - some View { TimelineView(.animation(minimumInterval: engine.minimumInterval)) { context in content .environment(\.animationFrameIndex, engine.frameIndex(at: context.date)) } } } enum AnimationEngine { case rotation(speed: Double) case frameSequence(fps: Int) var minimumInterval: TimeInterval { switch self { case .rotation: return 1.0 / 30.0 case .frameSequence(let fps): return 1.0 / TimeInterval(fps) } } func frameIndex(at date: Date) - Int { switch self { case .rotation(let speed): return Int(date.timeIntervalSinceReferenceDate * speed * 30) % 360 case .frameSequence(let fps): return Int(date.timeIntervalSinceReferenceDate * Double(fps)) % 30 } } }这样做的好处是动画逻辑和视图解耦调试的时候可以只改AnimationEngine的枚举值而不用去每个视图里调整 TimelineView 参数。这其实就是不少团队在“动画工作流”里沉淀下来的做法把时间轴、帧率、帧索引封装成数据驱动的东西让设计师和开发共用一套参数描述。5.2 锁屏小组件和灵动岛共享一个动画状态如果 App 同时做了锁屏小组件和灵动岛要注意两个容器不是同一个进程不能直接共享内存。推荐做法是把动画状态写入 App Group 的共享 UserDefaults 或一个小型 JSON 文件锁屏小组件在刷新时读取。但这种机制的同步频率不高适合播放、暂停、当前进度等低频状态。高频动画数据不应该跨进程。比如音量波动这种需要每秒刷新数十次的数据只放在 Live Activity 的ContentState里实时更新。锁屏小组件就展示静态数据和最近一次快照不要试图同步每一帧。这是常见的误用场景两边都想要连续动画结果把跨进程通信的负载打满最后两边都掉帧。5.3 用 iOS 自动化做推送测试不打断动画状态机调试更新流程时我会用快捷指令配合服务端做一次远程通道测试。做法是在快捷指令里用“获取 URL 内容”向自己的服务端发一个 POST服务端再通过 APNs 向当前 Activity 的 pushToken 推一条更新。这样可以验证远程推送链路是否通畅同时不打断本地动画状态机的连续节奏。注意 pushToken 是Data类型需要转成十六进制字符串后才能发给 APNs。正常情况下 token 会在 Activity 启动后的几秒内回调。如果一直拿不到 token确认pushType是否传了.token以及 App 是否有远程通知权限。测试结束后记得把current实例调用end(dismissalPolicy: .immediate)避免残留 Activity 影响后续测试。5.4 验证动画是否流畅的三个手段第一个手段是拿秒表直接掐录一段灵动岛的屏幕视频把视频放到剪辑软件里逐帧拖看动画是不是均匀推进。这是最朴素的验证方法但效果最直接。第二个手段是把 Xcode 的os_signpost埋点放进 TimelineView 更新闭包里统计每秒实际刷新次数对比设计目标帧率。第三个手段是开 MeterKit 观测实时活动的 CPU 占用如果动画逻辑占用了过多 CPU系统会主动降频这时优先优化视图体量而不是继续堆动画帧数。// os_signpost 埋点示例用 Instruments 的 os_signpost 模板查看 import os.signpost let log OSLog(subsystem: com.example.player, category: LiveActivityAnimation) let spid OSSignpostID(log: log) TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { context in os_signpost(.event, log: log, name: FrameUpdate, signpostID: spid, fps: %d, Int(1.0 / max(context.date.timeIntervalSince(lastDate), 0.0001))) }看刷新间隔的分布如果大部分时间落在 30~40 ms 左右说明刷新率在 25~30 Hz对灵动岛动画来说已经够用。如果大量间隔超过 100 ms就要回第 4 章查视图重量和更新频率了。最后记住一条灵动岛动画的核心是“用系统时间代替手动推进”把握住这一点动画显示不全、卡顿、被节流的问题至少能少一半。本文还有配套的精品资源点击获取