第8章 Slidev 幻灯片导出指南:CLI 与浏览器支持
导出
幻灯片通常在浏览器中展示,但你也可以把它们导出为 PDF、PPTX、PNG 或 Markdown 文件,方便分享或打印。这个功能通过 CLI 命令 slidev export 提供。
需要注意的是,幻灯片中的交互功能在导出后的文件里可能无法使用。如果想保留交互性,可以把幻灯片构建并部署为 Web 应用,详情见 Building and Hosting。
浏览器导出器(推荐)
此功能自 v0.50.0-beta.11 起可用。
Slidev 在浏览器中提供了导出界面。点击导航栏“更多选项”菜单中的"Export"按钮即可进入,也可以直接访问 http://localhost:
在这个界面中,你可以把幻灯片导出为 PDF,或者将幻灯片截图为图片并打包下载成 PPTX 或 zip 文件。可编辑的 PPTX 只能通过 CLI 导出。
注意,非现代 Chromium 内核的浏览器可能无法正常使用这个导出界面。如果遇到问题,请改用 CLI。
本页接下来的内容仅针对 CLI。
CLI
导出 PDF、PPTX 或 PNG 依赖 Playwright 来渲染幻灯片,因此需要在项目中安装 playwright-chromium:
$ pnpm add -D playwright-chromium $ npm i -D playwright-chromium $ yarn add -D playwright-chromium $ bun add -D playwright-chromium $ deno add -D npm:playwright-chromium
格式
按照上述方式安装 playwright-chromium 之后,使用以下命令即可将幻灯片导出为 PDF:
$ slidev export
默认情况下,PDF 会输出到 ./slides-export.pdf。
PPTX
Slidev 也可以把幻灯片导出为 PPTX 文件:
$ slidev export --format pptx
注意:PPTX 中的每页幻灯片都会以图片形式导出,文字无法选中。演讲者备注会按页写入 PPTX 文件。
在此模式下,--with-clicks 选项默认开启,如需关闭,请传入 --with-clicks false。
可编辑 PPTX
如果接收方需要编辑幻灯片而不只是放映,可以导出为原生图形而非图片:
$ slidev export --format pptx-editable
幻灯片会在浏览器中完成度量,然后重建为 PowerPoint 原生图形,因此文字可以选中和编辑,文本框可以移动和改色,演讲者备注也会照常保留。这并不能取代 --format pptx——后者仍然是视觉还原度最高的选项。
以下内容仍会导出为图片:PowerPoint 没有对应实现的元素,包括 SVG(因此 Mermaid 图表和图标)、
如果某页幻灯片无法安全重建,或者重建后几乎全是图片,则会针对该页单独回退到与 --format pptx 相同的图片导出方式,并打印原因。
发送文件前有几点值得了解:
.pptx 只是引用字体名称,并不嵌入字体。导出时会打印所用到的字体族,接收方需要安装这些字体,否则 PowerPoint 会用其他字体替代。
PowerPoint 对文本的度量方式与浏览器不完全一致,较长的段落换行数可能不同。
主题通过 ::before 或 ::after 在正常文档流中绘制的装饰元素会被忽略,导出时会列出这些元素。代码块行号就属于这种情况:它来自 CSS counter,没有文本和盒子可供计算样式读取。
与 --format pptx 一样,除非传入 --with-clicks false,否则每次点击步骤都会导出一页幻灯片。此模式不支持 --per-slide。
PNG 和 Markdown
传入 --format png 选项时,Slidev 会为每页幻灯片导出 PNG 图片,而不是 PDF:
$ slidev export --format png
也可以使用 --format md 生成一个由编译后的 PNG 组成的 Markdown 文件:
$ slidev export --format md
演讲者备注
如果想把演讲者备注从幻灯片中单独打印出来,可以使用 slidev export-notes。它需要与幻灯片导出相同的 Playwright 安装。
$ slidev export-notes
默认会生成 ./slides-export-notes.pdf。该 PDF 包含有备注的幻灯片的备注、标题和页码;没有备注的幻灯片和幻灯片预览不会包含在内。
使用其他入口文件或输出文件名:
$ slidev export-notes talk.md --output speaker-notes.pdf
选项
以下是 slidev export 命令的一些常用选项,完整列表见 CLI 文档。
导出点击步骤
默认情况下,Slidev 导出时每页幻灯片只生成一页,并禁用点击动画(PPTX 格式除外,它会为每个点击步骤导出一页幻灯片)。如果希望把包含多步动画的幻灯片导出为多页,请传入 --with-clicks 选项:
$ slidev export --with-clicks
输出文件名
可以用 --output 选项指定输出文件名:
$ slidev export --output my-pdf-export
也可以在 headmatter 配置中指定:
--- exportFilename: my-pdf-export ---
按范围导出
默认会导出演示文稿中的所有幻灯片。如果想导出特定的一页或某个范围的幻灯片,可以设置 --range 选项:
$ slidev export --range 1,6-8,10
该选项同时支持具体页码和范围写法。上面的例子会导出第 1、6、7、8 和 10 页。
批量导出
还可以一次导出多个幻灯片文件:
$ slidev export slides1.md slides2.md
或者(仅在部分 shell 中可用):
$ slidev export *.md
在这种情况下,每个输入文件都会各自生成一份 PDF。
暗色模式
如果想使用主题的暗色版本导出幻灯片,使用 --dark 选项:
$ slidev export --dark
超时
对于大型演示文稿,可能需要通过 --timeout 增加 Playwright 的超时时间:
$ slidev export --timeout 60000
等待
幻灯片中某些部分的渲染可能需要更长时间。可以使用 --wait 选项在导出前增加额外延迟:
$ slidev export --wait 10000
还有一个 --wait-until 选项,用于在导出每页幻灯片前等待某个状态。如果持续遇到超时问题,可以尝试设置该选项:
$ slidev export --wait-until none
可选值: - 'networkidle' -(默认)当至少 500 ms 内没有任何网络连接时,认为操作完成。这是最安全的方式,但可能导致超时。 - 'domcontentloaded' - 当 DOMContentLoaded 事件触发时,认为操作完成。 - 'load' - 当 load 事件触发时,认为操作完成。 - 'none' - 不等待任何事件。
警告
使用 'networkidle' 以外的值时,请务必确认导出的幻灯片内容完整且正确。如果有内容缺失,可能需要改用 --wait 选项。
可执行文件路径
Chromium 可能缺少某些功能,例如解码部分视频所需的编解码器。可以通过 --executable-path 把 Playwright 的浏览器可执行路径指向你的 Chrome 或 Edge:
$ slidev export --executable-path [path_to_chromium]
PDF 大纲
此功能自 v0.36.10 起可用。
传入 --with-toc 选项即可生成 PDF 大纲:
$ slidev export --with-toc
省略背景
导出 PNG 时,可以通过 --omit-background 去掉浏览器默认背景:
$ slidev export --omit-background
浏览器默认背景是指所有浏览器窗口都可见的白色背景,与应用中通过 CSS 样式设置的其他背景不同。参见 Playwright 文档。去除后,你需要为应用添加额外的 CSS 样式才能显现透明效果。
下面是一个覆盖应用中所有背景的基础示例:
* { background: transparent !important; }
故障排查
内容缺失或动画未完成
如果导出的 PDF 中有内容缺失或动画未播完,可以尝试在导出每页幻灯片前增加等待时间:
$ slidev export --wait 1000
Emoji 显示异常
如果导出的 PDF 或 PNG 中缺少 Emoji,很可能是环境中缺少所需字体(例如 Google 的 Noto Emoji)。
这类问题常见于 CI/CD 等容器化的 Linux 环境。可以这样修复:
$ curl -L --output NotoColorEmoji.ttf https://github.com/googlefonts/noto-emoji/raw/main/fonts/NotoColorEmoji.ttf $ sudo mv NotoColorEmoji.ttf /usr/local/share/fonts/ $ fc-cache -fv
Global Layers 中的上下文错误
参见 https://sli.dev/features/global-layers 中的提示。