Client App Enhance 的使用方法

Plugin API 提供的 clientAppEnhanceFiles Hook 允许你设置 Client App Enhance 文件的路径。你可以在你的插件或者主题中使用它:

  1. const pluginOrTheme = {
  2. clientAppEnhanceFiles: path.resolve(__dirname, './path/to/clientAppEnhance.ts'),
  3. }

然后,创建 clientAppEnhance.ts 文件。你可以使用 defineClientAppEnhance Helper 来获取类型提示。注意这个函数既可以是同步的,也可以是异步的。

  1. import { defineClientAppEnhance } from '@vuepress/client'
  2. export default defineClientAppEnhance(({ app, router, siteData }) => {
  3. // ...
  4. })

Client App Enhance 会在客户端应用创建后被调用,它可以为 Vue 应用添加任意功能。

提示

为了方便用户配置使用, .vuepress/clientAppEnhance.{js,ts} 文件会被隐式地用作 Client App Enhance 文件,除非你在配置文件中显式设置了 clientAppEnhanceFiles

注册 Vue 组件

你可以通过 componentClient App Enhance 的使用方法 - 图3在新窗口打开 方法来注册 Vue 全局组件:

  1. import { defineClientAppEnhance } from '@vuepress/client'
  2. import MyComponent from './MyComponent.vue'
  3. export default defineClientAppEnhance(({ app, router, siteData }) => {
  4. app.component('MyComponent', MyComponent)
  5. })

使用不支持 SSR 的功能

VuePress 会在构建过程中生成一个 SSR 应用,用以对页面进行预渲染。一般而言,如果一段代码在客户端应用 Mount 之前就使用了浏览器或 DOM API ,我们就认为其对 SSR 不友好,即不支持 SSR 。

我们已经提供了一个 ClientOnly 组件来包裹不支持 SSR 的内容。

在 Client App Enhance 文件中,你可以使用 __SSR__ 标记来处理这种情况。

  1. import { defineClientAppEnhance } from '@vuepress/client'
  2. export default defineClientAppEnhance(async ({ app, router, siteData }) => {
  3. if (!__SSR__) {
  4. const nonSsrFriendlyModule = await import('non-ssr-friendly-module')
  5. // ...
  6. }
  7. })

使用 Router 方法

你可以使用 vue-router 提供的 Router 方法Client App Enhance 的使用方法 - 图4在新窗口打开 。例如,添加导航钩子:

  1. import { defineClientAppEnhance } from '@vuepress/client'
  2. export default defineClientAppEnhance(({ app, router, siteData }) => {
  3. router.beforeEach((to) => {
  4. console.log('before navigation')
  5. })
  6. router.afterEach((to) => {
  7. console.log('after navigation')
  8. })
  9. })

注意

我们不推荐使用 addRoute 方法来添加动态路由,因为这些路由记录 不会 在构建模式中被预渲染出来。

当然,如果你了解了这种用法的缺点,你还是可以这样使用。