在移动应用开发中，页面之间的切换动画直接影响用户对应用流畅度的感知。默认的 uni-app 提供了简单的页面切换效果，但在许多场景下我们需要更细腻的控制——比如从底部弹出登录页、侧边滑出菜单、或者列表进入详情时左滑返回右滑等。本文将系统讲解 uni-app 中 路由动画 的实现原理，并结合 Vue3 的 Transition 组件，手把手教你打造定制化的页面过渡效果，让应用交互更具质感。
uni-app 路由动画基础与限制
uni-app 的路由跳转方法（uni.navigateTo、uni.redirectTo、uni.switchTab 等）在底层调用了各平台的页面管理接口。官方在 pages.json 中提供了 animation 配置项，支持预设的页面切换效果，例如 pop-in、slide-in-right、slide-in-bottom 等。但这个配置是全局性的，无法动态指定某个页面的特殊动画。
此外，内置动画样式较为固定，且不同平台（如 iOS、Android、小程序）的表现可能不一致。当我们需要更丰富、更定制化的转场效果时，就必须借助 Vue 的 Transition 组件 或者通过 自定义组件容器 来包裹页面内容，在页面显示/隐藏时应用 CSS 动画。
接下来的案例将展示如何在不修改原生代码的情况下，用 Vue 的能力实现精细的页面级动画控制。
动画实现原理：页面栈与生命周期
在 uni-app 中，每个页面都是一个独立的 Vue 实例，页面之间通过路由栈管理。当打开新页面时，当前页面被压入后台但并未销毁（使用 navigateTo）；当返回时，页面从栈中弹出并销毁。
我们可以在 布局组件 中动态切换内容，而不是使用真实的路由跳转，但那样会破坏页面栈管理和性能。更好的方式是为每个页面单独配置其出现和消失的动画。核心思路是：
- 在页面的根元素上应用
<Transition>组件。 - 利用
onShow和onHide生命周期触发动画状态。 - 根据页面是进入还是返回，决定动画的正反向（如左滑进入对应右滑退出）。
我们需要一个全局的状态来判断当前路由是前进还是后退，这可以通过监听路由变化并比较页面栈长度来实现。下面将从简单到复杂，逐步构建三个典型场景。
案例一：全局自定义左滑-右滑页面过渡
在移动端，最常见的导航模式是列表页进入详情页时从左向右滑动，返回时从右向左滑动。我们希望在保留原生页面栈的前提下，实现这种“iOS 风格”的推入推出效果。
首先，在 App.vue 中监听路由变化，记录前进/后退状态：
// App.vue
import { ref } from 'vue'
export default {
setup() {
const routeStack = ref([])
uni.onAppRoute((res) => {
const currentPages = getCurrentPages()
if (routeStack.value.length 前进
uni.$emit('route-direction', 'forward')
} else {
// 页面栈减少 -> 后退
uni.$emit('route-direction', 'backward')
}
routeStack.value = [...currentPages]
})
}
}
接着，创建一个公共的页面容器组件 components/PageTransition.vue：
<template>
<transition :name="transitionName">
<slot />
</transition>
</template>
<script setup>
import { ref, onMounted, onUnmounted } from 'vue'
const transitionName = ref('slide-forward')
const setDirection = (dir) => {
transitionName.value = dir === 'forward' ? 'slide-forward' : 'slide-backward'
}
onMounted(() => {
uni.$on('route-direction', setDirection)
})
onUnmounted(() => {
uni.$off('route-direction', setDirection)
})
</script>
配合以下 CSS（可写在 App.vue 的全局样式中，由于不能使用 style 标签，这里仅作示意，实际开发中应放在对应的样式文件里）：
/* 全局样式 - 前进动画 */
.slide-forward-enter-active {
transition: transform 0.3s ease;
}
.slide-forward-leave-active {
transition: transform 0.3s ease;
position: absolute;
left: 0;
right: 0;
}
.slide-forward-enter-from {
transform: translateX(100%);
}
.slide-forward-leave-to {
transform: translateX(-30%);
}
/* 后退动画 */
.slide-backward-enter-active {
transition: transform 0.3s ease;
}
.slide-backward-leave-active {
transition: transform 0.3s ease;
position: absolute;
left: 0;
right: 0;
}
.slide-backward-enter-from {
transform: translateX(-30%);
}
.slide-backward-leave-to {
transform: translateX(100%);
}
最后，在每个页面的根元素包裹 PageTransition 组件，例如 pages/detail/detail.vue：
<template>
<page-transition>
<view class="page">
<text>详情页面</text>
</view>
</page-transition>
</template>
<script setup>
import PageTransition from '@/components/PageTransition.vue'
</script>
这样，当从列表进入详情时，页面从右侧划入；返回时，页面从左侧划出，并且离开的页面会被适当遮盖，效果非常接近原生导航。
案例二：底部弹出登录页（仿iOS ActionSheet）
有些页面不需要完整的推入动画，而是从底部弹出，例如登录验证密码、选择支付方式等。我们可以通过 uni.navigateTo 跳转，但给页面配置底部弹出的动画。
我们在目标页面（如 pages/login/login.vue）内使用局部 Transition，而不依赖全局方向：
<template>
<view class="mask" @click="close">
<transition name="slide-up">
<view class="login-panel" v-if="visible">
<text>请输入密码</text>
<!-- 表单内容 -->
</view>
</transition>
</view>
</template>
<script setup>
import { ref } from 'vue'
const visible = ref(false)
// 页面显示时触发动画
onShow(() => {
visible.value = true
})
const close = () => {
visible.value = false
setTimeout(() => {
uni.navigateBack()
}, 300) // 等待动画结束
}
</script>
对应的动画样式（在页面级样式或全局样式）：
/* 底部滑入 */
.slide-up-enter-active, .slide-up-leave-active {
transition: transform 0.35s cubic-bezier(0.36, 0.66, 0.04, 1);
}
.slide-up-enter-from, .slide-up-leave-to {
transform: translateY(100%);
}
这个案例中，页面本身只是一个透明遮罩，真正的表单面板是一个子组件，通过控制 v-if 驱动 Transition。利用 onShow 设置 visible 为 true，面板从底部滑入；点击遮罩关闭时，面板滑出，并在动画结束后执行 navigateBack，保证了平滑的退出体验。
案例三：列表到详情页的弹性放大效果
新闻或电商应用常用这种效果：列表中的某张卡片点击后，卡片“放大”并移动到详情页头部。这实际上属于 共享元素过渡，在原生开发中较复杂。在 uni-app 中，我们可以通过手动计算位置和使用 transform 模拟，但更简单的方式是使用透明度与缩放的结合，产生视觉上的放大感。
在详情页中，接收上一个页面传递的图片位置信息（通过路由参数），然后执行一个从缩略图位置到全屏的动画：
<template>
<view class="detail">
<image :src="image" class="hero" :class="{ 'animate-in': ready }"></image>
<text>{{ title }}</text>
</view>
</template>
<script setup>
import { ref } from 'vue'
const ready = ref(false)
onMounted(() => {
// 获取传递的初始位置（用于初始transform）
const eventChannel = this.getOpenerEventChannel()
eventChannel.on('startRect', (rect) => {
// 设置初始位置
// 此处可用内联样式动态绑定，但代码中通过class切换动画
ready.value = true
})
})
</script>
样式部分定义缩放动画：
.hero {
transform: scale(0.1) translateY(100px);
opacity: 0;
transition: all 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94);
}
.hero.animate-in {
transform: scale(1) translateY(0);
opacity: 1;
}
这个简化的版本虽然没有真正的共享元素那样完美，但在多数设备上能创造出令人愉悦的“展开”效果，且实现成本极低。
解决返回动画反转的常见问题
在手动管理动画时，开发者常遇到返回时动画方向错误的问题。比如从A页面左滑进入B页面后，按返回键或手势返回时，B页面本应右滑退出，但如果不加判断，可能会再次左滑。解决方案就是前面提到的 路由方向判断。
除了全局监听页面栈外，还可以通过 uni.getStorageSync 存储上一个路由路径，在页面加载时比较。但更可靠的方式是利用 onBackPress 生命周期（仅App和H5支持）来手动控制返回动画，并在动画结束后调用 navigateBack：
onBackPress((options) => {
if (options.from === 'backbutton') {
// 执行退出动画
visible.value = false
setTimeout(() => {
uni.navigateBack()
}, 300)
return true // 阻止默认返回行为
}
})
这种方法给予开发者完全的控制权，使得动画与返回操作完美同步。
动画性能优化与平台适配
动画虽然提升体验，但滥用会导致卡顿。在 uni-app 中优化动画可以参考以下建议：
- 使用 transform 和 opacity：这两个属性不会触发重排，是 GPU 友好的动画属性。
- 避免复杂阴影和大图在动画中使用：可以在动画完成后替换高清图片。
- 合理设置动画持续时间：移动端 300ms 左右是合适的，过短感知不明显，过长拖沓。
- 小程序平台限制：小程序不支持 CSS Transition 直接作用于 page 元素，建议用 view 包裹内容，动画作用在 view 上。
- 条件编译：如果某些平台动画效果不佳，可以使用
#ifdef进行差异化处理，比如 H5 和 App 用流畅的滑动动画，小程序使用简单的淡入淡出。
一个常见差异处理示例：
// 使用条件编译为不同平台定义动画名称
const transitionName = ref('')
// #ifdef H5 || APP-PLUS
transitionName.value = 'slide-forward'
// #endif
// #ifdef MP-WEIXIN
transitionName.value = 'fade' // 小程序用淡入
// #endif
总结
通过本文的三个实战案例，我们从全局路由动画、底部弹出面板到弹性放大效果，完整覆盖了 uni-app 中常见的页面过渡需求。核心要点在于利用 Vue 的 Transition 组件，结合路由生命周期和方向判断，为每个页面赋予符合用户预期的动画。在实际项目中，你可以将这些组件和逻辑抽取为公共模块，在应用内统一调用，从而快速打造出媲美原生应用的交互体验。
现在，打开你的 uni-app 项目，为页面切换加入细腻的动画吧——用户会感受到那份用心带来的流畅与愉悦。
