Vue动画实战：CSS关键帧与类名机制配合实现弹窗与列表动效

Vue动画这块，很多同学一上来就盯着transition组件和六个类名看，结果动手做弹窗、列表错峰入场的时候，还是会被各种跳变、闪烁、时序问题折腾到怀疑人生。12-01这篇笔记，我单独把 CSS 关键帧（@keyframes）拎出来记，是因为它和 Vue 动画体系的配合方式和普通的 CSS transition 玩法有本质区别——如果你已经掌握了一点 Vue 动画基础，但想实现弹跳、多阶段位移、错峰入场这类“有节奏感”的动效，那这篇内容正好能帮你把关键帧和 Vue 的类名机制焊在一起理解透。

1. 这次要解决什么：Vue 动画配 CSS 关键帧的核心思路

1.1 有了 transition 属性，为什么还要上关键帧

先说一个最基础的问题。Vue 内置的<transition>组件本身不产生动画，它只是个调度器，负责在你切换元素显示状态时，往元素上挂/摘几个特定类名。至于这个元素到底怎么动，完全由 CSS 说了算。

最常见的做法是用 CSS transition 属性做单次状态过渡：

.fade-enter-active, .fade-leave-active { transition: opacity 0.3s ease; } .fade-enter, .fade-leave-to { opacity: 0; }

这套写法在“从 A 状态到 B 状态”的场景下非常够用。但一旦你想要的动画是弹跳、回弹、中间转折、多段位移叠加，比如一个弹窗先快速落下再轻微回弹，或者一个列表项从左侧滑入后再颤一下，transition 就力不从心了——它只认起点和终点，中间过程你管不了。

关键帧动画@keyframes就是干这个的。它可以把动画拆成多个阶段，每个阶段单独控制元素的样式参数，配合animation属性里的时长、缓动、填充模式，能实现各种有“表现力”的动效。

1.2 Vue 动画体系和关键帧的对接位置

Vue 的<transition>组件在元素进入和离开时，会按顺序应用六个类名：

关键帧动画的接入点非常明确：写在-active类里。也就是：

.modal-enter-active { animation: popIn 0.4s ease-out both; } .modal-leave-active { animation: popOut 0.3s ease-in both; }

这里有个隐藏的知识点：-enter和-enter-to这两个类其实可以不用写。因为@keyframes已经在动画内部定义了起始帧和结束帧（0% 和 100% 那一帧），-active里的animation属性会直接接管整个过渡过程。前提是你记得加both填充模式，不加的话，动画开始前元素会以“没有样式”的状态在页面上闪一下，视觉上就是一顿乱跳。

2. 六个动画类名和 @keyframes 的对接细节

2.1 类名的存活时间线，搞懂它就不会乱

我见过不少同学把六个类名混在一起记，写出来的 CSS 经常互相打架。这里我按自己的理解重新梳理一遍时间线，你照着理解就不会乱。

进入动画（v-if 从 false 变 true）：

1. 元素被插入 DOM 的下一帧，Vue 添加xxx-enter和xxx-enter-active。
2. 下一帧，浏览器强制回流一次，Vue 移除xxx-enter，添加xxx-enter-to。
3. 如果xxx-enter-active里写的是transition，那现在就是从enter状态到enter-to状态的过渡。
4. 如果xxx-enter-active里写的是animation，那动画会在enter被移除后立即播放，起点由@keyframes的 0% 帧决定。

离开动画（v-if 从 true 变 false）：

1. Vue 添加xxx-leave和xxx-leave-active。
2. 下一帧移除xxx-leave，添加xxx-leave-to。
3. 同样，如果leave-active里是animation，动画会直接播放，终点由@keyframes的 100% 帧决定。
4. 动画结束后，Vue 监听transitionend或animationend事件，把元素从 DOM 里移除（v-if场景）。

注意第 2 步那句“下一帧”。这意味这-enter-active里的animation生效时机，和transition略有差异，但绝大多数情况下不用太较真。真正需要较真的是animationend事件的触发条件——如果动画时长设置成 0 或者动画根本不存在，Vue 可能等不到事件回调，导致 DOM 迟迟不卸载。所以别在-active里写一个空动画。

2.2 同一个属性被 animation 和 transition 同时碰到，谁说了算

这是我在 A 同学的代码里看到过的一个真实事故。他在enter-active里写了关键帧动画，同时又在enter-to里写了transition，而且两个都动了transform属性。结果元素一边执行关键帧的位移，一边又被 transition 拽回另一个位置，画面直接撕裂。

CSS 规范里明确：当同一个属性同时被animation和transition影响时，animation的优先级更高。也就是说，只要enter-active里的animation存在并在运行，enter-to里设置的 transition 效果会被压住。但因为动画结束时animation不会再“霸占”属性值，元素可能瞬间回到enter-to定义的状态，产生一次肉眼可见的跳变。

我的建议很简单：用了关键帧，就不要在同一条动画链路上同时写 transition 动同一个属性。关键帧管过程，最终态尽量也交给关键帧的 100% 帧去收尾，别多写一个enter-to里的 transition 去抢戏。

2.3 动画填充模式 both 到底管什么

animation的fill-mode参数有四个值：none、forwards、backwards、both。在 Vue 动画里我基本无脑用both。

• backwards：动画开始前，把 0% 帧的样式应用到元素上。这对入场动画非常关键——不加它，元素在 DOM 插入后的那一两个帧里是“无样式”状态，容易闪现。
• forwards：动画结束后，保留 100% 帧的样式。对出场动画非常关键——不加它，动画播完元素又跳回动画前的状态。
• both：两头都管，完美覆盖入场和出场场景。

实际写代码时，两个场景一起考虑就写both。比如弹窗进入时用了scale(0.8)到scale(1)的关键帧，如果没写backwards，弹窗出现的第一帧可能是原始大小，然后才突然缩到 0.8 再放大，哪怕只闪了一帧，观感也很糙。

3. 三组真实场景：从弹窗到列表错峰一步步做出来

3.1 场景一：模态框弹出动画，用三层关键帧做出回弹质感

先来最常见的模态框。一个粗糙的弹窗动画是“从透明到不透明 + 从缩小到正常”，但优秀的弹窗反馈通常带一点回弹，比如落到目标位置后轻微过冲再回来。关键帧可以把这个过程拆成三段：0% 缩小并透明，60% 放大到比正常稍大，100% 回到正常。

模板部分：

<template> <div> <button @click="showModal = true">打开弹窗</button> <transition name="modal"> <div class="mask" v-if="showModal" @click.self="showModal = false"> <div class="modal-box"> <h3>提示</h3> <p>这是一个用 CSS 关键帧做的弹窗</p> <button @click="showModal = false">关闭</button> </div> </div> </transition> </div> </template>

样式部分：

.mask { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.5); display: flex; align-items: center; justify-content: center; } .modal-enter-active { animation: pop-in 0.4s cubic-bezier(0.68, -0.55, 0.265, 1.55) both; } .modal-leave-active { animation: pop-out 0.25s ease-in both; } @keyframes pop-in { 0% { opacity: 0; transform: scale(0.7) translateY(-40px); } 60% { opacity: 1; transform: scale(1.05) translateY(4px); } 100% { opacity: 1; transform: scale(1) translateY(0); } } @keyframes pop-out { 0% { opacity: 1; transform: scale(1) translateY(0); } 100% { opacity: 0; transform: scale(0.85) translateY(16px); } }

这里缓动我特意用了cubic-bezier(0.68, -0.55, 0.265, 1.55)，这是一个回弹感很强的贝塞尔曲线。不过要注意，animation的缓动是作用于整个动画过程的，它会交错叠加在关键帧的阶段变化上。如果你把 0% 到 60% 和 60% 到 100% 之间想象成两段运动，总体的节奏就是“快速落下 -> 轻微过冲 -> 回稳”，正好符合弹窗的物理直觉。

如果你连每段之间的节奏都想独立控制，可以把animation-timing-function写进关键帧内部：

@keyframes pop-in { 0% { opacity: 0; transform: scale(0.7); animation-timing-function: ease-out; } 60% { opacity: 1; transform: scale(1.05); animation-timing-function: ease-in; } 100% { transform: scale(1); } }

这样拖拽感更细腻，但注意命中的是骨架感，不是代码的复杂度。

离开动画同样值得注意。很多同学只关注入场，离开随便设个 0.2 秒的透明度渐变就完事，结果弹窗关闭时“啪”地一下消失，整个界面立刻变得很生硬。我之前踩过这个坑，后来统一把离开动画也做成关键帧，哪怕只是缩小 + 上移 + 透明度，视觉完成度都能上一个台阶。

3.2 场景二：列表错峰入场，animation-delay 配 both 才有用

列表动画是另一个高频需求。用transition-group包住v-for渲染的列表，可以控制每个列表项插入、移除、移动时的动画。配合关键帧，能轻松做出“依次滑入”的错峰效果。

模板部分：

<transition-group name="list" tag="ul" class="list-wrap"> <li v-for="(item, index) in list" :key="item.id" class="list-item" :style="{ animationDelay: index * 80 + 'ms' }" > {{ item.content }} </li> </transition-group>

样式部分：

.list-item { list-style: none; padding: 12px 16px; border: 1px solid #eee; border-radius: 8px; margin-bottom: 8px; } .list-enter-active { animation: slide-in 0.5s ease-out both; } .list-leave-active { animation: slide-out 0.3s ease-in both; position: absolute; width: 100%; left: 0; right: 0; } .list-move { transition: transform 0.4s ease; } @keyframes slide-in { 0% { opacity: 0; transform: translateX(-30px) scale(0.95); } 100% { opacity: 1; transform: translateX(0) scale(1); } } @keyframes slide-out { 0% { opacity: 1; transform: translateX(0); } 100% { opacity: 0; transform: translateX(30px) scale(0.95); } }

这段代码里有三个细节，每一个都值得单独说。

第一，animation-delay是写在每个li的内联样式上的，配合index * 80计算错峰间隔。但如果你用了scoped样式，内联样式不受 scoped 影响，所以这里不用做穿透处理，直接写就行。

第二，Delay 期间元素的状态由animation-fill-mode决定。both模式下，元素会保持 0% 帧的样式（透明 + 左侧偏移）等待动画开始。如果你写的是none或者backwards，在 delay 期间元素会以原始样式显示，等动画真正开始时才突然跳到 0% 帧，视觉上就是“闪一下再动”。

第三，list-leave-active里我加了position: absolute。这可能是列表动画里最容易忽略的一步：不加它，被移除的元素还占着文档流的位置，后面的元素不会补上来，直到 DOM 真正被移除后才会瞬间跳位，整个收起过程会产生一次“抽搐”。mark 一下，这个坑我至少帮三个人排过。

transition-group的move类名也有讲究。list-move里的transition: transform 0.4s ease，负责元素在列表里变序或别人让位时的平滑移动。如果用不上变序，这行可以不写；但配合 key 变更、列表拖拽排序时，没有move过渡，整个列表会在数据变化的一瞬间直接换位，错峰效果会打折扣。

3.3 场景三：消息通知进出自动播放，关键帧同时控制位移和留白

第三个场景是轻提示（Toast）这类短暂停留的组件。它的特别之处在于：入场动画结束之后，要在页面上停留几秒，再触发离开动画。这类需求如果完全靠 CSS 自己玩，可以写好animation的 delay，但在 Vue 里更常用的做法是把停留逻辑放在 JS 侧，动画本身交给关键帧。

模板部分：

<transition name="toast" @after-enter="handleAfterEnter"> <div v-if="showToast" class="toast"> {{ message }} </div> </transition>

逻辑部分：

function handleAfterEnter() { clearTimeout(timer) timer = setTimeout(() => { showToast.value = false }, 2000) }

样式部分：

.toast { position: fixed; top: 48px; left: 50%; transform: translateX(-50%); padding: 12px 20px; background: #333; color: #fff; border-radius: 8px; z-index: 999; } .toast-enter-active { animation: toast-in 0.4s cubic-bezier(0.68, -0.55, 0.265, 1.55) both; } .toast-leave-active { animation: toast-out 0.3s ease-in both; } @keyframes toast-in { 0% { opacity: 0; transform: translate(-50%, -16px) scale(0.9); } 100% { opacity: 1; transform: translate(-50%, 0) scale(1); } } @keyframes toast-out { 0% { opacity: 1; transform: translate(-50%, 0) scale(1); } 100% { opacity: 0; transform: translate(-50%, -12px) scale(0.95); } }

这里有一个非常容易踩到的细节：Toast 的定位是left: 50%配合transform: translateX(-50%)居中，但关键帧动画里你又必须要动transform来实现位移和缩放，两边直接冲突了。解决方案是在每个关键帧里都带上translate(-50%, ...)，把“居中的偏移”和“动画位移”合并成一个 transform 值。

不这么干的话，动画一开始transform被关键帧接管，居中偏移就丢了，Toast 会瞬间跑到页面最左侧。我第一次写的时候就被这个坑绊了一跤，排查了半天才发现是 transform 覆盖问题。

4. 动画不生效、乱跳、卡顿：排错记录与填坑经验

4.1 动画完全不跑，先查这几个位置

遇到@keyframes在 Vue 里不生效，我现在的排查顺序是固定的。

第一步，确认<transition>确实包住了要切换的元素，而且name属性和 CSS 类名前缀一致。name="modal"对应的类名是modal-enter-active，不是v-enter-active。如果你不写 name，Vue 默认用v-前缀，也就是v-enter-active。

第二步，确认触发切换的是v-if/v-show/<component>这类 Vue 能感知的状态变化，而且状态确实发生了改变。有次我把数字从 1 改成 2，过渡没生效，后来才发现监听数据用的是watch但对象是响应式丢失的副本。

第三步，打开浏览器控制台看元素有没有拿到类名。如果类名在，但动画不动，问题基本在 CSS 侧；如果类名根本没出现，问题在组件配置或数据流。

第四步，确认元素不是display: none状态下被操作。transition对display的变化是无能为力的，v-show切换时 Vue 会通过内联样式控制display，这个时机和类名的添加时机是配合好的，一般没问题。但如果你自己在父组件里写了控制子元素display的逻辑，很容易抢在 Vue 的动画机制之前，动画就被吞了。

4.2 动画播完元素跳回原位，检查 fill-mode 和多余类名

跳变最典型的两个原因，我前面都已经提到过：一是animation-fill-mode没设，动画结束后的状态没有被保留，元素回到关键帧定义前的样式；二是在enter-to或leave-to里又写了和关键帧冲突的属性。

举个例子，你写了一个向右滑出的离开动画，关键帧的 100% 是transform: translateX(100%)，但同时在list-leave-to里写了opacity: 0。那动画执行完后，transform仍在但opacity可能被强制归零，视觉上没问题，可如果语义上你把opacity写在关键帧之外，这两者就会产生微妙竞争，偶尔表现漂移。

我的建议是：凡是关键帧动画已经覆盖的属性，不要再在-enter-to/-leave-to里写第二遍。让关键帧闭环表达整个动画，类名只负责把动画挂上去。

4.3 离开动画结束时 DOM 不卸载，多半是动画事件没触发

Vue 是靠监听animationend或transitionend来决定何时把元素从 DOM 里移除的。所以如果leave-active里的animation时长和实际关键帧总时长对不上，或者关键帧里animation-duration被改成了 0s，事件可能早早就触发了或者压根不触发，导致v-if切换后元素吊在页面上不消失。

这个坑还经常出现在重复触发场景里：用户快速点击两次关闭，第一次元素还在播放离开动画，第二次点击又让它重新进入。此时组件状态和动画实例没做互斥，可能出现“动画事件丢失”的情况。我后来在处理复杂动画时，会在组件里加一个isAnimating标志位，动画未结束前不接受新的切换指令。

4.4 全局同名关键帧冲突，scoped 也救不了你

@keyframes的名称在全局是共享的，跟 scoped 不 scoped 没关系。你在两个组件里都定义了@keyframes fade-in，后加载的样式会覆盖先加载的，某一天上线后莫名其妙出现动画错乱，多半就是这个原因。

解决方式有两种。第一种最简单，关键帧命名带上组件前缀，比如modal-fade-in、toast-fade-in，用约定避免冲突。第二种是在构建工具里配置 CSS Module 的动画名处理，但配置成本高，大多数项目不值得。我自己一般用第一种，配合scoped样式一起用，还没出现过二次踩坑。

如果项目用了样式压缩工具，有个别压缩配置会把关键帧名称也做混淆，导致两个组件重名后看不出规律。遇到这种情况时，别花太多时间找规律，直接用前缀命名统一规避掉。

5. 性能与工程化：让关键帧动画在真实项目里稳得住

5.1 只动 transform 和 opacity，别去 layout 雷区

做关键帧动画时，尽量只动transform和opacity这两个属性。transform可以由 GPU 合成，opacity的渐变走的是合成层，这两兄弟几乎不触发布局和重绘。反过来，如果你在关键帧里写了width、height、top、left、margin，每帧变化浏览器都要重新走一遍布局流程，尤其是列表多、层级深的时候，帧率直接崩到肉眼可见的卡顿。

我之前有个折叠面板需求，同事用height: 0 -> auto做关键帧展开，结果展开过程一卡一卡的。替换方案是用max-height配合 transform 视觉缩放，或者干脆用grid-template-rows: 0fr -> 1fr这类布局动画，效果顺滑很多。当然这种 CSS 方法兼容性要看自己的项目环境，但思路是一致的：减少 layout 触发。

5.2 will-change 要克制使用

有些优化教程会建议在动画元素上加上will-change: transform，意思是提前告诉浏览器“这个元素马上要动”，让浏览器把它放在独立合成层。这个属性在单个元素上效果明显，但如果你给十来个列表项全加上，GPU 内存会被白占一大块，反而更卡。

我的经验是：在入场类动画上不用刻意加，因为动画本身只持续几百毫秒；如果是长驻页面、频繁参与动画的核心元素，比如悬浮球、常驻菜单，再考虑加will-change。而且动画结束后的after-leave或after-enter钩子里，记得把will-change移除掉，别让它一直占着合成层。

5.3 动画时长统一交给 CSS 变量管理

一个项目里动画时长如果散落在各个组件里，改起来非常痛苦。我在工程里会维护一组 CSS 变量：

:root { --anim-fast: 0.15s; --anim-base: 0.3s; --anim-slow: 0.6s; --anim-ease: cubic-bezier(0.25, 0.1, 0.25, 1); }

然后在关键帧动画里直接引用：

.modal-enter-active { animation: pop-in var(--anim-base) var(--anim-ease) both; }

这样全局改交互节奏的时候只需要动变量，不用满项目找选择器。配合:duration属性同步 JS 逻辑里的延时也方便：

<transition name="modal" :duration="{ enter: 400, leave: 250 }" @after-leave="handleAfterLeave" >

Vue 的duration属性会告诉它实际的动画时长，后续触发after-enter/after-leave的时间点会更准，不会出现 CSS 动画还没播完、JS 钩子已经跑了的情况。

6. 最后一个实用技巧：enter 和 leave 用两套关键帧，别共用一套

很多初学者图省事，一套关键帧进出共用。比如进入时从左边滑入，离开时也让元素回到左边，视觉上确实对称，但真实交互里，用户看到“从哪来回哪去”只会觉得傻。合理的做法是：进入动画用弹性和速度感，离开动画用轻量、干脆的收束，两者节奏不同，产品气质才立得住。

我在实际项目里，一个弹窗组件的进入动画是 0.4 秒带回弹，离开动画只给 0.2 秒的快速透明 + 缩小。用户操作时心理模型是“点开是重点，关掉不拖沓”。这个节奏配合好之后，整体页面质感立刻不一样。

12-01 这篇笔记大体上就是把 CSS 关键帧在 Vue 动画里的接入点和几个实操场景捋清楚了。后面我会继续整理 JS 钩子配合关键帧做拖动方向感知动画，以及<transition-group>在真实列表拖拽排序里的完整实践，到时候再更新笔记。