查看“VuePress客户端配置的使用方法”的源代码


你可以直接在你的项目中使用 客户端配置文件 。或者，在你的插件或者主题中，使用 clientConfigFile Hook 来指定客户端配置文件的路径：

<syntaxhighlight lang="ts">import { getDirname, path } from '@vuepress/utils'

const __dirname = getDirname(import.meta.url)

const pluginOrTheme = {
  clientConfigFile: path.resolve(__dirname, './path/to/clientConfig.ts'),
}</syntaxhighlight>
在客户端配置文件中，<code>@vuepress/client</code> 包提供了一个 defineClientConfig 函数来帮助你定义客户端配置：

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  enhance({ app, router, siteData }) {},
  setup() {},
  layouts: {},
  rootComponents: [],
})</syntaxhighlight>
== enhance ==

<code>enhance</code> 函数既可以是同步的，也可以是异步的。它接收一个 Context 参数，包含以下属性：

* <code>app</code> 是由 [https://staging-cn.vuejs.org/api/application.html#create-app createApp] 创建的 Vue 应用实例。
* <code>router</code> 是由 [https://router.vuejs.org/zh/api/index.html#createrouter createRouter] 创建的路由实例。
* <code>siteData</code> 是一个根据用户配置生成的 Ref 对象，包含 base, lang, title, description, head 和 locales。

<code>enhance</code> 函数会在客户端应用创建后被调用，你可以对 Vue 应用添加各种能力。

<span id="注册-vue-组件"></span>
=== 注册 Vue 组件 ===

你可以通过 [https://staging-cn.vuejs.org/api/application.html#app-component app.component] 方法来注册 Vue 全局组件：

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import MyComponent from './MyComponent.vue'

export default defineClientConfig({
  enhance({ app }) {
    app.component('MyComponent', MyComponent)
  },
})</syntaxhighlight>
<span id="使用不支持-ssr-的功能"></span>
=== 使用不支持 SSR 的功能 ===

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

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

在 <code>enhance</code> 函数中，你可以使用 <code>__VUEPRESS_SSR__</code> 标记来处理这种情况。

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  async enhance() {
    if (!__VUEPRESS_SSR__) {
      const nonSsrFriendlyModule = await import('non-ssr-friendly-module')
      // ...
    }
  },
})</syntaxhighlight>
<span id="使用-router-方法"></span>
=== 使用 Router 方法 ===

你可以使用 vue-router 提供的 [https://router.vuejs.org/zh/api/index.html#router-方法 Router 方法] 。例如，添加导航钩子：

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'

export default defineClientConfig({
  enhance({ router }) {
    router.beforeEach((to) => {
      console.log('before navigation')
    })

    router.afterEach((to) => {
      console.log('after navigation')
    })
  },
})</syntaxhighlight>
<div class="warning">

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

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


</div>
== setup ==

<code>setup</code> 函数会在客户端 Vue 应用的 [https://staging-cn.vuejs.org/api/composition-api-setup.html setup] Hook 中被调用。

<span id="使用组合式-api"></span>
=== 使用组合式 API ===

你可以把 <code>setup</code> 函数当作根组件的 [https://staging-cn.vuejs.org/api/composition-api-setup.html setup] Hook 中的一部分。因此，所有的组合式 API 都可以在这里使用。

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import { provide, ref } from 'vue'
import { useRoute, useRouter } from 'vue-router'

export default defineClientConfig({
  setup() {
    // 获取当前的路由位置
    const route = useRoute()
    // 或者 vue-router 实例
    const router = useRouter()
    // 供给一个值，可以被布局、页面和其他组件注入
    const count = ref(0)
    provide('count', count)
  }
})</syntaxhighlight>
<span id="使用不支持-ssr-的功能-1"></span>
=== 使用不支持 SSR 的功能 ===

在 <code>setup</code> 函数中，<code>__VUEPRESS_SSR__</code> 标记同样可用。

使用不支持 SSR 的功能的另一种方式就是将他们放在 [https://staging-cn.vuejs.org/api/composition-api-lifecycle.html#onmounted onMounted] Hook 中：

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import { onMounted } from 'vue'

export default defineClientConfig({
  setup() {
    onMounted(() => {
      // 在 mounted 之后使用 DOM API
      document.querySelector('#app')
    })
  }
})</syntaxhighlight>
== layouts ==

<code>layouts</code> 配置项用于设置布局组件。你在此处注册布局后，用户就可以通过 layout frontmatter 来使用它们。

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import MyLayout from './layouts/MyLayout.vue'

export default defineClientConfig({
  layouts: {
    MyLayout,
  },
})</syntaxhighlight>
<span id="rootcomponents"></span>
== rootComponents ==

<code>rootComponents</code> 是一个组件数组，它们将会直接被放置在客户端 Vue 应用的根节点下。

该选项的典型使用方式就是放置一些全局的 UI 组件，比如全局弹窗等：

<syntaxhighlight lang="ts">import { defineClientConfig } from '@vuepress/client'
import GlobalPopup from './components/GlobalPopup.vue'

export default defineClientConfig({
  rootComponents: [GlobalPopup],
})</syntaxhighlight>