reveal.js 主题定制指南:基于 Sass 模板体系创建与编译自定义主题

原创2026-09-30 12:56:201,690 阅读
文章标签:前端Web框架UI组件

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,创建自定义主题的推荐方式是:

  1. 在 css/theme 目录下复制一个已有的 .scss 主题文件作为起点(例如 black.scss);
  2. 按需修改其中的变量与样式;
  3. 运行 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 步:可选的自定义字体与附加样式

模板引入完成后,主题文件还可以追加两类内容:

  1. 引入主题专属字体:通过 @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。

  2. 追加自定义样式:直接编写主题特有的选择器。例如 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-* 变量的实际用法。

五、把新主题用起来:从源码目录到演示页的完整链路

综合以上内容,创建一个可用的自定义主题的完整流程为:

  1. 复制起点:在 css/theme 中复制一份现有 .scss(如 cp css/theme/black.scss css/theme/mytheme.scss),并删除原文件头部的版权注释以免混淆。
  2. 覆写变量:修改 @use 'template/settings' with (...) 中的色值、字体与字号;如需浅色背景适配,保留或新增 @include mixins.light-bg-text-color(...)。
  3. 可选扩展:在第 4 步追加自定义字体引入(参考 css/theme/fonts 的用法)与附加样式。
  4. 编译:运行 npm run build:styles,由 vite.config.styles.ts 自动将 mytheme.scss 编译为 dist/theme/mytheme.css。
  5. 引用:在演示页(如 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 中的落点,即可在数分钟内定制出风格统一、可随内置主题自由切换的自定义主题。

登录后查看全文
reveal.js