feat: add reference docs for shape, table, image, chart, slide, master, output, coordinate

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-23 12:36:09 +08:00
parent 768ac12740
commit 17d232dcef
9 changed files with 2618 additions and 0 deletions
@@ -0,0 +1,222 @@
+# 幻灯片参数 (Slide Props)
+
+幻灯片相关类型包括 `Slide` 类、`PresSlide` 接口和 `BackgroundProps`，通过 `pptx.addSlide()` 创建。
+
+---
+
+## 添加幻灯片 (addSlide)
+
+```ts
+pptx.addSlide(props?: AddSlideProps): PptxGenJS.Slide
+```
+
+### AddSlideProps
+
+- **masterName**：母版名称
+  - 类型：`string`
+  - 说明：使用已定义的 Slide Master 名称
+
+- **sectionTitle**：节标题
+  - 类型：`string`
+  - 说明：将幻灯片添加到指定节
+
+---
+
+## Slide 类属性
+
+- **background**：幻灯片背景
+  - 类型：`BackgroundProps`
+  - 说明：背景颜色或图片
+
+- **color**：默认文字颜色
+  - 类型：`HexColor`
+  - 格式：6 位十六进制（无 `#`）
+  - 默认值：`'000000'`
+
+- **hidden**：幻灯片是否隐藏
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **slideNumber**：幻灯片编号选项
+  - 类型：`SlideNumberProps`
+
+- **newAutoPagedSlides**：自动分页创建的新幻灯片
+  - 类型：`PresSlide[]`
+
+---
+
+## Slide 类方法
+
+- **addChart(type, data, options?)**
+  - 说明：添加图表
+  - 参数：
+    - `type`：`CHART_NAME | IChartMulti[]`
+    - `data`：`any[]`
+    - `options?`：`IChartOpts`
+  - 返回：`Slide`
+
+- **addImage(options)**
+  - 说明：添加图片
+  - 参数：`options` — `ImageProps`
+  - 返回：`Slide`
+
+- **addMedia(options)**
+  - 说明：添加媒体（音频/视频）
+  - 参数：`options` — `MediaProps`
+  - 返回：`Slide`
+
+- **addNotes(notes)**
+  - 说明：添加演讲者备注
+  - 参数：`notes` — `string`
+  - 返回：`Slide`
+
+- **addShape(shapeName, options?)**
+  - 说明：添加形状
+  - 参数：
+    - `shapeName`：`SHAPE_NAME`
+    - `options?`：`ShapeProps`
+  - 返回：`Slide`
+
+- **addTable(tableRows, options?)**
+  - 说明：添加表格
+  - 参数：
+    - `tableRows`：`TableRow[]`
+    - `options?`：`TableProps`
+  - 返回：`Slide`
+
+- **addText(text, options?)**
+  - 说明：添加文字
+  - 参数：
+    - `text`：`string | TextProps[]`
+    - `options?`：`TextPropsOptions`
+  - 返回：`Slide`
+
+---
+
+## PresSlide 接口
+
+`PresSlide` 为内部幻灯片表示，包含以下属性和方法：
+
+- **addChart**：添加图表
+  - 类型：`Function`
+
+- **addImage**：添加图片
+  - 类型：`Function`
+
+- **addMedia**：添加媒体
+  - 类型：`Function`
+
+- **addNotes**：添加备注
+  - 类型：`Function`
+
+- **addShape**：添加形状
+  - 类型：`Function`
+
+- **addTable**：添加表格
+  - 类型：`Function`
+
+- **addText**：添加文字
+  - 类型：`Function`
+
+- **background**：背景
+  - 类型：`BackgroundProps`
+
+- **color**：默认文字颜色
+  - 类型：`HexColor`
+
+- **hidden**：是否隐藏
+  - 类型：`boolean`
+
+- **slideNumber**：幻灯片编号
+  - 类型：`SlideNumberProps`
+
+---
+
+## BackgroundProps
+
+继承 `DataOrPathProps`（`path`、`data`）和 `ShapeFillProps`（`color`、`transparency`、`type`）。
+
+- **path**：背景图片 URL 或本地路径
+  - 类型：`string`
+  - 示例：`'https://onedrives.com/myimg.png'`
+
+- **data**：背景图片 base64 数据
+  - 类型：`string`
+  - 示例：`'image/png;base64,iVtDafDrBF[...]='`
+
+- **color**：背景颜色
+  - 类型：`Color`（来自 ShapeFillProps）
+  - 格式：6 位十六进制（无 `#`）或主题色
+
+- **transparency**：背景透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`
+  - 默认值：`0`
+
+- **type**：填充类型
+  - 类型：`'none' | 'solid'`
+  - 默认值：`'solid'`
+
+---
+
+## SlideNumberProps
+
+继承 `PositionProps` 和 `TextBaseProps`。
+
+- **margin**：边距
+  - 类型：`Margin`（`number | [number, number, number, number]`）
+  - 单位：pt
+
+---
+
+## 幻灯片布局 (PresLayout)
+
+```ts
+pptx.defineLayout(layout: PresLayout)
+```
+
+- **name**：布局名称
+  - 类型：`string`
+  - 示例：`'LAYOUT_WIDE'`
+
+- **width**：宽度
+  - 类型：`number`
+  - 单位：英寸
+
+- **height**：高度
+  - 类型：`number`
+  - 单位：英寸
+
+### 标准布局尺寸
+
+| 常量名 | 宽度 | 高度 |
+|---|---|---|
+| `LAYOUT_4x3` | 10" | 7.5" |
+| `LAYOUT_16x9` | 10" | 5.625" |
+| `LAYOUT_16x10` | 10" | 6.25" |
+| `LAYOUT_WIDE` | 13.33" | 7.5" |
+
+---
+
+## 节属性 (SectionProps)
+
+```ts
+pptx.addSection(props: SectionProps)
+```
+
+- **title**：节标题
+  - 类型：`string`
+
+- **order**：节顺序
+  - 类型：`number`
+  - 取值范围：`1`–`n`
+  - 说明：在指定索引添加节
+
+---
+
+## 已废弃参数 (BackgroundProps)
+
+| 已废弃参数 | 替代参数 | 废弃版本 |
+|---|---|---|
+| `fill` | `ShapeFillProps.color` | v3.6.0 |
+| `src` | `DataOrPathProps.path` | v3.6.0 |