怎么自定义 reveal.js 主题与 CSS 样式

一、明确定制需求与路径选择

reveal.js 自带了 black、white、league、beige 等十多种预设主题，存放在 dist/theme/ 目录下。当这些预设样式的字体、背景色或标题风格不满足特定演示需求时，我们需要进行个性化定制。根据项目改动幅度与维护周期，可采用以下两种解决路径：

• 独立 CSS 覆盖法：无需配置任何前端构建工具（如 Node.js 或 Sass 编译器），直接新建一个 custom.css 文件并在 HTML 头部引用。其优势在于开箱即用、随改随看，适合单次技术演讲、活动汇报或小范围的样式调整。
• SCSS 源码编译法：利用 reveal.js 源码工程中的 Sass 架构，新建主题入口并覆盖基础变量，随后通过构建命令输出独立的压缩版主题 CSS。其优势是体系完备、变量集中、输出文件纯净，适合需要多次复用的品牌演示模板。

二、方案一：使用独立 CSS 文件直接覆盖

这是最轻量、上手最快的定制方式。其核心逻辑是在 HTML 文档中，将自定义样式表放置在官方主题样式表之后，依靠层叠样式表的先后顺序与选择器权重实现覆盖。

1. HTML 引入顺序配置

打开承载幻灯片的 HTML 文件（通常为 index.html），在 <head> 区域确保引入顺序如下：

<!-- 1. 基础核心结构样式（必选） -->
<link rel="stylesheet" href="dist/reset.css">
<link rel="stylesheet" href="dist/reveal.css">

<!-- 2. 官方基础主题（作为基底，如 white.css 或 black.css） -->
<link rel="stylesheet" href="dist/theme/white.css" id="theme">

<!-- 3. 自定义样式覆盖表（必须放在官方主题之后） -->
<link rel="stylesheet" href="css/custom.css">

2. 编写覆盖规则与选择器权重提升

很多初学者在此步骤容易遇到“修改了 CSS 却没有任何变化”的问题。原因在于 reveal.js 官方主题对标题、列表和正文的规则都带有 .reveal 前缀（例如 .reveal h1、.reveal p）。如果直接写普通的 h1 或 p，选择器权重为 (0, 0, 1)，低于官方主题的 (0, 1, 1)，因而无效。

在项目根目录新建 css/custom.css，编写带有 .reveal 作用域的自定义样式：

/* ========================================================
   reveal.js 自定义样式覆盖文件：css/custom.css
   ======================================================== */

/* 1. 全局字体与正文行距优化 */
.reveal {
  font-family: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
  font-size: 32px;
  color: #2C3E50;
}

/* 2. 标题层级定制：调整主色与字体粗细 */
.reveal h1,
.reveal h2,
.reveal h3 {
  color: #456581;
  font-weight: 700;
  text-transform: none; /* 取消 reveal.js 默认的大写强制转换 */
  letter-spacing: -0.5px;
}

.reveal h1 {
  font-size: 2.2em;
  margin-bottom: 0.6em;
}

.reveal h2 {
  font-size: 1.6em;
  border-bottom: 3px solid #438A80; /* 为二级标题增加青绿色底边装饰 */
  padding-bottom: 0.2em;
  display: inline-block;
}

/* 3. 强调高亮与链接配色 */
.reveal a {
  color: #438A80;
  transition: color 0.2s ease;
}

.reveal a:hover {
  color: #2C4257;
  text-decoration: underline;
}

/* 4. 底层控制元素微调：进度条与幻灯片页码 */
.reveal .progress {
  height: 5px;
  color: #438A80;
}

.reveal .slide-number {
  font-size: 14px;
  color: #64748B;
  background-color: rgba(247, 249, 251, 0.85);
  padding: 4px 8px;
  border-radius: 4px;
}

三、方案二：基于 SCSS 源码创建与编译全新主题

当需要从底层构建一套体系完整的企业级主题、并在多个演示项目中复用时，推荐采用官方的 SCSS 构建流程。该方案能够借助 Sass 变量统一管理主色、辅色、字体系列和文本选区高亮，编译出来的 CSS 不包含任何重复冗余声明。

1. 准备源码工程环境

获取 reveal.js 完整源码工程（包含构建配置文件），在终端中安装工程所需的依赖包：

# 1. 终端进入 reveal.js 源码根目录
cd reveal.js

# 2. 安装构建所需的 node 模块
npm install

reveal.js 的主题样式源码位于 css/theme/ 目录下，其内部结构分为两层：

• css/theme/template/settings.scss：定义所有主题共享的基础默认变量与 Sass 混入指令。
• css/theme/template/theme.scss：主题核心框架模板，消费上层传入的变量并生成各元素选择器。
• css/theme/source/：具体的独立主题定义源文件。所有官方主题（如 black.scss、white.scss）都存放在此处。

2. 创建自定义主题源文件

在 css/theme/source/ 目录内新建属于你自己的主题文件，例如命名为 brand-slate.scss。文件名将直接决定最终输出的 CSS 文件名。

3. 定义变量并引入核心模板

编辑 css/theme/source/brand-slate.scss，在文件最顶部声明自定义变量，然后通过 @import 引入官方模板：

/**
 * brand-slate 主题源码
 * 文件位置：css/theme/source/brand-slate.scss
 */

// 1. 引入基础配置预设（设置通用工具与默认占位）
@import "../template/settings.scss";

// 2. 覆盖色彩体系变量
$backgroundColor: #F7F9FB;       // 幻灯片底色：雾白
$mainColor: #2C3E50;             // 正文基础字色：石板深灰
$headingColor: #456581;          // 各级标题色彩：石板蓝
$linkColor: #438A80;             // 链接及交互强调色：青绿
$linkColorHover: lighten($linkColor, 15%); // 链接悬浮浅青色
$selectionBackgroundColor: #438A80; // 鼠标选中文本背景
$selectionColor: #FFFFFF;        // 鼠标选中文本前景色

// 3. 覆盖字体排版变量
$mainFont: "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
$headingFont: "PingFang SC", "Microsoft YaHei", sans-serif;
$mainFontSize: 38px;
$headingFontWeight: 700;
$headingLetterSpacing: -0.5px;
$headingTextTransform: none;     // 禁用全大写转换

// 4. 引入官方核心模板（依据上述变量生成全部 reveal.js 元素规则）
@import "../template/theme.scss";

// 5. 追加特定组件的定制规则（可选）
.reveal section .callout-card {
  background: #FFFFFF;
  border: 1px solid #DDE3EA;
  border-left: 5px solid $linkColor;
  border-radius: 8px;
  padding: 20px 24px;
  text-align: left;
  box-shadow: 0 4px 12px rgba(69, 101, 129, 0.08);
}

4. 常用主题变量速查表

以下是 reveal.js 主题模板中支持的最常用配置变量：

5. 执行编译与验证产物

编写完成后，在终端执行官方预设的构建命令：

# 仅编译主题相关 SCSS
npm run build -- css-themes

终端将调用构建脚本扫描 css/theme/source/ 中的全部源文件，并在 dist/theme/ 目录下生成对应的纯 CSS 产物：

# 生成的最终文件：
dist/theme/brand-slate.css

随后在 HTML 中直接引入该主题，无需再额外叠加基础主题：

<link rel="stylesheet" href="dist/reset.css">
<link rel="stylesheet" href="dist/reveal.css">
<link rel="stylesheet" href="dist/theme/brand-slate.css" id="theme">

如果处于开发阶段，需要频繁调整样式参数，可运行 npm start 启动本地服务，构建系统会自动监听 SCSS 文件变动并实时刷新浏览器。

四、深入 reveal.js 样式层级与单页定制

掌握了全局定制后，实际制作演示文稿常会遇到单页特殊背景、代码块高亮脱节或投影缩放变形等细节问题。理解 reveal.js 的 DOM 架构有助于精准实现局部差异化控制。

1. 单页个性化主题色与状态钩子（data-state）

如果整套幻灯片是浅色主题，但其中某一张总结页或代码演示页希望呈现深色终端风格，不应在 CSS 中使用 !important 强行覆盖，推荐使用 reveal.js 官方支持的 data-state 属性。

在目标幻灯片的 <section> 标签添加状态标识：

<!-- 普通浅色页面 -->
<section>
  <h2>普通幻灯片内容</h2>
  <p>遵循全局主题设计规范。</p>
</section>

<!-- 深色差异化页面 -->
<section data-state="terminal-mode" data-background-color="#1E293B">
  <h2>控制台模式</h2>
  <p>本页文字将动态切换为终端亮绿。</p>
</section>

当翻页切换到该幻灯片时，reveal.js 会自动在最外层的 <div class="reveal"> 容器添加类名 terminal-mode。利用这一特性，可以在 CSS 中编写局部隔离的样式：

/* 针对 terminal-mode 状态页面的专用样式 */
.terminal-mode .reveal .slides section h2 {
  color: #56AB9E;
}

.terminal-mode .reveal .slides section p {
  color: #E2E8F0;
}

2. 同步匹配代码高亮主题（Highlight.js）

reveal.js 的代码高亮是由内置的 plugin/highlight/ 插件控制的，代码块的配色不随 dist/theme/*.css 自动变化，需要单独引入匹配的高亮样式表。

在 HTML 头部同步指定风格一致的代码高亮 CSS：

<!-- 浅色背景主题推荐：github.css 或 vs.css -->
<link rel="stylesheet" href="plugin/highlight/github.css">

<!-- 深色背景主题推荐：monokai.css 或 atom-one-dark.css -->
<!-- <link rel="stylesheet" href="plugin/highlight/monokai.css"> -->

若需要调整代码容器自身的字号、内边距或圆角，同样需要通过 .reveal pre code 选择器进行限定：

.reveal pre {
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
  border-radius: 8px;
}

.reveal pre code {
  font-family: Consolas, Monaco, monospace;
  font-size: 0.85em;
  line-height: 1.5;
  padding: 16px 20px;
  max-height: 520px; /* 防止超长代码撑爆幻灯片高度 */
}

3. 避免破坏幻灯片缩放机制

reveal.js 的工作机制是在初始化时将 .slides 容器设定为固定分辨率（默认通常为 960x700 像素），随后通过 CSS transform: scale(...) 将内容等比缩放并垂直居中居中于浏览器视口中。

五、自查清单与常见问题排查

在完成样式编写并准备正式演示或交付之前，可对照以下四大维度进行系统校验，确保所有样式在不同分辨率与模式下表现稳健。

常见排错指南

• 问题一：编写的 CSS 规则完全不生效
  排查依据：按 F12 打开浏览器开发者工具，检查目标元素上的样式。如果自定义规则未出现，检查 HTML 中 <link> 引用路径是否正确；如果自定义规则被划掉了，说明权重低于官方的 .reveal ... 规则，需在选择器前补充 .reveal 前缀。
• 问题二：标题英文字母全部变成大写
  排查依据：官方主题预设了 text-transform: uppercase。在自定义 CSS 中明确加上 .reveal h1, .reveal h2 { text-transform: none; } 即可恢复自然大小写。
• 问题三：导出 PDF 时部分样式错位或缺失
  排查依据：在浏览器 URL 后面追加 ?print-pdf 参数即可预览打印布局（例如 http://localhost:8000/?print-pdf）。确保没有为 section 设置绝对定位大偏移，保证每一页内容在 PDF 分页中完整呈现。
• 问题四：脱机演示时字体变为系统默认宋体或黑体
  排查依据：使用了网络 WebFont 但现场演示环境无网络连接。在生产部署时，应优先使用本地安全回退字体链（如 "PingFang SC", "Microsoft YaHei", sans-serif），或将字体文件下载至本地通过 @font-face 离线引入。

掌握了外链覆盖与 SCSS 变量重构两套方法后，即可根据演说场景随心定制个性化展示效果。无论是快速微调单场讲演细节，还是沉淀统一的公司品牌幻灯片规范，清晰的层级组织与合理的选择器书写都是保持样式稳定可维护的关键。