HTML to PPTX

一个强大的前端库，用于将 HTML DOM 元素转换为可编辑的 PowerPoint (.pptx) 文件。

它不仅仅是截图，而是将 HTML 元素解析为原生的 PPT 形状、文本框、表格和图表，因此生成的 PPT 是清晰且可编辑的。

✨ 特性

• 所见即所得：基于 DOM 的 getBoundingClientRect 计算坐标，高度还原网页布局。
• 可编辑文本：HTML 文本会被转换为独立的 PPT 文本框，支持字体、颜色、字号、加粗、斜体、下划线等样式。
• 原生表格：<table> 标签会被转换为 PPT 的原生表格，支持合并单元格 (rowspan/colspan)。
• 原生图表支持：通过 data- 属性配置，可以将 HTML 元素渲染为可编辑的 PPT 图表。
• 动画支持：支持 CSS 动画（如 fadeIn, slideInUp）映射到 PPT 动画，也支持自定义动画属性。
• 样式还原：支持背景色、背景图、边框、圆角（自动识别矩形/圆角矩形/椭圆）、透明度、旋转角度等。
• 多页支持：通过指定类名，自动分割多页 PPT。
• Canvas & 图片：自动处理 <img> 和 <canvas> 元素。

📦 安装

npm install html-to-pptx
# 或者
yarn add html-to-pptx

注意：本项目依赖 pptxgenjs 作为底层生成引擎。

🚀 快速开始

1. 准备 HTML 结构

在你的页面中，将每一页 PPT 的内容包裹在一个容器中，并赋予一个统一的类名（例如 h-ppt-page）。

<!-- 第一页 -->
<div
  class="h-ppt-page"
  style="width: 1000px; height: 562.5px; position: relative; background: white;"
>
  <h1 style="color: red;">Hello World</h1>
  <p style="font-size: 20px;">这是一个示例文本。</p>
</div>

<!-- 第二页 -->
<div
  class="h-ppt-page"
  style="width: 1000px; height: 562.5px; position: relative;"
>
  <img src="image.png" />
</div>

建议：为了获得最佳效果，建议将容器宽高比设置为 16:9 (例如 1000px * 562.5px)，因为插件默认输出 16:9 的幻灯片。

2. 调用导出函数

在你的 JavaScript/TypeScript 代码中：

import { downloadHtmlToPpt } from "html-to-pptx";

const handleExport = async () => {
  try {
    // 传入类名和文件名
    await downloadHtmlToPpt("h-ppt-page", "我的演示文稿");
    console.log("下载成功！");
  } catch (error) {
    console.error("导出失败", error);
  }
};

📚 API 文档

downloadHtmlToPpt(pageClassName, fileName)

直接在浏览器中触发 PPT 文件下载。

| 参数 | 类型 | 默认值 | 描述 | | :-------------- | :-------------- | :--------------- | :---------------------------------- | | pageClassName | string | "page" | 标识每一页 PPT 的 DOM 类名 | | fileName | string | "presentation" | 下载的文件名（不需要加 .pptx 后缀） | | 返回 | Promise<void> | - | - |

exportHtmlToPpt(pageClassName, outputType)

生成 PPT 数据流，不自动下载，适合需要上传到服务器或自定义处理的场景。

| 参数 | 类型 | 默认值 | 描述 | | :-------------- | :------------------------------- | :------- | :----------------------------------------------------------------- | | pageClassName | string | "page" | 标识每一页 PPT 的 DOM 类名 | | outputType | string | "blob" | 输出类型: "arraybuffer", "base64", "blob", "uint8array" 等 | | 返回 | Promise<Blob \| string \| ...> | - | 返回对应格式的文件数据 |

🎨 高级功能

1. 原生图表 (Native Charts)

你可以通过在 DOM 元素上添加 data-pptx-chart-config 属性，让插件在 PPT 中生成可编辑的图表，而不是截图。

该属性的值必须是一个符合 JSON 格式的字符串，包含 type, data, 和 options。

<div
  style="width: 400px; height: 300px;"
  data-pptx-chart-config='{
    "type": "bar",
    "data": [
      {
        "name": "Series 1",
        "labels": ["Category 1", "Category 2"],
        "values": [10, 20]
      }
    ],
    "options": {
      "chartColors": ["FF0000"]
    }
  }'
>
  <!-- 这里可以放一个普通的 img 或 canvas 用于网页展示，PPT 导出时会被替换为原生图表 -->
</div>

2. 动画支持 (Animations)

插件支持两种方式添加动画：

方式 A: 自动识别 CSS 动画 插件会自动解析元素的 animation-name 并映射到 PPT 动画。 支持的 CSS 动画名包括：fadeIn, fadeInUp, slideInUp, zoomIn, bounceIn 等。

方式 B: 使用 data- 属性（推荐） 显式指定 PPT 动画类型、持续时间和延迟。

<div
  data-pptx-animation="flyInBottom"
  data-pptx-duration="1500"
  data-pptx-delay="500"
>
  从底部飞入的文本
</div>

• data-pptx-animation: 动画类型 (参考 PptxGenJS 文档)
• data-pptx-duration: 持续时间 (毫秒)
• data-pptx-delay: 延迟时间 (毫秒)

3. 忽略元素

如果你希望某个元素在网页显示，但在导出 PPT 时被忽略，可以添加 data-html2pptx-ignore 属性（需在样式中配合 display: none 或在代码逻辑中自行扩展，目前核心代码逻辑会忽略 display: none, visibility: hidden, opacity: 0 的元素）。

⚠️ 注意事项 & 限制

1. CORS 跨域图片：如果页面包含跨域图片（<img>），请确保服务器配置了正确的 CORS 头，或者图片允许跨域访问，否则可能无法生成到 PPT 中。
2. 布局依赖：插件通过 getBoundingClientRect 计算位置。请确保在调用导出函数时，DOM 元素是可见的且已渲染。如果在 display: none 的容器中进行转换，坐标计算将失败。
3. CSS 支持：虽然支持大部分常用 CSS，但复杂的 CSS 布局（如复杂的伪元素、复杂的 clip-path、滤镜等）可能无法完美还原，建议使用简单的 Flex/Grid/Absolute 布局。
4. 字体：PPT 文件中引用的字体取决于用户系统是否安装了该字体。插件默认设置了 fallback 字体。

🛠 开发与贡献

欢迎提交 Issue 或 Pull Request 来改进此项目！

📄 License

MIT