实时活动(灵动岛)
LiveActivity API 允许你的脚本在 iOS 的锁屏界面以及支持的设备上的动态岛中展示实时数据。通过该 API,你可以创建、更新并结束 Live Activity,同时监听其生命周期状态和系统支持情况。
本文件详细介绍 Scripting app 中的 LiveActivity API,包括:
- Live Activity 的生命周期与核心概念
- 如何注册 Live Activity UI
- 如何在脚本中启动、更新、结束 Live Activity
- 如何构建 Live Activity UI(包括 Dynamic Island 多种布局)
- 所有类型参数说明
- 完整示例代码与最佳实践
本 API 基于 Apple ActivityKit 能力,并以 TypeScript/TSX 的方式封装,允许开发者使用 React 风格构建 Lock Screen 与 Dynamic Island 界面。
1. Live Activity 概念理解
Live Activity 展示在以下区域:
- 锁屏界面
- iPhone 14 Pro+ 的 Dynamic Island
- 其他设备的悬浮样式(Banner)
它能随着应用或脚本运行实时更新内容,如:
- 计时器
- 外卖进度
- 健身、运动状态
- 倒计时、打卡、提醒
在 Scripting app 中,一个 Live Activity 由两部分组成:
- 内容状态(contentState) 一个 JSON 可序列化的对象,会随时间改变。
- UI Builder 通过 TSX 描述不同区域的展示方式。
2. Live Activity 状态类型
3. LiveActivityDetail 类型
用于描述当前正在运行的所有 Live Activity 信息。
4. LiveActivity UI 构建类型
4.1 LiveActivityUIProps
这些字段对应 Dynamic Island:
- content:锁屏和普通设备顶部 Banner 显示
- compactLeading / compactTrailing:Dynamic Island 收缩状态左右区域
- minimal:最小化的单点显示
- children:展开后的多个区域(使用
LiveActivityUIExpanded*包裹)
5. 注册 Live Activity UI
Live Activity 必须放在单独的文件中,例如 live_activity.tsx:
6. 在脚本中使用 Live Activity
下面展示如何启动、更新、监听状态并结束 Live Activity。
7. LiveActivity 类 API 说明
7.1 start(contentState, options?)
- 请求系统启动 Live Activity
- contentState 必须可以 JSON 序列化
LiveActivityOptions
- staleDate:到期变为 stale 的时间戳(ms) 或 Date 对象
- relevanceScore:控制 Dynamic Island 的优先级
7.2 update(contentState, options?)
LiveActivityUpdateOptions
可带 Apple Watch 的更新提示。
7.3 end(contentState, options?)
LiveActivityEndOptions
dismissTimeInterval(单位秒):
- 未提供:系统默认最长保留 4 小时
- <= 0:立即移除
- > 0:指定多久后移除
7.4 获取活动状态
7.5 监听状态更新
当 Live Activity 状态变更时回调,例如:
- active → stale
- active → ended
- ended → dismissed
7.6 静态方法
8. Live Activity UI 组件
用于构建 Dynamic Island 展开布局。
9. 注意事项与最佳实践
9.1 必须 JSON 可序列化
contentState 中不能包含:
- 函数
- Date 对象(需转 timestamp)
- class 实例
- 非可序列化对象
9.2 Live Activity 必须放在独立文件
例如:
这与系统对 UI 构建的要求有关。
9.3 Scripting 的 Live Activity 与脚本生命周期隔离
即使脚本结束,Live Activity 会继续保持。
若你希望脚本保持运行,可使用:
10. 完整示例(简化版)
11. 注意事项
- Live Activity 的启动是异步的,需要等到
start返回true时才能调用update和end - Live Activity 不能访问 Documents 和 iCloud 目录,只能访问 app group 目录,如果你想要访问文件或者渲染图片,必须把文件或图片保存到
FileManager.appGroupDocumentsDirectory目录中。 比如渲染图片,你保存到FileManager.appGroupDocumentsDirectory中, 再通过<Image filePath={Path.join(FileManager.appGroupDocumentsDirectory, 'example.png')} />渲染 - Live Activity 可以访问与 App 共享的 Storage 数据
