Skip to main content

自定义组件

初始化的一个 docusaurus 项目就已经有预留好的的组件,例如博客布局,标签页归档页等等。但是这些组件的样式可能不满你的审美,或者是想增加在这些主题组件中增加点东西。那么就需要用到 Swizzle

主题组件

在 docusaurus 中的主题组件存放在 @docusaurus/theme-classic/theme 下,如果想要覆盖某个组件的话可以在 src/theme 目录下创建与之对应文件路径结构相同的文件。

像下面这样

website
├── node_modules
│ └── @docusaurus/theme-classic
│ └── theme
│ └── Navbar.js
└── src
└── theme
└── Navbar.js

每当导入 @theme/Navbar 时,website/src/theme/Navbar.js 都会被优先载入。

关于分层架构可看客户端架构 | Docusaurus

swizzle 组件

要输出所有 @docusaurus/theme-classic 组件的总览,可以运行:

yarn run swizzle @docusaurus/theme-classic -- --list

不过我更倾向于直接在 node_modules/@docusaurus/theme-classic/src/theme 查看所有组件。

这里以归档页举例,官方的归档页面组件是 theme/BlogArchivePage

有两种方式可以完成自定义组件:弹出组件或者包装组件

例如弹出组件,可以执行以下命令

yarn run swizzle @docusaurus/theme-classic BlogArchivePage -- --eject --typescript

这样会创建 src/theme/BlogArchivePage/index.tsx,也就是归档页面的代码,而要做的就是修改代码,实现自己所需的样式与功能。

不过这样获取到的只是 index.tsx 文件,有可能还存在子组件。所有我一般的做法是在 node_modules/@docusaurus/theme-classic/src/theme 中找到组件所在文件夹,然后将整个文件夹复制到 src/theme 下。这样能得到就是最原始的 ts 文件,同时所能修改的地方也就越多,更方便的个性化。

warning

但是,在使用自定义组件的时候,有些主题组件可能会存在一定风险。尤其是在升级 Docusaurus 变得更困难,因为如果接收的属性发生变化,或内部使用的主题 API 发生变化,有可能就会导致页面渲染失败。

就比如我在将 docusaurus 升级到 2.0.0 正式版的时候就出现页面错误,原因是 plugin-content-blog 在传递给组件的数据发生了变动,导致数据无法解析,自然而然页面就渲染失败。

如果不升级依赖也确实不会有问题,但谁能保证新版本的一些特性不吸引使用者去升级呢?所以在自定义组件的时候,升级依赖后就可能需要维护一定的代码。要做的是重新 swizzle 一份最新的文件,然后去比对变化,最终排查问题。