# 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' });
```