# Expo Live Activity 计时器

By Tarik Pinarci (https://tarikpinarci.com). Published 2025-05-01. Canonical: https://tarikpinarci.com/zh/blog/expo-live-activity-timer

# 在 Expo 中构建 Live Activity 计时器

iOS 上的 Live Activities 改变了很多东西，它让应用可以直接在锁屏或灵动岛上显示实时更新。我自然开始想象：如果健身计时器能在那里运行，用户不用解锁手机就能保持状态，那该多酷。但有个问题：Live Activities 是用 Apple 的原生工具构建的，比如 Swift 和 ActivityKit。就在这时，我发现了一个叫 [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets) 的工具，不用从零开始写整个模块，整个过程比我预想的简单得多。在这篇文章里，我会带你看看我是如何为 iOS 构建一个基于计时器的 Live Activity 的，包括我走过的步骤和一路上学到的东西。

## 为什么我对 Live Activities 着了迷

Live Activities 不只是一个炫酷的小技巧，它能实实在在地提升用户参与度。Apple 的 [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/live-activities) 把它描述为一种为时间敏感任务提供“当前的、一眼可见的信息”的方式。想象一下：健身应用在训练中显示你的平板支撑时间，外卖应用追踪你的披萨送到了哪里，打车应用更新司机的预计到达时间，这些都直接显示在锁屏上，或者在 iPhone 14 Pro 及之后的机型上显示在灵动岛里。这就像给用户一张 VIP 通行证，让他们不用解锁手机就能看到应用里最重要的更新。

我希望用户在做一组训练时能看到计时器在走，让他们保持专注，而不必打开应用。这种打磨会让应用显得很专业，我决定全力投入。但不碰原生层是做不到这些的，所以我知道自己要深入 Swift，还要和 Xcode 较劲。后来我发现了 [expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets)，这个包在 Expo 的 JavaScript 世界和 iOS 原生功能之间架起了桥梁。非常感谢 [Evan Bacon](https://x.com/Baconbrix)，这个工具把一项令人望而生畏的任务变成了一个有挑战但能解开的谜题。

## 全局视角：Expo 应用中的 Live Activities

Live Activities 是 iOS 独有的功能。它由 ActivityKit 驱动，这是一个基于 Swift 的框架，也就是说不管你愿不愿意，都得写原生代码。对 Expo 应用来说，这就像劝一条鱼去爬树：可以做到，但要费点力气。expo-apple-targets 就像一位经验丰富的向导，提供了一个框架来创建原生模块和 widget 扩展，不用从零开始。它建立在 Expo 的模块系统（[Expo Modules API](https://docs.expo.dev/modules/module-api/)）之上，让你用 Swift 写原生代码并暴露给 JavaScript，整个过程没那么痛苦了。

## 搭建项目

起步并不算轻松，但 expo-apple-targets 让它变得可控。下面是我的起步方式：

- **安装 expo-apple-targets**：一句 npm install expo-apple-targets 就能开始。这个包的 README 是个宝库，会指导你在 Xcode 中添加 widget 扩展，并在 app.json 中加入 Live Activity 的 entitlement（com.apple.developer.activitykit）。

- **原生模块设置**：我用 Expo 的模块系统创建了一个与 ActivityKit 通信的 Swift 模块。[Expo Modules 文档](https://docs.expo.dev/modules/module-api/) 强调要定义清晰的函数签名和事件，这让我毫不费力地把 startActivity 这样的方法暴露给 JavaScript。

- **Widget 扩展**：这里用到了 SwiftUI，我用它来设计 Live Activity 在锁屏和灵动岛上的外观。expo-apple-targets 提供了一个 widget 模板，但我必须自定义它，让它显示一个走动的计时器和可交互的按钮。

- **Intents**：它让用户可以点击 widget 上的按钮来暂停或继续计时。expo-apple-targets 简化了 intent 的设置，但我还是得调试几次失灵的情况，才让通知正常流转。

## 每秒更新一次的计时器？

![一名开发者兴奋地实现了每秒一次的计时器更新，结果计时器肆虐，系统陷入混乱的过载。([由 gpt-4o 生成](https://openai.com/index/hello-gpt-4o/))](https://cdn-images-1.medium.com/max/2048/1*Nq1a3rqsEIBCgTsAWdvgNQ.png)_一名开发者兴奋地实现了每秒一次的计时器更新，结果计时器肆虐，系统陷入混乱的过载。([由 gpt-4o 生成](https://openai.com/index/hello-gpt-4o/))_

刚开始做计时器时，我的第一反应是：“_每秒用当前时间更新一次 Live Activity 就行了_。”听起来很直接，对吧？错了。我偶然看到一个 [Reddit 帖子](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173)，开发者们在讨论如何更新 Live Activity 的计时器。结论很一致：每秒更新一次是一场灾难。这就像用仓鼠跑轮给宇宙飞船供电，它会动，但很快就会烧坏。持续的更新会猛烈消耗 CPU、耗尽电量，让应用变得迟钝。

那个 Reddit 帖子给我敲响了警钟。我在 Apple 的 [SwiftUI 文档](<https://developer.apple.com/documentation/swiftui/text/init(timerinterval:pausetime:countsdown:showshours:)>) 中找到了 SwiftUI 的 Text(timerInterval:)，这简直是个启示。这个视图在原生层处理计时器更新，不需要刷新整个 Live Activity 就能一直走动。这就像把无聊的活外包给 iOS，你就能专注于有趣的部分。

于是我放弃了每秒更新的方案，改用 startedAt/pausedAt 的方式。下面是它胜出的原因：

- **性能**：我不再每秒发出更新，而是存储计时器的开始时间（startedAt）和暂停时间（pausedAt，如果已暂停）。widget 用 Text(timerInterval:) 基于 startedAt 显示一个实时计时器，暂停时则用 pausedAt 显示一个静态时间。这把 API 调用降到了几乎为零。

- **省电**：频繁更新是吸电鬼。让 SwiftUI 负责走动，应用保持轻量，用户的手机也更开心。

- **符合 API 规范**：Apple 的 Live Activity API 并不是为实时刷屏式更新设计的。startedAt/pausedAt 的方案符合 iOS 的预期，降低了被限流的可能。

- **代码简洁**：管理两个时间戳比应付一连串更新容易得多。代码保持干净，我的压力也在可控范围内。

这种做法就像在电子游戏里找到了一条秘密捷径。计时器运行流畅，看起来很棒，也不占用资源。那个 Reddit 帖子（[再贴一次链接](https://www.reddit.com/r/iOSProgramming/comments/18n12wh/how_does_this_app_achieve_to_update_its_live/?rdt=52173)）值得一枚奖章，是它为我指明了方向。

## Live Activity 的核心

我不会用每一行代码来烦你，我们重点看让这个计时器运转起来的关键片段。文章最后我会在 GitHub 上分享完整源码。

### LiveActivityAttributes 结构体

这个结构体是 Live Activity 的骨架，定义了它的数据以及数据如何变化。

```swift
    struct LiveActivityAttributes: ActivityAttributes {
      public struct ContentState: Codable, Hashable {
        var startedAt: Date
        var pausedAt: Date?

        func getElapsedTimeInSeconds() -> TimeInterval {
          if let pausedAt = pausedAt {
            return pausedAt.timeIntervalSince(startedAt)
          } else {
            return Date().timeIntervalSince(startedAt)
          }
        }
        func isRunning() -> Bool {
          return pausedAt == nil
        }
        func getFormattedElapsedTime() -> String {
          let elapsed = getElapsedTimeInSeconds()
          let totalSeconds = Int(elapsed)
          let hours = totalSeconds / 3600
          let minutes = (totalSeconds % 3600) / 60
          let seconds = totalSeconds % 60
          if hours > 0 {
            return String(format: "%d:%02d:%02d", hours, minutes, seconds)
          } else {
            return String(format: "%d:%02d", minutes, seconds)
          }
        }
        func getFutureDate() -> Date {
          return Date().addingTimeInterval(365 * 24 * 60 * 60)
        }
      }
      var activityName: String
      var activityIcon: String
    }
```

它就像 Live Activity 的 DNA。外层的 LiveActivityAttributes 保存静态内容，也就是在活动开始时设置的 activityName（例如 “Workout”）和 activityIcon（例如 “RUNNING”）。内层的 ContentState 才是动作发生的地方，它追踪 startedAt（计时器开始的时间）和 pausedAt（暂停的时间，如果有的话）。这些辅助方法才是真正的功臣：

- getElapsedTimeInSeconds() 计算计时器已经运行了多久：如果已暂停，就截止到 pausedAt；如果在运行，就用当前时间。这让逻辑紧凑且可复用。

- isRunning() 是一个简单的检查：如果 pausedAt 为 null，计时器就在运行。这样就避免了在别处写一堆凌乱的状态检查。

- getFormattedElapsedTime() 把秒数转换成好看的 “MM:SS” 或 “HH:MM:SS” 字符串供 widget 使用。我意识到有些用户可能会做马拉松这样超长的训练后，才加上了小时的支持。

- getFutureDate() 设置一个一年后的日期，我把它传给 Text(timerInterval:)，让计时器可以无限运行，不用担心结束日期。

我很喜欢这个结构体把一切组织得井井有条。它就像一个收拾得很好的背包：需要的都在，不需要的一样没有。遵循 Codable 和 Hashable 让它在更新时很容易序列化，也方便在 SwiftUI 中使用，在模块和 widget 之间同步状态时这帮了我大忙。

### 启动 Live Activity

startActivity 函数是魔法开始的地方，它会启动一个新的 Live Activity。

```swift
    AsyncFunction("startActivity") { (activityName: String, activityIcon: String) -> String in
        if #available(iOS 16.2, *) {
            await self.endAllActivities()
            self.startedAt = Date()
            self.pausedAt = nil
            if !ActivityAuthorizationInfo().areActivitiesEnabled {
                return ""
            }
            let attributes = LiveActivityAttributes(activityName: activityName, activityIcon: activityIcon)
            let contentState = LiveActivityAttributes.ContentState(startedAt: self.startedAt!, pausedAt: nil)
            do {
                let activity = try Activity.request(attributes: attributes, content: .init(state: contentState, staleDate: nil), pushType: nil)
                self.currentActivityId = activity.id
                self.sendTimerUpdateEvent()
                return activity.id
            } catch {
                throw error
            }
        }
        return ""
    }
```

这个函数是点燃一切的火花。它通过 Expo 的模块系统暴露给 JavaScript，让我的 React Native 应用可以传入名称和图标来调用它。它做了这些事：

- 检查系统是否为 iOS 16.2 或更高版本，在此之前没有 Live Activities。

- 调用 endAllActivities() 清除已有的活动。iOS 允许同时存在多个 Live Activity，但为了避免混乱，我只想要一个。

- 把 startedAt 设为当前时间并清空 pausedAt，为计时器运行做好准备。

- 确认 Live Activities 已启用（用户可以在设置中关闭它，早期这一点让我摸不着头脑）。

- 用传入的名称和图标构建一个 LiveActivityAttributes，并用开始时间构建一个 ContentState。

- 通过 Activity.request 请求一个新活动，得到一个带有唯一 ID 的 Activity 对象。

- 保存这个 ID，向 JavaScript 发送一个更新事件，并返回 ID，让应用可以追踪它。

### 暂停计时器

暂停计时器由 performPause 处理，它会更新 Live Activity 的状态。

```swift
    private func performPause(activityId: String?) async -> Bool {
        guard #available(iOS 16.2, *), self.pausedAt == nil else {
            return false
        }
        let targetId = activityId ?? self.currentActivityId
        guard let targetId = targetId else {
            return false
        }
        guard let activity = await self.findActivityById(targetId) else {
            return false
        }
        guard let currentStartedAt = self.startedAt else {
            return false
        }
        let now = Date()
        self.pausedAt = now
        let contentState = LiveActivityAttributes.ContentState(startedAt: currentStartedAt, pausedAt: self.pausedAt)
        await activity.update(using: contentState)
        self.sendTimerUpdateEvent()
        return true
    }
```

这里正是 startedAt/pausedAt 方案大放异彩的地方。当用户暂停计时器时（无论是在应用里还是在 widget 上），这个函数会：

- 检查系统是否为 iOS 16.2，并且计时器尚未暂停（不允许重复暂停）。

- 获取活动 ID，如果没有传入，就回退到 currentActivityId。

- 用 findActivityById 在当前活动中查找对应的活动。

- 把 pausedAt 设为当前时间，冻结计时器。

- 用原来的 startedAt 和新的 pausedAt 创建一个新的 ContentState。

- 用 activity.update 更新活动，让 widget 显示暂停时的时间。

- 向 JavaScript 发送一个事件，保持应用 UI 同步。

这里的逻辑讲究精确，每一项检查（比如 pausedAt == nil）都是为了防止奇怪的边界情况，比如暂停一个不存在的活动。事件处理方面我参考了 [Expo Modules 文档](https://docs.expo.dev/modules/overview/)，用 sendEvent 把更新推送给 JavaScript。这个函数的早期版本没有校验 startedAt，导致计时器显示得很古怪。教训是：一定要守护好你的 state。

## 锁屏视图

LockScreenLiveActivityView 是用户在手机锁屏时看到的界面，必须好看。

![锁屏上的 Live Activity](https://cdn-images-1.medium.com/max/2000/1*IZ1ZSG7_99jfTMBJosePGQ.png)_锁屏上的 Live Activity_

```swift
    struct LockScreenLiveActivityView: View {
        let context: ActivityViewContext<LiveActivityAttributes>
        var body: some View {
            ZStack {
                Color.black.opacity(0.8)
                    .clipShape(RoundedRectangle(cornerRadius: 16))
                HStack(spacing: 16) {
                    VStack(alignment: .leading, spacing: 12) {
                        HStack(spacing: 8) {
                            ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                                        themeColor: .white,
                                        size: 18)
                            Text(context.attributes.activityName)
                                .font(.headline)
                                .foregroundColor(.white)
                        }
                        VStack(alignment: .leading, spacing: 4) {
                            if !context.state.isRunning() {
                                Text(context.state.getFormattedElapsedTime())
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            } else {
                                Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                                     pauseTime: nil,
                                     countsDown: false,
                                     showsHours: false)
                                    .font(.system(size: 34, weight: .semibold, design: .rounded))
                                    .foregroundColor(.white)
                                    .fontWeight(.medium)
                                    .monospacedDigit()
                            }
                        }
                    }
                    .frame(maxHeight: .infinity, alignment: .center)
                    Spacer()
                    VStack {
                        Spacer()
                        if context.state.isRunning() {
                            Button(intent: PauseIntent()) {
                                ZStack {
                                    Circle()
                                        .fill(Color(hex: "#007bff"))
                                        .frame(width: 44, height: 44)
                                    Image(systemName: "pause.fill")
                                        .font(.system(size: 18, weight: .bold))
                                        .foregroundColor(.white)
                                }
                            }
                            .buttonStyle(PlainButtonStyle())
                        } else {
                            HStack(spacing: 8) {
                                Button(intent: CompleteIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#28a745"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "checkmark")
                                            .font(.system(size: 16, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                                Button(intent: ResumeIntent()) {
                                    ZStack {
                                        Circle()
                                            .fill(Color(hex: "#007bff"))
                                            .frame(width: 44, height: 44)
                                        Image(systemName: "play.fill")
                                            .font(.system(size: 18, weight: .bold))
                                            .foregroundColor(.white)
                                    }
                                }
                                .buttonStyle(PlainButtonStyle())
                            }
                        }
                        Spacer()
                    }
                }
                .padding(16)
            }
        }
    }
```

这是 Live Activity 的视觉核心，也是 SwiftUI 真正大显身手的地方。视图分为左右两部分：

- **左侧**：显示活动名称、图标和计时器。如果计时器在运行，Text(timerInterval:) 承担主要工作，从 startedAt 一直计到一年之后（多亏了 getFutureDate）。如果已暂停，它会显示 getFormattedElapsedTime 给出的静态时间。.monospacedDigit() 修饰符让数字保持清晰，我还调整了字体，让它加粗、易读。

- **右侧**：放置按钮。运行时有一个蓝色的暂停按钮。暂停时，会出现一个用来打开应用的绿色对勾，以及一个用来继续的蓝色播放按钮。每个按钮都会触发一个 intent，由原生模块捕获并处理。

## 深入[灵动岛](https://developer.apple.com/design/human-interface-guidelines/live-activities#The-Dynamic-Island)

![灵动岛视图](https://cdn-images-1.medium.com/max/2000/1*iqy0d6FZe9UU0Tce7qCDug.png)_灵动岛视图_

这段代码定义了 Live Activity 在灵动岛三种模式下的样子：expanded（完整视图）、compact（压缩视图）和 minimal（极简视图）。

```swift
    dynamicIsland: { context in
      DynamicIsland {
        DynamicIslandExpandedRegion(.leading) {
          VStack(alignment: .leading, spacing: 8) {
            HStack(spacing: 8) {
              ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                          themeColor: .white,
                          size: 18)

              Text(context.attributes.activityName)
                .foregroundColor(.white)
                .font(.system(size: 16, weight: .semibold))
            }

            if !context.state.isRunning() {
              Text(context.state.getFormattedElapsedTime())
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            } else {
              Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
                   pauseTime: nil,
                   countsDown: false,
                   showsHours: false)
                .font(.system(size: 32, weight: .bold, design: .rounded))
                .foregroundColor(.white)
                .fontWeight(.medium)
                .monospacedDigit()
            }
          }
          .padding(.leading, 8)
        }

        DynamicIslandExpandedRegion(.trailing) {
          VStack {
            Spacer()

            if context.state.isRunning() {
              Button(intent: PauseIntent()) {
                ZStack {
                  Circle()
                    .fill(Color(hex: "#007bff"))
                    .frame(width: 44, height: 44)
                  Image(systemName: "pause.fill")
                    .font(.system(size: 18, weight: .bold))
                    .foregroundColor(.white)
                }
              }
              .buttonStyle(PlainButtonStyle())
              .padding(.horizontal, 8)
            } else {
              HStack(spacing: 8) {
                Button(intent: CompleteIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#28a745"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "checkmark")
                      .font(.system(size: 16, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())

                Button(intent: ResumeIntent()) {
                  ZStack {
                    Circle()
                      .fill(Color(hex: "#007bff"))
                      .frame(width: 44, height: 44)
                    Image(systemName: "play.fill")
                      .font(.system(size: 18, weight: .bold))
                      .foregroundColor(.white)
                  }
                }
                .buttonStyle(PlainButtonStyle())
              }
            }
          }
          .frame(maxHeight: .infinity)
        }
      } compactLeading: {
        HStack(spacing: 4) {
          ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                      themeColor: .white,
                      size: 16)

          Text(context.attributes.activityName)
            .foregroundColor(.white)
            .font(.system(size: 12))
            .lineLimit(1)
            .truncationMode(.tail)
        }
      } compactTrailing: {
        if !context.state.isRunning() {
          Text(context.state.getFormattedElapsedTime())
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        } else {
          Text(timerInterval: context.state.startedAt...context.state.getFutureDate(),
               pauseTime: nil,
               countsDown: false,
               showsHours: false)
            .foregroundColor(.white)
            .monospacedDigit()
            .font(.system(size: 12, weight: .medium))
        }
      } minimal: {
        ActivityIcon(activityIcon: mapJSIconToSFSymbol(context.attributes.activityIcon),
                    themeColor: .white,
                    size: 12)
      }
    }
```

- [\*\*Expanded 模式](https://developer.apple.com/design/human-interface-guidelines/live-activities#Expanded-presentation)\*\*：长按时显示，分为 .leading 和 .trailing 两部分。leading 一侧把图标（例如一个跑步的小人）和名称（“Workout”）叠放在一起，下面是一个大号计时器：暂停时显示静态时间（getFormattedElapsedTime），运行时显示走动的时间（Text(timerInterval:)）。trailing 一侧放按钮：运行时是蓝色暂停按钮，暂停时是绿色对勾（打开应用）和蓝色播放按钮（继续）。我调整了字体和内边距，让它贴合灵动岛的弧度。

- [\*\*Compact 模式](https://developer.apple.com/design/human-interface-guidelines/live-activities#Compact-presentation)\*\*：空间变小时，compactLeading 显示一个小图标和截断的名称，compactTrailing 显示计时器（静态或走动）。.lineLimit(1) 让名称保持整洁，12 号字体保证了可读性。

- [\*\*Minimal 模式](https://developer.apple.com/design/human-interface-guidelines/live-activities#Minimal-presentation)\*\*：空间极其有限，只有一个 12 号大小的图标，比如一个哑铃，用来表示“计时器还在”。简单但有效。

## \_shared 文件夹：为什么它很重要

![\_shared 文件夹概览](https://cdn-images-1.medium.com/max/2000/1*OdZlqw2AXJeTakpTlghLDQ.png)_\_shared 文件夹概览_

[expo-apple-targets](https://github.com/EvanBacon/expo-apple-targets?tab=readme-ov-file#_shared) 中的 \_shared 文件夹是一个顶层目录，用来把关键代码同时链接到主应用 target 和子 target（比如 Live Activity widget）。

widget 这样的扩展运行在独立的进程中，需要把特定文件同时链接到它自己的 target 和主应用的 target。\_shared 文件夹确保这些文件会被自动链接到两边，省去了手动配置。对于我的计时器，我把 LiveActivityAttributes 结构体放在这里，保证应用和 widget 共享同一份计时器状态（startedAt、pausedAt），不会出现同步问题。

## 从 Live Activity Widget 启动应用

CompleteIntent 让用户可以点击 Live Activity widget 上的对勾按钮来打开应用，表示他们已经完成了计时。这是结束一次训练时一个简单但关键的交互。

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct CompleteIntent: AppIntent, LiveActivityIntent {
        static var title: LocalizedStringResource = "Complete Exercise"
        static var description: IntentDescription = "Opens the app to complete the exercise"
        static var openAppWhenRun: Bool = true

        init() {}
        func perform() async throws -> some IntentResult {
            NotificationCenter.default.post(name: Notification.Name("completeActivityFromWidget"), object: nil)

            return .result()
        }
    }
```

当用户点击绿色对勾时，这个 intent 会触发，发出一个 completeActivityFromWidget 通知。原生模块捕获它，向 JavaScript 触发 onWidgetCompleteActivity 事件，同时 iOS 会打开应用，这要归功于 [openAppWhenRun](https://developer.apple.com/documentation/appintents/openurlintent/openappwhenrun): true。

## 用 Intents 处理用户点击

PauseIntent 是让 widget 可以交互的 intent 之一。

![锁屏 Live Activity 的 Intents](https://cdn-images-1.medium.com/max/2000/1*k2nzvHgwgqj6tFESIFcmbw.png)_锁屏 Live Activity 的 Intents_

```swift
    import AppIntents
    import WidgetKit

    @available(iOS 16.2, *)
    struct PauseIntent: AppIntent, LiveActivityIntent {
      static var title: LocalizedStringResource = "Pause Timer"
      static var description: IntentDescription = "Pauses the current timer."

      init() {}

      func perform() async throws -> some IntentResult {
        NotificationCenter.default.post(name: Notification.Name("pauseTimerFromWidget"), object: nil)
        return .result()
      }
    }
```

当用户点击 widget 上的暂停按钮时，这个 intent 会被触发。它极其简单，但很强大：

- 它发出一个通知（pauseTimerFromWidget），原生模块通过 setupNotificationObservers 捕获这个通知。

- 然后模块运行 performPause，更新 Live Activity 的状态并通知 JavaScript。

它的妙处在于 intents 形成了一个无缝的闭环：用户点击 → intent 触发 → 模块更新 → 应用保持同步。expo-apple-targets 提供了模板，让设置 intents 变得很轻松，但我还是遇到过一次点击没有反应的情况，需要调试。结果发现是我把一个通知名称拼错了。很经典。[Expo Modules 文档](https://docs.expo.dev/modules/overview/) 帮我理解了如何处理由原生操作触发的事件，这是让这一切跑通的关键。

## 与 JavaScript 通信的事件

![](https://cdn-images-1.medium.com/max/2000/1*F5GUBNYqWxbZbLU8-LZ0Ug.png)

下面这一节中的事件，是原生模块借助 Expo 的事件系统让 React Native 应用与 Live Activity 状态保持同步的方式。

### onWidgetCompleteActivity

当用户点击对勾完成活动时，这个事件会被触发，触发源是 CompleteIntent。

```swift
    @objc func completeIntentHandler(_ notification: Notification) {
        guard let currentId = self.currentActivityId, self.startedAt != nil else {
            return
        }

        let elapsed = self.calculateElapsedTime()

        sendEvent("onWidgetCompleteActivity", [
            "activityId": currentId,
            "elapsedTime": Int(elapsed)
        ])
    }
```

completeIntentHandler 捕获 completeActivityFromWidget 通知，计算已用时间，然后把 onWidgetCompleteActivity 事件连同活动 ID 和已用秒数一起发送给 JavaScript。JavaScript 随后就可以更新应用 UI，或者记录这次训练已经完成

### onLiveActivityUpdate

每当计时器状态发生变化（例如暂停、继续）时，这个事件都会触发。

```swift
    private func sendTimerUpdateEvent() {
        guard let currentId = self.currentActivityId else { return }
        guard self.startedAt != nil else { return }

        let state = self.pausedAt == nil ? "active" : "paused"
        let elapsed = self.calculateElapsedTime()

        sendEvent("onLiveActivityUpdate", [
            "state": state,
            "elapsedTime": Int(elapsed),
            "activityId": currentId
        ])
    }
```

它在状态变化之后被调用（比如在 performPause 或 performResume 中），发送 onLiveActivityUpdate 事件，带上当前状态（“active” 或 “paused”）、已用时间和活动 ID。JavaScript 监听这个事件，让应用里的计时器 UI 与 widget 保持同步。

这两个事件在原生模块和 JavaScript 之间建立了一个紧密的反馈闭环。

## 为什么这一切很重要

这个 Live Activity 不只是一个计时器，它让我的应用像一个真正的 iOS 原生应用。下面是它重要的原因：

- **用户参与度**：在锁屏或灵动岛上显示计时器，让用户在不打断节奏的情况下与应用保持联系。这对训练来说再合适不过，每一秒都很重要。

- **原生的精致感**：widget 简洁的设计和可交互的按钮，让应用看起来就属于 iOS，而不是一个事后补上的跨平台产物。

- **性能**：由 Text(timerInterval:) 驱动的 startedAt/pausedAt 方案，确保计时器运行流畅，既不耗电，也不会触碰 API 限制。

expo-apple-targets 和 [Expo Modules API](https://docs.expo.dev/modules/module-api/) 是这里的幕后英雄，为连接 JavaScript 和 Swift 提供了一个可靠的框架。文档对清晰的函数定义和事件处理的强调，让我的代码保持了条理和可维护性。

## 最后的想法

这个 Live Activity 为应用增添了流畅的原生体验，直接在锁屏和灵动岛上显示实时更新。多亏了 expo-apple-targets、Expo Modules API 以及社区的经验（没错，包括 Reddit 帖子），把它做出来相当顺利。Live Activities 是让应用更有连接感、更有活力的一种强大方式

这是完整源码仓库的 GitHub 链接 👉🏻 [https://github.com/tarikfp/expo-live-activity-timer](https://github.com/tarikfp/expo-live-activity-timer)

