0.5.0重磅发布：动画插件+H5体验全面优化

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

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

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

ts 复制代码

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 相对路径导入，现由库入口直接导出：

ts 复制代码

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 升级无需任何改动（无破坏性变更）。按需启用动画：

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

版本兼容性

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

五、相关链接

欢迎反馈与共建：GitHub