ppt-dsl-renderer 1.1.1 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/AGENT_PPTX_EXPORT.md +24 -5
  2. package/AGENT_USAGE.md +28 -8
  3. package/README.md +6 -5
  4. package/THIRD_PARTY_NOTICES.md +3 -1
  5. package/dist/cli.js +3510 -152
  6. package/dist/pptx/exporter.js +60 -47
  7. package/dist/pptx/index.js +4103 -4252
  8. package/package.json +7 -6
package/AGENT_PPTX_EXPORT.md CHANGED
@@ -6,15 +6,15 @@ Agent 默认使用统一 CLI。命令、参数、输入和返回协议以 [Agent
6
6
 
7
7
  ### 部署与浏览器
8
8
 
9
- 需要 Node.js 22+、包含 `export-pptx` 的构建包，以及后端机器/容器中已安装的 Chrome/Chromium、系统库和字体。调用方必须显式安装可选 peer dependency `playwright-core@1.62.1`；主包不会自动安装浏览器驱动。它不下载浏览器，也不要求 Python 安装 `playwright`。
9
+ 需要 Node.js 18+、包含导出命令的构建包，以及后端机器/容器中已安装的 Chrome/Chromium、系统库和字体。调用方必须显式安装可选 peer dependency `playwright-core@1.61.1`；主包不会自动安装浏览器驱动。它不下载浏览器，也不要求 Python 安装 `playwright`。
10
10
 
11
11
  ```bash
12
- yarn add ppt-dsl-renderer playwright-core@1.62.1
12
+ yarn add ppt-dsl-renderer playwright-core@1.61.1
13
13
  ```
14
14
 
15
15
  只使用 HTML、Vue 或浏览器端 PPTX API 的项目无需安装 `playwright-core`。
16
16
 
17
- 默认使用 Google Chrome。若后端通过自己的 Playwright 安装了 Chromium，可将其实际可执行文件路径传给 `--browser-executable`，并确保 CLI 进程有执行权限。**每次 CLI 调用仍会启动一个新实例，不复用已有浏览器进程或 Playwright 对象；当前没有 CDP/远程连接参数。**
17
+ 默认使用 Google Chrome。若后端通过自己的 Playwright 安装了 Chromium，可将其实际可执行文件路径传给 `--browser-executable`，并确保 CLI 进程有执行权限。**DSL 导出每次调用启动一个新实例；HTML 目录导出按页依次启动和关闭实例，不复用已有浏览器进程或 Playwright 对象。当前没有 CDP/远程连接参数。**
18
18
 
19
19
  ### Python 任务进程示例
20
20
 
@@ -55,31 +55,50 @@ pptx_bytes = pptx_path.read_bytes()
55
55
 
56
56
  成功依据是退出码 0，而不是 stderr 为空或文件存在。结果文件已经写好，路径在顶层 `file`。CLI 正常完成或生成失败后关闭自己的浏览器，不操作后端其他实例。
57
57
 
58
+ ### 普通 HTML 导出
59
+
60
+ 已有 HTML 文件或按页排列的 HTML 目录可以直接导出，不需要 DSL JSON：
61
+
62
+ ```bash
63
+ node /app/node_modules/ppt-dsl-renderer/dist/cli.js \
64
+ export-html-pptx /work/ppt-task/slides \
65
+ --out /work/ppt-task/editable.pptx \
66
+ --assets-root /work/ppt-task/assets
67
+ ```
68
+
69
+ 目录仅读取直接子级 `.html` 文件并自然排序。`--assets-root` 可省略；它只在 HTML 原路径失效时查找本地图片，缺失、同名冲突或图片加载失败时使用透明空白图。可用 `--selector` 指定页面根节点，`--browser-executable` 指定 Chromium。该命令不接受 DSL 的 `--pages`、`--timeout`。成功 JSON 含 `file`、`pages[].sourceFile`、`bytes`、对象统计 `objects` 和缺图清单 `imagePlaceholders`；返回前原子替换输出，其他失败保留已有文件。
70
+
58
71
  ### 任务管理
59
72
 
60
- - 限制并发量，每次调用都会启动浏览器；各任务使用独立输出路径。
73
+ - 限制并发量，导出会启动浏览器；各任务使用独立输出路径。
61
74
  - `--timeout` 分别约束浏览器启动和页面生成，不是总时限，也不覆盖最后写文件。后端总时限需留出两个阶段及写入时间。
62
75
  - 若外部强制终止 CLI，任务执行器还需回收该任务的子进程，不能依赖 finally 一定执行。
63
76
  - CLI 不提供实时进度、HTTP 服务、上传或断点续传。业务方负责任务状态、存储和下载；不要在每个任务中安装包、下载浏览器或执行 build。
64
77
 
65
78
  ## CLI 实现范围
66
79
 
67
- `src/cli.js` 提供 `export-pptx` 及其参数；`src/pptx-cli.js` 包装浏览器生命周期、二进制传输和文件保存。`package.json` 将 `playwright-core` 声明为可选 peer dependency，并保留为包自身测试所需的 dev dependency；`vite.cli.config.js` 将驱动作为外部依赖，发布入口仍为 `dist/cli.js`。
80
+ `src/cli.js` 提供 `export-pptx` 和 `export-html-pptx` 及其参数；`src/pptx-cli.js` 包装 DSL 导出，`src/html-pptx-cli.js` 包装普通 HTML 导出。`package.json` 将 `playwright-core` 声明为可选 peer dependency，并保留为包自身测试所需的 dev dependency；`vite.cli.config.js` 将驱动和 HTML 专用 PptxGenJS 作为外部依赖，发布入口仍为 `dist/cli.js`。
68
81
 
69
82
  CLI 复用原 `dist/pptx/exporter.js`，没有修改 DSL、Vue/HTML 渲染或 PPTX 转换算法，没有增加 demo 接口。原有 `render` 和浏览器 `exportToPptx` API 保持兼容。
70
83
 
84
+ 普通 HTML 导出移入独立模块，使用隔离的 `pptxgenjs 4.0.1`；原 DSL 导出继续使用 `pptxgenjs 3.12.0`。它读取浏览器布局并转成可编辑文字/形状，照片、SVG 和复杂 CSS 背景为局部图片；不要求特定 HTML 标签结构，也不保证任意 CSS 与 PowerPoint 逐像素一致。
85
+
71
86
  ## 导出兼容边界
72
87
 
73
88
  - 结构化资源使用 HTTP(S) URL 或 data URL。空白页面通常使用不透明来源，远程素材仍受 CORS、网络和权限约束；来源不被允许时，可由后端读取素材并明确转成 data URL 后传入 DSL。本包不会自动绕过跨域限制或以占位内容替换读取失败的资源。
74
89
  - 默认嵌入音视频。视频支持 avi、mp4、m4v、mov、wmv；音频支持 mp3、m4a、mp4、wav、wma。URL 无后缀时填写元素 `ext`；data URL 可按明确的媒体 MIME 识别。格式不支持会报告页码和元素 ID。实际播放还取决于 Office/系统编解码器，原有 autoplay/loop 字段不额外映射。
75
90
  - 视频封面会转成 PNG 后写入 PPTX；音视频实际内容嵌入文件，不仅保留链接或封面。
76
91
  - 渐变／特殊形状、图片填充形状和有路径的公式使用 SVG 图片导出，不能当作原生可编辑形状／公式。无公式路径时沿用当前预览，输出公式源码文字。
92
+ - 标记为 `roundRect` 且路径为标准四角圆框或横向胶囊的普通形状导出为原生圆角矩形，按原路径半径设置 `rectRadius`，支持 Office/WPS 的黄色圆角调节手柄。仅顶部圆角、异形路径及拉伸后角弧为椭圆的形状保留自定义几何，不改变原形状。
93
+ - 闭合直线路径为左右对称、上底较窄且下底铺满 viewBox 的规则梯形导出为原生 `trapezoid`，按缩放后的上底内缩量设置调整参数，支持黄色手柄调整上底宽度／斜边倾斜。不对称梯形、三角形和曲线路径仍保留自定义几何。
77
94
  - 渐变页面背景取首尾色的混合色，渐变文字取显式色标平均色；普通图表使用原生可编辑图表，`bar` 横向、`column` 竖向。表格禁止自动拆成额外页面，保持选定页数；合并区域使用包含占位单元格的完整行列网格，导出时跳过被覆盖的单元格。
78
95
  - 默认母版背景取 `document.theme.backgroundColor`，省略时为白色；各页显式背景优先。不把主题字体、颜色自动下沉到所有元素。
79
96
  - 普通文本与形状文字的 `inset` 均按「上、右、下、左」解释，单位为 CSS 像素；默认分别为 0px、8px，与网页一致。两者均读取 `lineHeight`、`paragraphSpace`、`wordSpace`，默认行高 1.4、段距和字距为 0；富文本内显式的 `line-height`、`letter-spacing`、段落 `margin-top/bottom` 优先。行高按字号换算为 PPTX 点数，显式换行分别计算；Office 自动折行的混合字号段落仍可能与浏览器存在差异。
80
97
  - 字体栈取第一个字体名并进行 XML 属性转义，避免引号或 `&` 破坏 PPTX。图片背景按 `image.size` 导出：默认 `cover` 居中裁切，`contain` 等比完整显示，`stretch` 拉伸；背景图片作为最底层图片对象，留白使用页面背景色。
81
98
  - 富文本里的粗体细对勾 `✓` 导出为可编辑的重对勾 `✔`，避免浏览器字体回退与 Office 固定字体产生明显不同的字形；非粗体细对勾保持原字符。
82
99
  - 普通文本、标题及 `fixedHeight` 文本均保持 DSL 的位置和宽高，不再额外扩宽或设置 Office 自动改框。字体不一致导致的换行差异应通过字体环境核对，不能靠修改原框掩盖。
100
+ - 普通文本在网页中实际只有一行时关闭 Office 自动换行，避免大号章节数字被重新拆行；网页已折行、显式多行、列表和竖排保留自动换行。测量使用原字号、字体、字距和扣除左右内边距后的宽度，不改变输入 DSL 或导出文本框尺寸。
101
+ - 文字颜色保留 RGBA 的 alpha，包括默认颜色和富文本继承；显式子颜色使用自身的 alpha，并与元素 `opacity` 相乘。底图上的形状蒙层继续按原图层顺序和填充透明度导出。
83
102
  - 普通文本无显式换行、列表或段距，且行高等于扣除上下内边距后的框高时，按 HTML 的单行居中用法导出为原生垂直居中，不再保留整框高度的段落行距。多行、竖排及未撑满框高的正文保留原来的行距和对齐。
84
103
  - 选页导出的元素页内链接按输出页序重新定位；目标页不在范围时不生成该链接。导出支持 DSL 的主要几何、颜色和文字样式，不承诺与浏览器逐像素一致，也不保留浏览器的所有图片滤镜。
85
104
  - 字体依赖浏览器和打开 PPTX 的系统，不自动嵌入字体；生成成功不能代替 Office/WPS 中的实际视觉和媒体播放验收。
package/AGENT_USAGE.md CHANGED
@@ -4,8 +4,8 @@ Agent 先读取安装包内的 `node_modules/ppt-dsl-renderer/AGENT_USAGE.md`，
4
4
 
5
5
  ## 运行准备
6
6
 
7
- - Node.js 22+。部署时安装 `ppt-dsl-renderer`，使用包含当前 CLI 和渲染/导出产物的构建包；不在每个任务中临时安装包或执行 build。
8
- - HTML 生成不启动浏览器。仅使用 `export-pptx` 时，调用方需要显式安装可选 peer dependency `playwright-core@1.62.1`；只使用 HTML、Vue 或浏览器端 PPTX API 时不需要安装。
7
+ - Node.js 18+。部署时安装 `ppt-dsl-renderer`，使用包含当前 CLI 和渲染/导出产物的构建包；不在每个任务中临时安装包或执行 build。
8
+ - HTML 生成不启动浏览器。使用 `export-pptx` 或 `export-html-pptx` 时，调用方需要显式安装可选 peer dependency `playwright-core@1.61.1`；只使用 HTML、Vue 或浏览器端 PPTX API 时不需要安装。
9
9
  - PPTX CLI 使用运行机器上已安装的 Google Chrome/Chromium；`playwright-core` 不会下载浏览器。
10
10
  - 浏览器所需系统库、字体、素材访问权限及可写任务目录由部署方准备。
11
11
  - DSL 是完整 JSON 文件，不是命令行 JSON 字符串或 stdin。字段见 [DSL 文档](docs/DSL.md)，示例见 [deck.json](examples/deck.json)。相对路径以终端当前目录为基准，并发任务使用独立的输入/输出路径。
@@ -23,6 +23,7 @@ ppt-dsl-renderer render ./deck.json --out-dir ./preview
23
23
 
24
24
  # 导出全部页为一个 PPTX
25
25
  ppt-dsl-renderer export-pptx ./deck.json --out ./result.pptx
26
+ ppt-dsl-renderer export-html-pptx ./slides --out ./editable.pptx
26
27
 
27
28
  # 仅导出第 1、3 页
28
29
  ppt-dsl-renderer export-pptx ./deck.json --out ./selected.pptx --pages 1,3
@@ -30,13 +31,16 @@ ppt-dsl-renderer export-pptx ./deck.json --out ./selected.pptx --pages 1,3
30
31
 
31
32
  | 参数 | 适用命令 | 规则 |
32
33
  | --- | --- | --- |
33
- | `<deck.json>` | 两个命令 | 必填，完整 DSL 文件路径 |
34
+ | `<deck.json>` | `render`、`export-pptx` | 必填，完整 DSL 文件路径 |
35
+ | `<文件.html\|目录>` | `export-html-pptx` | 必填；目录只读取直接子级 `.html`，按文件名自然排序，一文件一页 |
34
36
  | `--out-dir <directory>` | `render` | 必填，HTML 输出目录 |
35
- | `--out <file.pptx>` | `export-pptx` | 必填，PPTX 文件路径，不能覆盖输入 DSL |
36
- | `--pages 1,3` | 两个命令 | 可选，默认全部页；从 1 开始，排序去重；越界、空列表和非整数报错 |
37
- | `--browser-executable <path>` | `export-pptx` | 可选，已有 Chromium 的程序路径；省略时使用已安装的 Google Chrome |
37
+ | `--out <file.pptx>` | 两个导出命令 | 必填，PPTX 文件路径，不能覆盖输入文件 |
38
+ | `--pages 1,3` | `render`、`export-pptx` | 可选，默认全部页；从 1 开始，排序去重；越界、空列表和非整数报错 |
39
+ | `--browser-executable <path>` | 两个导出命令 | 可选，已有 Chromium 的程序路径；省略时使用已安装的 Google Chrome |
40
+ | `--selector <css>` | `export-html-pptx` | 可选，指定幻灯片根节点；否则自动识别常见根节点，未识别时使用 `body` |
41
+ | `--assets-root <directory>` | `export-html-pptx` | 可选，仅在本地图片路径失效时从该目录查找；仍缺失或同名冲突时使用空白图 |
38
42
  | `--timeout <milliseconds>` | `export-pptx` | 可选，正整数，默认 120000；启动、生成阶段各自的超时，不是进程总时限 |
39
- | `--help` / `-h` | 两个命令 | 查看用法，不启动浏览器 |
43
+ | `--help` / `-h` | 三个命令 | 查看用法，不启动浏览器 |
40
44
 
41
45
  `--out` 与 `--out-dir` 不可混用。若帮助中没有 `export-pptx`，由部署方更新安装包；重复运行或改用 `--out-dir` 不能补上缺失命令。
42
46
 
@@ -78,6 +82,22 @@ CLI 成功只表示文件生成成功。需要截图时打开 HTML，按 [渲染
78
82
 
79
83
  不必先执行 `render` 或启动网页服务。CLI 每次新建无头浏览器，加载包内 `dist/pptx/exporter.js`，调用原 `window.exportToPptx`；正常完成或生成失败后关闭本次实例。`--browser-executable` 只指定浏览器程序，不接受 Playwright 包目录或连接地址，也不复用后端已运行的浏览器。
80
84
 
85
+ ### 普通 HTML 转 PPTX
86
+
87
+ `export-html-pptx` 独立读取普通 HTML 文件或目录，不读取 DSL JSON，也不要求 `render` 先运行。输出清单示例：
88
+
89
+ ```json
90
+ {
91
+ "file": "/work/ppt-task/editable.pptx",
92
+ "pages": [{ "pageNumber": 1, "sourceFile": "/work/ppt-task/slides/01.html" }],
93
+ "bytes": 12345,
94
+ "objects": { "rendered-text": 12, "shape": 8, "border-strip": 2 },
95
+ "imagePlaceholders": [{ "pageNumber": 1, "sourceFile": "/work/ppt-task/slides/01.html", "src": "file:///work/ppt-task/slides/missing.png", "reason": "not_found" }]
96
+ }
97
+ ```
98
+
99
+ HTML 中相对图片路径先按 HTML 文件位置解析。只有显式传入 `--assets-root` 时才搜索失效的本地图片；仍缺失、找到多个同名候选或图片无法加载时使用透明空白图，保持图片区域，并在 `imagePlaceholders` 中列出原路径和原因（`not_found`、`ambiguous`、`invalid_path`、`load_failed`）。没有替换时该数组为空。该命令不使用 `--pages` 或 `--timeout`，不会扫描默认 Desktop。文字与主要形状可编辑；照片、SVG 和复杂背景保留为局部图片。不同 Office 渲染器的字体与圆角效果可能有差异，不承诺逐像素一致。
100
+
81
101
  CLI 只返回最终清单，不提供结构化实时进度。生成成功不等于已通过 Office/WPS 视觉验收。
82
102
 
83
103
  ## 失败处理
@@ -85,4 +105,4 @@ CLI 只返回最终清单，不提供结构化实时进度。生成成功不等
85
105
  - 退出码为 1：读取 stderr，不返回成功清单。PPTX 生成后才替换目标，失败保留原文件；不能因同名旧文件存在就报告本次成功。
86
106
  - 缺少命令、产物或浏览器：由部署方修正版本/环境，不擅自安装浏览器、执行 build 或更改安全设置。
87
107
  - 参数或 DSL 错误：按错误修正输入；不要用其他字段或参数隐式替代。
88
- - 素材错误：检查运行机器的网络、权限及空白页面跨域访问条件，或由调用方明确提供 data URL；不要静默替换或丢弃素材。
108
+ - DSL 素材错误：检查运行机器的网络、权限及空白页面跨域访问条件，或由调用方明确提供 data URL；`export-html-pptx` 的缺图以 `imagePlaceholders` 返回。
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  提供浏览器侧标准可编辑 PPTX 生成方法，返回完整 ArrayBuffer，默认全部页，可指定页码，保留音视频并应用默认母版。后端通过统一 CLI 直接保存 PPTX。
6
6
 
7
- 运行要求：Node.js 22+；Vue 接入要求 Vue 3.4.21+（3.x）；浏览器需要支持现代 DOM、SVG、Canvas。
7
+ 运行要求：Node.js 18+；Vue 接入要求 Vue 3.4.21+（3.x）；浏览器需要支持现代 DOM、SVG、Canvas。
8
8
 
9
9
  ## 安装
10
10
 
@@ -14,10 +14,10 @@
14
14
  yarn add ppt-dsl-renderer
15
15
  ```
16
16
 
17
- Vue 渲染、Node HTML 生成和浏览器端 PPTX 导出只需安装主包。仅后端使用 `export-pptx` CLI 时，还需由调用方显式安装浏览器驱动：
17
+ Vue 渲染、Node HTML 生成和浏览器端 PPTX 导出只需安装主包。后端使用任一 PPTX CLI 导出命令时，还需由调用方显式安装浏览器驱动：
18
18
 
19
19
  ```bash
20
- yarn add ppt-dsl-renderer playwright-core@1.62.1
20
+ yarn add ppt-dsl-renderer playwright-core@1.61.1
21
21
  ```
22
22
 
23
23
  `playwright-core` 是可选 peer dependency，不会随主包自动安装，也不会下载浏览器。CLI 仍要求部署机器已有 Google Chrome/Chromium。
@@ -28,11 +28,12 @@ yarn add ppt-dsl-renderer playwright-core@1.62.1
28
28
  ppt-dsl-renderer --help
29
29
  ppt-dsl-renderer render ./deck.json --out-dir ./preview
30
30
  ppt-dsl-renderer export-pptx ./deck.json --out ./result.pptx
31
+ ppt-dsl-renderer export-html-pptx ./slides --out ./editable.pptx
31
32
  ```
32
33
 
33
- 仅在当前项目安装时，使用 `./node_modules/.bin/ppt-dsl-renderer`。PPTX CLI 通过调用方显式安装的 `playwright-core@1.62.1` 启动已有 Chrome/Chromium，每次创建新实例，不复用后端正在运行的浏览器；不改变原导出算法。
34
+ 仅在当前项目安装时，使用 `./node_modules/.bin/ppt-dsl-renderer`。PPTX CLI 通过调用方显式安装的 `playwright-core@1.61.1` 启动已有 Chrome/Chromium，不复用后端正在运行的浏览器；原 DSL 导出算法保持不变。
34
35
 
35
- Agent 先读 [统一调用指南](AGENT_USAGE.md)，其中集中说明运行前提、全部参数、JSON 返回值及失败处理。后端子进程调用、浏览器生命周期和修改范围见 [PPTX 后端接入](AGENT_PPTX_EXPORT.md)。两份文档随 npm 包发布。
36
+ Agent 先读 [统一调用指南](AGENT_USAGE.md)，其中集中说明运行前提、全部参数、JSON 返回值及失败处理。`export-html-pptx` 接受普通 HTML 文件或目录，独立于 DSL 导出；后端子进程调用和浏览器生命周期见 [PPTX 后端接入](AGENT_PPTX_EXPORT.md)。两份文档随 npm 包发布。
36
37
 
37
38
  ## Node API
38
39
 
package/THIRD_PARTY_NOTICES.md CHANGED
@@ -26,7 +26,7 @@ The PPTX exporter is implemented against this package's DSL and the public PptxG
26
26
  | --- | --- | --- |
27
27
  | pptxgenjs | 3.12.0 | MIT |
28
28
  | tinycolor2 | 1.6.0 | MIT |
29
- | svg-pathdata | 7.2.0 | MIT |
29
+ | svg-pathdata | 6.0.3 | MIT |
30
30
  | jszip | 3.10.1 | (MIT OR GPL-3.0-or-later) |
31
31
  | pako | 1.0.11 | (MIT AND Zlib) |
32
32
  | lie | 3.3.0 | MIT |
@@ -41,3 +41,5 @@ The PPTX exporter is implemented against this package's DSL and the public PptxG
41
41
  | isarray | 1.0.0 | MIT |
42
42
 
43
43
  Node-only PptxGenJS dependencies such as image-size and https are excluded by its browser mapping. DOMPurify's notice above also applies to export text sanitization.
44
+
45
+ 普通 HTML 的 Node CLI 单独使用 npm 别名 `pptxgenjs-html`（PptxGenJS 4.0.1，MIT）；它不进入浏览器导出 bundle，原 DSL 导出仍使用表中的 3.12.0。`playwright-core@1.61.1` 是调用方显式安装的可选 peer dependency，使用本机 Chrome/Chromium，不随本包下载浏览器。