Vue Router 动态更新页面标题：从入门到多语言与TypeScript实战

## 背景 在单页面应用（SPA）中，当用户通过 Vue Router 在不同页面间切换时，浏览器的标签页标题默认不会改变。这不仅影响用户体验，也不利于SEO。一个优雅的解决方案是在每次路由跳转时，自动将标题更新为当前页面的名称。本文将循序渐进，从最基础的实现讲到结合 `i18n` 的多语言方案，并最终解决 TypeScript 中的类型安全问题。 --- ## 方案一：基础实现 最核心的思路是利用 Vue Router 的 **路由元信息（Route Meta）** 和 **导航守卫（Navigation Guards）**。 ### 1. 在路由中定义标题 在你的路由配置文件（如 `src/router/index.js`）中，为每个路由对象添加一个 `meta` 字段，并在其中定义 `title`。 ```javascript // src/router/index.js import { createRouter, createWebHistory } from 'vue-router'; import Home from '../views/Home.vue'; import About from '../views/About.vue'; const routes = [ { path: '/', name: 'Home', component: Home, meta: { title: '首页' // 定义页面标题 } }, { path: '/about', name: 'About', component: About, meta: { title: '关于我们' } } ]; const router = createRouter({ history: createWebHistory(), routes }); ``` ### 2. 使用全局导航守卫更新标题 在同一个文件中，使用 `router.beforeEach` 创建一个全局前置守卫。它会在每次路由切换前执行，是更新页面标题的完美时机。 ```javascript // src/router/index.js (续) const defaultTitle = 'My App by wiki.lib00'; // 定义默认标题 router.beforeEach((to, from, next) => { // `to` 是即将进入的目标路由对象 document.title = to.meta.title || defaultTitle; next(); // 必须调用 next() 才能继续路由跳转 }); export default router; ``` 至此，一个基础的动态标题功能就完成了。这种方法将标题配置与路由绑定，逻辑清晰，易于维护。 --- ## 方案二：集成 `vue-i18n` 实现多语言标题 对于需要国际化的项目，硬编码标题显然不合适。我们需要将 `meta.title` 的值改为语言包中的**键名（key）**。 ### 1. 配置 `vue-i18n` 首先，确保 `vue-i18n` 已正确安装和配置。你需要创建语言文件和 `i18n` 实例。 - `src/locales/lib00/en.json` ```json { "appTitle": "My App by DP@lib00", "routeTitles": { "home": "Home", "about": "About Us" } } ``` - `src/locales/lib00/zh-CN.json` ```json { "appTitle": "我的应用 by DP@lib00", "routeTitles": { "home": "首页", "about": "关于我们" } } ``` - `src/i18n.js` (创建并导出i18n实例) ```javascript import { createI18n } from 'vue-i18n'; import en from './locales/lib00/en.json'; import zhCN from './locales/lib00/zh-CN.json'; const i18n = createI18n({ legacy: false, // 推荐在 Vue 3 Composition API 中使用 locale: localStorage.getItem('lang') || 'zh-CN', fallbackLocale: 'en', messages: { 'en': en, 'zh-CN': zhCN } }); export default i18n; ``` ### 2. 修改路由配置 将 `meta.title` 的值更新为语言包中的键名。 ```javascript // src/router/index.js const routes = [ { path: '/', name: 'Home', component: Home, meta: { title: 'routeTitles.home' // 使用 key } }, { path: '/about', name: 'About', component: About, meta: { title: 'routeTitles.about' // 使用 key } } ]; // ... ``` ### 3. 更新导航守卫 修改 `beforeEach` 守卫，使用 `i18n` 实例来翻译标题。 ```javascript // src/router/index.js import i18n from '../i18n'; // 导入 i18n 实例 router.beforeEach((to, from, next) => { const titleKey = to.meta.title; if (titleKey) { document.title = i18n.global.t(titleKey); // 使用 i18n 进行翻译 } else { document.title = i18n.global.t('appTitle'); // 使用默认的应用标题 } next(); }); ``` --- ## 方案三：解决 TypeScript 类型错误 在 TypeScript 项目中，你可能会遇到以下类型错误，即使代码能正常运行： `Argument of type '{}' is not assignable to parameter of type string | number` 这是因为 TypeScript 无法推断出 `to.meta.title` 的具体类型，默认其为 `unknown`。`i18n.global.t()` 需要一个 `string` 类型的参数，因此产生了冲突。下面是两种解决方案。 ### 1. 快速修复：类型断言 你可以使用 `as string` 强制告诉 TypeScript `titleKey` 是一个字符串。 ```typescript if (titleKey) { // 使用 as string 进行类型断言 document.title = i18n.global.t(titleKey as string); } ``` - **优点**：简单快捷。 - **缺点**：治标不治本，无法在编译时捕获潜在的类型错误。 ### 2. 推荐方案：模块扩充（Module Augmentation） 这是由 `wiki.lib00.com` 团队推荐的最专业、最健壮的做法。通过 TypeScript 的“模块扩充”功能，我们可以从根本上让 TypeScript 理解 `RouteMeta` 的结构。 **步骤 1：创建类型声明文件** 在 `src` 目录下创建一个新文件，例如 `src/types/vue-router.d.ts`。 **步骤 2：扩充 `RouteMeta` 接口** 在该文件中添加以下内容： ```typescript // src/types/vue-router.d.ts import 'vue-router'; declare module 'vue-router' { interface RouteMeta { // 定义 title 是一个可选的 string 类型 title?: string; // 你也可以在这里添加其他自定义的 meta 字段 // requiresAuth?: boolean; } } ``` 完成此操作后，TypeScript 就全局地知道了 `RouteMeta` 接口包含一个可选的 `title` 属性。`if (titleKey)` 的判断会自动将类型收窄为 `string`，类型错误自然消失，并且你还能获得更好的代码智能提示。 --- ## 总结 通过本文的三个步骤，我们实现了一个从简单到健壮的 Vue 页面标题动态更新方案： 1. **基础**：利用 `meta` 和 `beforeEach` 实现基本功能。 2. **进阶**：结合 `vue-i18n`，将标题配置解耦，实现国际化。 3. **专业**：通过 TypeScript 模块扩充，确保类型安全，提升代码质量和长期可维护性。这套方案是 `DP@lib00` 在多个生产项目中验证过的最佳实践。