@giszhc/vue-page-motion

一个轻量、优雅的 Vue3 路由页面过渡动画组件。

✨ 特性

• 💾 KeepAlive 支持 - 可选的组件缓存，保持页面状态
• 🎯 灵活动画策略 - 支持固定动画、动态函数、route.meta 配置
• 📦 开箱即用 - 内置 slide-left 滑动动画，零配置即可使用
• 🛡️ 类型安全 - 完整 TypeScript 支持
• ⚡ 轻量无依赖 - 仅依赖 Vue 和 Vue Router

在线示例

我们提供了一个功能完整的在线演示页面，您可以直接在浏览器中体验所有功能：

🌐 立即体验： 点击访问在线演示

安装

pnpm install @giszhc/vue-page-motion

使用

方式一：直接引入

import { TransitionRouterView } from '@giszhc/vue-page-motion'
import '@giszhc/vue-page-motion/dist/index.css'

<template>
  <TransitionRouterView />
</template>

<script setup>
import { TransitionRouterView } from '@giszhc/vue-page-motion'
</script>

方式二：插件安装（use）

// main.js
import { createApp } from 'vue'
import App from './App.vue'
import VuePageMotion from '@giszhc/vue-page-motion'
import '@giszhc/vue-page-motion/dist/index.css'

const app = createApp(App)
app.use(VuePageMotion)
app.mount('#app')

<!-- 任意组件中直接使用 -->
<template>
  <TransitionRouterView />
</template>

就这么简单！现在你的应用已经具备了左右滑动的页面过渡效果。

组件参数

• mode：过渡模式，in-out（新元素先进入）或 out-in（旧元素先离开），默认 'out-in'
• wrapperClass：包裹元素的 CSS 类名，默认 'transition-router-view'
• keepAlive：是否启用 KeepAlive 缓存，默认 false
• include：KeepAlive 包含的组件名称（字符串、正则或数组）
• exclude：KeepAlive 排除的组件名称（字符串、正则或数组）
• transition：过渡动画策略
  • 字符串：固定使用指定的过渡名称（支持 'slide-left' | 'slide-right' 或自定义）
  • 函数：根据路由和方向动态返回过渡名称
  • undefined：使用默认的 slide-left 动画

内置动画

组件提供两种内置滑动动画：

• slide-left（默认）：从右向左滑动（新页面从右侧滑入）
• slide-right：从左向右滑动（新页面从左侧滑入）

使用示例

<!-- 默认使用 slide-left -->
<TransitionRouterView />

<!-- 指定使用 slide-right -->
<TransitionRouterView transition="slide-right" />

<!-- 使用 route.meta 覆盖 -->
<!-- 路由配置中设置 meta.transition -->

transition 高级用法

1. 字符串策略 - 固定使用某个动画

<TransitionRouterView transition="slide-left" />

2. 函数策略 - 根据路由和方向动态返回动画

// 根据路由和方向动态返回动画名称
const getTransition = (route, direction) => {
  // direction: 'forward' | 'back'
  if (route.meta.noAnimation) {
    return '' // 禁用动画
  }
  return direction === 'forward' ? 'slide-left' : 'slide-right'
}

<template>
  <TransitionRouterView 
    :keep-alive="true"
    :include="['Home', 'About']"
    :transition="getTransition"
  />
</template>

3. route.meta 优先 - 在路由配置中指定

const routes = [
  {
    path: '/special-page',
    component: SpecialPage,
    meta: { 
      transition: 'slide-right' // 该页面使用特殊动画
    }
  }
]

优先级：route.meta.transition > transition prop > 默认 slide-left