reveal.js 主题定制指南:基于 Sass 模板体系创建与编译自定义主题
reveal.js 主题定制指南:基于 Sass 模板体系创建与编译自定义主题
本篇指南聚焦 reveal.js 的主题(Theme)体系,围绕 css/theme/README.md 的官方说明,系统讲解主题的 Sass 组织方式、模板文件结构与 npm run build:styles 编译流程,并结合仓库源码与内置主题,手把手演示如何复制一个 .scss 文件、覆写样式变量并产出可发布的 CSS 主题文件。
一、主题与 Sass:为什么主题要用 Sass 编写
reveal.js 的主题文件全部以 Sass(SCSS 语法)编写,存放于仓库的 css/theme 目录。官方 README 给出的理由是:使用 Sass 可以保持主题的模块化(modular),并减少跨文件重复书写选择器(reduce the need for repeated selectors across files)。
这一点从目录结构可以得到印证:所有主题共享同一套模板,差异只体现在变量覆写上。例如 css/theme/black.scss 与 css/theme/league.scss 都只是先 @use 'template/settings' with (...) 覆写一组变量,再 @use 'template/theme' 引入同一份模板,最终编译出风格迥异的成品 CSS。
因此,在动手写主题之前,需要先满足依赖条件:
依赖要求:主题编译依赖 reveal.js 的开发环境(Sass 编译器与 Vite 构建工具链)。官方 README 明确要求先完成 reveal.js 的完整开发环境安装(full setup)后再进行主题开发。对应地,package.json 的
devDependencies中声明了sass(^1.98.0)与vite(^8.0.16)等依赖,仓库根目录的npm install即可一次性就绪。
二、创建主题的两种方式与自动编译机制
2.1 核心操作:复制 .scss 文件
根据 css/theme/README.md,创建自定义主题的推荐方式是:
- 在 css/theme 目录下复制一个已有的
.scss主题文件作为起点(例如black.scss); - 按需修改其中的变量与样式;
- 运行
npm run build:styles,Sass 会自动将其编译为对应的 CSS 文件。
2.2 自动编译机制:vite.config.styles.ts
README 特别指出,编译由 vite.config.styles.ts 驱动。查看该构建配置,可以看清"自动编译"的底层原理:
// vite.config.styles.ts(节选)
const themeFiles = fs
.readdirSync(resolve(__dirname, 'css/theme'))
.filter((file) => file.endsWith('.scss'));
const themeEntries = themeFiles.reduce((acc, file) => {
acc[`theme/${file.replace('.scss', '')}`] = resolve(__dirname, `css/theme/${file}`);
return acc;
}, {});
也就是说,构建脚本会扫描 css/theme 目录下所有以 .scss 结尾的文件,并逐一注册为构建入口,输出到 dist/theme/<文件名>.css。这意味着:只要把新的 .scss 文件放进 css/theme 目录,npm run build:styles 就会自动发现并编译它,无需修改任何构建配置。
对应的 npm 脚本在 package.json 中定义:
"build:styles": "vite build -c vite.config.styles.ts"
构建产物可通过 package.json 的 exports 字段按 ./theme/* 映射到 ./dist/theme/*,因此发布包后使用者可以直接以 dist/theme/<名称>.css 的方式引用你的主题。
2.3 在演示页中切换主题
编译完成后,主题 CSS 通过 <link> 标签引入。以仓库根目录的 index.html 为例:
<link rel="stylesheet" href="dist/reset.css" />
<link rel="stylesheet" href="dist/reveal.css" />
<link rel="stylesheet" href="dist/theme/black.css" />
将 dist/theme/black.css 替换为 dist/theme/<你的主题名>.css,即可在演示文稿中启用新主题。
三、主题文件的四段式标准结构
官方 README 明确给出每个主题文件遵循的同一套结构,共四步。下面逐一结合源码拆解。
第 1 步:引入 mixins.scss(共享工具函数)
@use 'template/mixins' as mixins;
css/theme/template/mixins.scss 提供了两个核心 mixin,专门处理浅色/深色幻灯片背景下的文字颜色适配:
// 浅色背景幻灯片:将文字(含各级标题)强制设为指定颜色
@mixin light-bg-text-color($color) {
section.has-light-background {
&, h1, h2, h3, h4, h5, h6 {
color: $color;
}
}
}
// 深色背景幻灯片:同上,针对 has-dark-background
@mixin dark-bg-text-color($color) {
section.has-dark-background {
&, h1, h2, h3, h4, h5, h6 {
color: $color;
}
}
}
在深色主题中通常会调用 light-bg-text-color,例如 css/theme/black.scss 末尾的 @include mixins.light-bg-text-color(#222);——当某一页幻灯片设置了浅色背景(.has-light-background)时,正文与标题会自动切换为深色,保证可读性;反之,浅色主题(如 css/theme/solarized.scss)则调用 @include mixins.dark-bg-text-color(#fff);。
第 2 步:引入 settings.scss(声明可覆写的变量)
@use 'template/settings' with ( ...覆写... );
css/theme/template/settings.scss 是主题的变量中枢。它声明了模板(第 4 步的 theme.scss)所依赖的全部自定义变量,且每个变量都带 !default 标记,意味着任何覆写都会优先生效,未覆写的变量回落到默认值。
变量分为以下几组,同时覆盖背景、正文、标题、代码、链接、选区与浮层 UI:
| 分组 | 变量 | 默认值 | 说明 |
|---|---|---|---|
| 背景 | $background |
#2b2b2b |
展示区背景(可设为渐变,如 league 主题) |
| 背景 | $background-color |
#bbb |
打印等场景的背景色 |
| 正文 | $main-font |
'Lato', sans-serif |
主字体栈 |
| 正文 | $main-font-size |
40px |
正文字号 |
| 正文 | $main-color |
#eee |
正文颜色 |
| 间距 | $block-margin |
20px |
文本块之间的垂直间距 |
| 标题 | $heading-margin |
0 0 20px 0 |
标题外边距 |
| 标题 | $heading-font |
'League Gothic', Impact, sans-serif |
标题字体 |
| 标题 | $heading-color |
#eee |
标题颜色 |
| 标题 | $heading-line-height |
1.2 |
标题行高 |
| 标题 | $heading-letter-spacing |
normal |
标题字距 |
| 标题 | $heading-text-transform |
uppercase |
标题大小写转换 |
| 标题 | $heading-text-shadow |
none |
标题文字阴影 |
| 标题 | $heading-font-weight |
normal |
标题字重 |
| 标题 | $heading1-text-shadow |
none |
H1 专属阴影 |
| 标题 | $heading1-size |
3.77em |
H1 字号 |
| 标题 | $heading2-size |
2.11em |
H2 字号 |
| 标题 | $heading3-size |
1.55em |
H3 字号 |
| 标题 | $heading4-size |
1em |
H4 字号 |
| 代码 | $code-font |
monospace |
代码字体 |
| 链接 | $link-color |
#13daec |
链接颜色 |
| 链接 | $link-color-dark |
链接色暗化 15% | 滚动翻转等暗色场景 |
| 链接 | $link-color-hover |
链接色提亮 20% | 悬停颜色 |
| 选区 | $selection-background-color |
#0fadbb |
文本选中背景 |
| 选区 | $selection-color |
#fff |
文本选中颜色 |
| 浮层 | $overlay-element-bg-color |
240, 240, 240 |
覆盖 UI 的背景(RGB 三元组) |
| 浮层 | $overlay-element-fg-color |
0, 0, 0 |
覆盖 UI 的前景(RGB 三元组) |
该文件最关键的机制在于文件末尾:它把所有 SCSS 变量以 CSS 自定义属性(Custom Properties)的形式暴露到 :root,命名统一为 --r- 前缀,例如 --r-background、--r-main-font、--r-heading1-size、--r-link-color、--r-selection-background-color 等。这一层转换是模板得以工作的桥梁——模板只消费这些 var(--r-*),而具体值由主题的变量覆写决定。
第 3 步:引入 theme.scss(模板生成最终 CSS)
@use 'template/theme';
css/theme/template/theme.scss 是所有主题共用的模板文件,负责根据当前变量生成最终 CSS 输出。它本身不写死任何颜色或字体,全部通过 var(--r-*) 引用:
- 全局样式:
.reveal-viewport使用var(--r-background)与var(--r-background-color)作为背景;.reveal使用var(--r-main-font)、var(--r-main-font-size)、var(--r-main-color)定义正文; - 标题体系:
.reveal h1 ~ h4统一消费--r-heading-*系列变量,其中 H1~H4 的字号分别对应--r-heading1-size~--r-heading4-size; - 其他元素:段落间距(
--r-block-margin)、代码(--r-code-font)、链接(--r-link-color/--r-link-color-hover/--r-link-color-dark)、选区(--r-selection-*)、导航控件与进度条颜色(均取--r-link-color)、打印背景(@media print下的--r-background-color)等。
因此,理解这层模板,就能预判"覆写哪个变量会影响页面上的哪个元素"。
第 4 步:可选的自定义字体与附加样式
模板引入完成后,主题文件还可以追加两类内容:
-
引入主题专属字体:通过
@import url(...)引入,例如 css/theme/black.scss 引入本地字体:@import url('./fonts/source-sans-pro/source-sans-pro.css');仓库在 css/theme/fonts 下内置了两套字体:
league-gothic/(含 LICENSE 与 woff 文件)和source-sans-pro/(含多种字重 woff)。部分主题还会引用 Google Fonts 在线字体,如 league 主题的 Lato、night 主题的 Montserrat 与 Open Sans。 -
追加自定义样式:直接编写主题特有的选择器。例如 css/theme/serif.scss 额外调整了链接行高:
.reveal a { line-height: 1.3em; }
四、内置主题的覆写范式(源码实例)
仓库 css/theme 目录下共 14 个内置主题,它们的差异全部体现在第 2 步的变量覆写中。以三个代表性主题为例:
black 主题(css/theme/black.scss)——深色主题的典型范式:
@use 'template/settings' with (
$background-color: #191919,
$main-font: "'Source Sans Pro', Helvetica, sans-serif",
$main-font-size: 42px,
$main-color: #fff,
$heading-color: #fff,
$heading-font: "'Source Sans Pro', Helvetica, sans-serif",
$heading-font-weight: 600,
$heading1-size: 2.5em,
$heading2-size: 1.6em,
$heading3-size: 1.3em,
$heading4-size: 1em,
$link-color: $active-color, // 强调色 #42affa
$link-color-hover: color.scale($active-color, $lightness: 15%),
$selection-color: #fff,
$selection-background-color: color.scale($active-color, $lightness: -35%)
);
注意这里使用了 Sass 内置函数 color.scale(...) 动态派生链接悬停色与选区背景色,无需手算色值。
league 主题(css/theme/league.scss)——利用 $background 声明径向渐变背景,并为 H1 设计多层层叠阴影:
$background: radial-gradient(rgba(85, 90, 95, 1), rgba(28, 30, 32, 1)),
$heading1-text-shadow: #{0 1px 0 #ccc, 0 2px 0 #c9c9c9, ... 0 20px 20px rgba(0,0,0,0.15)}
serif 主题(css/theme/serif.scss)——浅色衬线主题,把 $heading-text-transform 覆写为 none 以取消标题大写转换,符合衬线字体风格。
solarized 主题(css/theme/solarized.scss)——直接以 Solarized 色板变量组织覆写,并将浮层 UI 的 RGB 三元组改为字符串形式传入('0 0 0'),展示了 $overlay-element-* 变量的实际用法。
五、把新主题用起来:从源码目录到演示页的完整链路
综合以上内容,创建一个可用的自定义主题的完整流程为:
- 复制起点:在 css/theme 中复制一份现有
.scss(如cp css/theme/black.scss css/theme/mytheme.scss),并删除原文件头部的版权注释以免混淆。 - 覆写变量:修改
@use 'template/settings' with (...)中的色值、字体与字号;如需浅色背景适配,保留或新增@include mixins.light-bg-text-color(...)。 - 可选扩展:在第 4 步追加自定义字体引入(参考 css/theme/fonts 的用法)与附加样式。
- 编译:运行
npm run build:styles,由 vite.config.styles.ts 自动将mytheme.scss编译为dist/theme/mytheme.css。 - 引用:在演示页(如 index.html)将主题
<link>指向dist/theme/mytheme.css。
六、小结
reveal.js 的主题体系由三层模板与一层构建机制构成:mixins.scss 提供浅/深背景文字适配工具,settings.scss 以 !default 变量 + --r-* CSS 自定义属性定义全部可调参数,theme.scss 作为统一模板消费这些变量生成最终样式;而 vite.config.styles.ts 的目录扫描机制让"复制 .scss → 覆写变量 → 自动编译"成为创建新主题的完整闭环。只要掌握 css/theme/template/settings.scss 中的变量清单及其在 css/theme/template/theme.scss 中的落点,即可在数分钟内定制出风格统一、可随内置主题自由切换的自定义主题。