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,127 @@
+# 母版参数 (Master Props)
+
+母版参数来自 `SlideMasterProps`，通过 `pptx.defineSlideMaster()` 定义幻灯片母版（布局）。
+
+---
+
+## SlideMasterProps
+
+- **title**：母版唯一名称
+  - 类型：`string`
+  - 说明：母版的唯一标识名，`addSlide({ masterName })` 时引用
+
+- **background**：母版背景
+  - 类型：`BackgroundProps`
+  - 说明：背景颜色或图片，继承 `DataOrPathProps` 和 `ShapeFillProps`
+  - 子参数：
+    - **background.color**：背景颜色
+      - 类型：`Color`
+    - **background.transparency**：透明度
+      - 类型：`number`
+      - 取值范围：`0`–`100`
+    - **background.path**：背景图片 URL 或本地路径
+      - 类型：`string`
+    - **background.data**：背景图片 base64 数据
+      - 类型：`string`
+
+- **margin**：母版边距
+  - 类型：`Margin`（`number | [number, number, number, number]`）
+  - 单位：pt
+
+- **slideNumber**：幻灯片编号
+  - 类型：`SlideNumberProps`
+  - 说明：继承 `PositionProps` 和 `TextBaseProps`
+  - 子参数：
+    - **slideNumber.margin**：编号边距
+      - 类型：`Margin`
+
+- **objects**：母版对象数组
+  - 类型：`Array<{ chart: IChartOpts } | { image: ImageProps } | { line: ShapeProps } | { rect: ShapeProps } | { text: TextProps } | { placeholder: { options: PlaceholderProps, text?: string } }>`
+  - 说明：母版上的固定对象，包括图表、图片、线条、矩形、文字和占位符
+  - 占位符子参数：
+    - **placeholder.options**：占位符选项
+      - 类型：`PlaceholderProps`
+    - **placeholder.text**：占位符默认文字
+      - 类型：`string`
+      - 说明：留空则 PowerPoint 显示默认提示文字（如"单击此处添加标题"）
+
+---
+
+## PlaceholderProps
+
+继承 `PositionProps` 和 `TextBaseProps`。
+
+- **name**：占位符名称
+  - 类型：`string`
+
+- **type**：占位符类型
+  - 类型：`PLACEHOLDER_TYPE`
+  - 取值范围：`'title' | 'body' | 'pic' | 'chart' | 'tbl' | 'media'`
+
+- **margin**：占位符边距
+  - 类型：`Margin`（`number | [number, number, number, number]`）
+  - 单位：pt
+
+- **x**：水平位置
+  - 类型：`Coord`
+
+- **y**：垂直位置
+  - 类型：`Coord`
+
+- **w**：宽度
+  - 类型：`Coord`
+
+- **h**：高度
+  - 类型：`Coord`
+
+### PLACEHOLDER_TYPES 枚举
+
+| 常量 | 值 | 说明 |
+|---|---|---|
+| `PLACEHOLDER_TYPES.title` | `'title'` | 标题 |
+| `PLACEHOLDER_TYPES.body` | `'body'` | 正文 |
+| `PLACEHOLDER_TYPES.image` | `'pic'` | 图片 |
+| `PLACEHOLDER_TYPES.chart` | `'chart'` | 图表 |
+| `PLACEHOLDER_TYPES.table` | `'tbl'` | 表格 |
+| `PLACEHOLDER_TYPES.media` | `'media'` | 媒体 |
+
+---
+
+## ThemeProps
+
+用于 `pptx.theme` 属性。
+
+- **headFontFace**：标题字体
+  - 类型：`string`
+  - 默认值：`'Calibri Light'`
+  - 示例：`'Arial Narrow'`
+
+- **bodyFontFace**：正文字体
+  - 类型：`string`
+  - 默认值：`'Calibri'`
+  - 示例：`'Arial'`
+
+---
+
+## 使用示例
+
+```ts
+pptx.defineSlideMaster({
+  title: 'MyMaster',
+  background: { color: 'FFFFFF' },
+  margin: 0,
+  objects: [
+    { rect: { x: 0, y: 0, w: 10, h: 0.5, fill: { color: '003366' } } },
+    { text: { text: '即稿即用', options: { x: 0.5, y: 0.05, w: 9, h: 0.4, color: 'FFFFFF', fontSize: 14 } } },
+    { placeholder: { options: { name: 'title', type: 'title', x: 0.5, y: 1, w: 9, h: 1 } } },
+  ],
+})
+```
+
+---
+
+## 已废弃参数
+
+| 已废弃参数 | 替代参数 | 废弃版本 |
+|---|---|---|
+| `bkgd` | `background` | v3.3.0 |