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,175 @@
+# 坐标与尺寸参数 (Coordinate Props)
+
+坐标与尺寸参数用于指定元素在幻灯片上的位置和大小。
+
+---
+
+## Coord 类型
+
+```ts
+type Coord = number | `${number}%`
+```
+
+- **number**：英寸值
+  - 说明：以英寸为单位的数值
+  - 示例：`1.5`（1.5 英寸）、`10`（10 英寸）
+
+- **`${number}%`**：百分比
+  - 说明：相对于幻灯片尺寸的百分比
+  - 示例：`'50%'`（一半宽度/高度）、`'100%'`（全宽/全高）
+
+---
+
+## PositionProps
+
+所有可放置元素通用的位置属性。
+
+- **x**：水平位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+  - 示例：`10.25`、`'75%'`
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+  - 示例：`10.25`、`'75%'`
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+  - 示例：`10.25`、`'75%'`
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+  - 示例：`10.25`、`'75%'`
+
+---
+
+## 标准布局尺寸
+
+| 布局常量名 | 宽度 | 高度 | 宽高比 |
+|---|---|---|---|
+| `LAYOUT_4x3` | 10" | 7.5" | 4:3 |
+| `LAYOUT_16x9` | 10" | 5.625" | 16:9 |
+| `LAYOUT_16x10` | 10" | 6.25" | 16:10 |
+| `LAYOUT_WIDE` | 13.33" | 7.5" | ~16:9 |
+
+可通过 `pptx.defineLayout({ name, width, height })` 自定义布局。
+
+### px 换算参考
+
+在 96dpi 屏幕上的参考换算关系：
+- 1 英寸 = 96px
+- 1pt = 1/72 英寸 ≈ 1.33px
+- 1cm ≈ 0.394 英寸
+
+---
+
+## Margin 类型
+
+```ts
+type Margin = number | [number, number, number, number]
+```
+
+- **number**：统一边距
+  - 说明：四边使用相同值
+  - 单位：pt
+  - 示例：`0`（无边距）、`10`（四边 10pt）
+
+- **[top, right, bottom, left]**：四边独立边距
+  - 说明：按上右下左（TRBL）顺序分别设置
+  - 单位：pt
+  - 示例：`[10, 5, 10, 5]`（上下 10pt、左右 5pt）
+
+---
+
+## Color 类型
+
+```ts
+type HexColor = string         // 6 位十六进制，无 # 前缀
+type ThemeColor = 'tx1' | 'tx2' | 'bg1' | 'bg2'
+                | 'accent1' | 'accent2' | 'accent3'
+                | 'accent4' | 'accent5' | 'accent6'
+type Color = HexColor | ThemeColor
+```
+
+### 十六进制颜色 (HexColor)
+
+- 格式：6 位十六进制值，不含 `#` 前缀
+- 示例：`'FF0000'`（红色）、`'0088CC'`（蓝色）、`'FFFFFF'`（白色）
+
+### 主题色 (ThemeColor)
+
+| 值 | 说明 | PowerPoint 名称 |
+|---|---|---|
+| `'tx1'` | 文字 1 | Theme Color Text 1 |
+| `'tx2'` | 文字 2 | Theme Color Text 2 |
+| `'bg1'` | 背景 1 | Theme Color Background 1 |
+| `'bg2'` | 背景 2 | Theme Color Background 2 |
+| `'accent1'` | 强调色 1 | Accent 1 |
+| `'accent2'` | 强调色 2 | Accent 2 |
+| `'accent3'` | 强调色 3 | Accent 3 |
+| `'accent4'` | 强调色 4 | Accent 4 |
+| `'accent5'` | 强调色 5 | Accent 5 |
+| `'accent6'` | 强调色 6 | Accent 6 |
+
+可通过 `pptx.SchemeColor.XXX` 常量引用：
+- `pptx.SchemeColor.text1` → `'tx1'`
+- `pptx.SchemeColor.background1` → `'bg1'`
+- `pptx.SchemeColor.accent1` → `'accent1'`
+
+---
+
+## 对齐类型
+
+### HAlign
+
+```ts
+type HAlign = 'left' | 'center' | 'right' | 'justify'
+```
+
+| 值 | 说明 |
+|---|---|
+| `'left'` | 左对齐 |
+| `'center'` | 居中对齐 |
+| `'right'` | 右对齐 |
+| `'justify'` | 两端对齐 |
+
+### VAlign
+
+```ts
+type VAlign = 'top' | 'middle' | 'bottom'
+```
+
+| 值 | 说明 |
+|---|---|
+| `'top'` | 顶部对齐 |
+| `'middle'` | 垂直居中 |
+| `'bottom'` | 底部对齐 |
+
+---
+
+## 其他常用类型
+
+### ChartAxisTickMark
+
+```ts
+type ChartAxisTickMark = 'none' | 'inside' | 'outside' | 'cross'
+```
+
+### ChartLineCap
+
+```ts
+type ChartLineCap = 'flat' | 'round' | 'square'
+```
+
+### SHAPE_NAME
+
+形状名称类型，包含约 180 种 PowerPoint 形状的字面量联合类型。
+
+### CHART_NAME
+
+```ts
+type CHART_NAME = 'area' | 'bar' | 'bar3D' | 'bubble' | 'doughnut' | 'line' | 'pie' | 'radar' | 'scatter'
+```