# 主题的继承
# 动机
我们有两个主要的理由来支持这个特性:
VuePress 为开发者提供了一个默认主题,它能在大多数场景下满足了文档编写者的需求。即便如此,仍然还是会有不少用户选择将其 eject 出来进行修改,即使他们可能只是想要修改其中的某个组件。
在 0.x (opens new window) 中,主题的入口只需要一个
Layout.vue
,所以我们可以通过包装另一个主题的Layout.vue
来实现简单的拓展。到了 1.x 中,一个主题的元素开始变得复杂,我们开始有了主题级别的配置,它支持为主题添加插件、自定义 GlobalLayout 等。除此之外,我们还有一些引入了主题开发的 目录结构的约定,如
styles/index.styl
,在这样的背景下,我们无法使用 0.x 的方式来实现继承了。
因此,我们需要提供一种合理、可靠的主题继承方案。
# 概念
为了介绍本节,我们先几个基本概念:
- 原子主题:即父主题,类似默认主题这种完全从头实现的主题。
- 派生主题:即子主题,基于父主题创建的主题;
提示
主题继承暂时不支持高阶继承,也就是说,一个派生主题无法被继承。
# 使用
假设你想创建一个继承自 VuePress 默认主题的派生主题,你只需要在你的主题配置中配置 extend 选项:
// .vuepress/theme/index.js
module.exports = {
extend: '@vuepress/theme-default'
}
# 继承策略
父主题的所有能力都会"传递"给子主题,对于文件级别的约定,子主题可以通过在同样的位置创建同名文件来覆盖它;对于某些主题配置选项,如 globalLayout,子主题也可以通过同名配置来覆盖它。
文件级别的约定如下:
- 全局组件,即放置在
theme/global-components
中的 Vue 组件。 - 组件,即放置在
theme/components
中的 Vue 组件。 - 全局的样式和调色板,即放置在
theme/styles
中的index.styl
和palette.styl
。 - HTML 模板,即放置在
theme/templates
中的dev.html
和ssr.html
。 - 主题水平的客户端增强文件,即
theme/enhanceApp.js
对于主题配置,能被子主题覆盖的配置选项如下:
无法被子主题覆盖的主题配置选项如下:
需要特殊处理的主题选项:
# 插件的覆盖
对于父主题中的 plugins, 子主题不会直接覆盖它,但是插件的选项可以通过创建同名的插件配置来覆盖。
举例来说,如果父主题具有如下配置:
// parentThemePath/index.js
module.exports = {
plugins: [
['@vuepress/search', {
searchMaxSuggestions: 5
}]
]
}
那么子主题可以通过如下方式来修改该插件的默认值:
// .vuepress/theme/index.js
module.exports = {
plugins: [
['@vuepress/search', {
searchMaxSuggestions: 10
}]
]
}
也可以选择禁用它:
// .vuepress/theme/index.js
module.exports = {
plugins: [
['@vuepress/search', false]
]
}
注意
一般情况下,你都不需要这样做,除非你明确知道禁用父主题中的插件不会带来问题。
# 组件的覆盖
你可能想要在子主题中覆盖父主题中的同名组件,默认情况下,当父主题中的组件都使用相对路径引用其他组件时,你将不可能做到这一点,因为你无法在运行时修改父主题的代码。
VuePress 则通过一种巧妙的方式实现了这种需求,但这对父主题有一定的要求——所有的组件都必须使用 @theme
别名来引用其他组件。
举例来说,如果你正在开发的一个原子主题的结构如下:
theme
├── components
│ ├── Home.vue
│ ├── Navbar.vue
│ └── Sidebar.vue
├── layouts
│ ├── 404.vue
│ └── Layout.vue
├── package.json
└── index.js
那么,在该主题中的任意 Vue 组件中,你都应该通过 @theme
来访问主题根目录:
<script>
import Navbar from '@theme/components/Navbar.vue'
// ...
</script>
在这样的前提下,当你在子主题中同样的位置创建一个 Navbar
组件时:
theme
└── components
└── Navbar.vue
@theme/components/Navbar.vue
会自动地映射到子主题中的 Navbar 组件,当你移除这个组件时,@theme/components/Navbar.vue
又会自动恢复为父主题中的 Navbar 组件。
如此一来,就可以实现轻松地“篡改”一个原子主题的某个部分。
提示
- 组件的覆盖,最好直接基于父主题中对应组件的代码来修改;
- 目前,在本地开发子主题,每次创建或移除组件时,你需要手动重启 Dev Server。
# 访问父主题
你可以使用 @parent-theme
来访问父主题的根路径,下述示例展示了在子主题中创建一个同名的布局组件,并简单使用父主题中的 slot,@vuepress/theme-vue (opens new window) 便是通过这种方式创造的。
<!-- .vuepress/theme/components/Foo.vue -->
<template>
<ParentLayout>
<Foo #foo/>
</ParentLayout>
</template>
<script>
import ParentLayout from '@parent-theme/layouts/Layout.vue'
import Foo from '@theme/components/Foo.vue'
export default {
components: {
ParentLayout,
Foo
}
}
</script>