实时活动（灵动岛）#

LiveActivity 接口在 Scripting 中为您提供在 灵动岛 和 锁屏 上展示实时数据的能力，提供便捷的互动功能。#

1. 类型和接口#

LiveActivityState#

定义 Live Activity 的状态：

• active: Live Activity 正在显示，并可接收更新。
• dismissed: Live Activity 已结束，不再显示。
• ended: Live Activity 虽仍可见，但不再更新。
• stale: Live Activity 的内容已过期，需要更新。

LiveActivityDetail#

用于提供每个 Live Activity 实例的详细信息。

• id: Live Activity 的唯一标识符。
• state: 当前的 LiveActivityState。

LiveActivityUI#

描述 Live Activity 的布局：

• content: 在锁屏上显示的主要视图。
• expanded: 在动态岛展开后显示的视图组件(以下内容必须提供一个)：
  • leading: 位于左侧的内容(可选)。
  • trailing: 位于右侧的内容(可选)。
  • center: 摄像头区域下方居中的内容(可选)。
  • bottom: 所有其他部分下方的内容(可选)。
• compactLeading 与 compactTrailing: 动态岛收起时，左侧和右侧的紧凑布局。
• minimal: 更加简洁的紧凑视图布局。

LiveActivityUIBuilder<T>#

一个基于动态属性来构建 LiveActivityUI 的函数。

LiveActivityOptions#

配置 Live Activity 的选项：

• staleDate: 当 Live Activity 被视为过期的时间戳。
• relevanceScore: 当存在多个 Live Activity 时，决定其优先级。

LiveActivityUpdateOptions & LiveActivityEndOptions#

与 LiveActivityOptions 类似，用于配置更新时的提醒方式（update）及结束时的移除时机或其他选项（end）。

2. LiveActivity 类#

构造器#

1constructor(builder: LiveActivityUIBuilder<T>)

使用一个 UI 构建函数（LiveActivityUIBuilder<T>）来创建一个新的 Live Activity。

属性#

• activityId: string | undefined
  当调用 start 后，Live Activity 的 ID。

• started: boolean
  指示 Live Activity 是否已启动。

方法#

start(attributes: T, options?: LiveActivityOptions): Promise<boolean>#

使用指定的属性和选项启动一个 Live Activity。若启动成功，返回 true。

update(attributes: T, options?: LiveActivityUpdateOptions): Promise<boolean>#

更新 Live Activity 的动态属性。如果在 options 中指定了提醒配置，则会向用户发送通知提醒。

end(attributes: T, options?: LiveActivityEndOptions): Promise<boolean>#

结束一个正在运行的 Live Activity，可选地附加最终属性和结束选项。

getActivityState(): Promise<LiveActivityState | null>#

获取当前 Live Activity 的状态。

addUpdateListener(listener: (state: LiveActivityState) => void): void#

为 Live Activity 的状态变化添加一个监听器。

removeUpdateListener(listener: (state: LiveActivityState) => void): void#

移除指定的状态更新监听器。

静态方法#

• areActivitiesEnabled()
  检查是否可以启动 Live Activity（由系统配置或限制决定）。

• addActivitiesEnabledListener(listener: LiveActivityActivitiesEnabledListener)
  当 Live Activities 的可用状态发生变化时，添加一个监听器进行监测。

• getAllActivities()
  返回当前所有处于活动状态的 Live Activities 数组。

• getAllActivitiesIds()
  返回当前所有活动 Live Activity 的 ID 列表。

• endAllActivities(options?: LiveActivityEndOptions)
  结束所有正在运行的 Live Activities。

3. 使用示例#

示例 1: 启动 Live Activity#

1const liveActivity = new LiveActivity(({ status, eta, icon }) => ({
2    content: <Text>{status}</Text>,
3    expanded: {
4        leading: <Text>ETA: {eta}</Text>,
5        trailing: <Image systemName={icon} />
6    },
7    compactLeading: <Text>{eta}</Text>,
8    compactTrailing: <Image systemName={icon} />,
9    minimal: <Text>{eta}</Text>
10}))
11
12await liveActivity.start({
13    status: "Tracking delivery",
14    eta: "20 min",
15    icon: "truck.box.badge.clock"
16})

示例 2: 更新 Live Activity#

1await liveActivity.update(
2    { status: "Arriving soon", eta: "10 min", icon: "truck.box.badge.clock" },
3    {
4        alert: {
5            title: "Order Update",
6            body: "Your order is arriving soon!"
7        }
8    }
9)

示例 3: 结束 Live Activity#

1await liveActivity.end(
2    { status: "Delivered", eta: "0 min", icon: "truck.box" },
3    { dismissTimeInterval: 5000 }
4)

在上述示例中，使用了相同结构的属性（status、eta、icon），并在 start、update、end 三种场景下保持一致，以确保 Live Activity UI 能根据动态数据进行正确的展示和更新。