自定义页面
Rspress 提供了多种方式能让你自定义页面的内容,包括:
- 添加自定义全局组件;
- 添加自定义全局样式;
- 自定义页面布局结构。
自定义全局组件
某些场景下,你可能需要在页面中添加一些自定义的全局组件,框架提供了一个配置项 globalUIComponents
来实现这个功能。
使用方法
在 rspress.config.ts
中添加以下配置:
rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';
export default defineConfig({
globalUIComponents: [path.join(__dirname, 'components', 'MyComponent.tsx')],
});
globalUIComponents
的每一项可以是一个字符串,代表组件的文件路径;也可以是一个数组,第一项为组件的文件路径,第二项为组件的 props 对象,比如:
rspress.config.ts
import { defineConfig } from 'rspress/config';
export default defineConfig({
globalUIComponents: [
[
path.join(__dirname, 'components', 'MyComponent.tsx'),
{
foo: 'bar',
},
],
],
});
当你注册了全局组件之后,框架会自动将这些 React 组件在主题中进行渲染,而不用你手动引入。
通过全局组件,你可以完成诸多自定义的功能,比如:
compUi.tsx
import React from 'react';
// 需要默认导出一个组件
// 通过 props 来拿到配置中传入的 props 数据
export default function PluginUI(props?: { foo: string }) {
return <div>This is a global layout component</div>;
}
这样,在主题页面中会渲染组件的内容,比如添加回到顶部按钮。
同时,你也可以通过全局组件来注册全局副作用。比如:
compSideEffect.tsx
import { useEffect } from 'react';
import { useLocation } from 'rspress/runtime';
// 需要默认导出一个组件
export default function PluginSideEffect() {
const { pathname } = useLocation();
useEffect(() => {
// 组件初次渲染时执行
}, []);
useEffect(() => {
// 路由变化时执行
}, [pathname]);
return null;
}
这样,在主题页面中会执行组件的副作用。比如以下的一些需要副作用的场景:
- 针对某些页面路由进行重定向操作。
- 对页面的 img 标签进行事件监听,实现图片放大功能。
- 路由变化时,上报不同页面的 PV 数据。
- ......
自定义样式
某些场景下,你可能需要在主题 UI 的基础上添加一些全局样式,框架提供了一个配置项 globalStyles
来实现这个功能。
使用方法
在 rspress.config.ts
中添加以下配置:
rspress.config.ts
import { defineConfig } from 'rspress/config';
import path from 'path';
export default defineConfig({
globalStyles: path.join(__dirname, 'styles/index.css'),
});
然后可以添加以下代码:
/* styles/index.css */
:root {
--rp-c-brand: #f00;
}
这样框架会自动搜集所有的全局样式并合并到最终的样式文件中。
下面列举一些常用的全局样式:
/* styles/index.css */
:root {
/* 修改主题色 */
--rp-c-brand: #f00;
--rp-c-brand-dark: #ffa500;
--rp-c-brand-darker: #c26c1d;
--rp-c-brand-light: #f2a65a;
--rp-c-brand-lighter: #f2a65a;
/* 修改左侧侧边栏宽度 */
--rp-sidebar-width: 280px;
/* 修改右侧大纲栏宽度 */
--rp-aside-width: 256px;
/* 修改代码块标题背景 */
--rp-code-title-bg: rgba(250, 192, 61, 0.15);
/* 修改代码块内容背景 */
--rp-code-block-bg: rgba(214, 188, 70, 0.05);
}
如果想了解更多内部的全局样式,可以查看 vars.css
Tailwind CSS
要在 Rspress 中使用 Tailwind CSS,你可以按照以下步骤操作:
- 安装 Tailwind CSS:
npm install tailwindcss -D
- 创建一个包含
tailwindcss
插件的 postcss.config.js
文件:
postcss.config.js
module.exports = {
plugins: {
tailwindcss: {},
},
};
- 创建一个
tailwind.config.js
文件,并确保 content
包含了所有使用 Tailwind CSS 的文件:
tailwind.config.js
module.exports = {
content: ['./src/**/*.tsx', './docs/**/*.mdx'],
theme: {
extend: {},
},
plugins: [],
};
- 在你的 CSS 样式文件中添加 Tailwind 指令,参考 自定义样式:
styles/index.css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
请参考官方 Tailwind CSS 文档 了解最新用法。
自定义布局结构
Rspress 提供了 pageType
配置来让你自定义页面的布局结构。
使用 pageType
Rspress 的约定式路由支持了两种路由,一种是文档路由,即用 md(x) 文件编写的页面,另一种是组件路由,即 .jsx/.tsx
文件编写的页面。
对于前者,你可以在 frontmatter 中添加 pageType
字段来指定页面的布局结构,比如:
对于后者,你可以添加如下的导出来指定 pageType
:
foo.tsx
// 导出 frontmatter 对象,其含义与 md(x) 文件中的 frontmatter 一致
export const frontmatter = {
// 声明布局类型
pageType: 'custom',
};
pageType 可以配置为如下的值:
home
: 首页,包含顶部导航栏和首页的布局内容。
doc
: 文档页,包含顶部导航栏、左边侧边栏、正文内容和右侧的大纲栏。
custom
: 自定义页面,包含顶部导航栏和自定义的内容。
blank
: 也属于自定义页面,但是不包含顶部导航栏
。
404
: 404 页面。
使用细粒度开关
除了 pageType
页面布局级别的配置之外,Rspress 还提供了更细粒度的开关,你可以在 frontmatter 配置其它的字段,这些字段及其含义如下:
navbar
:是否展示顶部导航栏,当你想要隐藏顶部导航栏时,可以配置为 false
;
sidebar
:是否展示侧边栏,当你想要隐藏侧边栏时,可以配置为 false
;
outline
:是否展示大纲栏,当你想要隐藏大纲栏时,可以配置为 false
;
footer
:是否展示页脚,当你想要隐藏页脚时,可以配置为 false
;
globalComponents
: 是否展示全局组件,当你想要隐藏全局组件时,可以配置为 false
。
示例:
foo.mdx
---
navbar: false
sidebar: false
outline: false
footer: false
globalUIComponents: false
---
使用 URL 参数开关
除此之外,你还可以使用 URL 参数在运行时控制页面的布局结构,比如:
# 隐藏导航栏和右侧大纲栏
http://YOUR_DOMAIN/foo?navbar=0&outline=0
通过 URL 参数,你可以在不修改源码的情况下,快速地调整页面的布局结构,这些参数具体包括:
navbar
:是否展示导航栏,当你想要隐藏顶部导航栏时,可以配置为 0
;
sidebar
:是否展示侧边栏,当你想要隐藏侧边栏时,可以配置为 0
;
outline
:是否展示大纲栏,当你想要隐藏大纲栏时,可以配置为 0
;
footer
:是否展示页脚,当你想要隐藏页脚时,可以配置为 0
;
globalUIComponents
:是否展示全局组件,当你想要隐藏全局组件时,可以配置为 0
。