vue-page-stack-example

April 8, 2026 · View on GitHub

vue-page-stack 的示例项目，用来演示在 Vue 3 + Vue Router 场景下的页面堆栈缓存效果。

重要说明

本项目只适合移动端场景，不适合桌面端页面或通用后台系统。

项目中的页面布局、交互方式、滚动容器和视觉尺寸都以移动端体验为前提设计，主要适用于：

  • H5 页面
  • Hybrid App WebView
  • 移动端单页应用
  • 微信公众号或类似移动容器

不建议直接用于：

  • PC 管理后台
  • 桌面浏览器优先的业务系统
  • 复杂响应式多栏布局页面

项目目标

这个示例项目主要用于演示以下能力：

  • 基于 vue-router 扩展页面堆栈导航体验
  • 在前进和返回时缓存页面实例
  • 返回上一级页面时保留先前页面状态
  • 支持 push、replace、back、forward 等常见导航行为
  • 展示 vue-page-stack 在移动端导航中的基础接入方式

技术栈

  • Vue 3
  • Vite
  • Vue Router 4
  • Vue I18n
  • Vant
  • BetterScroll
  • vue-page-stack

快速开始

安装依赖

pnpm install

本地开发

pnpm run dev

构建生产版本

pnpm run build

代码检查

pnpm run lint

运行测试

pnpm test

运行端到端测试

pnpm run test:e2e

检查最近一次提交信息

pnpm run commit:check

目录结构

src/
├── assets/          静态资源
├── locales/         国际化文案
├── router/          路由配置
├── views/           页面与页面级组件
│   ├── about/
│   ├── home/
│   ├── index/
│   ├── login/
│   └── main/
├── App.vue          应用壳层
├── i18n.js          国际化初始化
└── main.js          应用入口

页面说明

  • Index：项目介绍页与语言切换入口
  • Home：底部标签页容器页
  • MainList：列表示例页
  • MainDetail：详情页，用于演示页面缓存和导航行为
  • Login：登录页示例
  • About：项目简介页

开发说明

  • 推荐在浏览器移动端模式或真机容器里调试这个项目
  • 这个仓库最核心的验证点是“前进后缓存页面、返回时恢复页面状态”
  • 调整页面结构时，建议优先保留首页、列表页、详情页、登录页之间的示例链路
  • 单元测试使用 Vitest + jsdom，当前主要覆盖语言持久化、标题同步、登录状态和详情页状态组合逻辑
  • 端到端测试使用 Playwright，当前覆盖“首页 -> 列表 -> 详情 -> 登录 -> 返回恢复”这条关键烟雾链路

提交规范

提交信息统一使用：

<type>(<scope>): <subject>

type 使用纯文本，不再带 emoji：

  • init
  • feat
  • fix
  • docs
  • style
  • refactor
  • perf
  • test
  • build
  • ci
  • chore
  • revert

scope 当前限定为：

  • 文档
  • 资源
  • 表现

示例：

fix(表现): 修正详情页当前页码展示
docs(文档): 补充移动端使用限制说明
chore(资源): 清理弃用依赖并升级工具链

推荐验证路径

  1. 进入首页，切换语言，确认首页文案和页面标题同步变化。
  2. 点击“开始体验”进入主页，观察列表卡片文案是否跟随语言变化。
  3. 打开任意详情页，在输入框里输入内容，记录当前页码和激活次数。
  4. 继续 push 到下一页，再返回上一页，确认输入内容和状态卡片仍然保留。
  5. 从详情页进入登录页，输入用户名后返回，确认详情页能显示当前用户。
  6. 在详情页测试 replace、浏览器返回、浏览器前进，确认标题和缓存行为仍然正常。

适用边界

这个仓库是演示项目，目标是帮助理解 vue-page-stack 的接入方式和页面切换效果，因此更强调示例可读性，而不是完整业务工程能力。

如果你要将它用于正式项目，建议至少补充以下内容：

  • 更完整的项目文档
  • 桌面端与移动端适配策略区分
  • 自动化测试
  • 路由元信息和页面标题管理
  • 状态管理与持久化方案

说明

如果你的目标是验证 vue-page-stack 在移动端导航中的表现，这个项目适合作为起点。

如果你的目标是搭建一个同时覆盖移动端和桌面端的通用模板，请不要直接基于这个示例继续扩展。

历史上使用过的 render function 应用壳层方案已经转存到 docs/AppWithRenderFunction.md。

当前页面缓存与状态恢复链路说明见 docs/STATE_FLOW.md。