Editable HTML Slides

为任意 HTML 演示稿注入通用播放与浏览器内编辑能力。

Add reusable presentation controls and in-browser editing to any HTML slide deck.

它不依赖某个特定的 PPT 生成工具。无论页面来自 AI Skill、HTML 模板、格式转换工具还是手写代码，只要能够识别“舞台”和“页面”，就可以使用。

功能

• 固定 16:9 画布等比缩放
• 上一页、下一页和播放进度
• 键盘、滚轮与触摸翻页
• 浏览器全屏播放
• 非编辑状态隐藏编辑工具
• 浏览器内直接修改文字
• 替换、删除和恢复图片
• 删除页面并进行二次确认
• 自动更新页码和总页数
• 保存为仍可继续编辑的 HTML
• 重复注入时自动升级，不叠加多份运行时
• 支持播放-only 锁定模式

环境要求

• Node.js 18 或更高版本
• 现代浏览器，推荐 Chrome 或 Edge
• 零 npm 依赖，无需执行 npm install

快速开始

克隆仓库：

git clone https://github.com/siryeah/editable-html-slides.git
cd editable-html-slides

给现有 HTML 演示稿注入功能：

node scripts/inject-runtime.mjs /path/to/presentation.html

默认生成：

/path/to/presentation-editable.html

验证输出文件：

node scripts/verify-deck.mjs /path/to/presentation-editable.html

HTML 基础结构

推荐使用：

<main data-ehs-stage>
  <section data-ehs-slide class="slide active visible">
    <h1>第一页</h1>
  </section>
  <section data-ehs-slide class="slide">
    <h1>第二页</h1>
  </section>
</main>

默认约定：

• 优先舞台选择器：[data-ehs-stage]
• 优先页面选择器：[data-ehs-slide]
• 设计尺寸：1920 × 1080

旧结构中的 #deckStage、.slide、[data-slide] 等选择器仍会自动识别。

非标准页面可以显式指定选择器：

node scripts/inject-runtime.mjs presentation.html \
  --output presentation-editable.html \
  --stage-selector '#presentationStage' \
  --slide-selector '.presentation-page' \
  --editable-selector 'h1,h2,h3,p,li,.tag' \
  --width 1920 \
  --height 1080

播放操作

操作	方式
下一页	→、空格、Page Down、底部按钮
上一页	←、Page Up、底部按钮
第一页	Home
最后一页	End
全屏/退出	F 或底部全屏按钮
移动端	左右滑动

默认情况下，全屏播放时底部控制条会完全隐藏。

编辑操作

1. 按 E，或者移动到页面左上角并点击编辑入口。
2. 点击文字直接编辑。
3. 点击图片后可选择替换、删除或恢复。
4. 点击“删除本页”后，需要在确认弹窗中再次确认。
5. 按 Cmd/Ctrl + S 或点击“保存 HTML”。

编辑工具只在编辑状态出现，不影响正常播放和截图导出。

保存说明

• 支持 File System Access API 的浏览器会显示文件保存选择器。
• 其他浏览器会下载一个新的 HTML 文件。
• 替换后的图片默认以 Data URL 嵌入保存后的 HTML。
• 纯静态网页无法直接覆盖服务器上的源文件。在线编辑后，需要保存新 HTML 并重新部署。

常用参数

--output <path>                 指定输出路径
--in-place                      覆盖源文件
--stage-selector <selector>     舞台选择器
--slide-selector <selector>     页面选择器
--editable-selector <selector>  可编辑文字选择器
--width <number>                设计画布宽度
--height <number>               设计画布高度
--locked                        只保留播放功能
--show-controls-fullscreen      全屏时保留控制条
--no-wheel                      禁用滚轮翻页
--no-touch                      禁用触摸翻页

除非已经备份，建议不要使用 --in-place。

Codex Skill 安装

将仓库克隆到 Codex Skills 目录：

git clone https://github.com/siryeah/editable-html-slides.git \
  ~/.codex/skills/editable-html-slides

重启 Codex 后，可以这样调用：

使用 $editable-html-slides 给这个 HTML 演示稿增加全屏、翻页、
文字编辑、图片替换和页面删除功能，保留原来的内容与设计。

Skill 并不负责限定演示稿的设计来源，可以与任意 HTML PPT 生成方式配合使用。

本地示例

npm run demo

命令会根据 examples/basic-deck.html 生成 examples/basic-deck-editable.html 并执行静态检查。

项目结构

editable-html-slides/
├── SKILL.md
├── agents/openai.yaml
├── assets/
│   ├── ppt-runtime.css
│   └── ppt-runtime.js
├── examples/basic-deck.html
├── references/
│   ├── compatibility.md
│   └── html-contract.md
└── scripts/
    ├── inject-runtime.mjs
    └── verify-deck.mjs

兼容性说明

如果原页面已经实现键盘、滚轮、触摸或全屏控制，注入命令会输出潜在冲突提示。请只保留一套控制逻辑，避免同一个事件被处理两次。

• HTML 接入规范：references/html-contract.md
• 已有运行时兼容：references/compatibility.md

License

MIT