HarmonyOS APP开发---“启动秀“应用引导页App，需要用到这个库

HarmonyOS APP开发---"启动秀"应用引导页App，需要用到这个库

做一个应用引导页，首次启动时用精美的 Lottie 动画介绍产品功能------@ohos/lottie 是鸿蒙上最成熟的 Lottie 方案，完整播放控制 + 边界场景健壮性保障，久经大量应用打磨。
📦 仓库地址：https://gitcode.com/CPF-ApplicationTPC/lottieArkTS ｜安装：ohpm install @ohos/lottie

写在前面

"启动秀"的场景是：用户第一次打开 App，展示 3-4 屏引导页，每屏一个 Lottie 动画 + 一句产品卖点。用户左右滑动切换，最后一屏点击"立即体验"进入首页。

这个场景对 Lottie 库的要求：

稳定：引导页是第一印象，动画崩了 = 用户流失
完整控制：每屏动画要随滑动切换暂停/播放
多种加载方式：本地 JSON、网络 JSON、动态 JSON 数据

@ohos/lottie（基于 lottieArkTS 仓库）是鸿蒙上最成熟的 Lottie 方案，被大量应用采用。v2.0.31 增强了对空 canvasShadow、空 dynamicProperties、空 assetData 等边界场景的防护，避免空指针崩溃。

💡 新项目/多动画同屏性能敏感场景推荐 lottie-turbo；本文适合稳定性优先的场景。

这篇文章聊什么

引导页结构------Swiper + LottieView 逐屏切换
播放联动------滑动切换时暂停上一个、播放当前
三种加载方式------本地文件、网络 URL、JSON 数据

#mermaid-svg-Edz2jzKJ9b6ZubkJ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .error-icon{fill:#552222;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .marker.cross{stroke:#333333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ p{margin:0;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster-label text{fill:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster-label span{color:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster-label span p{background-color:transparent;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .label text,#mermaid-svg-Edz2jzKJ9b6ZubkJ span{fill:#333;color:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .node rect,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node circle,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node ellipse,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node polygon,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .rough-node .label text,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node .label text,#mermaid-svg-Edz2jzKJ9b6ZubkJ .image-shape .label,#mermaid-svg-Edz2jzKJ9b6ZubkJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .rough-node .label,#mermaid-svg-Edz2jzKJ9b6ZubkJ .node .label,#mermaid-svg-Edz2jzKJ9b6ZubkJ .image-shape .label,#mermaid-svg-Edz2jzKJ9b6ZubkJ .icon-shape .label{text-align:center;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .node.clickable{cursor:pointer;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .arrowheadPath{fill:#333333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Edz2jzKJ9b6ZubkJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Edz2jzKJ9b6ZubkJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster text{fill:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .cluster span{color:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Edz2jzKJ9b6ZubkJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .icon-shape,#mermaid-svg-Edz2jzKJ9b6ZubkJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .icon-shape p,#mermaid-svg-Edz2jzKJ9b6ZubkJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .icon-shape .label rect,#mermaid-svg-Edz2jzKJ9b6ZubkJ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Edz2jzKJ9b6ZubkJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Edz2jzKJ9b6ZubkJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Edz2jzKJ9b6ZubkJ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 左滑
左滑
左滑
点击
动画播放中
切换时
首次启动
引导页 1: 功能A动画
引导页 2: 功能B动画
引导页 3: 功能C动画
最后一屏: 立即体验
进入首页
不可见自动跳过绘制
暂停上一个, 播放当前

第一步：安装

bash 复制代码

ohpm install @ohos/lottie

第二步：Swiper + LottieView 引导页

typescript 复制代码

import { LottieView, LottieController } from '@ohos/lottie'

@Entry
@Component
struct OnboardingPage {
  private controllers: LottieController[] = [
    new LottieController(),
    new LottieController(),
    new LottieController(),
  ]
  @State currentIndex: number = 0

  // 三屏引导：动画 + 卖点文案
  private pages: Array<{ anim: Resource; title: string; desc: string }> = [
    { anim: $rawfile('lottie/feature_scan.json'), title: '智能扫描', desc: '一键识别万物' },
    { anim: $rawfile('lottie/feature_sync.json'), title: '云端同步', desc: '数据永不丢失' },
    { anim: $rawfile('lottie/feature_share.json'), title: '便捷分享', desc: '一键发送好友' },
  ]

  build() {
    Stack() {
      Swiper() {
        ForEach(this.pages, (page, index) => {
          Column() {
            // Lottie 动画
            LottieView({
              source: page.anim,
              controller: this.controllers[index],
              loop: true,
              autoplay: index === 0, // 第一屏自动播放，其他等切换到再播
            })
              .width('80%').height('50%')

            // 卖点文案
            Text(page.title).fontSize(28).fontWeight(FontWeight.Bold).margin({ top: 40 })
            Text(page.desc).fontSize(16).fontColor('#999999').margin({ top: 8 })
          }
          .width('100%').height('100%')
          .justifyContent(FlexAlign.Center)
        }, (page, index) => index.toString())
      }
      .indicator(true)
      .onChange((index: number) => {
        // 切换时：暂停上一个，播放当前
        this.controllers[this.currentIndex].pause()
        this.controllers[index].start()
        this.currentIndex = index
      })

      // 最后一屏的"立即体验"按钮
      if (this.currentIndex === this.pages.length - 1) {
        Button('立即体验')
          .fontSize(18).fontColor('#FFFFFF')
          .backgroundColor('#4ECDC4')
          .width('80%').height(48)
          .position({ x: '10%', y: '85%' })
          .onClick(() => {
            // 标记已看过引导页，进入首页
            preferences.putBoolean('onboarding_done', true)
            router.replaceUrl({ url: 'pages/Index' })
          })
      }
    }
    .width('100%').height('100%')
  }
}

播放联动 是引导页的关键：Swiper 的 onChange 回调里暂停上一个动画、播放当前动画，避免多个动画同时跑浪费资源。lottie-turbo 还支持不可见时自动跳过绘制，进一步省电。

第三步：三种加载方式

typescript 复制代码

// 方式一：本地 rawfile（最常用）
LottieView({ source: $rawfile('lottie/anim.json') })

// 方式二：网络 URL（动画资源在 CDN 上）
LottieView({ source: 'https://cdn.example.com/anim.json' })

// 方式三：JSON 字符串（动态生成/服务端下发）
const dynamicJson = '{"v":"5.7.0","fr":30,"ip":0,"op":60,"w":300,"h":300,...}'
LottieView({ source: dynamicJson })

三种方式覆盖了所有场景：本地打包、CDN 托管、服务端动态下发。

第四步：高级控制

typescript 复制代码

// 播放指定片段（引导页动画只播前 3 秒）
this.controllers[0].playFromFrame(0, 90) // 0~90 帧（30fps = 3 秒）

// 修改动画颜色（品牌色适配）
this.controllers[0].setColor('shape1', '#4ECDC4')

// 设置填充模式
LottieView({ source: anim, resizeMode: 'cover' })

为什么"启动秀"选了 @ohos/lottie？

需求	自研动画	@ohos/lottie
AE 动画复现	❌ 不可能	✅ Bodymovin JSON
播放控制	手写	✅ 完整 API
稳定性	---	✅ 边界场景防护
三种加载方式	手写	✅ 内置
不可见跳过绘制	手写	✅ 自动
生态验证	---	✅ 大量应用采用

总结

"启动秀"这个场景里，@ohos/lottie 解决了三件事：

AE 动画复现------设计师的 Bodymovin JSON 直接加载，零成本触达终端
播放联动------Swiper 切换时暂停/播放，资源不浪费
稳定可靠------边界场景防护 + 不可见自动跳过绘制，引导页不崩

如果你也需要在鸿蒙应用里播放 Lottie 动画，且稳定性优先 ，@ohos/lottie 是久经考验的成熟之选。多动画同屏性能敏感场景可搭配 lottie-turbo。