纯血鸿蒙HarmonyOS TransitionEffect 内置动画效果整理

TransitionEffect官方定义是 ArkUI 组件出现/消失转场的核心对象。本文基于个人项目开发过程笔记进行整理，记录TransitionEffect内置动画使用方法适用场景。

可直接使用的内置转场效果包括：

1. TransitionEffect.IDENTITY
2. TransitionEffect.OPACITY
3. TransitionEffect.SLIDE
4. TransitionEffect.SLIDE_SWITCH
5. TransitionEffect.translate(...)
6. TransitionEffect.rotate(...)
7. TransitionEffect.scale(...)
8. TransitionEffect.opacity(...)
9. TransitionEffect.move(...)
10. TransitionEffect.asymmetric(appear, disappear)

其中前 4 个更像预置效果，后 6 个用于构造、定制和组合复杂转场。真正实现复杂动画时，主要依赖 combine()、asymmetric() 和 animation()。

官方定义

• API 参考：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-transition-animation-component
• 指南：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-enter-exit-transition
• 转场总览：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-transition-overview

内置效果清单

1. IDENTITY

• 含义：禁用转场效果。
• 用途：明确关闭默认转场，避免组件在动画作用域内自动套上 OPACITY。

2. OPACITY

• 含义：默认透明度转场。
• 入场：透明度 0 -> 1。
• 出场：透明度 1 -> 0。
• 等价写法：TransitionEffect.opacity(0)。

3. SLIDE

• 含义：预置滑动转场。
• 官方等价定义：

TransitionEffect.asymmetric(TransitionEffect.move(TransitionEdge.START),TransitionEffect.move(TransitionEdge.END))

• LTR 模式：左进右出。
• RTL 模式：右进左出。

4. SLIDE_SWITCH

• 含义：预置切换式滑动转场。
• 效果： 入场时从右侧先缩小再放大滑入； 出场时从左侧先缩小再放大滑出。
• 自带参数： 时长 600ms； 曲线 cubicBezierCurve(0.24, 0.0, 0.50, 1.0)； 最小缩放比例 0.8。
• 说明：这些参数可被显式 animation() 覆盖。

5. translate(options)

• 含义：按给定平移量做转场。
• 典型参数：x、y、z。
• 入场：从设定偏移量回到默认位置 0。
• 出场：从默认位置 0 移动到设定偏移量。

6. rotate(options)

• 含义：按给定旋转参数做转场。
• 典型参数：x、y、z、angle、centerX、centerY、centerZ。
• 入场：从设定旋转状态回到默认角度。
• 出场：从默认角度旋转到设定状态。
• 注意：perspective 不支持做转场动画。

7. scale(options)

• 含义：按给定缩放参数做转场。
• 典型参数：x、y、z、centerX、centerY。
• 入场：从设定缩放值过渡到默认值 1。
• 出场：从默认值 1 过渡到设定缩放值。
• 注意：该缩放是叠加在组件当前 scale 属性上的。

8. opacity(alpha)

• 含义：自定义透明度转场。
• 范围：[0, 1]，越界会被裁剪。
• 与 OPACITY 的区别：OPACITY 固定等于 opacity(0)，而这里可以指定任意目标透明度，比如 0.3、0.99。

9. move(edge)

• 含义：从窗口边缘滑入/滑出，本质上是基于边缘的平移效果。
• 可选边： TOPBOTTOMSTARTEND

10. asymmetric(appear, disappear)

• 含义：入场和出场使用不同的转场效果。
• 作用：把“对称动画”扩展成“非对称动画”。
• 典型用途：入场缩放淡入，出场旋转淡出；或只入场不出场。

组合规则

combine(effect)

• 作用：把多个转场效果叠加到同一个组件上，同时生效。
• 结果：组件出现时是所有“入场效果”的叠加，消失时是所有“出场效果”的叠加。

示例：

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0.8, y: 0.8 }))  .combine(TransitionEffect.rotate({ z: 1, angle: 15 }))

上面会形成“淡入淡出 + 缩放 + 旋转”的复合转场。

animation(param)

• 作用：给当前 TransitionEffect 指定动画参数。
• 可控制：时长、延时、曲线等。
• 关键规则：前面效果上设置的 animation()，会继续影响后面 combine() 进来的效果，除非后面的效果自己又声明了 animation()。

生效优先级：

1. 当前效果自己的 animation()
2. 前序 TransitionEffect 上声明的 animation()
3. 外层 animateTo() 的动画参数

默认行为和注意点

1. 如果既没有 animateTo()，又没有在 TransitionEffect 上写 animation()，组件会直接出现或消失，没有可见动效。
2. 如果设置值等于默认值，该属性不会产生动画，例如 TransitionEffect.opacity(1)。
3. 在动画作用域里触发上下树或 visibility 变化，若根组件没有配置 transition，系统会默认补一个 TransitionEffect.OPACITY。
4. 如果不希望补默认淡入淡出，需要显式配置 TransitionEffect.IDENTITY。
5. 删除整棵子树时，想完整看到子组件的消失动画，需要根节点也保留足够的消失时长。

通过组合可以实现哪些复杂动画

下面这些都能直接用官方提供的效果组合完成，不需要自定义底层动画引擎。

1. 淡入淡出 + 缩放

适合卡片、弹层、宫格项出现和消失。

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0.8, y: 0.8 }))

效果特征：组件出现时会从更小、更透明的状态恢复到正常状态；消失时反向执行。

2. 淡入淡出 + 旋转

适合图片、徽标、状态切换卡片。

TransitionEffect.OPACITY.animation({ duration: 2000, curve: Curve.Ease })  .combine(TransitionEffect.rotate({ z: 1, angle: 180 }))

效果特征：官方示例就是“透明度 + 绕 z 轴 180 度旋转”。

3. 淡入淡出 + 平移

适合消息条、提示条、从局部位置浮现的卡片。

TransitionEffect.OPACITY  .combine(TransitionEffect.translate({ y: 80 }))

效果特征：从下方浮现并伴随透明度变化。

4. 平移 + 缩放 + 旋转的多重叠加

适合强调型入口动画、运营卡片、复杂面板弹出。

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0, y: 0 }))  .combine(TransitionEffect.rotate({ angle: 90 }))  .combine(TransitionEffect.translate({ x: 150, y: 150 }))

效果特征：一个转场里同时具备“淡入 + 放大 + 旋转 + 位移”。

5. 非对称入场/出场

适合抽屉、菜单、弹窗、首屏引导，因为进入和退出通常不是同一套节奏。

TransitionEffect.asymmetric(TransitionEffect.OPACITY.combine(TransitionEffect.scale({ x: 0.9, y: 0.9 })  ),TransitionEffect.OPACITY.combine(TransitionEffect.rotate({ z: 1, angle: 30 })  ))

效果特征：入场是“淡入放大”，出场是“淡出旋转”。

6. 只入场、不出场 或 只出场、不入场

适合局部强化展示，避免退出动画拖慢响应。

TransitionEffect.asymmetric(TransitionEffect.scale({ x: 0, y: 0 }),TransitionEffect.IDENTITY)

效果特征：出现时有缩放动画，消失时直接移除。

7. 边缘滑入滑出 + 透明度/缩放叠加

适合侧边菜单、侧滑面板、轻弹层。

TransitionEffect.move(TransitionEdge.END)  .combine(TransitionEffect.OPACITY)  .combine(TransitionEffect.scale({ x: 0.95, y: 0.95 }))

效果特征：不只是“平移进来”，还会同步做淡入和轻微缩放，观感更完整。

8. 列表/宫格的渐次出现和渐次消失

适合九宫格、瀑布流、工具面板。

实现方式不是单个新效果，而是：

• 每个子项使用相同的 TransitionEffect
• 通过 animation({ delay }) 给不同索引配置不同延时

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0.5, y: 0.5 }))  .animation({ duration: 300, delay: 30 * index, curve: Curve.Friction })

效果特征：形成瀑布式、波浪式的依次进出场。

9. 模态弹窗/菜单的分层转场

官方参考中，Popup、Menu、Modal 等组件都支持直接接入 TransitionEffect。因此可以做：

• 内容层：缩放 + 透明度
• 遮罩层：单独透明度变化
• 入场/出场分别采用不同参数

这类场景通常用 asymmetric() 加 combine() 最合适。

10. 类似页面切换的“切屏感”效果

直接可用的方案有两类：

• 使用 SLIDE
• 使用 SLIDE_SWITCH

其中 SLIDE_SWITCH 更像轻量版页面切换动效，自带“滑动 + 缩放”的组合观感。

实用模式建议

轻量默认型

适合普通卡片和按钮区域：

TransitionEffect.OPACITY

浮层弹出型

适合弹窗、气泡、菜单：

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0.9, y: 0.9 }))

侧滑面板型

适合抽屉、侧边设置面板：

TransitionEffect.move(TransitionEdge.END)  .combine(TransitionEffect.OPACITY)

强调展示型

适合运营入口、重要提示卡片：

TransitionEffect.OPACITY  .combine(TransitionEffect.scale({ x: 0.7, y: 0.7 }))  .combine(TransitionEffect.rotate({ z: 1, angle: 12 }))

非对称交互型

适合进场强调、退场快速结束：

TransitionEffect.asymmetric(TransitionEffect.OPACITY.combine(TransitionEffect.scale({ x: 0.8, y: 0.8 })),TransitionEffect.OPACITY.animation({ duration: 120 }))

开发注意事项

1. TransitionEffect 主要用于组件新增、删除、可见性变化，不适合长期驻留组件的连续属性动画。
2. 长驻组件请优先用属性动画；转场动画更适合“上树/下树”场景。
3. 子组件消失动画不生效时，优先检查父组件是否也需要保留一个转场，官方示例常用 TransitionEffect.opacity(0.99) 让父节点在退场阶段继续存在。
4. 如果组合很多效果，建议明确为关键效果单独配置 animation()，否则容易出现动画参数继承不符合预期的情况。

一句话总结

TransitionEffect 的核心不是“内置了很多现成动画”，而是“提供少量基础效果 + 组合机制”。复杂动效基本都可以拆成 透明度 / 平移 / 缩放 / 旋转 / 边缘滑动 这几类基础效果，再通过 combine() 叠加、通过 asymmetric() 区分进出场、通过 animation() 做节奏控制。