v2.7.0：H5 端导航动画扩展与 meta.animation 门控优化

v2.7.0 将导航动画能力从 App 端扩展到 H5 平台。新增 plugins/animation/h5.ts，通过注入的关键帧 CSS 在 H5 端实现与 App 端 animationType 命名对齐的过渡效果：push 生效进入动画（animatePageEnter），back
播放退出动画（animatePageExit）。同时优化 meta.animation 门控，使其统一在 router 层注入。

前言

此前导航动画仅 App 端生效：

• App 端：通过 uni.navigateTo / uni.navigateBack 的 animationType / animationDuration 原生窗口动画
• App 端自定义：无法自定义动画；改为 configuration
• 小程序端：导航动画由宿主控制，无法自定义

v2.7.0 通过运行时注入 CSS 关键帧 + getPlatform().isH5 判断，在 H5 端补齐 push / back 的过渡动画，使两端体验趋于一致。

说明：npm 发布产物由 tsup 构建、不会处理 #ifdef H5 条件编译，因此 H5 平台判断必须在运行时完成（getPlatform().isH5），并采用注入 <style> 的方式提供动画样式。

---

一、功能总览

功能	说明
H5 push 进入动画（animatePageEnter）	uni.navigateTo 成功后对目标页播放 CSS 进入过渡，经 requestAnimationFrame 延后
H5 back 退出动画（animatePageExit）	uni.navigateBack 前先播放当前页退出过渡，结束后再执行返回
CSS 关键帧样式注入	幂等注入 @keyframes，覆盖 slide-in/out-*、fade、zoom、pop 等方向
meta.animation 门控优化	需注册 AnimationPlugin 才注入，未注册时即使配置也不生效

---

二、H5 端导航动画（CSS 过渡）

1. 实现文件 plugins/animation/h5.ts

• ANIMATION_CSS：定义与 App 端 animationType 命名对齐的关键帧（mxuni-slide-in-right 等），基于 transform / opacity 实现
• ensureH5AnimationStyles()：幂等注入 <style> 到 document.head，仅 H5 平台执行
• animatePageEnter(animation)：进入动画。因目标页在 success 时可能尚未渲染，通过 requestAnimationFrame 延后到下一帧再应用动画；animationend 后清理样式，并带定时兜底
• animatePageExit(animation)：退出动画。先播放再 resolve，供 goBack 等待动画结束

2. 接入点

// navigation/helpers/uni-api.ts - push
success: res => {
	if (getPlatform().isH5 && animation) animatePageEnter(animation)
	resolve(res.eventChannel)
}

// navigation/navigate.ts - back
export async function goBack(delta = 1, animation?: NavigationAnimation): Promise<void> {
	if (getPlatform().isH5 && animation) {
		await animatePageExit(animation) // 先播退出动画，再执行返回
	}
	return uniNavigateBack(delta, animation)
}

3. 动画类型

进入动画（push / replace / relaunch）与退出动画（back）的映射与 App 端 UniAnimationType 命名保持一致：

进入动画	退出动画
slide-in-right / slide-in-left / slide-in-top / slide-in-bottom	slide-out-right / slide-out-left / slide-out-top / slide-out-bottom
fade-in / zoom-in / zoom-fade-in / pop-in	fade-out / zoom-out / zoom-fade-out / pop-out

• 动画时长默认 300ms（DEFAULT_ANIMATION_DURATION），可通过 duration 覆盖
• 优先级：调用时传入 animation > meta.animation

4. 平台能力矩阵

平台	自定义动画能力
App	✅ 原生窗口动画（animationType）
H5	✅ push（进入）+ back（退出）CSS 过渡
小程序	❌ 由宿主控制，无法自定义

---

三、meta.animation 门控优化

导航动画有效值统一在 router 层计算：

• meta.animation 仅在注册 AnimationPlugin 时注入导航选项
• 未注册 AnimationPlugin 时，即使路由配置了 meta.animation 也不生效（与调用时传入 animation 的 PLUGIN_REQUIRED 门控保持一致）
• navigation/navigate.ts 不再内部回退读取 meta.animation，消除此前"导航层与 router 层均读取动画默认值"的分歧

---

四、重构

• 抽出 navigation/helpers/uni-api.ts，收敛 uni.navigateTo / switchTab / redirectTo / navigateBack / reLaunch 的 uni 调用与 Promise 化
• 抽出 plugins/animation/helpers、plugins/interceptor/helpers/parse.ts 等助手模块，统一平台判断（getPlatform）

以上为模块与代码结构调整，对外 API 无变化，不影响使用。

---

五、升级指南

v2.7.0 完全向后兼容，无破坏性变更：

• 新增的 H5 动画能力仅在传入 animation（或注册 AnimationPlugin 并通过 meta.animation）时生效，未配置动画不影响现有行为
• 此前 H5 端无自定义动画，升级后在配置了 animation 的 push / back 上开始出现 CSS 过渡
• meta.animation 现在需注册 AnimationPlugin 才生效；若之前未注册插件却依赖 meta.animation，需补注册 AnimationPlugin
• 公开 API（createRouter / 导航方法 / 守卫 / 组合式 API 等）签名不变

版本兼容性

功能	v2.6.0	v2.7.0
App 原生窗口动画	支持	支持
H5 push / back CSS 过渡	不支持	支持（animatePageEnter / animatePageExit）
meta.animation 默认动画	导航层读取	router 层注入（需 AnimationPlugin）
getPlatform() 平台判断	支持	支持
onBeforeBack / 返回拦截	支持	支持
完整导航守卫链	支持	支持