【鸿蒙心迹】ArkUI动画体系实战：从属性动画到粒子特效

摘要：本文系统梳理 ArkUI 的四层动画体系——属性动画（组件级）、转场动画（页面/组件级）、共享元素动画（跨页面）与粒子动画（系统级）。文章先建立整体认知并给出选型决策图，再逐一拆解 animateTo 与 animation 修饰器、Transition、SharedTransition、ParticleComponent 的机制与 API，随后通过按钮按压、列表增删、图片放大、庆祝粒子四个实战案例落地，最后总结 animation 书写顺序、共享元素 ID 唯一性、粒子数量控制等常见坑与最佳实践，帮助读者快速选对动画类型并避开性能陷阱。

动画是应用体验的灵魂——一个没有动画的应用就像PPT，切换生硬、操作突兀。但ArkUI的动画体系文档分散在各个角落，属性动画、转场动画、共享元素动画、粒子动画各有各的API和配置方式，第一次接触很容易搞混。我刚开始做ArkUI动画时，属性动画和animation修饰器傻傻分不清，共享元素动画怎么都跑不起来，粒子动画的配置参数更是看了一头雾水。

如果你有ArkUI开发基础，想让你的应用有流畅自然的动画效果，但对ArkUI动画体系不熟悉，这篇正好适合你。读完后你会知道：ArkUI四种动画类型的核心区别、每种动画的适用场景和实现方法、动画性能优化的关键技巧。

本文分三层来讲：第一层建立对ArkUI动画体系的整体认知；第二层拆解四种动画类型的原理和API；第三层是完整的实战落地和踩坑排错。

入门认知：ArkUI动画到底有几种

一句话定义

ArkUI动画体系是鸿蒙声明式UI框架提供的四层动画能力——从最基础的属性动画到最复杂的粒子特效，覆盖从组件级到页面级到系统级的全部动画场景。

打个比方：属性动画就像调整灯光亮度——简单直接，转一下旋钮就变了；转场动画就像舞台换幕——一块布景撤下，另一块布景上场；共享元素动画就像电影中的"镜头跟随"——同一个物体从画面A移动到画面B，观众视角连续不中断；粒子动画就像烟花——无数小颗粒按物理规则散开，形成视觉冲击。

四种动画类型对比

动画类型	作用层级	核心API	典型场景	复杂度
属性动画	组件级	animateTo / animation	缩放、旋转、透明度	低
转场动画	页面/组件级	Transition	页面切换、列表增删	中
共享元素动画	跨页面级	SharedTransition	图片放大、卡片展开	中
粒子动画	系统级	Particle	烟花、雨雪、气泡	高

表1：四种动画类型核心对比

全景图示

图2：ArkUI动画体系全景架构

适用边界

属性动画适合：组件状态变化时的视觉过渡（按钮按压、选中高亮）。转场动画适合：页面切换、列表项增删。共享元素动画适合：列表→详情的图片放大、卡片→全屏的展开。粒子动画适合：庆祝特效、天气动画、交互反馈。

下面这张决策图可以帮助你快速判断该用哪种动画：

图3：动画类型选型决策图

进阶原理：四种动画的机制与API

属性动画：animateTo vs animation

属性动画有两种写法，很多人搞不清区别：

写法	用法	特点	适用场景
animateTo	闭包内修改属性值	显式触发，精确控制	按钮点击后执行动画
animation	修饰器绑定到组件	隐式触发，属性变化自动动画	状态驱动的持续动画

表2：animateTo与animation对比

// 写法1：animateTo（显式触发）
Button('点击放大')
  .onClick(() => {
    animateTo({ duration: 300, curve: Curve.EASE_IN_OUT }, () => {
      this.scale = 1.5  // 在闭包内修改属性，触发动画
    })
  })

// 写法2：animation（隐式触发）
Image($r('app.media.logo'))
  .scale({ x: this.scale, y: this.scale })
  .animation({ duration: 300, curve: Curve.EASE_IN_OUT })
  // 当 this.scale 变化时，自动产生动画过渡

[注意] animation 修饰器必须写在属性之后！如果写在属性之前，属性变化不会触发动画。这是最常见的坑。

转场动画：Transition

转场动画分组件级和页面级：

组件级转场（列表项增删）：

ForEach(this.list, (item: string) => {
  Text(item)
    .transition({ type: TransitionType.Insert, effect: TransitionEffect.OPACITY })
    .transition({ type: TransitionType.Delete, effect: TransitionEffect.OPACITY })
}, (item: string) => item)

页面级转场（自定义页面切换效果）：

// 页面A
PageA()
  .transition({ type: TransitionType.Enter, effect: TransitionEffect.translate({ x: 300 }) })
  .transition({ type: TransitionType.Exit, effect: TransitionEffect.translate({ x: -300 }) })

// 页面B
PageB()
  .transition({ type: TransitionType.Enter, effect: TransitionEffect.translate({ x: -300 }) })
  .transition({ type: TransitionType.Exit, effect: TransitionEffect.translate({ x: 300 }) })

共享元素动画：SharedTransition

共享元素动画让同一个元素在两个页面间无缝过渡：

// 页面A：列表中的小图片
Image($r('app.media.photo'))
  .sharedTransition('photo_id', { duration: 300, curve: Curve.EASE_IN_OUT })
  .onClick(() => {
    // 跳转到详情页
    router.pushUrl({ url: 'pages/DetailPage' })
  })

// 页面B：详情页中的大图片
Image($r('app.media.photo'))
  .sharedTransition('photo_id', { duration: 300, curve: Curve.EASE_IN_OUT })

关键点：两端用相同的 sharedTransitionId（这里是 'photo_id'），系统自动计算位置和尺寸的过渡动画。

共享元素动画的执行流程如下：

图4：共享元素动画执行时序

粒子动画：Particle

粒子动画是ArkUI中最复杂的动画类型：

ParticleComponent({
  particles: [
    {
      emitter: {
        position: { x: '50%', y: '50%' },
        shape: ParticleEmitterShape.CIRCLE,
        size: { width: 10, height: 10 }
      },
      particle: {
        type: ParticleType.POINT,
        count: 50,
        lifetime: 3000,
        velocity: { x: { min: -50, max: 50 }, y: { min: -50, max: 50 } },
        acceleration: { x: 0, y: 100 }, // 重力效果
        color: { min: '#FF6B35', max: '#FFD700' },
        opacity: { min: 0.3, max: 1.0 },
        scale: { min: 0.5, max: 2.0 }
      }
    }
  ]
})

常见误区

误区1：animation修饰器写在属性之前

// 错误：animation在scale之前，不生效
Image($r('app.media.logo'))
  .animation({ duration: 300 })
  .scale({ x: this.scale, y: this.scale })

// 正确：animation在scale之后
Image($r('app.media.logo'))
  .scale({ x: this.scale, y: this.scale })
  .animation({ duration: 300 })

误区2：共享元素动画ID不唯一

共享元素ID必须在当前页面内唯一。如果列表中有多个图片都用了同一个ID，共享元素动画会混乱或失效。

把上面两个误区串起来看，属性动画的正确书写顺序可以这样记：

图5：animation 修饰器正确书写顺序

高级应用：四种动画实战落地

实战1：按钮按压动画（属性动画）

@Component
struct PressableButton {
  @State isPressed: boolean = false

  build() {
    Button('确认')
      .scale({ x: this.isPressed ? 0.95 : 1.0, y: this.isPressed ? 0.95 : 1.0 })
      .opacity(this.isPressed ? 0.8 : 1.0)
      .animation({ duration: 150, curve: Curve.EASE_OUT })
      .onTouch((event) => {
        if (event.type === TouchType.Down) {
          this.isPressed = true
        } else if (event.type === TouchType.Up) {
          this.isPressed = false
        }
      })
  }
}

实战2：列表项增删动画（转场动画）

@Component
struct AnimatedList {
  @State items: string[] = ['项目1', '项目2', '项目3']

  build() {
    Column() {
      Button('添加')
        .onClick(() => {
          this.items.push(`项目${this.items.length + 1}`)
        })

      ForEach(this.items, (item: string, index: number) => {
        Row() {
          Text(item)
          Button('删除')
            .onClick(() => {
              this.items.splice(index, 1)
            })
        }
        .transition({
          type: TransitionType.Insert,
          effect: TransitionEffect.translate({ y: 50 }).combine(TransitionEffect.OPACITY)
        })
        .transition({
          type: TransitionType.Delete,
          effect: TransitionEffect.translate({ y: -50 }).combine(TransitionEffect.OPACITY)
        })
      }, (item: string) => item)
    }
  }
}

实战3：图片放大共享元素动画

// 列表页
@Component
struct PhotoList {
  build() {
    Grid() {
      ForEach(this.photos, (photo: PhotoItem) => {
        GridItem() {
          Image(photo.url)
            .sharedTransition(`photo_${photo.id}`, { duration: 300, curve: Curve.EASE_IN_OUT })
            .onClick(() => {
              router.pushUrl({
                url: 'pages/PhotoDetail',
                params: { photoId: photo.id }
              })
            })
        }
      }, (photo: PhotoItem) => photo.id)
    }
  }
}

// 详情页
@Component
struct PhotoDetail {
  @State photoId: string = ''

  build() {
    Image(this.getPhotoUrl(this.photoId))
      .sharedTransition(`photo_${this.photoId}`, { duration: 300, curve: Curve.EASE_IN_OUT })
  }
}

实战4：庆祝粒子特效

@Component
struct CelebrationEffect {
  @State showParticles: boolean = false

  build() {
    Stack() {
      Button('庆祝')
        .onClick(() => {
          this.showParticles = true
        })

      if (this.showParticles) {
        ParticleComponent({
          particles: [
            {
              emitter: {
                position: { x: '50%', y: '50%' },
                shape: ParticleEmitterShape.CIRCLE,
                size: { width: 5, height: 5 },
                emitRate: 30
              },
              particle: {
                type: ParticleType.POINT,
                count: 80,
                lifetime: 2000,
                velocity: {
                  x: { min: -100, max: 100 },
                  y: { min: -150, max: -50 }
                },
                acceleration: { x: 0, y: 200 },
                color: { min: '#FF6B35', max: '#FFD700' },
                opacity: { min: 0.5, max: 1.0 },
                scale: { min: 0.5, max: 1.5 }
              }
            }
          ]
        })
      }
    }
  }
}

踩坑排错

坑1：animation修饰器不生效

现象：属性值变化了但没有动画过渡，直接跳变。

原因：animation 修饰器写在目标属性之前，或者属性变化发生在 animation 绑定之前。

解决：确保 animation 写在所有需要动画的属性之后，且属性变化是通过状态变量驱动。

坑2：共享元素动画闪烁

现象：页面跳转时共享元素先消失再出现，有闪烁感。

原因：目标页面加载延迟，共享元素找不到匹配项就先完成了跳转。

解决：在目标页面的 onPageShow 中延迟设置共享元素可见，或者预加载目标页面数据。

坑3：粒子动画性能卡顿

现象：粒子数量超过50时帧率明显下降。

原因：粒子动画在UI线程计算，大量粒子会阻塞渲染。

解决：控制粒子数量在合理范围（建议不超过100），减少粒子lifetime，使用简单粒子类型（POINT比IMAGE快）。

三个坑的排查路径可以归纳为下面这张图：

图6：动画常见问题排查路径

最佳实践

• animation写在属性之后：这是最常见的坑，顺序不对动画不生效
• 共享元素ID要唯一：同一页面内不能有重复的sharedTransitionId
• 粒子数量要克制：不超过100个，类型用POINT最轻量
• 转场动画要组合：单独用OPACITY或translate效果单一，组合使用更自然
• 动画时长要适中：属性动画150-300ms，转场动画300-500ms，太短看不见太长嫌慢

总结

核心要点：

1. ArkUI动画体系分四层：属性动画（组件级）、转场动画（页面/组件级）、共享元素动画（跨页面）、粒子动画（系统级）
2. animateTo是显式触发，animation是隐式触发，animation必须写在属性之后
3. 共享元素动画通过相同ID匹配两端元素，系统自动计算位置和尺寸过渡
4. 粒子动画是最复杂但视觉冲击最强的类型，需控制粒子数量保证性能

最佳实践清单：

• animation修饰器写在目标属性之后，否则不生效
• 共享元素ID在页面内必须唯一
• 粒子数量控制在100以内，类型优先用POINT
• 转场动画组合使用OPACITY+translate效果更自然
• 动画时长：属性动画150-300ms，转场动画300-500ms

你在ArkUI动画开发中遇到过什么坑？评论区聊聊。