企业官网建设流程全解析

做 Android 页面跳转，带不带动画的体感差距是实打实的。Compose 全面接管 UI 之后，Navigation Compose 从 2.7.0 版本开始把过渡动画直接内置进 NavHost，你不用再像以前那样额外引入 accompanist-navigation-animation，也不用自己包一层 AnimatedContent 去模拟转场。但正因为动画是内置的，反而有一堆参数需要搞清楚：enterTransition、exitTransition、popEnterTransition、popExitTransition 这四个到底分别在控制什么场景，全局参数和单页面参数谁优先，以及为什么返回时的动画方向经常跟预期反着来。

这篇文章提供一套可以直接跑起来的完整示例代码，把路由设计、带动画的页面跳转、参数传递、返回结果回传、底部导航状态保存全部串在一起。我会先讲清动画参数背后的原理，再贴出完整代码，最后把我真机调试时踩过的坑和排查思路整理成速查表。适合正在用 Navigation Compose 但没系统整理过动画逻辑的开发者，也适合想把跳转体验从"能跳"提升到"顺滑"的 Android 项目。

1. 动画这套东西在 Navigation 里到底管什么

1.1 导航动画不是装饰，而是导航状态的视觉反馈

很多人把页面切换动画理解成"好看"，这个理解太窄了。在 Navigation 的语境里，动画承担的是解释任务：新页面从哪里来、旧页面到哪里去、当前是前进还是返回。用户通过动画建立空间感，知道自己在导航栈的哪个位置。

举个例子，你从列表页点进详情页，默认的过渡是从右往左滑入，返回时详情页从左往右滑出。这跟 iOS 的 push/pop 交互语言是一致的，用户不需要思考就知道自己"回去了"。如果动画做反了——前进时新页面从左边出来，返回时旧页面又从右边回去——用户会明显觉得别扭，哪怕他说不出哪里不对。

所以在设计 Navigation 动画时，我建议你把四个参数当成一组完整的"进出场编排"来看，而不是单独调某一个。前进动画和返回动画是镜像关系，通常前进时新页面从右往左滑入、旧页面向左滑出，返回时反向执行。这个镜像关系在代码里就体现在 popEnterTransition 和 popExitTransition 这两个参数上。

1.2 内置动画之前，大家是怎么做的

Navigation Compose 2.7.0 之前，官方 NavHost 是不带动画的。当时的常见做法是引第三方库，最流行的是 accompanist-navigation-animation，它提供了 AnimatedNavHost，让你可以在每个 composable 里指定 enterTransition 和 exitTransition。

这个库确实好用，但它和官方 Navigation 的 API 是两套体系，升级 Navigation 版本时经常出现兼容性问题。到了 2.7.0，官方把动画能力合并进 navigation-compose，AnimatedNavHost 的所有核心功能都以参数形式出现在 NavHost 上，API 设计基本沿用下来，迁移成本很低。2.8.0 又加入了类型安全路由和预测性返回动画的支持，算是把导航动画这块补齐了。

我的建议很直接：新项目一律用官方 navigation-compose 2.8.x，老项目如果还在用 accompanist，尽早迁移。这不是赶时髦，而是 accompanist 的导航动画库已经停止维护，继续用下去迟早要处理依赖冲突。

2. 环境准备：版本、依赖和四种过渡参数

2.1 依赖配置与版本选择

先在 module 的 build.gradle.kts 里加上依赖。我建议用 Compose BOM 统一管理 Compose 相关版本，Navigation 单独指定版本，因为它的发版节奏和 Compose 不完全同步。

dependencies { implementation(platform("androidx.compose:compose-bom:2024.10.01")) implementation("androidx.compose.material3:material3") implementation("androidx.navigation:navigation-compose:2.8.4") }

如果你在 2.7.0 之前的老版本上升级，注意两个点：第一，navigation-compose 2.7.0 要求项目的 compileSdk 至少是 34，minSdk 至少是 21；第二，如果你的代码里还残留着对 accompanist-navigation-animation 的引用，需要一并移除，否则会出现两个导航实现共存导致的诡异问题，具体表现我后面在排查章节里会讲。

2.2 四个过渡参数分别管什么场景

NavHost 的动画参数一共有四个，它们的触发场景完全不同。我用一张表先讲清楚，再逐个说明：

关键点在"返回"这件事上。前进（navigate）时，系统同时触发新页面的 enterTransition 和旧页面的 exitTransition，这两个是同时进行的。返回（popBackStack）时，触发的是原栈顶页面的 popExitTransition 和它下面那个页面的 popEnterTransition。

我见过不少人在返回动画上翻车：只配了 enterTransition 和 exitTransition，然后发现返回时页面是"闪"回去的，没有任何过渡。原因就是返回场景走的是 pop 系列参数，你不配它就等于没有动画。这一点务必记住。

2.3 全局参数和单页面参数的优先级

NavHost 上可以直接设置四个动画参数作为全局默认值，每个 composable 也支持单独设置，覆盖全局配置。优先级是：composable 级别的参数 > NavHost 级别的参数。

但这里有个容易误会的细节：composable 级别的 enterTransition 只影响"该页面作为新页面被 navigate 进入时"的动画，composable 级别的 exitTransition 只影响"该页面作为旧页面被新页面覆盖时"的动画。也就是说，你的全局动画和单页面动画可以混着用，比如首页保持全局的淡入淡出，详情页单独指定左右滑动，列表页保持全局默认。系统会按每个页面自己的配置去执行对应方向的过渡。

我在实际项目里的策略是：全局只配一个温和的默认动画（淡入淡出加轻微缩放），需要强调层级关系的页面（比如详情页、大图预览页）单独配置滑动或缩放动画。这样既保证了整体一致性，又让重点页面有差异化体验。

3. 全套示例代码：路由、跳转、传值与返回

3.1 路由表与 NavHost 骨架

先定义路由常量。我习惯用一个 Routes 对象统一管理，避免字符串散落在各个文件里。这里用带占位符的字符串路由，配合 navArgument 声明参数类型，是当前最通用、兼容性最好的写法。

object Routes { const val MAIN = "main" const val DETAIL = "detail/{itemId}" fun detail(itemId: Int) = "detail/$itemId" }

然后是 AppRoot，也就是整个应用的导航根节点。这里我配了一组全局动画：进入时渐显加轻微放大，退出时渐隐，返回时反向。

@Composable fun AppRoot() { val navController = rememberNavController() NavHost( navController = navController, startDestination = Routes.MAIN, enterTransition = { fadeIn(animationSpec = tween(300)) + scaleIn(initialScale = 0.94f, animationSpec = tween(300)) }, exitTransition = { fadeOut(animationSpec = tween(300)) }, popEnterTransition = { fadeIn(animationSpec = tween(300)) }, popExitTransition = { fadeOut(animationSpec = tween(300)) + scaleOut(targetScale = 0.94f, animationSpec = tween(300)) } ) { composable(Routes.MAIN) { MainScreen(navController = navController) } // detail 页面的注册在下一节 } }

注意几个细节。fadeIn、fadeOut、scaleIn、scaleOut 是 Compose Animation 提供的顶级函数，返回的是 EnterTransition / ExitTransition 类型，可以直接用加号组合，这跟 AnimatedVisibility 里的用法一致。tween() 是动画核心库里的 easing 曲线函数，默认是 FastOutSlowInEasing，300 毫秒是一个比较稳妥的时长——太短会显得生硬，太长会让频繁跳转的用户觉得拖沓。

3.2 带参数的跳转与单页面动画

详情页的注册要复杂一些。它接收一个 Int 类型的 itemId 参数，同时拥有自己独立的滑动动画。这里的思路是：详情页作为列表页的下一层，应该用"从右往左推入"的动画来表达层级递进关系，而不是用全局的淡入淡出。

composable( route = Routes.DETAIL, arguments = listOf( navArgument("itemId") { type = NavType.IntType } ), enterTransition = { slideIntoContainer( AnimatedContentTransitionScope.SlideDirection.Left, animationSpec = tween(350) ) + fadeIn(animationSpec = tween(350)) }, exitTransition = { slideOutOfContainer( AnimatedContentTransitionScope.SlideDirection.Left, animationSpec = tween(350) ) + fadeOut(animationSpec = tween(350)) }, popEnterTransition = { slideIntoContainer( AnimatedContentTransitionScope.SlideDirection.Right, animationSpec = tween(350) ) + fadeIn(animationSpec = tween(350)) }, popExitTransition = { slideOutOfContainer( AnimatedContentTransitionScope.SlideDirection.Right, animationSpec = tween(350) ) + fadeOut(animationSpec = tween(350)) } ) { backStackEntry -> val itemId = backStackEntry.arguments?.getInt("itemId") ?: 0 DetailScreen( navController = navController, itemId = itemId ) }

这段代码里最重要的一点是 SlideDirection 的用法。slideIntoContainer 和 slideOutOfContainer 是 AnimatedContentTransitionScope 的成员函数，它们和普通的 slideInHorizontally 最大的区别在于：滑动方向是相对于当前导航动作的，系统会自动判断"推入"还是"推出"。

具体到这个例子，navigate 进入详情页时，新页面从 Left 方向滑入，旧页面往 Left 方向滑出，视觉上整体向左推进。popBackStack 返回时完全反向，详情页往 Right 滑出，列表页从 Right 滑入，视觉上整体向右退回。如果你用 slideInHorizontally 自己传 initialOffset，就得手动区分前进和返回，代码会啰嗦不少，而且很容易在边界情况下算错偏移量。

触发跳转的代码在列表页的 Item 点击事件里，直接拼路由字符串：

// MainScreen 中 onClick = { navController.navigate(Routes.detail(item.id)) }

3.3 返回结果传值：savedStateHandle 的正确用法

页面跳转带参数很简单，返回时把结果传回上一个页面就稍微绕一点。Navigation 官方推荐的方案是用上一个 BackStackEntry 的 savedStateHandle。

什么叫"上一个 BackStackEntry"？就是导航栈里当前页面下面的那一个。比如 MainScreen 是栈底，navigate 到 DetailScreen 之后栈变成 [Main, Detail]，此时 previousBackStackEntry 就是 Main 的那个 entry。往它的 savedStateHandle 里塞数据，等 pop 回去之后，MainScreen 就能读到。

DetailScreen 里的回传逻辑：

@Composable fun DetailScreen( navController: NavController, itemId: Int ) { var inputText by remember { mutableStateOf("") } Button( onClick = { // 把结果写入上一个页面的 SavedStateHandle navController.previousBackStackEntry ?.savedStateHandle ?.set("detail_result", inputText) navController.popBackStack() } ) { Text("保存并返回") } }

MainScreen 这边接收结果，我推荐用 getStateFlow 加 collectAsState 的方式，这样结果到达时 UI 会自动重组更新，不需要手动刷新：

@Composable fun MainScreen(navController: NavController) { val backStackEntry = navController.currentBackStackEntry val result by backStackEntry ?.savedStateHandle ?.getStateFlow("detail_result", "") ?.collectAsState() ?: remember { mutableStateOf("") } // result 非空时显示在界面上 }

这里有个容易踩的坑：千万不要在 navigate 之前就调用 getStateFlow。因为 MainScreen 在被 DetailScreen 覆盖时，它的 currentBackStackEntry 还在，但状态是从 SavedStateHandle 里读的，必须等写入发生之后才能拿到值。我见过有人把接收逻辑写在 init 块里或者用 LaunchedEffect 只跑一次，结果返回时界面不更新，排查半天才发现是读取时机的问题。

3.4 底部导航 + 状态保存的完整写法

底部导航和普通页面跳转有一个本质区别：用户会频繁地在几个 Tab 之间切换，如果每次切换都重新创建页面、丢失滚动位置和输入内容，体验会非常差。Navigation Compose 提供了 saveState 和 restoreState 两个标志位来解决这个问题。

我常用的写法是这样：底部导航的容器里再放一个 NavHost，Tab 页面作为它的子页面，切换时用 navigate 配合标志位：

@Composable fun MainScaffold(navController: NavController) { val items = listOf("home", "search", "profile") val navBackStackEntry by navController.currentBackStackEntryAsState() val currentRoute = navBackStackEntry?.destination?.route Scaffold( bottomBar = { NavigationBar { items.forEach { route -> NavigationBarItem( selected = currentRoute == route, onClick = { navController.navigate(route) { popUpTo(navController.graph.findStartDestination().id) { saveState = true } launchSingleTop = true restoreState = true } }, icon = { /* 按 route 设置图标 */ }, label = { /* 按 route 设置文案 */ } ) } } } ) { innerPadding -> NavHost( navController = navController, startDestination = "home", modifier = Modifier.padding(innerPadding), enterTransition = { fadeIn(animationSpec = tween(250)) }, exitTransition = { fadeOut(animationSpec = tween(250)) } ) { composable("home") { HomeScreen() } composable("search") { SearchScreen() } composable("profile") { ProfileScreen() } } } }

这段代码里三个标志位各有分工：launchSingleTop 保证同一个 Tab 被反复点击时不会重复压栈；popUpTo 配合 saveState 把当前 Tab 之外的所有页面出栈，但保存它们的状态；restoreState 在重新进入某个 Tab 时恢复之前保存的状态。

我需要提醒你的是：这种写法下，如果某个 Tab 内部还有二级页面（比如 home Tab 里点进详情再切走），切回 home 时详情页还在栈顶，用户看到的不是 home 而是详情。要处理这种情况，可以在切 Tab 时把 popUpTo 的目标改成该 Tab 的起始页而不是整个图的起始页。这是个很典型的业务场景，网上很多示例代码都没覆盖到。

4. 自定义动画：把内置函数组合成自己的过渡效果

4.1 内置动画函数的家底

Navigation 动画的可选"零件"其实就是 Compose Animation 里那套动画函数。我把常用的列一下，方便你组合时心里有数：

这里要特别说明 expandIn / expandOut。它俩在 AnimatedVisibility 里很好用，但放到 Navigation 的转场里要谨慎，因为它涉及目标尺寸变化，如果配合不好会出现内容被裁剪或者跳动的问题。我自己的经验是：Navigation 场景里最稳的组合是"位移 + 透明度"，其次是"缩放 + 透明度"，扩展收缩类留给局部控件的显隐动画去用。

4.2 组合一个完整的页面转场

有了零件，就可以拼出自己的转场效果。比如做一个"新页面从底部升起 + 旧页面轻微缩放后退"的效果，这在很多内容型 App 的二级页面里很常见：

NavHost( navController = navController, startDestination = Routes.MAIN, enterTransition = { slideIntoContainer( AnimatedContentTransitionScope.SlideDirection.Up, animationSpec = tween(450, easing = FastOutSlowInEasing) ) + fadeIn(animationSpec = tween(450)) }, exitTransition = { scaleOut( targetScale = 0.92f, animationSpec = tween(450) ) + fadeOut(animationSpec = tween(450)) }, popEnterTransition = { fadeIn(animationSpec = tween(450)) }, popExitTransition = { slideOutOfContainer( AnimatedContentTransitionScope.SlideDirection.Down, animationSpec = tween(450, easing = FastOutSlowInEasing) ) + fadeOut(animationSpec = tween(450)) } )

我解释一下这个组合的意图：新页面从底部升起，给用户"向上推进"的感觉；旧页面同时缩小并淡出，像被推远了一样。返回时新页面（现在是旧栈顶）往下滑出，下面的页面淡入恢复。整体视觉层次比单纯的左右滑动更柔和，适合详情、设置这类不强调"兄弟层级"的页面。

组合动画时有个性能上的注意点：位移和缩放这类变换尽量在 graphicsLayer 层面完成，Compose 的动画系统本身会自动做这个优化，但你在页面内容里如果用了大量 bitmap 绘制、blur 或阴影，动画期间的合成成本会明显上升，掉帧概率大增。后面排查章节我会再展开。

4.3 动画参数里的细节：duration、easing、offset

很多人配置动画时只填一个 duration，easing 和 offset 直接忽略。实际上这两个参数对动画质感的影响不亚于时长。

easing 决定动画速度的变化方式。Navigation 转场最常用的是 FastOutSlowInEasing，也就是"快进慢出"，这也是 Material Design 的推荐曲线。它让动画快速进入用户视野，然后缓慢稳定下来，看起来有惯性、不呆板。LinearEasing 只在极端简朴的场景下用，easeOut 之类也都有各自适用的场景。记住一点：转场动画是给人看"方向感"的，不是给人看"速度"的，所以曲线中段要快、首尾要缓。

offset 参数在 slideIntoContainer 里是一个 lambda，接收当前容器宽度或高度，返回偏移量。默认是容器完整尺寸，也就是完全滑出屏幕。你可以调整它实现"只滑一半"的效果：

enterTransition = { slideIntoContainer( AnimatedContentTransitionScope.SlideDirection.Left, animationSpec = tween(300), initialOffset = { fullSize -> fullSize / 2 } ) }

这样新页面只从屏幕中间位置开始滑入，配合背景半透明的话，能做出一种"浮层推进"的效果。我做引导页、弹层式页面时经常用这个技巧，比全屏滑动更有层次感。

5. 常见问题与排查技巧实录

5.1 动画不生效的几种情况

动画完全没执行，是我被问得最多的问题。整理下来，最常见的诱因有三个。

第一个是版本问题。如果项目还在 navigation-compose 2.6.x 或更早，NavHost 根本没有动画参数，你在代码里写了也会因为编译报错而无法运行。解决办法明确：升到 2.7.0 以上。

第二个是全局参数和单页面参数的覆盖关系没搞清楚。某个页面单独设置了动画，并且这些动画函数返回了 null 或者空实现，就会覆盖掉全局动画。我遇到过有人为了"取消某个页面的动画"，写了 enterTransition = { null }，结果这个页面确实没有进入动画了，但退出动画也被影响了，因为 exitTransition 用的是同一个全局配置的逻辑边界。正确做法是：想取消动画，显式地给四个参数都配置相同的空转场，而不是只置空一个。

第三个是导航动作发生太快。比如连续调用两次 navigate，第一次动画还没跑完第二次就开始了，Compose 会中断当前动画直接切到下一个状态。这在双击事件里特别常见。所以入口处加防抖或者用 launchSingleTop，不只是规范问题，也能避免动画被"打断成闪屏"。

5.2 返回手势、预测性返回和 BackHandler 的三角关系

这是一个新时代的坑。Android 14 之后系统默认开启预测性返回，用户从屏幕边缘右滑时，系统会提前显示上一页的预览动画。Navigation Compose 2.8.0 对此做了适配，前提是你在 manifest 的 Application 节点开启了 enableOnBackInvokedCallback：

<application android:enableOnBackInvokedCallback="true">

开启之后，系统返回手势会和 NavHost 的 pop 动画联动，体验很顺滑。但如果你在某个页面里用了 BackHandler 拦截返回事件，系统的手势预览就会被禁用，退化为传统的返回动画甚至直接退出。这本身是合理设计，但容易造成"同一个应用，有的页面能手势预览，有的页面不能"这种不一致的体验。

我的建议是：能不用 BackHandler 就不用，确实要拦截时（比如表单未保存提示），也只在页面处于栈顶的短暂生命周期内注册，用完立刻释放。别在 Composable 外部用 remember 缓存一个长期存活的拦截器，那会让整个导航栈的手势动画全部失效。

5.3 掉帧卡顿与性能排查

动画期间掉帧，绝大部分问题出在新页面首帧的渲染成本上。Navigation 的转场动画会驱动新旧两个页面的组合过程，如果新页面在 enterTransition 期间做了重活，比如加载大图、解析大 JSON、执行复杂布局，动画就会卡。

我的排查思路是分层看：先用系统自带的 Profile HWUI 渲染分析，确认掉帧是发生在 UI 线程还是 RenderThread。UI 线程的问题通常是新页面的首次 composition 太重，解决办法是把重活挪到后台线程，或者在页面真正进入之前做预加载。RenderThread 的问题通常是动画期间 GPU 合成压力大，解决办法是减少转场期间同时运动的元素数量，把多属性动画拆开，先做位移再做缩放。

还有一个容易被忽视的点：如果新页面里有 LazyColumn，并且加载了大量 item，动画期间列表会不断请求测量和布局，导致掉帧。我遇到过一次，详情页里有 200 多个 item 的列表，进入动画时掉到 20 帧，后来把列表的首屏 item 数量做了限制，动画立刻顺了。

5.4 常见问题速查表

我个人在实际操作中的体会是：Navigation 动画的配置本身不难，难的是它和导航栈生命周期、手势系统、页面性能三者交织在一起的那些边界情况。你只要把四个动画参数的触发场景彻底搞清楚，再记住全局和单页的覆盖规则，开发效率会提升一大截。最后再分享一个小技巧：调试动画时别用真机连着 Studio 逐步断点，那样会把动画时序彻底打乱，建议用日志打印导航栈状态，配合慢放录屏来确认每个场景的进出场是否符合预期。这套代码你拿过去改改路由和页面内容，就能直接开工。