# 在 SlideStage Lite 中把 HTML 转成 `.stage`

本教程说明如何用 SlideStage Lite 的浏览器转换器，把 HTML deck 转换成 `.stage` 文件。

这个流程适合不想使用 CLI 的用户。转换在浏览器本地完成，不会上传源文件。

## 前提条件

你需要：

- 可打开的 SlideStage Lite。
- 一份 HTML deck 文件、目录或 zip。
- 现代浏览器。目录拖放需要浏览器支持 File System Access 或等价目录读取能力。

## 1. 打开转换器

进入 SlideStage Lite 首页，点击 **Convert from HTML deck** 或同等入口。

你会看到转换面板。它接受：

- 单个 `.html` 文件。
- 包含 `index.html` 的目录。
- 包含 HTML deck 的 `.zip`。
- 已有 `.stage` 文件。

## 2. 选择源文件

把源拖入转换面板，或点击选择文件。

如果你的 deck 有多个 HTML 文件，推荐选择整个目录或 zip，而不是只选择入口 HTML。这样转换器才能复制图片、CSS、字体和脚本等资源。

## 3. 选择转换模式

默认使用 `auto`。转换器会识别源框架并选择合适模式。

常见模式：

- `split`：把每张 slide 拆成一个独立 HTML 文件。
- `wrap`：保留原 deck runtime，把整个 deck 包成一张 slide。
- `single`：把普通 HTML 作为一张 slide。
- `passthrough`：校验并重新输出已有 `.stage`。

建议：

- reveal.js 和 impress.js 通常用 `wrap`，保留 fragments、transition、3D 变换和插件。
- huashu-design、html-ppt-skill 这类结构化 inline deck 通常用 `split`。
- 普通单页 HTML 用 `single`。

## 4. 检查能力提示

如果源 HTML 保留了脚本，转换器会在 manifest 中写入 `compat.requires`。

常见能力包括：

- `same-origin-storage`
- `broadcast-channel`
- `window-open`

这些能力不会在转换时自动授权。播放时，Lite 会按 deck 指纹显示信任提示。

## 5. 可选：生成离线包

如果源 deck 依赖外部图片、字体或 CSS，可以开启离线镜像选项。

离线镜像会尝试把外部资源下载并写入 `.stage`，同时在 manifest 的 `offline` 字段中记录结果。

注意：

- 不可信 deck 不建议开启脚本或 iframe 的离线镜像。
- 私有网络、localhost 和云元数据地址默认应被拦截。
- 过大的资源会被跳过或触发大小限制。

## 6. 下载 `.stage`

点击转换按钮后，Lite 会生成 `.stage` 并触发下载。

下载完成后，建议立刻把它拖回 Lite 打开验收：

- slide 顺序是否正确。
- 资源是否完整。
- notes 是否正确显示。
- 是否出现预期的信任提示。

## 7. 上传或分发

验收通过后，你可以：

- 把 `.stage` 发给别人本地播放。
- 上传到 SlideStage Pro。
- 放进发布产物或归档系统。

## 常见问题

### 目录拖放失败

把目录压成 `.zip` 后再拖入转换器。

### reveal.js 动画丢失

检查是否使用了 `split`。如果 deck 依赖 reveal runtime，改用 `wrap`。

### 播放时提示需要授权

这是预期行为。说明 deck 声明了额外能力。只授权你信任的 deck。