企业官网建设流程全解析

• 前端
• UI组件

Spectacle 是基于 React 的演示文稿框架，允许开发者用 JSX 语法编写幻灯片，并支持在演示过程中实时演示代码。本文聚焦官方 FAQ 中两个高频问题——如何将演示文稿导出为 PDF，以及是否可以用 TypeScript 编写演示文稿——结合仓库源码深入讲解查询参数的底层原理、黑白打印机制与类型系统的开箱即用能力。读完本文，你将掌握 Spectacle 的导出/打印模式、演示模式的 URL 控制方式，以及基于 TypeScript 从零搭建演示文稿的完整方案。

一、将幻灯片导出为 PDF：exportMode与printMode

1. 一键进入"展平"导出模式

Spectacle 原生支持将演示文稿导出为 PDF。方式非常简单：在演示文稿的 URL 末尾追加查询参数?exportMode=true，Spectacle 会进入导出模式，将整个演示文稿"展平"（flatten）为适合逐页打印的形态，此时你只需要在浏览器中直接选择"打印 → 另存为 PDF"即可完成导出。

https://your-deck.example.com/?exportMode=true

所谓"展平"，指的是导出模式下演示文稿不再依赖 JavaScript 交互（如分步动画、键盘翻页），而是把每一页幻灯片按固定尺寸、无溢出地排布为可打印页面，从而保证浏览器打印出来的 PDF 与屏幕上的每页幻灯片一一对应。

2. 黑白打印版本：?exportMode=true&printMode=true

如果你需要一份节省墨水的黑白讲义版本，可以同时追加printMode参数：

https://your-deck.example.com/?exportMode=true&printMode=true

printMode会把幻灯片切换为"打印机友好"的黑白配色。两个参数可以自由组合，Spectacle 支持在同一 URL 中通过多个&连接多个查询参数，例如&exportMode=true&printMode=true，这正是官方文档推荐的标准组合方式。

3. 导出模式的源码实现原理

从源码层面看，导出与打印的差别其实非常小。在 packages/spectacle/src/components/deck/index.tsx 中，View组件根据当前模式分发渲染：

• PRINT_MODE渲染<PrintMode {...props} />
• EXPORT_MODE渲染<PrintMode {...props} exportMode />

源码注释明确写道："打印模式和导出模式除了使用的主题不同之外完全相同：打印模式使用通常是单色调的打印主题，而导出模式使用默认主题。"（Print mode and export mode are identical except for the theme that is used. Print mode uses the print theme which is usually monotone and export mode uses the default theme.）

也就是说，两者共用同一个 packages/spectacle/src/components/print-mode/index.tsx 组件，唯一的区别是：

• 导出模式（exportMode）保持你配置的默认主题，颜色与设计原样呈现；
• 打印模式（printMode）切换到 packages/spectacle/src/theme/print-theme.ts 定义的黑白主题——该主题将primary设为#777、secondary与quaternary、quinary设为#000、tertiary设为#fff，从而把整套配色压成灰阶，实现黑白打印效果。

PrintMode组件还做了几件对导出至关重要的事情（见 print-mode/index.tsx）：

1. 通过@media print全局样式清空body/html外边距，并利用@page { size: ... }将打印页尺寸设置为与幻灯片画布一致（默认取主题中theme.size.width与theme.size.height，例如1024px 768px）；
2. 将幻灯片背景替换为纯白Backdrop，保证打印底色干净；
3. 传入disableInteractivity关闭交互，使每页幻灯片以静态、完整的方式呈现。

4. 模式是如何被 URL 触发的：useModes与查询参数解析

?exportMode=true这类查询参数并非"魔法"，而是由 packages/spectacle/src/hooks/use-modes.ts 这个核心 Hook 负责解析的。其工作流程如下：

1. 组件挂载时，useModes读取window.location.search，用query-string库的parse（并开启parseBooleans: true）解析出所有查询参数；
2. modeKeyForSearchParam按优先级判断当前处于哪种模式——若presenterMode为真则进入演示者模式，否则依次判断overviewMode、printMode、exportMode，全部为空则回到默认模式（见 use-modes.ts）；
3. 五种模式常量定义在 packages/spectacle/src/utils/constants.ts 的SPECTACLE_MODES中：DEFAULT_MODE、PRESENTER_MODE、OVERVIEW_MODE、PRINT_MODE、EXPORT_MODE；
4. toggleMode在切换模式时会重写window.location.search，把对应的presenterMode/overviewMode/printMode/exportMode布尔参数写回 URL，并尽量保留当前的slideIndex与stepIndex。

这一行为有测试用例背书：packages/spectacle/src/hooks/use-modes.test.ts 逐一验证了切换演示者、概览、打印、导出模式后location.search会分别变成presenterMode=true、overviewMode=...、printMode=true、exportMode=true。这意味着：你完全可以把包含模式的 URL 发给协作者或投放到观众端，对方打开即进入对应模式，这也是导出场景"直接分享带参链接"能工作的根本原因。

5. 完整支持的查询参数一览

Spectacle 支持的全部查询参数可在官方演示控制文档中查看，详见 docs/presenting-controls.mdx。除导出外，常用参数还包括：

这些模式也都可以通过键盘快捷键即时切换（如Alt + Shift + P切换演示者模式、Alt + Shift + O切换概览模式），快捷键定义见 constants.ts，与查询参数在useModes内部共用同一套模式切换逻辑，方便你在演示现场自由进出导出/打印状态。

二、用 TypeScript 编写演示文稿：类型开箱即用

1. 类型随包发布，无需额外安装

Spectacle 官方 FAQ 的第二个高频问题：能否用 TypeScript 编写演示文稿？答案是肯定的。Spectacle 的类型定义直接随 npm 包发布，你不需要额外安装@types/spectacle之类的类型包，也不需要任何单独的类型定义导入语句，在任意.ts或.js演示文稿中都能安全使用。

这一点可以直接在包配置中得到印证：packages/spectacle/package.json 中声明了"types": "lib/index.d.ts"与"main": "lib/index.js"，TypeScript 编译器会自动从该字段解析类型，因此import { Deck, Slide, Heading } from 'spectacle'这类导入天然具备完整的类型提示与编译期检查。

2. TypeScript 是 Spectacle 与 create-spectacle 的默认语言

更进一步，TypeScript 目前已经是 Spectacle 及脚手架工具create-spectacle的默认语言。官方在 FAQ 中明确表示：TypeScript 是 Spectacle 与create-spectacleCLI 的默认语言，你可以直接使用，无需任何额外配置。

仓库中的脚手架模板印证了这一点：

• packages/create-spectacle/src/templates/file-writers.ts 生成的入口文件就是index.tsx；
• packages/create-spectacle/src/templates/webpack.ts 将构建入口配置为entry: './index.tsx'；
• packages/create-spectacle/src/templates/babel.ts 内置了@babel/preset-typescript用于转译 TSX 代码；
• packages/create-spectacle/src/templates/package.ts 的依赖中默认包含typescript: ^5.3.3。

由 packages/create-spectacle/src/templates/index.ts 生成的初始演示文稿就是一个标准的 TypeScript + React 组件：

import React from 'react'; import { createRoot } from 'react-dom/client'; import { Deck, DefaultTemplate, Slide, FlexBox, Heading, SpectacleLogo } from 'spectacle' const Presentation = () => ( <Deck template={() => <DefaultTemplate />}> <Slide> <FlexBox height="100%"> <Heading>My Presentation</Heading> </FlexBox> </Slide> <Slide> <FlexBox height="100%"> <Heading fontSize="h2">Made with</Heading> <SpectacleLogo size={300} /> </FlexBox> </Slide> </Deck> ); createRoot(document.getElementById('app')!).render(<Presentation />);

注意其中的非空断言document.getElementById('app')!——这正是 TypeScript 默认启用后的典型写法。如果你偏好纯 JavaScript，Spectacle 同样完全兼容，.js文件中不加任何类型注解即可运行，两者共享同一套 API 与组件。

3. TypeScript 示例项目参考

如果你想快速对照一个完整可运行的 TypeScript 演示文稿项目，可以直接参考仓库中的 examples/typescript 目录，其结构为：

• index.tsx：入口演示文稿组件；
• tsconfig.json：TypeScript 编译器配置；
• webpack.config.js：基于 webpack 的构建配置；
• package.json：依赖与脚本。

配合 README.md 中的说明，执行pnpm install后即可本地启动开发服务器，边改index.tsx边实时预览。

三、FAQ 速查总结

这两个能力共同构成了 Spectacle 从"编写"到"交付"的完整闭环：开发阶段用 TypeScript 获得类型安全保障，演示阶段用查询参数即时切换演示者/概览模式，收尾阶段用exportMode一键导出分享用的 PDF 或讲义。所有机制都基于 URL 查询参数与包内类型声明实现，无需任何外部工具，这也是 Spectacle 保持"开箱即用"体验的设计核心。

• 前端
• UI组件