v0.5.0 为 MINOR 版本，核心能力是新增 AnimationPlugin 导航窗口动画插件（App / 小程序透传原生动画、H5 用 Web Animations API 实现），并附带两处 H5 动画体验修复（首次进入卡顿、返回动画不生效）与查询参数工具的公共导出。本版本无破坏性变更。

一、新增：AnimationPlugin 导航窗口动画插件

为导航注入窗口过渡动画，对齐 uni-app x 原生 animationType：

import { createRouter, AnimationPlugin } from '@meng-xi/unix-router'

const router = createRouter({
  routes,
  plugins: [AnimationPlugin],
  animation: { type: 'slide-in-right', duration: 300 } // 全局默认动画（可选）
})

// 单次覆盖：本次导航使用 fade-in
router.push({ path: 'pages/detail/detail', animationType: 'fade-in', animationDuration: 500 })

跨端实现

平台	实现方式
App / 小程序	透传 animationType / animationDuration 给 uni.* 原生导航 API（原生窗口动画）
H5	通过 Web Animations API（element.animate）播放进入 / 退出动画，无需 CSS @keyframes（遵守项目 CSS 规则）

动画类型

slide-in-right / slide-in-left / slide-in-top / slide-in-bottom / fade-in / zoom-in / zoom-fade-in / pop-in / auto / none。

• back() 使用全局默认动画作为关闭动画（back 无 location 可传，单次覆盖仅对前向导航有效）；
• 未注册插件时携带 animationType 的导航仍正常执行（动画被忽略）；
• H5 端依赖核心新增的 onBeforeNavigation 异步钩子：返回时会先播完退出动画再真正 navigateBack。

二、修复：H5 动画体验

1. 首次进入二级页面动画卡顿

根因：onCompleteNavigation 回调触发时，uni-app x H5 已把新页内容替换进 uni-page（data-page 已切换），但旧实现等 rAF 动画第一帧才把元素跳到 translateX(100%)。页面在原位静止显示 1-2 帧后再跳向屏幕外滑入，造成「内容闪现后再滑一次」的割裂感（观感卡顿）。

修复：onCompleteNavigation 内同步应用动画起点样式（如 transform: translateX(100%)）+ 强制 reflow，让新页渲染首帧即位于屏幕外，再于下一帧播放滑入动画；动画结束后清理内联起点样式，避免残留注入影响后续 back 的退出动画起始帧。

2. H5 返回动画不生效

根因：back 时以进入型动画类型（如 slide-in-right）查找退出关键帧表，查不到 → 静默不播。

修复：新增 toExitType() 映射（进入型 → 退出型，如 slide-in-right → slide-out-right），退出动画得以正确播放。

三、新增：查询参数工具公共导出

queryInt() / queryNumber() / queryBool() 此前仅能从 utils/query.uts 相对路径导入，现由库入口直接导出：

import { queryInt, queryNumber, queryBool, useRoute } from '@meng-xi/unix-router'

const route = useRoute()
const idNum = queryInt(route.query, 'id', 0)     // 便捷解析数值
const flag  = queryBool(route.query, 'vip', false) // 便捷解析布尔

四、升级指南

从 ≤0.4.x 升级无需任何改动（无破坏性变更）。按需启用动画：

1. 注册插件并（可选）配置全局默认动画：plugins: [AnimationPlugin] + animation: { type, duration }；
2. 单次覆盖：导航位置对象携带 animationType / animationDuration。

版本兼容性

功能	≤0.4.x	0.5.0
导航动画	❌	✅ AnimationPlugin（跨端）
animation / animationType 选项	❌	✅
H5 back 退出动画	❌	✅
queryInt 等工具	仅相对路径	✅ 公共导出

五、相关链接

• 更新日志
• AnimationPlugin 文档
• 安装文档

欢迎反馈与共建：GitHub