Anthropic PPTX 技能深度解析（二）：PptxGenJS

一、从零创建工作流

当无可用 PPTX 模板时，Anthropic 技能采用 PptxGenJS 库在 Node.js 环境中从头创建演示文稿。该工作流包含三个阶段：初始化、元素添加与文件写入。

初始化阶段：通过 const pptxgen = require("pptxgenjs") 创建 PptxGenJS 实例，设定布局规格、作者信息与标题元数据。布局规格提供四种选项：LAYOUT_16x9（10 英寸 x 5.625 英寸，默认）、LAYOUT_16x10（10 英寸 x 6.25 英寸）、LAYOUT_4x3（10 英寸 x 7.5 英寸）与 LAYOUT_WIDE（13.3 英寸 x 7.5 英寸）。布局选择取决于目标展示场景。标题幻灯片可通过 slide.background 设置纯色或图片背景。每个元素的位置参数 x 和 y 以英寸为单位，原点位于幻灯片左上角。——16:9 宽屏适合现代商务演示，4:3 适合传统教育或投影设备。元数据字段包括 pres.author 与 pres.title，写入后可在 PPTX 文件属性的详细信息中查看。

元素添加阶段通过多个 API 逐元素构建幻灯片。slide.addText() 接受字符串或富文本数组，slide.addShape() 绘制基本几何图形，slide.addImage() 嵌入图片，slide.addTable() 创建数据表格，slide.addChart() 生成统计图表。位置参数以英寸为单位的浮点数指定，原点位于幻灯片左上角。图标生成采用三段式技术管线：通过 react-icons 库渲染 SVG 图标，经 sharp 库栅格化为 PNG（推荐 256px 以上分辨率），以 base64 数据 URI 形式嵌入幻灯片。文件写入阶段调用 pres.writeFile({ fileName: "output.pptx" }) 完成生成。每份演示文稿须使用全新 PptxGenJS 实例，禁止复用前序实例对象以避免内部状态污染。若需生成多份不同主题或布局的演示文稿，须分别为每份创建独立的 PptxGenJS 实例，各实例之间互不影响。

二、PptxGenJS 核心 API 详解

2.1 文本与格式化

文本模块支持三种使用形态：纯文本字符串用于简单标题或标注；富文本数组通过 [{text: "内容", options: {bold: true, italic: true, color: "363636"}}] 结构独立控制每段的加粗、斜体、颜色与字号，同一文本框内可包含多种格式；项目符号列表使用 bullet: true 布尔属性实现圆点列表（禁止使用 Unicode 点字符·），bullet: { type: "number" } 实现编号列表，indentLevel 控制缩进层级（从 0 开始）。子项目与主项目之间的间距由 paraSpaceAfter 参数统一控制。多段文本数组元素间须使用 breakLine: true 属性显式声明换行，最后一项不需要该属性。文本框中默认可设置 margin: 0 消除内边距——当文字需要与相邻形状或图标精确对齐时，此设置至关重要。字符间距使用 charSpacing 属性，letterSpacing 会被静默忽略。字体通过 fontFace 指定，字号通过 fontSize 设置。对齐方式通过 align 和 valign 组合控制，段落间距通过 paraSpaceBefore 与 paraSpaceAfter 调节，替代不兼容项目符号的 lineSpacing 属性。文本对齐选项支持水平对齐 left、center、right 与垂直对齐 top、middle、bottom 的组合配置，用于控制文字在文本框内的精确位置。字体颜色以六位十六进制字符串指定，与形状和图表保持统一的色彩编码规范。字号增量单位为半磅值——例如 fontSize: 36 对应 36 磅。幻灯片标题通常使用 36-44pt，正文使用 14-16pt，标注文字使用 10-12pt。加粗通过 bold: true 实现，斜体通过 italic: true 实现，下划线通过 underline: true 实现。字符间距 charSpacing 以磅为单位，正值增大间距，负值缩小间距。

2.2 形状模块

形状模块支持 RECTANGLE、OVAL、LINE、ROUNDED_RECTANGLE 四种基本图形。RECTANGLE 是最常用的容器形状，适合卡片、背景框与色块。OVAL 适合图标圆形衬底或装饰元素。LINE 支持设置 dashType 虚线样式以区分不同类型的连线。ROUNDED_RECTANGLE 的圆角半径通过 rectRadius 属性控制，但须注意其圆角覆盖区域与直角边框无法完全吻合——因此不应与直角装饰边框配对使用。所有形状均支持填充色（含 transparency 透明度 0-100）、边框色与边框宽度设置。阴影参数系统包含五个维度：type（outer 外阴影或 inner 内阴影）、blur（0-100pt）、offset（仅非负值，负值导致文件损坏）、angle（0-359 度）、opacity（0.0-1.0）。阴影向上投射（如页脚栏的上方阴影）使用 angle: 270 配合正 offset 实现。渐变填充不被 PptxGenJS 原生支持，须以渐变图片作为背景组件替代。图片背景可通过 slide.background 传入 base64 数据或文件路径实现，适用于需要复杂渐变效果的封面或章节过渡页。

2.3 图表模块

图表模块支持 BAR（柱状图）、LINE（折线图）、PIE（饼图）、DOUGHNUT（环形图）、SCATTER（散点图）、BUBBLE（气泡图）、RADAR（雷达图）七种类型。技能内置现代风格预设参数以替代默认的过时样式：chartColors 数组自定义系列色（使用演示文稿主色调）；catAxisLabelColor 与 valAxisLabelColor 控制坐标轴标签色调为柔和的灰色；catGridLine 设置为 { style: "none" } 隐藏分类轴网格线；valGridLine 设定浅色网格线；dataLabelPosition 取 "outEnd" 在数据点外端显示数值标签；showLegend: false 在单系列时隐藏图例；chartArea 设置白色填充与圆角。折线图可通过 lineSmooth: true 启用曲线拟合。

2.4 表格模块

表格模块通过 slide.addTable() 创建，数据以二维数组 [["行1列1", "行1列2"], ["行2列1", "行2列2"]] 传递。单元格完整支持跨列合并（colspan）和跨行合并（rowspan），通过 [{text: "合并单元格", options: {colspan: 2}}] 结构实现。每个单元格可独立设置填充色 fill、字体色 color、加粗 bold 与字号 fontSize。表格整体边框通过 border 参数统一设置粗细与颜色，列宽通过 colW 数组以英寸为单位指定。表头行可通过独立的 fill 与 bold 属性与其他数据行区分。表格默认无边框显示，须通过 border 参数显式设置粗细与颜色。单元格内文本的水平和垂直对齐方式与普通文本框保持一致规则。

2.5 图片模块

图片模块支持三种来源。若使用本地路径且需保持原始宽高比，可通过原始宽度与高度计算渲染尺寸以精确适配幻灯片区域，避免图片拉伸变形影响视觉效果。：本地文件路径 {path: "images/chart.png"}、远程 URL {path: "https://example.com/image.jpg"} 和 base64 数据 URI {data: "image/png;base64,..."}。三种尺寸适配模式分别为 contain（保持比例适配容器，可能留白）、cover（保持比例填充容器，可能裁剪）、crop（裁切指定区域）。附加属性包括旋转角度 rotate（0-359 度）、圆形裁剪 rounding（布尔值）、透明度 transparency（0-100）和翻转 flipH/flipV。推荐使用 base64 方式嵌入图片以获得最快加载速度——避免文件 I/O 操作和网络请求。

2.6 图标生成管线

图标采用三段式技术管线。首先通过 react-icons 库中的 SVG 组件配合 ReactDOMServer.renderToStaticMarkup 渲染为 SVG 字符串。常用图标集包括 react-icons/fa（Font Awesome）、react-icons/md（Material Design）、react-icons/hi（Heroicons）、react-icons/bi（Bootstrap Icons）。其次通过 sharp 库将 SVG 栅格化为 PNG 缓冲区，推荐使用 256px 以上分辨率以保证渲染清晰度。最后将 PNG 转换为 base64 数据 URI，以 slide.addImage({ data: "image/png;base64,编码字符串", x: 1, y: 1, w: 0.5, h: 0.5 }) 嵌入幻灯片。

2.7 幻灯片母版

幻灯片母版机制允许通过 pres.defineSlideMaster() 预先定义全局布局模板，包含背景色、标题占位符与内容占位符的定义。添加幻灯片时通过 { masterName: "TITLE_SLIDE" } 引用对应母版，可通过 placeholder: "title" 属性将标题或正文内容自动定位到母版预留的占位符区域。该机制适用于在多张幻灯片间保持标题位置、页脚样式与品牌标识一致的场景。母版中定义的占位符可设置 name、type（title 或 body）、position 与尺寸属性，在添加幻灯片时通过 placeholder 属性名将内容自动填充到对应占位符区域。若需在全部幻灯片底部统一添加页码或公司标志，母版是最优方案——只需在母版中定义一次即对所有引用该母版的幻灯片生效，避免逐张重复添加。

三、依赖链与开发环境配置

3.1 Node.js 依赖

PptxGenJS 路径的 Node.js 依赖包括：pptxgenjs（演示文稿生成引擎）、react-icons（图标组件库）、react 与 react-dom（SVG 渲染）、sharp（PNG 栅格化）。安装命令为 npm install -g pptxgenjs react-icons react react-dom sharp。

3.2 辅助依赖

辅助依赖包括 Python 层的 markitdown[pptx] 用于生成文件的文本提取与内容验证，以及系统工具层的 LibreOffice soffice 与 pdftoppm 用于渲染图像检查。

四、常见陷阱与规避方案

技能文档记录了 PptxGenJS 特有的若干高频错误。十六进制颜色字符串禁止使用 # 前缀——正确的写法是 "FF0000" 而非 "#FF0000"，否则导致文件损坏且难以调试。透明度不得编码为 8 位颜色字符串，须通过 opacity 属性分离声明。阴影 offset 参数禁止使用负值。选项对象禁止在多次 API 调用间复用——PptxGenJS 在首次调用时会将其中的数值属性就地转换为 EMU 单位。ROUNDED_RECTANGLE 不得与直角装饰边框配对。letterSpacing 无效须改用 charSpacing。lineSpacing 与项目符号共用时会导致过大间距，应改用 paraSpaceAfter。背景色在 slide.background 中设置而非通过形状覆盖实现。

共用规范要求每个 PptxGenJS 实例仅对应一份演示文稿文件，不可重复写入。