stack-router-vue3

Vue3 栈式路由 - 仿原生APP的页面栈管理，专为移动端H5设计。

✨ 特性

• 🎯 原生体验 - 完全仿照原生APP的页面栈管理方式
• 🎨 自定义动画 - 支持自定义页面切换动画
• 🔄 生命周期钩子 - 提供 onViewShow / onViewHide 生命周期
• 📦 轻量级 - 核心代码简洁，仅依赖 lodash-es
• 💪 TypeScript - 完整的 TypeScript 类型支持
• 🚀 Vue3 组合式API - 完美适配 Vue3 Composition API
• 📱 移动端优化 - 专为移动端 H5 和 WebView 场景设计

📦 安装

npm install stack-router-vue3
# 或
yarn add stack-router-vue3
# 或
pnpm add stack-router-vue3

🚀 快速开始

1. 创建路由配置

// router.ts
import { createStackRouter } from 'stack-router-vue3'

const router = createStackRouter([
  {
    name: 'home',
    component: () => import('./pages/Home.vue'),
    meta: { title: '首页' }
  },
  {
    name: 'detail',
    component: () => import('./pages/Detail.vue'),
    meta: { title: '详情' }
  }
], {
  // 可选：自定义动画类名
  defaultAnimation: {
    enter: 'slide-in',
    leave: 'slide-out'
  }
})

export default router

2. 注册路由插件

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import router from './router'

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

3. 使用路由容器

<!-- App.vue -->
<template>
  <StackRouter />
</template>

<script setup>
import { onMounted } from 'vue'
import { useStackRouter } from 'stack-router-vue3'

const router = useStackRouter()

onMounted(() => {
  // 打开首页
  router.push('home')
})
</script>

4. 在页面中使用

<!-- pages/Home.vue -->
<template>
  <div class="page">
    <h1>首页</h1>
    <button @click="goToDetail">查看详情</button>
  </div>
</template>

<script setup lang="ts">
import { useStackRouter, onViewShow, onViewHide } from 'stack-router-vue3'

const router = useStackRouter()

const goToDetail = () => {
  router.push('detail', { id: 123 })
}

// 页面显示时触发
onViewShow(() => {
  console.log('页面显示')
})

// 页面隐藏时触发
onViewHide(() => {
  console.log('页面隐藏')
})
</script>

<!-- pages/Detail.vue -->
<template>
  <div class="page">
    <button @click="goBack">返回</button>
    <h1>详情页</h1>
    <p>接收参数: {{ props.data }}</p>
  </div>
</template>

<script setup lang="ts">
import { useStackRouter } from 'stack-router-vue3'

interface Props {
  data?: any
}

const props = defineProps<Props>()
const router = useStackRouter()

const goBack = () => {
  // 返回上一页，可以传递数据
  router.back({ result: 'success' })
}
</script>

📖 API 文档

createStackRouter(routes, options?)

创建路由实例。

参数：

• routes: RouteConfig[] - 路由配置数组
• options: RouterOptions - 路由选项（可选）

RouteConfig:

interface RouteConfig {
  name: string                    // 路由名称（唯一标识）
  component: Component | Lazy     // 页面组件
  meta?: Record<string, any>      // 自定义元信息
}

RouterOptions:

interface RouterOptions {
  defaultAnimation?: {
    enter: string    // 进入动画类名
    leave: string    // 离开动画类名
  }
}

useStackRouter()

在组件中获取路由实例（组合式API）。

const router = useStackRouter()

路由方法

router.push(name, data?)

打开新页面。

// 基础用法
router.push('detail')

// 携带参数
router.push('detail', { id: 123, title: '商品' })

// 等待页面返回数据
const result = await router.push('detail', { id: 123 })
result?.wait((data) => {
  console.log('详情页返回的数据:', data)
})

router.back(data?, step?)

返回上一页。

// 返回上一页
router.back()

// 返回并传递数据
router.back({ result: 'success' })

// 返回多页
router.back(undefined, 2)  // 返回2页

router.replace(name, data?)

替换当前页面。

// 替换为新页面
router.replace('login')

// 携带参数
router.replace('login', { from: 'expired' })

router.flush(name, data?, count?)

清空页面栈并跳转。

// 清空所有页面并跳转到首页
router.flush('home')

// 清空最后2页并跳转
router.flush('home', {}, 2)

router.getLength()

获取当前页面栈深度。

const length = router.getLength()
console.log('当前栈深度:', length)

生命周期钩子

onViewShow(callback)

页面显示时触发（包括首次显示和从其他页面返回）。

import { onViewShow } from 'stack-router-vue3'

onViewShow(() => {
  console.log('页面显示了')
  // 适合：刷新数据、启动定时器等
})

onViewHide(callback)

页面隐藏时触发（被其他页面覆盖或移出视图）。

import { onViewHide } from 'stack-router-vue3'

onViewHide(() => {
  console.log('页面隐藏了')
  // 适合：清理定时器、暂停动画、取消请求等
})

🎨 自定义动画

库内置了默认的滑动动画，你可以通过CSS自定义动画效果：

<style>
/* 页面容器默认样式 */
.stack-router-container {
  position: absolute;
  width: 100%;
  height: 100%;
  transition: transform 0.3s ease;
}

/* 进入动画 */
.slide-in {
  transform: translateX(100%);
}

/* 离开动画 */
.slide-out {
  transform: translateX(100%);
}

/* 自定义动画示例 */
.fade-in {
  opacity: 0;
  transition: opacity 0.3s;
}
</style>

🔧 适用场景

• 📱 移动端 H5 单页应用
• 🔌 嵌入原生 APP 的 WebView
• 🎯 需要原生般页面栈体验的场景
• 📦 小程序 H5 页面

⚠️ 注意事项

1. 页面组件结构：每个页面组件应该有独立的根元素
2. 数据传递：通过 props.data 接收页面参数
3. 生命周期：onViewShow/onViewHide 只在页面组件中使用
4. 动画时长：确保 CSS 动画时长与 transitionend 事件匹配

📝 完整示例

查看 /examples 目录获取完整的示例代码，包括：

• 基础路由功能 - Home.vue, Detail.vue, List.vue
• 原生交互示例 - Native.vue
• 工具类 - native.ts, query.ts, eventBus.ts
• 初始化逻辑 - App.vue 中的 URL 参数处理

原生交互功能

本库特别适合嵌入到原生 APP 的 WebView 中使用。示例提供了完整的原生交互方案：

// 与原生通信
import native from './examples/utils/native'

// 调用原生方法
await native.call('commandName', { data: 'value' })

// 监听应用生命周期
import eventBus, { Events } from './examples/utils/eventBus'
eventBus.on(Events.APP_SHOW, () => {
  console.log('应用从后台恢复')
})

// URL 参数初始化
import query from './examples/utils/query'
query.init()
const page = query.get('page')

详见 examples/NATIVE_INTEGRATION.md

运行示例：

git clone https://github.com/你的用户名/stack-router-vue3.git
cd stack-router-vue3
npm install
npm run dev

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT

🙏 致谢

感谢所有贡献者的付出！