---
title: "用 Lottie 动画展示用户进度"
description: "在流程页面上以 Lottie 动画形式展示每位用户的进度，例如每日连续打卡记录。"
---

> **AI agents**: to search Adapty docs faster and with fewer tokens, install the Adapty skills: `npx adapty skills install --yes`

按照本教程，将用户进度以 Lottie 动画的形式呈现——例如，用一个逐渐填满的圆环来表示用户的每日连续打卡天数。你的应用会在[自定义元素](flow-custom-elements)中以原生 Lottie 视图渲染该动画。

:::tip
此方案仅适用于 iOS 应用。使用其他框架构建的应用只会显示自定义元素的[备用内容](flow-custom-elements#set-fallback-content)。Android 及跨平台框架的支持即将推出。
:::

## 开始之前 \{#before-you-start\}

- 将您的应用更新至 Adapty iOS SDK 4.4 或更高版本。早期 SDK 版本会为每个自定义元素显示[备用内容](flow-custom-elements#set-fallback-content)。
- 配置您的应用以[获取](get-pb-paywalls)并[展示](ios-present-paywalls)流程。
- 通过 Swift Package Manager 将 Lottie 添加到您的应用，地址为 `https://github.com/airbnb/lottie-spm.git`。
- 准备 `.json` 格式的 Lottie 动画，或下载示例文件 [`streak_ring.json`](https://raw.githubusercontent.com/adaptyteam/adapty-docs/refs/heads/main/Downloads/streak_ring.json)。应用会从头开始播放动画，并按进度比例停止，例如进度为 50% 时停在动画的一半位置。为了准确呈现进度，动画需要满足：
  - 第一帧无进度，最后一帧为完整进度。
  - 匀速播放，不带缓动效果。如果动画开始时较慢然后加速，则在进度达到 50% 时显示的进度会少于一半。

## 1. 在屏幕中添加自定义元素 \{#1-add-the-custom-element-to-the-screen\}

在 Flow & Paywall Builder 中，[添加自定义元素](flow-custom-elements#add-and-configure)到流程屏幕，并为动画进行如下配置：

- **Type**：`lottie_animation`。
- **ID**：`streak_ring`。在本示例中，ID 同时也是动画文件的名称。
- **Height**：保持默认的 **Fixed** 高度。动画会自动缩放以适应自定义元素的大小。

在自定义元素内，添加一个[**Image**](custom-media#image)，展示戒指的静态图片。当用户的应用版本不支持播放动画时，他们会看到这张图片作为[备用内容](flow-custom-elements#set-fallback-content)。

## 2. 将动画文件添加到应用 \{#add-the-animation-file-to-your-app\}

在 Xcode 中，将动画文件添加到应用的 target。文件名（不含 `.json` 后缀）必须与自定义元素的 ID 一致，例如 `streak_ring.json` 对应 `streak_ring`。

## 3. 创建动画视图 \{#3-create-the-animation-view\}

创建一个用于记录连续签到的模型，以及一个播放动画的 SwiftUI 视图。当连续签到状态发生变化时，你的应用更新该模型；视图读取模型数据，因此每次打开页面时，圆环都会显示当前的连续签到天数：

<Tabs groupId="current-os" queryString>
<TabItem value="ios" label="iOS" default>

```swift showLineNumbers title="Swift"

// The streak that your app keeps up to date
@MainActor
final class StreakStore: ObservableObject {
    @Published var currentStreak = 0 // days in a row
}

struct StreakRingView: View {
    let animation: LottieAnimation
    @ObservedObject var streakStore: StreakStore

    // 7 days fill the ring: from 0 for an empty ring to 1 for a full one
    private var progress: AnimationProgressTime {
        min(AnimationProgressTime(streakStore.currentStreak) / 7, 1)
    }

    var body: some View {
        LottieView(animation: animation)
            .resizable()
            .playing(.fromProgress(0, toProgress: progress, loopMode: .playOnce))
    }
}
```

</TabItem>
</Tabs>

`.playing(.fromProgress(0, toProgress: progress, loopMode: .playOnce))` 将进度环从空白填充到 `progress`。如果你的应用已经在 `ObservableObject` 中维护连击数据，可以直接用该对象替换 `StreakStore`。

## 4. 将动画与自定义元素关联 \{#4-match-the-animation-to-the-custom-element\}

在你的[全局解析器](ios-flow-custom-elements#set-an-app-wide-resolver)中，为连胜模型添加一个属性。然后添加一个 case，对 `lottie_animation` 类型和 `streak_ring` ID 返回 `StreakRingView`。高亮行显示了需要添加的内容。如果你的应用还没有全局[解析器](ios-flow-custom-elements#write-a-resolver-to-match-custom-elements-and-views)，请复制完整代码：

<Tabs groupId="current-os" queryString>
<TabItem value="ios" label="iOS" default>

```swift showLineNumbers title="Swift" {2,6,14-18}

struct CustomElementsResolver: AdaptyUICustomElementsResolver {
    let streakStore: StreakStore

    func view(
        forType type: String,
        id: String,
        context: AdaptyUICustomElementContext
    ) -> AnyView? {
        switch type {
        case "lottie_animation" where id == "streak_ring":
            guard let animation = LottieAnimation.named(id) else {
                return nil // no animation file: show the fallback
            }
            return AnyView(StreakRingView(animation: animation, streakStore: streakStore))
        // the other cases of your resolver
        default:
            return nil
        }
    }
}
```

</TabItem>
</Tabs>

将 `streak_ring` case 放在其他所有 `lottie_animation` case 之前，因为 Swift 只会执行第一个匹配的 case。如果应用包中没有该 ID 对应的文件，resolver 会返回 `nil`，用户将看到备用内容。

用 streak 模型创建 resolver，并将其设置为全局 resolver。在应用启动时调用一次 `AdaptyUI.setCustomElementsResolver(_:)`：

<Tabs groupId="current-os" queryString>
<TabItem value="ios" label="iOS" default>

```swift showLineNumbers title="Swift"

// the streak model that your app updates
@MainActor let streakStore = StreakStore()

// keep this instance: a resolver for one flow can reuse it
@MainActor let customElementsResolver = CustomElementsResolver(streakStore: streakStore)

AdaptyUI.setCustomElementsResolver(customElementsResolver)
```

</TabItem>
</Tabs>

## 5. 在设备上测试 \{#test-on-a-device\}

流程与付费墙编辑工具无法运行你的应用代码，因此其画布只会显示备用内容。要预览动画效果：

1. [发布流程](builder-save-publish)。若要查看最新发布版本而非缓存版本，请将设备注册为[测试设备](test-devices)。
2. 运行包含解析器的应用构建版本。将连续天数设为几个不同的值，例如 0、4 和 7 天。逐一打开对应的屏幕，验证圆环是否填充到相应位置。

如需测试备用内容，请从构建版本中移除动画文件，然后重新打开该屏幕。

要了解为什么显示的是备用付费墙而非动画，请参阅 iOS 指南中[在设备上测试](ios-flow-custom-elements#test-on-a-device)部分的说明。