452 lines
8.8 KiB
Markdown
452 lines
8.8 KiB
Markdown
# 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' });
|
|
```
|