diff --git a/README.md b/README.md index 49f8163..6292dea 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,94 @@ # html2pptx -HTML to editable PPTX export engine. +HTML / 截图 → 标准 JSON → 可编辑 PPTX -将 HTML 演示文稿导出为**文字可编辑、布局可还原**的 PPTX 文件。 +将任何格式的演示文稿描述转化为**文字可编辑、布局可还原**的 PPTX 文件。 -## 原理 +## 架构 ``` -HTML 文件 → HTTP 服务 → Chrome headless 渲染 → DOM 遍历提取位置/样式 → pptxgenjs 生成 PPTX +输入（任意来源） 中间层 输出 +━━━━━━━━━━━━━━━ ━━━━━━━━━━━ ━━━━━ +AI 生成的描述 标准 JSON PPTX 文件 +HTML 提取的结构 → Schema 校验 → pptxgenjs 渲染 +多模态识别结果 ↓ +Markdown / 其他 翻译引擎（机械映射） ``` +### 三层结构 + +| 层 | 目录 | 说明 | +|---|------|------| +| **知识库** | `reference/` | pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值。给 AI 用的操作手册 | +| **Schema** | `schema/` | JSON Schema 定义 + 示例。AI 输出符合此 Schema 的 JSON 即可驱动 PPT 生成 | +| **翻译引擎** | `renderer/` | JSON → pptxgenjs API 调用的机械映射。不做逻辑判断，只做参数透传 | + +## 快速开始 + +```bash +npm install +``` + +### 从 JSON 生成 PPTX + +```javascript +const { render } = require('./renderer/index'); +const pptx = render(jsonObject); +pptx.writeFile({ fileName: 'output.pptx' }); +``` + +### 从 JSON 文件生成 + +```javascript +const { renderFile } = require('./renderer/index'); +renderFile('./schema/examples/ui-dashboard.json', 'output.pptx'); +``` + +## 目录结构 + +``` +reference/ ← 知识库：每个元素的完整参数表 + text.md 文字参数 + shape.md 形状参数 + table.md 表格参数 + image.md 图片参数 + chart.md 图表参数 + slide.md 页面参数 + master.md 母版参数 + output.md 输出参数 + coordinate.md 坐标换算 + +schema/ ← JSON Schema 定义 + presentation.schema.json + examples/ + basic.json 基础示例（2页） + full.json 全功能示例 + ui-dashboard.json UI 看板示例 + ui-advanced.json 精细化 UI 示例 + +renderer/ ← 翻译引擎 + index.js 主入口 + text-renderer.js 文字渲染 + shape-renderer.js 形状渲染 + table-renderer.js 表格渲染 + image-renderer.js 图片渲染 + chart-renderer.js 图表渲染 + slide-renderer.js 页面属性 + +PPTXGENJS_API.md ← pptxgenjs v4.0.1 完整 API 参考 +``` + +## 设计原则 + +- **翻译引擎是纯机械映射** — 不做样式推断，不做逻辑判断。JSON 里有什么就画什么 +- **Schema 是 AI 友好** — 字段名直观，不暴露 pptxgenjs 内部命名 +- **知识库是完整参考** — 每个参数都有类型+取值范围+默认值，不需要 AI 去猜 + ## 依赖 -- Node.js 18+ -- Chrome / Chromium / Edge（用于渲染页面） - -## 使用 - -```bash -# 安装 -npm install - -# 导出 -node bin/html2pptx input.html output.pptx -``` - -## 核心依赖 - | 包 | 用途 | |---|------| -| playwright | 控制 Chrome headless 渲染页面 | -| pptxgenjs | 生成 PPTX 文件 | -| http-server | 本地静态文件服务（可选） | +| pptxgenjs | 生成 PPTX 文件（OOXML） | ## License diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md index bc2dcbb..b506df2 100644 --- a/REQUIREMENTS.md +++ b/REQUIREMENTS.md @@ -1,115 +1,62 @@ -# HTML to PPTX 导出引擎 +# html2pptx 项目文档 -## 背景 +## 项目定位 -DashiAI PPT Skill 中包含一个 `html-deck-to-pptx` 导出子包，能将 HTML 演示文稿导出为可编辑的 PPTX 文件。该子包目前为专有组件（非开源），但其核心逻辑可复刻。 +一套通用 PPT 生成基础设施。核心价值在于**翻译引擎**——把标准 JSON 描述翻译成可编辑的 PPTX 文件。 -我们需要一个独立、可控的导出引擎，集成到现有工作流中。凡是 Hermes/Agogent 生成的 HTML PPT，都能一键导出为**文字可编辑、布局可还原**的 PPTX 文件。 - ---- - -## 需求 - -### 输入 - -- 一个 HTML 文件（含完整 CSS 内联或外联），结构为横向翻页的演示文稿 -- 每页用 `
` 或特定容器标识 -- 样式通过 CSS 定义（font-size, color, font-weight, text-align, background-color 等） - -### 输出 - -- 一个标准的 `.pptx` 文件，可用 Microsoft PowerPoint / WPS / Keynote 打开 -- **文字必须可编辑**（双击修改字体、大小、颜色） -- **形状/框线/背景色保持矢量**（可拖动、缩放） -- **排版布局按原始位置还原**（x, y, width, height 尽可能一致） - -### 可放弃的特性（第一期不做） - -- JS 图表（ECharts/Chart.js）→ 导出为截图占位或忽略 -- CSS 渐变/阴影/圆角 → 简化或忽略 -- 入场/翻页动画 → 忽略 -- Web 字体 → 映射为 Office 相近字体 -- 响应式布局 → 固定一宽高比 - ---- - -## 技术方案 - -### 架构 +## 架构 ``` -HTML 文件 - ↓ -启动本地 HTTP 服务（Node.js http-server 或 express） - ↓ -Chrome headless（通过 playwright）打开页面 - ↓ -遍历 DOM，提取每页每个元素： - - 位置（offsetLeft, offsetTop, offsetWidth, offsetHeight） - - 文字内容（innerText） - - 样式（font-size, color, font-weight, text-align, background-color 等） - ↓ -pptxgenjs 按页创建 slide，按坐标绘制 TextBox / Shape - ↓ -输出 .pptx 文件 +输入（任意来源） 中间层 输出 +━━━━━━━━━━━━━━━ ━━━━━━━━━━━ ━━━━━ +AI 直接输出 标准 JSON PPTX 文件 +HTML 提取 → JSON → Schema 校验 → 翻译引擎 +截图识别 → JSON （机械映射） pptxgenjs +Markdown → JSON ``` -### 核心依赖 +### 三层 -| 依赖 | 用途 | 备注 | -|------|------|------| -| `playwright` | 控制 Chrome headless 渲染页面、提取 DOM 信息 | 你的环境已有 Chrome | -| `pptxgenjs` | 生成 PPTX 文件（OOXML） | 纯 JS，不依赖 Office | -| `http-server` 或 express | 本地静态文件服务 | | +| 层 | 内容 | 状态 | +|---|------|------| +| **知识库** (`reference/`) | pptxgenjs 完整参数表，每个参数的类型/取值范围/默认值 | ✅ 已完成 | +| **Schema** (`schema/`) | JSON Schema 定义 + 多种场景的示例文件 | ✅ 已完成 | +| **翻译引擎** (`renderer/`) | JSON → pptxgenjs API 调用的机械映射代码 | ✅ 已验收 | -### 可选升级 +### 前端处理器（待开发） -- 支持 PNG/JPEG 图片的提取与还原 -- 表格结构识别（`` → PPT 表格） -- 列表识别（`