---
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 视图渲染该动画。

<DocVideo id="custom-element-lottie-demo.mp4" width="300px" alt="最终效果演示：用户点击「查看我的连续打卡」，进入下一屏后，圆环填充至 7 天中的第 4 天。" />

## 开始前的准备 \{#before-you-start\}

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

- 将应用更新至 Adapty Android SDK 4.4 或更高版本。较早的 SDK 版本会为每个自定义元素显示[备用内容](flow-custom-elements#set-fallback-content)。
- 配置应用以[获取](android-get-pb-paywalls)和[展示](android-present-paywalls)流程。
- 在应用模块中配置 Jetpack Compose。本示例中的动画视图是一个可组合项（composable）。
- 通过 Gradle 将 Lottie for Jetpack Compose 添加到应用中，来源为 `com.airbnb.android:lottie-compose`。

</TabItem>
<TabItem value="java" label="Java">

- 将您的应用更新至 Adapty Android SDK 4.4 或更高版本。早期 SDK 版本会为每个自定义元素显示[备用内容](flow-custom-elements#set-fallback-content)。
- 配置您的应用以[获取](android-get-pb-paywalls)和[展示](android-present-paywalls)流程。
- 通过 Gradle 从 `com.airbnb.android:lottie` 将 Lottie 添加到您的应用中。

</TabItem>
</Tabs>

准备一个 `.json` 格式的 Lottie 动画，或下载示例文件 [`streak_ring.json`](https://raw.githubusercontent.com/adaptyteam/adapty-docs/refs/heads/main/Downloads/streak_ring.json)。应用会从头播放动画，并按进度比例停止，例如进度为 50% 时停在中间位置。为了准确呈现进度，动画需要满足以下要求：

- 第一帧不显示任何进度，最后一帧显示完整进度。
- 匀速播放，不带缓动效果。如果动画开始时较慢、后来加速，则播放到一半时显示的进度会少于 50%。

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

在流程与付费墙编辑工具中，向流程屏幕[添加自定义元素](flow-custom-elements#add-and-configure)，并为动画进行如下配置：

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

在自定义元素内部，添加一个包含圆环静态图片的[**图片**](custom-media#image)。当用户使用的应用版本不支持播放动画时，该图片将作为[备用内容](flow-custom-elements#set-fallback-content)显示。

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

将动画文件放入 `src/main/assets`，即应用模块的 `assets` 文件夹。请将其放在该文件夹的根目录下，不要放在子文件夹中。

文件名（不含 `.json` 扩展名）必须与自定义元素的 ID 一致，例如 `streak_ring` 对应 `streak_ring.json`。

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

创建连续打卡的数据模型，以及播放动画的视图。当连续打卡数变化时，你的应用更新该模型。视图读取模型数据，因此当页面打开时，圆环会显示当前的连续打卡数：

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"

// the streak that your app keeps up to date
class StreakStore {
    val currentStreak = MutableStateFlow(0) // days in a row
}

@Composable
fun StreakRing(animationFile: String, streakStore: StreakStore) {
    val composition by rememberLottieComposition(LottieCompositionSpec.Asset(animationFile))
    val streak by streakStore.currentStreak.collectAsState()

    // 7 days fill the ring: from 0 for an empty ring to 1 for a full one
    val progress = minOf(streak / 7f, 1f)

    LottieAnimation(
        composition = composition,
        modifier = Modifier.fillMaxSize(), // scale the animation to fit the custom element
        clipSpec = LottieClipSpec.Progress(0f, progress),
    )
}
```

`clipSpec = LottieClipSpec.Progress(0f, progress)` 会将圆环从空填充到 `progress` 指定的位置。如果你的应用已经用 `StateFlow` 管理连续打卡天数，可以直接用该 `StateFlow` 替换 `StreakStore`。

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"

// the streak that your app keeps up to date
public class StreakStore {
    public final MutableLiveData<Integer> currentStreak = new MutableLiveData<>(0); // days in a row
}

public class StreakRingView extends LottieAnimationView {
    private final StreakStore streakStore;

    private final Observer<Integer> streakObserver = streak -> {
        // 7 days fill the ring: from 0 for an empty ring to 1 for a full one
        float progress = Math.min(streak / 7f, 1f);
        setMinAndMaxProgress(0f, progress);
        playAnimation();
    };

    public StreakRingView(Context context, String animationFile, StreakStore streakStore) {
        super(context);
        this.streakStore = streakStore;
        setAnimation(animationFile);
    }

    @Override
    protected void onAttachedToWindow() {
        super.onAttachedToWindow();
        streakStore.currentStreak.observeForever(streakObserver);
    }

    @Override
    protected void onDetachedFromWindow() {
        streakStore.currentStreak.removeObserver(streakObserver);
        super.onDetachedFromWindow();
    }
}
```

`setMinAndMaxProgress(0f, progress)` 和 `playAnimation()` 会将圆环从空状态填充至 `progress` 所指定的进度。如果你的应用已通过 `LiveData` 维护连续打卡天数，可以直接用该 `LiveData` 替换 `StreakStore`。

</TabItem>
</Tabs>

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

在你的[全局 resolver](android-flow-custom-elements#display-views-in-every-flow) 中，为 streak 模型添加一个属性。然后为 `lottie_animation` 类型和 `streak_ring` ID 返回动画视图。高亮行表示需要添加或修改的内容。如果你的应用还没有全局 [resolver](android-flow-custom-elements#write-a-resolver-to-match-custom-elements-and-views)，可以直接复制完整代码：

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin" {8,22-28}

class CustomElementsResolver(
    context: Context,
    private val streakStore: StreakStore,
) : AdaptyCustomElementsResolver {
    // the animation files in the assets folder, listed once
    private val animationFiles: Set<String> = try {
        context.assets.list("").orEmpty().toSet()
    } catch (e: IOException) {
        emptySet() // no list of files: every Lottie element shows the fallback
    }

    override fun resolve(type: String, id: String): AdaptyCustomElementContent? =
        when (type) {
            "lottie_animation" -> {
                // the ID names the animation file, such as streak_ring.json
                val file = "$id.json"
                when {
                    file !in animationFiles -> null // no file for this ID: show the fallback
                    id == "streak_ring" ->
                        AdaptyCustomElementContent.compose { StreakRing(file, streakStore) }
                    // the other animations of your resolver
                    else -> null
                }
            }
            // the other Types of your resolver
            else -> null
        }
}
```

如果 `assets` 文件夹中没有对应 ID 的文件，解析器将返回 `null`，用户将看到备用内容。如果您的解析器已经为[每个动画文件返回了一个视图](android-flow-custom-elements#write-a-resolver-to-match-custom-elements-and-views)，那么当 ID 不是 `streak_ring` 时，请返回该视图而不是 `null`。这样，用户仍然可以看到其他 `lottie_animation` 自定义元素的动画效果。

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java" {10,14-15,34-40}

public class CustomElementsResolver implements AdaptyCustomElementsResolver {
    private final StreakStore streakStore;
    // the animation files in the assets folder, listed once
    private final Set<String> animationFiles = new HashSet<>();

    public CustomElementsResolver(Context context, StreakStore streakStore) {
        this.streakStore = streakStore;
        try {
            String[] files = context.getAssets().list("");
            if (files != null) {
                animationFiles.addAll(Arrays.asList(files));
            }
        } catch (IOException e) {
            // no list of files: every Lottie element shows the fallback
        }
    }

    @Override
    public AdaptyCustomElementContent resolve(String type, String id) {
        if (type.equals("lottie_animation")) {
            // the ID names the animation file, such as streak_ring.json
            String file = id + ".json";
            if (!animationFiles.contains(file)) {
                return null; // no file for this ID: show the fallback
            }
            if (id.equals("streak_ring")) {
                return AdaptyCustomElementContent.view(
                        (context, elementContext) -> new StreakRingView(context, file, streakStore)
                );
            }
            // the other animations of your resolver
            return null;
        }
        // the other Types of your resolver
        return null;
    }
}
```

如果 `assets` 文件夹中没有对应该 ID 的文件，解析器会返回 `null`，用户将看到备用内容。如果你的解析器已经为[每个动画文件返回了视图](android-flow-custom-elements#write-a-resolver-to-match-custom-elements-and-views)，则在 ID 不是 `streak_ring` 时返回该视图而非 `null`。这样，用户仍然可以看到其他 `lottie_animation` 自定义元素的动画。

</TabItem>
</Tabs>

创建包含打卡模型的解析器，并将其设置为全局解析器。在应用启动时调用一次 `AdaptyUI.setCustomElementsResolver`：

<Tabs groupId="current-os" queryString>
<TabItem value="kotlin" label="Kotlin" default>

```kotlin showLineNumbers title="Kotlin"

class App : Application() {
    // the streak model that your app updates
    val streakStore = StreakStore()

    // keep this instance: a resolver for one flow can reuse it
    // lazy: the context isn't attached yet while App is constructed
    val customElementsResolver by lazy { CustomElementsResolver(this, streakStore) }

    override fun onCreate() {
        super.onCreate()
        AdaptyUI.setCustomElementsResolver(customElementsResolver)
    }
}
```

</TabItem>
<TabItem value="java" label="Java">

```java showLineNumbers title="Java"

public class App extends Application {
    // the streak model that your app updates
    private final StreakStore streakStore = new StreakStore();
    // keep this instance: a resolver for one flow can reuse it
    private CustomElementsResolver customElementsResolver;

    @Override
    public void onCreate() {
        super.onCreate();
        customElementsResolver = new CustomElementsResolver(this, streakStore);
        AdaptyUI.setCustomElementsResolver(customElementsResolver);
    }

    public StreakStore getStreakStore() {
        return streakStore;
    }

    public CustomElementsResolver getCustomElementsResolver() {
        return customElementsResolver;
    }
}
```

</TabItem>
</Tabs>

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

流程与付费墙编辑工具无法运行您的应用代码，因此画布上只显示备用内容。如需预览动画：

1. [发布流程](builder-save-publish)。若要查看最新发布版本而非缓存版本，请将设备注册为[测试设备](test-devices)。
2. 运行包含 resolver 的应用构建版本。将连续天数设为 0 天，打开界面，验证圆环保持空心状态。分别设为 4 天和 7 天后重复操作，验证圆环是否填充至对应值。

如需测试备用内容，请从构建版本中移除动画文件，然后再次打开界面。

要了解为什么显示的是备用内容而不是动画，请参照 Android 指南中[在设备上测试](android-flow-custom-elements#test-on-a-device)部分的说明。