1.1.0 • Published 6 months ago

html-to-pptx

Licence

MIT

Version

1.1.0

Deps

Size

746 kB

Vulns

Weekly

Stars

Summary Dependency Versions

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 的元素）。

注意事项 & 限制

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

开发与贡献

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

License

MIT