From ba8d17ba62711ea6d4083fbcb16fb30c34356bdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E8=BF=9B?= Date: Thu, 23 Jul 2026 12:00:19 +0800 Subject: [PATCH] add: pptxgenjs v4.0.1 full API reference --- PPTXGENJS_API.md | 451 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 451 insertions(+) create mode 100644 PPTXGENJS_API.md diff --git a/PPTXGENJS_API.md b/PPTXGENJS_API.md new file mode 100644 index 0000000..0b801bc --- /dev/null +++ b/PPTXGENJS_API.md @@ -0,0 +1,451 @@ +# PptxGenJS v4.0.1 完整 API 参考 + +> 从 TypeScript 类型定义生成 + +## 1. 初始化 + +```javascript +const pptxgen = require('pptxgenjs'); +const pres = new pptxgen(); +``` + +## 2. 布局设置 + +```javascript +// 自定义布局 +pres.defineLayout({ name: 'CUSTOM', width: 10, height: 5.625 }); +pres.layout = 'CUSTOM'; + +// 预设布局 +// 'LAYOUT_16x9' (10x5.63) +// 'LAYOUT_4x3' (10x7.5) +// 'LAYOUT_16x10' (10x6.25) +// 'LAYOUT_WIDE' (13.33x7.5) +``` + +## 3. Slide 管理 + +```typescript +interface PresSlide { + addChart() + addImage() + addMedia() + addNotes() + addShape() + addTable() + addText() +} +``` + +## 4. addText — 核心方法 + +```javascript +slide.addText(text, options); +// text: string | number | Array<{text, options}> +// options: TextPropsOptions +``` + +### 位置 (继承自 PositionProps) + +| 属性 | 类型 | 说明 | 默认值 | +|------|------|------|--------| + +### 文本样式 (继承自 TextBaseProps) + +| 属性 | 类型 | 说明 | 默认值 | +|------|------|------|--------| + +### TextPropsOptions 特有属性 + +| 属性 | 类型 | 说明 | 默认值 | +|------|------|------|--------| + +## 5. 图片 + +```javascript +slide.addImage({ + path: '/path/to/image.png', // 本地路径或URL + data: 'image/png;base64,...', // 或 base64 + x: 1, y: 1, w: 8, h: 4.5 +}); +``` + +## 6. 形状 + +```typescript +type SHAPE_NAME = | 'accentBorderCallout1' + | 'accentBorderCallout2' + | 'accentBorderCallout3' + | 'accentCallout1' + | 'accentCallout2' + | 'accentCallout3' + | 'actionButtonBackPrevious' + | 'actionButtonBeginning' + | 'actionButtonBlank' + | 'actionButtonDocument' + | 'actionButtonEnd' + | 'actionButtonForwardNext' + | 'actionButtonHelp' + | 'actionButtonHome' + | 'actionButtonInformation' + | 'actionButtonMovie' + | 'actionButtonReturn' + | 'actionButtonSound' + | 'arc' + | 'bentArrow' + | 'bentUpArrow' + | 'bevel' + | 'blockArc' + | 'borderCallout1' + | 'borderCallout2' + | 'borderCallout3' + | 'bracePair' + | 'bracketPair' + | 'callout1' + | 'callout2' + | 'callout3' + | 'can' + | 'chartPlus' + | 'chartStar' + | 'chartX' + | 'chevron' + | 'chord' + | 'circularArrow' + | 'cloud' + | 'cloudCallout' + | 'corner' + | 'cornerTabs' + | 'cube' + | 'curvedDownArrow' + | 'curvedLeftArrow' + | 'curvedRightArrow' + | 'curvedUpArrow' + | 'decagon' + | 'diagStripe' + | 'diamond' + | 'dodecagon' + | 'donut' + | 'doubleWave' + | 'downArrow' + | 'downArrowCallout' + | 'ellipse' + | 'ellipseRibbon' + | 'ellipseRibbon2' + | 'flowChartAlternateProcess' + | 'flowChartCollate' + | 'flowChartConnector' + | 'flowChartDecision' + | 'flowChartDelay' + | 'flowChartDisplay' + | 'flowChartDocument' + | 'flowChartExtract' + | 'flowChartInputOutput' + | 'flowChartInternalStorage' + | 'flowChartMagneticDisk' + | 'flowChartMagneticDrum' + | 'flowChartMagneticTape' + | 'flowChartManualInput' + | 'flowChartManualOperation' + | 'flowChartMerge' + | 'flowChartMultidocument' + | 'flowChartOfflineStorage' + | 'flowChartOffpageConnector' + | 'flowChartOnlineStorage' + | 'flowChartOr' + | 'flowChartPredefinedProcess' + | 'flowChartPreparation' + | 'flowChartProcess' + | 'flowChartPunchedCard' + | 'flowChartPunchedTape' + | 'flowChartSort' + | 'flowChartSummingJunction' + | 'flowChartTerminator' + | 'folderCorner' + | 'frame' + | 'funnel' + | 'gear6' + | 'gear9' + | 'halfFrame' + | 'heart' + | 'heptagon' + | 'hexagon' + | 'homePlate' + | 'horizontalScroll' + | 'irregularSeal1' + | 'irregularSeal2' + | 'leftArrow' + | 'leftArrowCallout' + | 'leftBrace' + | 'leftBracket' + | 'leftCircularArrow' + | 'leftRightArrow' + | 'leftRightArrowCallout' + | 'leftRightCircularArrow' + | 'leftRightRibbon' + | 'leftRightUpArrow' + | 'leftUpArrow' + | 'lightningBolt' + | 'line' + | 'lineInv' + | 'mathDivide' + | 'mathEqual' + | 'mathMinus' + | 'mathMultiply' + | 'mathNotEqual' + | 'mathPlus' + | 'moon' + | 'noSmoking' + | 'nonIsoscelesTrapezoid' + | 'notchedRightArrow' + | 'octagon' + | 'parallelogram' + | 'pentagon' + | 'pie' + | 'pieWedge' + | 'plaque' + | 'plaqueTabs' + | 'plus' + | 'quadArrow' + | 'quadArrowCallout' + | 'rect' + | 'ribbon' + | 'ribbon2' + | 'rightArrow' + | 'rightArrowCallout' + | 'rightBrace' + | 'rightBracket' + | 'round1Rect' + | 'round2DiagRect' + | 'round2SameRect' + | 'roundRect' + | 'rtTriangle' + | 'smileyFace' + | 'snip1Rect' + | 'snip2DiagRect' + | 'snip2SameRect' + | 'snipRoundRect' + | 'squareTabs' + | 'star10' + | 'star12' + | 'star16' + | 'star24' + | 'star32' + | 'star4' + | 'star5' + | 'star6' + | 'star7' + | 'star8' + | 'stripedRightArrow' + | 'sun' + | 'swooshArrow' + | 'teardrop' + | 'trapezoid' + | 'triangle' + | 'upArrow' + | 'upArrowCallout' + | 'upDownArrow' + | 'upDownArrowCallout' + | 'uturnArrow' + | 'verticalScroll' + | 'wave' + | 'wedgeEllipseCallout' + | 'wedgeRectCallout' + | 'wedgeRoundRectCallout' + + export enum SLIDE_OBJECT_TYPES { + 'chart' = 'chart', + 'hyperlink' = 'hyperlink', + 'image' = 'image', + 'media' = 'media', + 'online' = 'online', + 'placeholder' = 'placeholder', + 'table' = 'table', + 'tablecell' = 'tablecell', + 'text' = 'text', + 'notes' = 'notes', + } + export enum TEXT_HALIGN { + 'left' = 'left', + 'center' = 'center', + 'right' = 'right', + 'justify' = 'justify', + } + export enum TEXT_VALIGN { + 'b' = 'b', + 'ctr' = 'ctr', + 't' = 't', + } + + // @source `core-interfaces.d.ts` (direct) + // Core Types + // ========== + + /** + * Coordinate number - either: + * - Inches (0-n) + * - Percentage (0-100) + * + * @example 10.25 // coordinate in inches + * @example '75%' // coordinate as percentage of slide size + */ + export type Coord = number | `${number}%` + export interface PositionProps { + /** + * Horizontal position + * - inches or percentage + * @example 10.25 // position in inches + * @example '75%' // position as percentage of slide size + */ + x?: Coord + /** + * Vertical position + * - inches or percentage + * @example 10.25 // position in inches + * @example '75%' // position as percentage of slide size + */ + y?: Coord + /** + * Height + * - inches or percentage + * @example 10.25 // height in inches + * @example '75%' // height as percentage of slide size + */ + h?: Coord + /** + * Width + * - inches or percentage + * @example 10.25 // width in inches + * @example '75%' // width as percentage of slide size + */ + w?: Coord + } + /** + * Either `data` or `path` is required + */ + export interface DataOrPathProps { + /** + * URL or relative path + * + * @example 'https://onedrives.com/myimg.png` // retrieve image via URL + * @example '/home/gitbrent/images/myimg.png` // retrieve image via local path + */ + path?: string + /** + * base64-encoded string + * - Useful for avoiding potential path/server issues + * + * @example 'image/png; +``` + +```javascript +slide.addShape(pres.ShapeType.rect, { + x: 1, y: 1, w: 8, h: 4, + fill: { color: '0088CC' }, + line: { color: '0055AA', width: 2 } +}); +``` + +## 7. 表格 + +```javascript +slide.addTable([ + [ + { text: 'Header 1', options: { bold: true, color: 'FFFFFF' } }, + { text: 'Header 2', options: { bold: true, color: 'FFFFFF' } } + ], + [ + { text: 'Row 1 Col 1' }, + { text: 'Row 1 Col 2' } + ] +], { + x: 1, y: 1, w: 8, + border: { type: 'solid', color: 'CCCCCC', pt: 1 }, + colW: [4, 4] +}); +``` + +## 8. 图表 + +```javascript +slide.addChart(pres.ChartType.bar, [ + { + name: 'Sales', + labels: ['Q1', 'Q2', 'Q3', 'Q4'], + values: [100, 200, 150, 300] + } +], { + x: 1, y: 1, w: 8, h: 4 +}); +``` + +## 9. 输出 + +```javascript +// 保存到文件 +pres.writeFile({ fileName: 'output.pptx' }); + +// 浏览器下载 +pres.write({ outputType: 'blob' }); +pres.write({ outputType: 'arraybuffer' }); +pres.write({ outputType: 'dataUrl' }); + +// Node stream +pres.stream(); +``` + +## 10. 坐标换算 + +PptxGenJS 使用英寸作为单位。 + +| 单位 | 换算 | +|------|------| +| 1 英寸 | 1.0 | +| 1 厘米 | 0.3937 英寸 | +| CSS px (96dpi) | px / 96 英寸 | +| PPT pt (72dpi) | pt / 72 英寸 | + +常用：`pxToInches = px / 96` + +## 11. 完整示例 + +```javascript +const pptxgen = require('pptxgenjs'); +const pres = new pptxgen(); + +// 16:9 布局 +pres.defineLayout({ name: 'CUSTOM', width: 10, height: 5.625 }); +pres.layout = 'CUSTOM'; +pres.author = 'LiJin'; +pres.title = 'Presentation'; + +// 第一页 +let slide = pres.addSlide(); +slide.background = { fill: '1A1A2E' }; +slide.addText('Title Slide', { + x: 1, y: 1.5, w: 8, h: 1, + fontSize: 44, color: 'FFFFFF', bold: true, + align: 'center', fontFace: 'Arial' +}); +slide.addText('Subtitle', { + x: 1, y: 3, w: 8, h: 0.5, + fontSize: 18, color: 'AAAAAA', + align: 'center' +}); + +// 第二页 +slide = pres.addSlide(); +slide.background = { fill: 'FFFFFF' }; +slide.addText('Content Page', { + x: 0.5, y: 0.3, w: 9, h: 0.6, + fontSize: 28, bold: true +}); +slide.addText([ + { text: 'Bullet 1\n', options: { fontSize: 18, bullet: true } }, + { text: 'Bullet 2\n', options: { fontSize: 18, bullet: true } }, + { text: 'Bullet 3', options: { fontSize: 18, bullet: true } } +], { + x: 0.5, y: 1.5, w: 5, h: 2 +}); + +pres.writeFile({ fileName: 'demo.pptx' }); +```