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

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

reference/chart.md

@@ -0,0 +1,707 @@
+# 图表参数 (Chart Props)
+
+图表参数来自 `IChartOpts` 及其继承的所有接口，用于 `slide.addChart()` 方法。
+
+---
+
+## 图表类型 (CHART_NAME)
+
+- 类型：`'area' | 'bar' | 'bar3D' | 'bubble' | 'doughnut' | 'line' | 'pie' | 'radar' | 'scatter'`
+
+可通过 `pptxgen.ChartType.XXX` 常量引用：
+- `ChartType.area`、`ChartType.bar`、`ChartType.bar3d`、`ChartType.bubble`、`ChartType.bubble3d`、
+  `ChartType.doughnut`、`ChartType.line`、`ChartType.pie`、`ChartType.radar`、`ChartType.scatter`
+
+## 多图类型 (IChartMulti)
+
+```
+{ type: CHART_NAME, data: OptsChartData[], options: IChartOpts }
+```
+
+---
+
+## 数据接口 (OptsChartData)
+
+- **labels**：分类标签
+  - 类型：`string[] | string[][]`
+  - 示例：`['Year 2000', 'Year 2010', 'Year 2020']`
+  - 说明：`string[][]` 用于多级分类轴，始于 v3.11.0
+
+- **name**：系列名称
+  - 类型：`string`
+  - 示例：`'Locations'`
+
+- **sizes**：气泡大小
+  - 类型：`number[]`
+  - 说明：仅用于气泡图
+  - 示例：`[5, 1, 5, 1]`
+
+- **values**：分类数值
+  - 类型：`number[]`
+  - 示例：`[2000, 2010, 2020]`
+
+---
+
+## 位置属性 (PositionProps)
+
+- **x**：水平位置
+  - 类型：`Coord`（`number | `${number}%``）
+  - 单位：英寸（number）或百分比（`'50%'`）
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+---
+
+## 对象名称属性 (ObjectNameProps)
+
+- **objectName**：对象名称
+  - 类型：`string`
+  - 说明：替代默认的 "Object N" 名称
+  - 默认值：`'Object 1'`
+
+---
+
+## 基础图表属性 (IChartPropsBase)
+
+- **axisPos**：坐标轴位置
+  - 类型：`'b' | 'l' | 'r' | 't'`
+  - 取值范围：`b`（下）、`l`（左）、`r`（右）、`t`（上）
+
+- **chartColors**：图表系列颜色
+  - 类型：`HexColor[]`
+  - 格式：6 位十六进制颜色数组（无 `#`）
+
+- **chartColorsOpacity**：系列颜色不透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`
+  - 示例：`50`（50% 不透明）
+
+- **dataBorder**：数据点边框
+  - 类型：`BorderProps`
+  - 子参数：
+    - **dataBorder.type**：`'none' | 'dash' | 'solid'`
+    - **dataBorder.color**：`HexColor`
+    - **dataBorder.pt**：边框粗细（pt）
+
+- **displayBlanksAs**：空值显示方式
+  - 类型：`string`
+
+- **invertedColors**：反色数组
+  - 类型：`HexColor[]`
+
+- **lang**：语言
+  - 类型：`string`
+
+- **layout**：图表在幻灯片中的位置
+  - 类型：`PositionProps`
+
+- **shadow**：阴影
+  - 类型：`ShadowProps`
+
+- **showLabel**：显示数据标签
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showLeaderLines**：显示引导线
+  - 类型：`boolean`
+
+- **showLegend**：显示图例
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showPercent**：显示百分比
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showSerName**：显示系列名称
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showTitle**：显示图表标题
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showValue**：显示数值
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **v3DPerspective**：3D 透视
+  - 类型：`number`
+  - 取值范围：`0`–`120`
+  - 默认值：`30`
+
+- **v3DRAngAx**：直角坐标轴
+  - 类型：`boolean`
+  - 说明：启用时覆盖 `v3DPerspective`，以第一人称视角显示图表
+  - 默认值：`false`
+
+- **v3DRotX**：X 轴旋转
+  - 类型：`number`
+  - 取值范围：`0`–`359.9`
+  - 默认值：`30`
+
+- **v3DRotY**：Y 轴旋转
+  - 类型：`number`
+  - 取值范围：`0`–`359.9`
+  - 默认值：`30`
+
+- **chartArea**：图表区域样式
+  - 类型：`IChartAreaProps`（继承 `IChartPropsFillLine`）
+  - 子参数：
+    - **chartArea.border**：边框
+    - **chartArea.fill**：填充
+    - **chartArea.roundedCorners**：圆角
+      - 类型：`boolean`
+      - 默认值：`true`
+      - 始于：v3.11
+
+- **plotArea**：绘图区样式
+  - 类型：`IChartPropsFillLine`
+  - 子参数：
+    - **plotArea.border**：绘图区边框
+    - **plotArea.fill**：绘图区填充
+  - 始于：v3.11
+
+---
+
+## 分类轴属性 (IChartPropsAxisCat)
+
+- **catAxes**：多图多轴设置
+  - 类型：`IChartPropsAxisCat[]`
+
+- **catAxisBaseTimeUnit**：分类轴基础时间单位
+  - 类型：`string`
+
+- **catAxisCrossesAt**：数值轴交叉位置
+  - 类型：`number | 'autoZero'`
+
+- **catAxisHidden**：隐藏分类轴
+  - 类型：`boolean`
+
+- **catAxisLabelColor**：轴标签颜色
+  - 类型：`string`
+
+- **catAxisLabelFontBold**：轴标签粗体
+  - 类型：`boolean`
+
+- **catAxisLabelFontFace**：轴标签字体
+  - 类型：`string`
+
+- **catAxisLabelFontItalic**：轴标签斜体
+  - 类型：`boolean`
+
+- **catAxisLabelFontSize**：轴标签字号
+  - 类型：`number`
+
+- **catAxisLabelFrequency**：标签频率
+  - 类型：`string`
+
+- **catAxisLabelPos**：标签位置
+  - 类型：`'none' | 'low' | 'high' | 'nextTo'`
+
+- **catAxisLabelRotate**：标签旋转角度
+  - 类型：`number`
+
+- **catAxisLineColor**：轴线颜色
+  - 类型：`string`
+
+- **catAxisLineShow**：显示轴线
+  - 类型：`boolean`
+
+- **catAxisLineSize**：轴线粗细
+  - 类型：`number`
+
+- **catAxisLineStyle**：轴线样式
+  - 类型：`'solid' | 'dash' | 'dot'`
+
+- **catAxisMajorTickMark**：主轴刻度标记
+  - 类型：`ChartAxisTickMark`（`'none' | 'inside' | 'outside' | 'cross'`）
+
+- **catAxisMajorTimeUnit**：主要时间单位
+  - 类型：`string`
+
+- **catAxisMajorUnit**：主要刻度单位
+  - 类型：`number`
+
+- **catAxisMaxVal**：轴最大值
+  - 类型：`number`
+
+- **catAxisMinorTickMark**：副轴刻度标记
+  - 类型：`ChartAxisTickMark`
+
+- **catAxisMinorTimeUnit**：次要时间单位
+  - 类型：`string`
+
+- **catAxisMinorUnit**：次要刻度单位
+  - 类型：`number`
+
+- **catAxisMinVal**：轴最小值
+  - 类型：`number`
+
+- **catAxisMultiLevelLabels**：多级标签
+  - 类型：`boolean`
+  - 始于：v3.11.0
+
+- **catAxisOrientation**：轴方向
+  - 类型：`'minMax'`
+
+- **catAxisTitle**：轴标题
+  - 类型：`string`
+
+- **catAxisTitleColor**：轴标题颜色
+  - 类型：`string`
+
+- **catAxisTitleFontFace**：轴标题字体
+  - 类型：`string`
+
+- **catAxisTitleFontSize**：轴标题字号
+  - 类型：`number`
+
+- **catAxisTitleRotate**：轴标题旋转
+  - 类型：`number`
+
+- **catGridLine**：分类网格线
+  - 类型：`OptsChartGridLine`
+
+- **catLabelFormatCode**：分类标签格式代码
+  - 类型：`string`
+
+- **secondaryCatAxis**：使用次要分类轴
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showCatAxisTitle**：显示分类轴标题
+  - 类型：`boolean`
+
+---
+
+## 系列轴属性 (IChartPropsAxisSer)
+
+- **serAxisBaseTimeUnit**：系列轴基础时间单位
+  - 类型：`string`
+
+- **serAxisHidden**：隐藏系列轴
+  - 类型：`boolean`
+
+- **serAxisLabelColor**：系列轴标签颜色
+  - 类型：`string`
+
+- **serAxisLabelFontBold**：系列轴标签粗体
+  - 类型：`boolean`
+
+- **serAxisLabelFontFace**：系列轴标签字体
+  - 类型：`string`
+
+- **serAxisLabelFontItalic**：系列轴标签斜体
+  - 类型：`boolean`
+
+- **serAxisLabelFontSize**：系列轴标签字号
+  - 类型：`number`
+
+- **serAxisLabelFrequency**：系列轴标签频率
+  - 类型：`string`
+
+- **serAxisLabelPos**：系列轴标签位置
+  - 类型：`'none' | 'low' | 'high' | 'nextTo'`
+
+- **serAxisLineColor**：系列轴线颜色
+  - 类型：`string`
+
+- **serAxisLineShow**：显示系列轴线
+  - 类型：`boolean`
+
+- **serAxisMajorTimeUnit**：系列轴主要时间单位
+  - 类型：`string`
+
+- **serAxisMajorUnit**：系列轴主要刻度单位
+  - 类型：`number`
+
+- **serAxisMinorTimeUnit**：系列轴次要时间单位
+  - 类型：`string`
+
+- **serAxisMinorUnit**：系列轴次要刻度单位
+  - 类型：`number`
+
+- **serAxisOrientation**：系列轴方向
+  - 类型：`string`
+
+- **serAxisTitle**：系列轴标题
+  - 类型：`string`
+
+- **serAxisTitleColor**：系列轴标题颜色
+  - 类型：`string`
+
+- **serAxisTitleFontFace**：系列轴标题字体
+  - 类型：`string`
+
+- **serAxisTitleFontSize**：系列轴标题字号
+  - 类型：`number`
+
+- **serAxisTitleRotate**：系列轴标题旋转
+  - 类型：`number`
+
+- **serGridLine**：系列网格线
+  - 类型：`OptsChartGridLine`
+
+- **serLabelFormatCode**：系列标签格式代码
+  - 类型：`string`
+
+- **showSerAxisTitle**：显示系列轴标题
+  - 类型：`boolean`
+
+---
+
+## 数值轴属性 (IChartPropsAxisVal)
+
+- **secondaryValAxis**：使用次要数值轴
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showValAxisTitle**：显示数值轴标题
+  - 类型：`boolean`
+
+- **valAxes**：多图多数值轴
+  - 类型：`IChartPropsAxisVal[]`
+
+- **valAxisCrossesAt**：数值轴交叉位置
+  - 类型：`number | 'autoZero'`
+
+- **valAxisDisplayUnit**：显示单位
+  - 类型：`'billions' | 'hundredMillions' | 'hundreds' | 'hundredThousands' | 'millions' | 'tenMillions' | 'tenThousands' | 'thousands' | 'trillions'`
+
+- **valAxisDisplayUnitLabel**：显示单位标签
+  - 类型：`boolean`
+
+- **valAxisHidden**：隐藏数值轴
+  - 类型：`boolean`
+
+- **valAxisLabelColor**：数值轴标签颜色
+  - 类型：`string`
+
+- **valAxisLabelFontBold**：数值轴标签粗体
+  - 类型：`boolean`
+
+- **valAxisLabelFontFace**：数值轴标签字体
+  - 类型：`string`
+
+- **valAxisLabelFontItalic**：数值轴标签斜体
+  - 类型：`boolean`
+
+- **valAxisLabelFontSize**：数值轴标签字号
+  - 类型：`number`
+
+- **valAxisLabelFormatCode**：数值轴标签格式代码
+  - 类型：`string`
+
+- **valAxisLabelPos**：数值轴标签位置
+  - 类型：`'none' | 'low' | 'high' | 'nextTo'`
+
+- **valAxisLabelRotate**：数值轴标签旋转
+  - 类型：`number`
+
+- **valAxisLineColor**：数值轴线颜色
+  - 类型：`string`
+
+- **valAxisLineShow**：显示数值轴线
+  - 类型：`boolean`
+
+- **valAxisLineSize**：数值轴线粗细
+  - 类型：`number`
+
+- **valAxisLineStyle**：数值轴线样式
+  - 类型：`'solid' | 'dash' | 'dot'`
+
+- **valAxisLogScaleBase**：对数刻度基数
+  - 类型：`number`
+  - 取值范围：`2`–`99`
+  - 始于：v3.5.0
+
+- **valAxisMajorTickMark**：数值轴主刻度标记
+  - 类型：`ChartAxisTickMark`
+
+- **valAxisMajorUnit**：数值轴主要刻度单位
+  - 类型：`number`
+
+- **valAxisMaxVal**：数值轴最大值
+  - 类型：`number`
+
+- **valAxisMinorTickMark**：数值轴副刻度标记
+  - 类型：`ChartAxisTickMark`
+
+- **valAxisMinVal**：数值轴最小值
+  - 类型：`number`
+
+- **valAxisOrientation**：数值轴方向
+  - 类型：`'minMax'`
+
+- **valAxisTitle**：数值轴标题
+  - 类型：`string`
+
+- **valAxisTitleColor**：数值轴标题颜色
+  - 类型：`string`
+
+- **valAxisTitleFontFace**：数值轴标题字体
+  - 类型：`string`
+
+- **valAxisTitleFontSize**：数值轴标题字号
+  - 类型：`number`
+
+- **valAxisTitleRotate**：数值轴标题旋转
+  - 类型：`number`
+
+- **valGridLine**：数值网格线
+  - 类型：`OptsChartGridLine`
+
+- **valLabelFormatCode**：数值标签格式代码
+  - 类型：`string`
+  - 始于：v3.3.0
+  - 示例：`'#%'`、`'0.00%'`、`'$0.00'`
+
+---
+
+## 柱状图属性 (IChartPropsChartBar)
+
+- **bar3DShape**：3D 柱形形状
+  - 类型：`string`
+
+- **barDir**：柱形方向
+  - 类型：`string`
+  - 取值范围：`'bar'`（水平）、`'col'`（垂直）
+
+- **barGapDepthPct**：3D 柱形深度间距百分比
+  - 类型：`number`
+
+- **barGapWidthPct**：间距宽度百分比
+  - 类型：`number`
+  - 取值范围：`0`–`500`
+  - 默认值：`150`
+
+- **barGrouping**：分组方式
+  - 类型：`string`
+
+- **barOverlapPct**：系列重叠百分比
+  - 类型：`number`
+  - 取值范围：`-100`–`100`
+  - 默认值：`0`
+  - 始于：v3.9.0
+
+---
+
+## 圆环图属性 (IChartPropsChartDoughnut)
+
+- **dataNoEffects**：禁用数据点效果
+  - 类型：`boolean`
+
+- **holeSize**：中心孔大小
+  - 类型：`number`
+
+---
+
+## 折线图属性 (IChartPropsChartLine)
+
+- **lineCap**：线帽类型
+  - 类型：`ChartLineCap`（`'flat' | 'round' | 'square'`）
+  - 默认值：`'flat'`
+
+- **lineDash**：线型
+  - 类型：`'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'solid' | 'sysDash' | 'sysDot'`
+  - 默认值：`'solid'`
+
+- **lineDataSymbol**：数据点标记类型
+  - 类型：`'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'square' | 'triangle'`
+  - 默认值：`'circle'`
+
+- **lineDataSymbolLineColor**：标记边框颜色
+  - 类型：`string`
+
+- **lineDataSymbolLineSize**：标记边框宽度
+  - 类型：`number`
+  - 默认值：`0.75`
+
+- **lineDataSymbolSize**：标记大小
+  - 类型：`number`
+  - 取值范围：`2`–`72`
+  - 默认值：`6`
+
+- **lineSize**：线条宽度
+  - 类型：`number`
+  - 取值范围：`0`–`1584`
+  - 默认值：`2`
+
+- **lineSmooth**：平滑线
+  - 类型：`boolean`
+  - 默认值：`false`
+
+---
+
+## 饼图属性 (IChartPropsChartPie)
+
+- **dataNoEffects**：禁用数据点效果
+  - 类型：`boolean`
+
+- **firstSliceAng**：第一扇区起始角度
+  - 类型：`number`
+  - 取值范围：`0`–`359`
+  - 默认值：`0`
+  - 始于：v3.4.0
+
+---
+
+## 雷达图属性 (IChartPropsChartRadar)
+
+- **radarStyle**：雷达图样式
+  - 类型：`'standard' | 'marker' | 'filled'`
+  - 默认值：`'standard'`
+
+---
+
+## 数据标签属性 (IChartPropsDataLabel)
+
+- **dataLabelBkgrdColors**：数据标签背景色
+  - 类型：`boolean`
+
+- **dataLabelColor**：数据标签颜色
+  - 类型：`string`
+
+- **dataLabelFontBold**：数据标签粗体
+  - 类型：`boolean`
+
+- **dataLabelFontFace**：数据标签字体
+  - 类型：`string`
+
+- **dataLabelFontItalic**：数据标签斜体
+  - 类型：`boolean`
+
+- **dataLabelFontSize**：数据标签字号
+  - 类型：`number`
+
+- **dataLabelFormatCode**：数据标签格式代码
+  - 类型：`string`
+  - 示例：`'#%'`、`'0.00%'`、`'$0.00'`
+
+- **dataLabelFormatScatter**：散点图标签格式
+  - 类型：`'custom' | 'customXY' | 'XY'`
+
+- **dataLabelPosition**：数据标签位置
+  - 类型：`'b' | 'bestFit' | 'ctr' | 'l' | 'r' | 't' | 'inEnd' | 'outEnd'`
+
+---
+
+## 数据表属性 (IChartPropsDataTable)
+
+- **dataTableFontSize**：数据表字号
+  - 类型：`number`
+
+- **dataTableFormatCode**：数据表格式代码
+  - 类型：`string`
+  - 始于：v3.3.0
+
+- **showDataTable**：显示数据表
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **showDataTableHorzBorder**：显示水平边框
+  - 类型：`boolean`
+
+- **showDataTableKeys**：显示图例标示
+  - 类型：`boolean`
+
+- **showDataTableOutline**：显示外框
+  - 类型：`boolean`
+
+- **showDataTableVertBorder**：显示垂直边框
+  - 类型：`boolean`
+
+---
+
+## 图例属性 (IChartPropsLegend)
+
+- **legendColor**：图例文字颜色
+  - 类型：`string`
+
+- **legendFontFace**：图例字体
+  - 类型：`string`
+
+- **legendFontSize**：图例字号
+  - 类型：`number`
+
+- **legendPos**：图例位置
+  - 类型：`'b' | 'l' | 'r' | 't' | 'tr'`
+  - 取值范围：`b`（底部）、`l`（左侧）、`r`（右侧）、`t`（顶部）、`tr`（右上）
+
+---
+
+## 标题属性 (IChartPropsTitle)
+
+继承 `TextBaseProps`。
+
+- **title**：图表标题文字
+  - 类型：`string`
+
+- **titleAlign**：标题对齐
+  - 类型：`string`
+
+- **titleBold**：标题粗体
+  - 类型：`boolean`
+
+- **titleColor**：标题颜色
+  - 类型：`string`
+
+- **titleFontFace**：标题字体
+  - 类型：`string`
+
+- **titleFontSize**：标题字号
+  - 类型：`number`
+
+- **titlePos**：标题位置
+  - 类型：`{ x: number, y: number }`
+
+- **titleRotate**：标题旋转
+  - 类型：`number`
+
+---
+
+## 网格线属性 (OptsChartGridLine)
+
+- **cap**：线帽类型
+  - 类型：`ChartLineCap`（`'flat' | 'round' | 'square'`）
+  - 默认值：`'flat'`
+
+- **color**：网格线颜色
+  - 类型：`HexColor`
+
+- **size**：网格线粗细
+  - 类型：`number`
+
+- **style**：网格线样式
+  - 类型：`'solid' | 'dash' | 'dot' | 'none'`
+
+---
+
+## IChartPropsFillLine
+
+用于 `chartArea`、`plotArea` 的填充与边框基础类型。
+
+- **border**：边框
+  - 类型：`BorderProps`
+
+- **fill**：填充
+  - 类型：`ShapeFillProps`
+
+---
+
+## IChartOpts 附加属性
+
+- **altText**：替代文字（无障碍）
+  - 类型：`string`
+  - 说明：PowerPoint 中右击图表 > "编辑替代文字"

reference/coordinate.md

@@ -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'
+```

reference/image.md

@@ -0,0 +1,197 @@
+# 图片参数 (Image Props)
+
+图片参数来自 `ImageProps`（继承 `PositionProps`、`DataOrPathProps`、`ObjectNameProps`），用于 `slide.addImage()` 方法。
+
+---
+
+## 位置属性 (PositionProps)
+
+- **x**：水平位置
+  - 类型：`Coord`（`number | `${number}%``）
+  - 单位：英寸（number）或百分比（`'50%'`）
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+---
+
+## 数据/路径属性 (DataOrPathProps)
+
+- **path**：图片 URL 或本地路径
+  - 类型：`string`
+  - 示例：`'https://onedrives.com/myimg.png'`、`'/home/gitbrent/images/myimg.png'`
+
+- **data**：base64 编码数据
+  - 类型：`string`
+  - 格式：`'image/png;base64,iVtDafDrBF[...]='`
+  - 说明：base64 编码的图片数据，用时可避免路径/服务器问题
+
+---
+
+## 对象名称属性 (ObjectNameProps)
+
+- **objectName**：对象名称
+  - 类型：`string`
+  - 说明：替代默认的 "Object N" 名称，在 PowerPoint 选择窗格中显示
+  - 默认值：`'Object 1'`
+  - 始于：v3.10.0
+
+---
+
+## 图片专有属性 (ImageProps)
+
+- **altText**：替代文字（无障碍）
+  - 类型：`string`
+  - 说明：PowerPoint 中右击图片 > "编辑替代文字"
+
+- **flipH**：水平翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **flipV**：垂直翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **hyperlink**：超链接
+  - 类型：`HyperlinkProps`
+  - 子参数：
+    - **hyperlink.slide**：链接到页码
+      - 类型：`number`
+    - **hyperlink.url**：链接 URL
+      - 类型：`string`
+    - **hyperlink.tooltip**：超链接提示
+      - 类型：`string`
+
+- **placeholder**：占位符类型
+  - 类型：`string`
+  - 取值范围：`'body'`、`'header'`、`'footer'`、`'title'` 等
+  - 示例：`'body'`
+
+- **rotate**：旋转角度
+  - 类型：`number`
+  - 取值范围：`-360`–`360`（度）
+  - 默认值：`0`
+  - 示例：`180`（旋转 180 度）
+
+- **rounding**：启用图片圆角
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **shadow**：阴影
+  - 类型：`ShadowProps`
+  - 子参数：
+    - **shadow.type**：阴影类型
+      - 类型：`'outer' | 'inner' | 'none'`
+      - 默认值：`'none'`
+    - **shadow.opacity**：不透明度
+      - 类型：`number`
+      - 取值范围：`0.0`–`1.0`
+    - **shadow.blur**：模糊
+      - 类型：`number`
+      - 取值范围：`0`–`100`（pt）
+      - 默认值：`0`
+    - **shadow.angle**：角度
+      - 类型：`number`
+      - 取值范围：`0`–`359`（度）
+      - 默认值：`0`
+    - **shadow.offset**：偏移距离
+      - 类型：`number`
+      - 取值范围：`0`–`200`（pt）
+      - 默认值：`0`
+    - **shadow.color**：阴影颜色
+      - 类型：`HexColor`
+      - 格式：6 位十六进制（无 `#`）
+    - **shadow.rotateWithShape**：阴影是否随形状旋转
+      - 类型：`boolean`
+      - 默认值：`false`
+
+- **sizing**：图片大小调整
+  - 类型：`{ type: 'contain' | 'cover' | 'crop', w: Coord, h: Coord, x?: Coord, y?: Coord }`
+  - 子参数：
+    - **sizing.type**：调整类型
+      - 类型：`'contain' | 'cover' | 'crop'`
+      - 取值范围：
+        - `contain` — 包含（保持比例适配）
+        - `cover` — 覆盖（填充区域）
+        - `crop` — 裁剪
+    - **sizing.w**：图片宽度
+      - 类型：`Coord`（英寸或百分比）
+    - **sizing.h**：图片高度
+      - 类型：`Coord`（英寸或百分比）
+    - **sizing.x**：裁剪左偏移
+      - 类型：`Coord`（仅用于 `crop` 模式）
+    - **sizing.y**：裁剪上偏移
+      - 类型：`Coord`（仅用于 `crop` 模式）
+
+- **transparency**：透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`（百分比）
+  - 默认值：`0`
+  - 示例：`25`（25% 透明）
+
+---
+
+## ShadowProps
+
+用于 `shadow` 属性的类型定义（图表、图片、文字通用）。
+
+- **type**：阴影类型
+  - 类型：`'outer' | 'inner' | 'none'`
+  - 默认值：`'none'`
+
+- **opacity**：不透明度
+  - 类型：`number`
+  - 取值范围：`0.0`–`1.0`
+  - 示例：`0.5`（50% 不透明）
+
+- **blur**：模糊大小
+  - 类型：`number`
+  - 取值范围：`0`–`100`（pt）
+  - 默认值：`0`
+
+- **angle**：阴影角度
+  - 类型：`number`
+  - 取值范围：`0`–`359`（度）
+  - 默认值：`0`
+
+- **offset**：阴影偏移距离
+  - 类型：`number`
+  - 取值范围：`0`–`200`（pt）
+  - 默认值：`0`
+
+- **color**：阴影颜色
+  - 类型：`HexColor`
+  - 格式：6 位十六进制（无 `#`）
+
+- **rotateWithShape**：是否随形状旋转
+  - 类型：`boolean`
+  - 默认值：`false`
+
+---
+
+## HyperlinkProps
+
+用于 `hyperlink` 属性的类型定义。
+
+- **slide**：链接到页码
+  - 类型：`number`
+  - 说明：跳转到演示文稿的指定幻灯片
+
+- **url**：超链接 URL
+  - 类型：`string`
+  - 说明：链接到外部网址
+
+- **tooltip**：超链接提示
+  - 类型：`string`
+  - 说明：鼠标悬停时显示的文字

reference/master.md

@@ -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 |

reference/output.md

@@ -0,0 +1,156 @@
+# 输出参数 (Output Props)
+
+输出参数用于导出演示文稿，支持 `writeFile()`（写入文件）、`write()`（返回数据）和 `stream()`（返回流）三种方式。
+
+---
+
+## 输出方法
+
+### pptx.writeFile()
+
+```ts
+pptx.writeFile(props?: WriteFileProps): Promise<string>
+```
+
+- **fileName**：导出文件名
+  - 类型：`string`
+  - 默认值：`'Presentation.pptx'`
+
+- **compression**：是否启用压缩
+  - 类型：`boolean`
+  - 默认值：`false`
+  - 说明：可显著减小文件体积，但导出耗时略长
+  - 始于：v3.5.0
+
+### pptx.write()
+
+```ts
+pptx.write(props?: WriteProps): Promise<string | ArrayBuffer | Blob | Uint8Array>
+```
+
+- **outputType**：输出类型
+  - 类型：`WRITE_OUTPUT_TYPE`
+  - 取值范围：`'arraybuffer' | 'base64' | 'binarystring' | 'blob' | 'nodebuffer' | 'uint8array' | 'STREAM'`
+  - 默认值：`'blob'`
+
+- **compression**：是否启用压缩
+  - 类型：`boolean`
+  - 默认值：`false`
+  - 始于：v3.5.0
+
+### pptx.stream()
+
+```ts
+pptx.stream(props?: WriteBaseProps): Promise<string | ArrayBuffer | Blob | Uint8Array>
+```
+
+- **compression**：是否启用压缩
+  - 类型：`boolean`
+  - 默认值：`false`
+  - 始于：v3.5.0
+
+---
+
+## WriteBaseProps
+
+`writeFile()` 和 `stream()` 的输出基础属性。
+
+- **compression**：压缩选项
+  - 类型：`boolean`
+  - 默认值：`false`
+  - 始于：v3.5.0
+  - 说明：启用 Zip 压缩以减小文件体积
+
+---
+
+## WriteProps
+
+继承 `WriteBaseProps`，用于 `write()` 方法。
+
+- **outputType**：输出类型
+  - 类型：`WRITE_OUTPUT_TYPE`
+  - 取值范围：`'arraybuffer' | 'base64' | 'binarystring' | 'blob' | 'nodebuffer' | 'uint8array' | 'STREAM'`
+  - 默认值：`'blob'`
+
+- **compression**：压缩选项
+  - 类型：`boolean`
+  - 默认值：`false`
+
+---
+
+## WriteFileProps
+
+继承 `WriteBaseProps`，用于 `writeFile()` 方法。
+
+- **fileName**：导出文件名
+  - 类型：`string`
+  - 默认值：`'Presentation.pptx'`
+
+- **compression**：压缩选项
+  - 类型：`boolean`
+  - 默认值：`false`
+
+---
+
+## OutputType 枚举
+
+| 常量 | 值 | 说明 |
+|---|---|---|
+| `OutputType.arraybuffer` | `'arraybuffer'` | ArrayBuffer |
+| `OutputType.base64` | `'base64'` | Base64 字符串 |
+| `OutputType.binarystring` | `'binarystring'` | 二进制字符串 |
+| `OutputType.blob` | `'blob'` | Blob 对象（默认） |
+| `OutputType.nodebuffer` | `'nodebuffer'` | Node.js Buffer |
+| `OutputType.uint8array` | `'uint8array'` | Uint8Array |
+
+## JSZIP_OUTPUT_TYPE
+
+```ts
+type JSZIP_OUTPUT_TYPE = 'arraybuffer' | 'base64' | 'binarystring' | 'blob' | 'nodebuffer' | 'uint8array'
+```
+
+## WRITE_OUTPUT_TYPE
+
+```ts
+type WRITE_OUTPUT_TYPE = JSZIP_OUTPUT_TYPE | 'STREAM'
+```
+
+---
+
+## Presentation 属性
+
+导出前的演示文稿元数据属性。
+
+- **author**：作者
+  - 类型：`string`
+  - 说明：演示文稿作者名称
+
+- **company**：公司
+  - 类型：`string`
+  - 说明：公司名称
+
+- **layout**：布局名称
+  - 类型：`string`
+  - 说明：当前演示文稿布局
+  - 标准值：`'LAYOUT_4x3'`、`'LAYOUT_16x9'`、`'LAYOUT_16x10'`、`'LAYOUT_WIDE'`
+
+- **rtlMode**：从右向左模式
+  - 类型：`boolean`
+  - 默认值：`false`
+
+- **revision**：修订号
+  - 类型：`string`
+  - 说明：必须为整数（不含小数点或逗号），否则 PowerPoint 打开时会报错
+
+- **subject**：主题
+  - 类型：`string`
+  - 说明：演示文稿主题
+
+- **theme**：主题字体
+  - 类型：`ThemeProps`
+  - 子参数：
+    - **theme.headFontFace**：标题字体（默认 `'Calibri Light'`）
+    - **theme.bodyFontFace**：正文字体（默认 `'Calibri'`）
+
+- **title**：演示文稿标题
+  - 类型：`string`

reference/shape.md

@@ -0,0 +1,440 @@
+# 形状参数 (Shape Props)
+
+形状参数来自 `ShapeProps`（继承 `PositionProps`、`ObjectNameProps`），配合 `ShapeFillProps`、`ShapeLineProps` 使用，用于 `slide.addShape()` 方法。
+
+---
+
+## 位置属性 (PositionProps)
+
+- **x**：水平位置
+  - 类型：`Coord`（`number | `${number}%``）
+  - 单位：英寸（number）或百分比（`'50%'`）
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+---
+
+## 对象名称属性 (ObjectNameProps)
+
+- **objectName**：对象名称
+  - 类型：`string`
+  - 说明：替代默认的 "Object N" 名称，在 PowerPoint 选择窗格中显示
+  - 默认值：`'Object 1'`
+  - 始于：v3.10.0
+
+---
+
+## 形状专有属性 (ShapeProps)
+
+- **align**：水平对齐方式
+  - 类型：`HAlign`
+  - 取值范围：`'left'`、`'center'`、`'right'`、`'justify'`
+  - 默认值：`'left'`
+
+- **angleRange**：饼图/弧的角度范围
+  - 类型：`[number, number]`
+  - 说明：仅适用于 `pie`、`arc`、`blockArc` 形状
+  - 取值范围：`[0–359, 0–359]`
+  - 默认值：`[270, 0]`
+  - 始于：v3.4.0
+
+- **arcThicknessRatio**：弧的厚度比
+  - 类型：`number`
+  - 说明：仅适用于 `blockArc` 形状（需同时设置 `angleRange`）
+  - 取值范围：`0.0`–`1.0`
+  - 默认值：`0.5`
+  - 始于：v3.4.0
+
+- **fill**：形状填充
+  - 类型：`ShapeFillProps`
+  - 子参数：
+    - **fill.color**：填充颜色
+      - 类型：`Color`（`HexColor | ThemeColor`）
+    - **fill.transparency**：透明度
+      - 类型：`number`
+      - 取值范围：`0`–`100`
+      - 默认值：`0`
+    - **fill.type**：填充类型
+      - 类型：`'none' | 'solid'`
+      - 默认值：`'solid'`
+
+- **flipH**：水平翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **flipV**：垂直翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **hyperlink**：超链接
+  - 类型：`HyperlinkProps`
+  - 子参数：
+    - **hyperlink.slide**：链接到页码
+      - 类型：`number`
+    - **hyperlink.url**：链接 URL
+      - 类型：`string`
+    - **hyperlink.tooltip**：超链接提示
+      - 类型：`string`
+
+- **line**：线条（边框/轮廓线）
+  - 类型：`ShapeLineProps`
+  - 详见下方 ShapeLineProps 参数
+
+- **points**：自定义形状顶点
+  - 类型：`Array<{ x: Coord, y: Coord } | { x: Coord, y: Coord, curve: ... } | { close: true }>`
+  - 说明：仅适用于自定义几何形状（CUSTOM_GEOMETRY）
+  - 顶点类型：
+    - `{ x, y }` — 直线线段
+    - `{ x, y, moveTo }` — 移动到新位置
+    - `{ x, y, curve: { type: 'arc', hR, wR, stAng, swAng } }` — 弧线
+    - `{ x, y, curve: { type: 'cubic', x1, y1, x2, y2 } }` — 三次贝塞尔曲线
+    - `{ x, y, curve: { type: 'quadratic', x1, y1 } }` — 二次贝塞尔曲线
+    - `{ close: true }` — 闭合路径
+
+- **rectRadius**：圆角矩形半径
+  - 类型：`number`
+  - 说明：仅适用于 `roundedRect`（ROUNDED_RECTANGLE）形状
+  - 取值范围：`0.0`–`1.0`
+  - 默认值：`0`
+
+- **rotate**：旋转角度
+  - 类型：`number`
+  - 取值范围：`-360`–`360`（度）
+  - 默认值：`0`
+
+- **shadow**：阴影
+  - 类型：`ShadowProps`
+  - 子参数：
+    - **shadow.type**：阴影类型
+      - 类型：`'outer' | 'inner' | 'none'`
+      - 默认值：`'none'`
+    - **shadow.opacity**：不透明度
+      - 类型：`number`
+      - 取值范围：`0.0`–`1.0`
+    - **shadow.blur**：模糊
+      - 类型：`number`
+      - 取值范围：`0`–`100`（pt）
+      - 默认值：`0`
+    - **shadow.angle**：角度
+      - 类型：`number`
+      - 取值范围：`0`–`359`（度）
+      - 默认值：`0`
+    - **shadow.offset**：偏移距离
+      - 类型：`number`
+      - 取值范围：`0`–`200`（pt）
+      - 默认值：`0`
+    - **shadow.color**：阴影颜色
+      - 类型：`HexColor`
+      - 格式：6 位十六进制（无 `#`）
+    - **shadow.rotateWithShape**：阴影是否随形状旋转
+      - 类型：`boolean`
+      - 默认值：`false`
+
+---
+
+## 形状填充 (ShapeFillProps)
+
+用于 `fill` 属性的类型定义。
+
+- **color**：填充颜色
+  - 类型：`Color`（`HexColor | ThemeColor`）
+  - 取值范围：6 位十六进制颜色值（不含 `#`）或主题色
+  - 示例：`'FF0000'`、`pptx.SchemeColor.text1`
+
+- **transparency**：透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`（百分比）
+  - 默认值：`0`
+
+- **type**：填充类型
+  - 类型：`'none' | 'solid'`
+  - 默认值：`'solid'`
+
+---
+
+## 形状线条 (ShapeLineProps)
+
+继承 `ShapeFillProps`，用于 `line` 属性。
+
+- **width**：线条宽度
+  - 类型：`number`
+  - 单位：pt
+  - 默认值：`1`
+
+- **dashType**：虚线类型
+  - 类型：`'solid' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot'`
+  - 默认值：`'solid'`
+
+- **beginArrowType**：起点箭头类型
+  - 类型：`'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle'`
+  - 始于：v3.3.0
+
+- **endArrowType**：终点箭头类型
+  - 类型：`'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle'`
+  - 始于：v3.3.0
+
+- **color**：线条颜色
+  - 类型：`Color`
+
+- **transparency**：线条透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`
+
+- **type**：填充类型
+  - 类型：`'none' | 'solid'`
+
+---
+
+## 形状类型列表
+
+`SHAPE_NAME` 类型包含以下所有取值（约180个），可通过 `pptxgen.shapes.XXX` 常量引用。
+
+### 动作按钮 (Action Buttons)
+
+| 常量名 | 值 |
+|---|---|
+| `ACTION_BUTTON_BACK_OR_PREVIOUS` | `actionButtonBackPrevious` |
+| `ACTION_BUTTON_BEGINNING` | `actionButtonBeginning` |
+| `ACTION_BUTTON_CUSTOM` | `actionButtonBlank` |
+| `ACTION_BUTTON_DOCUMENT` | `actionButtonDocument` |
+| `ACTION_BUTTON_END` | `actionButtonEnd` |
+| `ACTION_BUTTON_FORWARD_OR_NEXT` | `actionButtonForwardNext` |
+| `ACTION_BUTTON_HELP` | `actionButtonHelp` |
+| `ACTION_BUTTON_HOME` | `actionButtonHome` |
+| `ACTION_BUTTON_INFORMATION` | `actionButtonInformation` |
+| `ACTION_BUTTON_MOVIE` | `actionButtonMovie` |
+| `ACTION_BUTTON_RETURN` | `actionButtonReturn` |
+| `ACTION_BUTTON_SOUND` | `actionButtonSound` |
+
+### 箭头 (Arrows)
+
+| 常量名 | 值 |
+|---|---|
+| `BENT_ARROW` | `bentArrow` |
+| `BENT_UP_ARROW` | `bentUpArrow` |
+| `CHEVRON` | `chevron` |
+| `CIRCULAR_ARROW` | `circularArrow` |
+| `CURVED_DOWN_ARROW` | `curvedDownArrow` |
+| `CURVED_LEFT_ARROW` | `curvedLeftArrow` |
+| `CURVED_RIGHT_ARROW` | `curvedRightArrow` |
+| `CURVED_UP_ARROW` | `curvedUpArrow` |
+| `DOWN_ARROW` | `downArrow` |
+| `DOWN_ARROW_CALLOUT` | `downArrowCallout` |
+| `LEFT_ARROW` | `leftArrow` |
+| `LEFT_ARROW_CALLOUT` | `leftArrowCallout` |
+| `LEFT_CIRCULAR_ARROW` | `leftCircularArrow` |
+| `LEFT_RIGHT_ARROW` | `leftRightArrow` |
+| `LEFT_RIGHT_ARROW_CALLOUT` | `leftRightArrowCallout` |
+| `LEFT_RIGHT_CIRCULAR_ARROW` | `leftRightCircularArrow` |
+| `LEFT_RIGHT_UP_ARROW` | `leftRightUpArrow` |
+| `LEFT_UP_ARROW` | `leftUpArrow` |
+| `NOTCHED_RIGHT_ARROW` | `notchedRightArrow` |
+| `QUAD_ARROW` | `quadArrow` |
+| `QUAD_ARROW_CALLOUT` | `quadArrowCallout` |
+| `RIGHT_ARROW` | `rightArrow` |
+| `RIGHT_ARROW_CALLOUT` | `rightArrowCallout` |
+| `STRIPED_RIGHT_ARROW` | `stripedRightArrow` |
+| `SWOOSH_ARROW` | `swooshArrow` |
+| `UP_ARROW` | `upArrow` |
+| `UP_ARROW_CALLOUT` | `upArrowCallout` |
+| `UP_DOWN_ARROW` | `upDownArrow` |
+| `UP_DOWN_ARROW_CALLOUT` | `upDownArrowCallout` |
+| `U_TURN_ARROW` | `uturnArrow` |
+
+### 标注框 (Callouts)
+
+| 常量名 | 值 |
+|---|---|
+| `LINE_CALLOUT_1` | `borderCallout1` |
+| `LINE_CALLOUT_1_ACCENT_BAR` | `accentCallout1` |
+| `LINE_CALLOUT_1_BORDER_AND_ACCENT_BAR` | `accentBorderCallout1` |
+| `LINE_CALLOUT_1_NO_BORDER` | `callout1` |
+| `LINE_CALLOUT_2` | `borderCallout2` |
+| `LINE_CALLOUT_2_ACCENT_BAR` | `accentCallout2` |
+| `LINE_CALLOUT_2_BORDER_AND_ACCENT_BAR` | `accentBorderCallout2` |
+| `LINE_CALLOUT_2_NO_BORDER` | `callout2` |
+| `LINE_CALLOUT_3` | `borderCallout3` |
+| `LINE_CALLOUT_3_ACCENT_BAR` | `accentCallout3` |
+| `LINE_CALLOUT_3_BORDER_AND_ACCENT_BAR` | `accentBorderCallout3` |
+| `LINE_CALLOUT_3_NO_BORDER` | `callout3` |
+| `LINE_CALLOUT_4` | `borderCallout4` |
+| `LINE_CALLOUT_4_ACCENT_BAR` | `accentCallout4` |
+| `LINE_CALLOUT_4_BORDER_AND_ACCENT_BAR` | `accentBorderCallout4` |
+| `LINE_CALLOUT_4_NO_BORDER` | `callout4` |
+| `CLOUD_CALLOUT` | `cloudCallout` |
+| `OVAL_CALLOUT` | `wedgeEllipseCallout` |
+| `RECTANGULAR_CALLOUT` | `wedgeRectCallout` |
+| `ROUNDED_RECTANGULAR_CALLOUT` | `wedgeRoundRectCallout` |
+
+### 基本形状 (Basic Shapes)
+
+| 常量名 | 值 |
+|---|---|
+| `ARC` | `arc` |
+| `BALLOON` | `wedgeRoundRectCallout` |
+| `BEVEL` | `bevel` |
+| `BLOCK_ARC` | `blockArc` |
+| `CAN` | `can` |
+| `CHORD` | `chord` |
+| `CLOUD` | `cloud` |
+| `CORNER` | `corner` |
+| `CROSS` | `plus` |
+| `CUBE` | `cube` |
+| `DIAMOND` | `diamond` |
+| `DONUT` | `donut` |
+| `DOUBLE_BRACE` | `bracePair` |
+| `DOUBLE_BRACKET` | `bracketPair` |
+| `DOUBLE_WAVE` | `doubleWave` |
+| `FOLDED_CORNER` | `folderCorner` |
+| `FRAME` | `frame` |
+| `FUNNEL` | `funnel` |
+| `GEAR_6` | `gear6` |
+| `GEAR_9` | `gear9` |
+| `HALF_FRAME` | `halfFrame` |
+| `HEART` | `heart` |
+| `HORIZONTAL_SCROLL` | `horizontalScroll` |
+| `ISOSCELES_TRIANGLE` | `triangle` |
+| `LEFT_BRACE` | `leftBrace` |
+| `LEFT_BRACKET` | `leftBracket` |
+| `LIGHTNING_BOLT` | `lightningBolt` |
+| `LINE` | `line` |
+| `LINE_INVERSE` | `lineInv` |
+| `MOON` | `moon` |
+| `NO_SYMBOL` | `noSmoking` |
+| `OVAL` | `ellipse` |
+| `PARALLELOGRAM` | `parallelogram` |
+| `PENTAGON` | `homePlate` |
+| `PIE` | `pie` |
+| `PIE_WEDGE` | `pieWedge` |
+| `PLAQUE` | `plaque` |
+| `PLAQUE_TABS` | `plaqueTabs` |
+| `RECTANGLE` | `rect` |
+| `REGULAR_PENTAGON` | `pentagon` |
+| `RIGHT_BRACE` | `rightBrace` |
+| `RIGHT_BRACKET` | `rightBracket` |
+| `RIGHT_TRIANGLE` | `rtTriangle` |
+| `ROUNDED_RECTANGLE` | `roundRect` |
+| `ROUND_1_RECTANGLE` | `round1Rect` |
+| `ROUND_2_DIAG_RECTANGLE` | `round2DiagRect` |
+| `ROUND_2_SAME_RECTANGLE` | `round2SameRect` |
+| `SMILEY_FACE` | `smileyFace` |
+| `SNIP_1_RECTANGLE` | `snip1Rect` |
+| `SNIP_2_DIAG_RECTANGLE` | `snip2DiagRect` |
+| `SNIP_2_SAME_RECTANGLE` | `snip2SameRect` |
+| `SNIP_ROUND_RECTANGLE` | `snipRoundRect` |
+| `SUN` | `sun` |
+| `TEAR` | `teardrop` |
+| `TRAPEZOID` | `trapezoid` |
+| `NON_ISOSCELES_TRAPEZOID` | `nonIsoscelesTrapezoid` |
+| `VERTICAL_SCROLL` | `verticalScroll` |
+| `WAVE` | `wave` |
+
+### 流程图 (Flowchart)
+
+| 常量名 | 值 |
+|---|---|
+| `FLOWCHART_ALTERNATE_PROCESS` | `flowChartAlternateProcess` |
+| `FLOWCHART_CARD` | `flowChartPunchedCard` |
+| `FLOWCHART_COLLATE` | `flowChartCollate` |
+| `FLOWCHART_CONNECTOR` | `flowChartConnector` |
+| `FLOWCHART_DATA` | `flowChartInputOutput` |
+| `FLOWCHART_DECISION` | `flowChartDecision` |
+| `FLOWCHART_DELAY` | `flowChartDelay` |
+| `FLOWCHART_DIRECT_ACCESS_STORAGE` | `flowChartMagneticDrum` |
+| `FLOWCHART_DISPLAY` | `flowChartDisplay` |
+| `FLOWCHART_DOCUMENT` | `flowChartDocument` |
+| `FLOWCHART_EXTRACT` | `flowChartExtract` |
+| `FLOWCHART_INTERNAL_STORAGE` | `flowChartInternalStorage` |
+| `FLOWCHART_MAGNETIC_DISK` | `flowChartMagneticDisk` |
+| `FLOWCHART_MANUAL_INPUT` | `flowChartManualInput` |
+| `FLOWCHART_MANUAL_OPERATION` | `flowChartManualOperation` |
+| `FLOWCHART_MERGE` | `flowChartMerge` |
+| `FLOWCHART_MULTIDOCUMENT` | `flowChartMultidocument` |
+| `FLOWCHART_OFFLINE_STORAGE` | `flowChartOfflineStorage` |
+| `FLOWCHART_OFFPAGE_CONNECTOR` | `flowChartOffpageConnector` |
+| `FLOWCHART_OR` | `flowChartOr` |
+| `FLOWCHART_PREDEFINED_PROCESS` | `flowChartPredefinedProcess` |
+| `FLOWCHART_PREPARATION` | `flowChartPreparation` |
+| `FLOWCHART_PROCESS` | `flowChartProcess` |
+| `FLOWCHART_PUNCHED_TAPE` | `flowChartPunchedTape` |
+| `FLOWCHART_SEQUENTIAL_ACCESS_STORAGE` | `flowChartMagneticTape` |
+| `FLOWCHART_SORT` | `flowChartSort` |
+| `FLOWCHART_STORED_DATA` | `flowChartOnlineStorage` |
+| `FLOWCHART_SUMMING_JUNCTION` | `flowChartSummingJunction` |
+| `FLOWCHART_TERMINATOR` | `flowChartTerminator` |
+
+### 星形与旗帜 (Stars & Ribbons)
+
+| 常量名 | 值 |
+|---|---|
+| `STAR_4_POINT` | `star4` |
+| `STAR_5_POINT` | `star5` |
+| `STAR_6_POINT` | `star6` |
+| `STAR_7_POINT` | `star7` |
+| `STAR_8_POINT` | `star8` |
+| `STAR_10_POINT` | `star10` |
+| `STAR_12_POINT` | `star12` |
+| `STAR_16_POINT` | `star16` |
+| `STAR_24_POINT` | `star24` |
+| `STAR_32_POINT` | `star32` |
+| `CURVED_DOWN_RIBBON` | `ellipseRibbon` |
+| `CURVED_UP_RIBBON` | `ellipseRibbon2` |
+| `DOWN_RIBBON` | `ribbon` |
+| `LEFT_RIGHT_RIBBON` | `leftRightRibbon` |
+| `UP_RIBBON` | `ribbon2` |
+| `CHART_PLUS` | `chartPlus` |
+| `CHART_STAR` | `chartStar` |
+| `CHART_X` | `chartX` |
+| `CORNER_TABS` | `cornerTabs` |
+| `SQUARE_TABS` | `squareTabs` |
+| `EXPLOSION1` | `irregularSeal1` |
+| `EXPLOSION2` | `irregularSeal2` |
+
+### 数学符号 (Math)
+
+| 常量名 | 值 |
+|---|---|
+| `MATH_DIVIDE` | `mathDivide` |
+| `MATH_EQUAL` | `mathEqual` |
+| `MATH_MINUS` | `mathMinus` |
+| `MATH_MULTIPLY` | `mathMultiply` |
+| `MATH_NOT_EQUAL` | `mathNotEqual` |
+| `MATH_PLUS` | `mathPlus` |
+
+### 多边形 (Polygons)
+
+| 常量名 | 值 |
+|---|---|
+| `DECAGON` | `decagon` |
+| `DODECAGON` | `dodecagon` |
+| `HEPTAGON` | `heptagon` |
+| `HEXAGON` | `hexagon` |
+| `OCTAGON` | `octagon` |
+| `DIAGONAL_STRIPE` | `diagStripe` |
+
+---
+
+## 已废弃参数
+
+| 已废弃参数 | 替代参数 | 废弃版本 |
+|---|---|---|
+| `lineSize` | `line.width` | v3.3.0 |
+| `lineDash` | `line.dashType` | v3.3.0 |
+| `lineHead` | `line.beginArrowType` | v3.3.0 |
+| `lineTail` | `line.endArrowType` | v3.3.0 |
+| `shapeName` | `objectName` | v3.10.0 |
+| `pt`（ShapeLineProps） | `width` | v3.3.0 |
+| `size`（ShapeLineProps） | `width` | v3.3.0 |
+| `alpha`（ShapeFillProps） | `transparency` | v3.3.0 |

reference/slide.md

@@ -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 |

reference/table.md

@@ -0,0 +1,203 @@
+# 表格参数 (Table Props)
+
+表格参数来自 `TableProps`（继承 `TextBaseProps`、`PositionProps`）和 `TableCellProps`（继承 `TextBaseProps`），用于 `slide.addTable()` 方法。
+
+---
+
+## 位置属性 (PositionProps)
+
+- **x**：水平位置
+  - 类型：`Coord`（`number | `${number}%``）
+  - 单位：英寸（number）或百分比（`'50%'`）
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+---
+
+## 表格专有属性 (TableProps)
+
+- **autoPage**：是否启用自动分页
+  - 类型：`boolean`
+  - 说明：内容溢出时自动创建新幻灯片
+  - 默认值：`false`
+
+- **autoPageCharWeight**：自动分页字符权重
+  - 类型：`number`
+  - 取值范围：`-1.0`–`1.0`
+  - 默认值：`0.0`
+  - 说明：调整每行字符数，正值使行更长
+
+- **autoPageLineWeight**：自动分页行权重
+  - 类型：`number`
+  - 取值范围：`-1.0`–`1.0`
+  - 默认值：`0.0`
+  - 说明：调整每页行数，正值使表格更高
+
+- **autoPageRepeatHeader**：自动分页时重复表头
+  - 类型：`boolean`
+  - 默认值：`false`
+  - 始于：v3.3.0
+
+- **autoPageHeaderRows**：表头行数
+  - 类型：`number`
+  - 说明：`autoPageRepeatHeader` 为 `true` 时需设置
+  - 默认值：`1`
+  - 示例：`2`（在前两行在新页上重复）
+  - 始于：v3.3.0
+
+- **autoPageSlideStartY**：自动分页新幻灯片的起始 Y 位置
+  - 类型：`number`
+  - 默认值：幻灯片上边距
+
+- **border**：表格边框
+  - 类型：`BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps]`
+  - 取值范围：单个值应用于所有四边；数组按上右下左（TRBL）顺序应用于各边
+
+- **colW**：列宽
+  - 类型：`number | number[]`
+  - 单位：英寸
+  - 说明：单个值均匀分配；数组按列依次应用
+  - 默认值：基于 `w` 的等宽列
+
+- **fill**：单元格填充
+  - 类型：`ShapeFillProps`
+  - 子参数：
+    - **fill.color**：填充颜色
+      - 类型：`Color`
+    - **fill.transparency**：透明度
+      - 类型：`number`
+      - 取值范围：`0`–`100`
+      - 默认值：`0`
+    - **fill.type**：填充类型
+      - 类型：`'none' | 'solid'`
+      - 默认值：`'solid'`
+
+- **margin**：单元格边距
+  - 类型：`Margin`（`number | [number, number, number, number]`）
+  - 单位：pt
+  - 说明：影响所有单元格，可被单元格级选项覆盖
+  - 默认值：PowerPoint 默认边距
+
+- **objectName**：对象名称
+  - 类型：`string`
+  - 说明：替代默认的 "Object N" 名称
+  - 默认值：`'Object 1'`
+
+- **rowH**：行高
+  - 类型：`number | number[]`
+  - 单位：英寸
+  - 说明：单个值均匀分配；数组按行依次应用
+  - 默认值：基于 `h` 的等高行
+
+- **verbose**：详细模式（开发工具）
+  - 类型：`boolean`
+  - 说明：在控制台输出自动分页计算的详细信息
+  - 默认值：`false`
+
+- **align**：水平对齐
+  - 类型：`'left' | 'center' | 'right' | 'justify'`
+  - 默认值：`'left'`
+
+- **valign**：垂直对齐
+  - 类型：`'top' | 'middle' | 'bottom'`
+  - 默认值：`'top'`
+
+---
+
+## 表格行与单元格
+
+- **TableCell**：单个单元格
+  - 类型：`{ text?: string | TableCell[], options?: TableCellProps }`
+  - 说明：`text` 可为字符串或嵌套表格；`options` 为单元格样式
+
+- **TableRow**：表格行
+  - 类型：`TableCell[]`
+  - 说明：每行由单元格数组组成
+
+- **TableRowSlide**：自动分页产出
+  - 类型：`{ rows: TableRow[] }`
+
+---
+
+## 表格单元格属性 (TableCellProps)
+
+继承 `TextBaseProps`。
+
+- **autoPageCharWeight**：自动分页字符权重
+  - 类型：`number`
+  - 取值范围：`-1.0`–`1.0`
+  - 默认值：`0.0`
+
+- **autoPageLineWeight**：自动分页行权重
+  - 类型：`number`
+  - 取值范围：`-1.0`–`1.0`
+  - 默认值：`0.0`
+
+- **border**：单元格边框
+  - 类型：`BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps]`
+  - 说明：单个值应用于所有四边；数组按上右下左（TRBL）顺序
+
+- **colspan**：列合并
+  - 类型：`number`
+  - 说明：跨列数
+
+- **fill**：单元格填充
+  - 类型：`ShapeFillProps`
+
+- **hyperlink**：单元格超链接
+  - 类型：`HyperlinkProps`
+  - 子参数：
+    - **hyperlink.slide**：链接到页码
+      - 类型：`number`
+    - **hyperlink.url**：链接 URL
+      - 类型：`string`
+    - **hyperlink.tooltip**：超链接提示
+      - 类型：`string`
+
+- **margin**：单元格边距
+  - 类型：`Margin`
+  - 单位：pt
+  - 默认值：`0`
+
+- **rowspan**：行合并
+  - 类型：`number`
+  - 说明：跨行数
+
+---
+
+## BorderProps
+
+用于 `border` 属性的类型定义。
+
+- **type**：边框类型
+  - 类型：`'none' | 'dash' | 'solid'`
+  - 默认值：`'solid'`
+
+- **color**：边框颜色
+  - 类型：`HexColor`
+  - 格式：6 位十六进制（无 `#`）
+  - 默认值：`'666666'`
+
+- **pt**：边框粗细
+  - 类型：`number`
+  - 单位：pt
+  - 默认值：`1`
+
+---
+
+## 已废弃参数 (TableProps)
+
+| 已废弃参数 | 替代参数 | 废弃版本 |
+|---|---|---|
+| `addHeaderToEach` | `autoPageRepeatHeader` | v3.3.0 |
+| `newSlideStartY` | `autoPageSlideStartY` | v3.3.0 |

reference/text.md

@@ -0,0 +1,391 @@
+# 文字参数 (Text Props)
+
+文字参数来自 `TextPropsOptions`（继承 `TextBaseProps`、`PositionProps`、`ObjectNameProps`）和 `TextGlowProps`，用于 `slide.addText()` 方法。
+
+---
+
+## 基础文字属性 (TextBaseProps)
+
+- **align**：水平对齐方式
+  - 类型：`'left' | 'center' | 'right' | 'justify'`
+  - 取值范围：`left`、`center`、`right`、`justify`
+  - 默认值：`'left'`
+
+- **bold**：粗体样式
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **breakLine**：添加换行符
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **bullet**：添加标准或自定义项目符号
+  - 类型：`boolean | BulletOptions`
+  - 取值范围：
+    - `true` — 使用标准项目符号
+    - `false` — 无项目符号
+    - 对象 — 自定义项目符号配置
+  - 默认值：`false`
+  - 子参数：
+    - **bullet.type**：项目符号类型
+      - 类型：`'bullet' | 'number'`
+      - 取值范围：`bullet`、`number`
+      - 默认值：`'bullet'`
+    - **bullet.characterCode**：项目符号字符代码（Unicode）
+      - 类型：`string`
+      - 示例：`'25BA'`（U+25BA 黑色右指向指针）
+    - **bullet.indent**：缩进量（项目符号与文字之间的距离，单位 pt）
+      - 类型：`number`
+      - 取值范围：任意正整数
+      - 默认值：`27`
+    - **bullet.numberType**：编号类型
+      - 类型：`string`
+      - 取值范围：
+        `alphaLcParenBoth` | `alphaLcParenR` | `alphaLcPeriod` | `alphaUcParenBoth` | `alphaUcParenR` |
+        `alphaUcPeriod` | `arabicParenBoth` | `arabicParenR` | `arabicPeriod` | `arabicPlain` |
+        `romanLcParenBoth` | `romanLcParenR` | `romanLcPeriod` | `romanUcParenBoth` | `romanUcParenR` |
+        `romanUcPeriod`
+    - **bullet.numberStartAt**：编号起始值
+      - 类型：`number`
+      - 取值范围：任意正整数
+      - 默认值：`1`
+
+- **color**：文字颜色
+  - 类型：`Color`（`HexColor | ThemeColor`）
+  - 取值范围：6 位十六进制颜色值（不含 `#`）或主题色（`tx1`、`tx2`、`bg1`、`bg2`、`accent1`–`accent6`）
+  - 示例：`'FF0000'`、`pptx.SchemeColor.text1`
+
+- **fontFace**：字体名称
+  - 类型：`string`
+  - 示例：`'Arial'`、`'微软雅黑'`
+
+- **fontSize**：字号
+  - 类型：`number`
+  - 取值范围：`1`–`400`（pt）
+  - 示例：`12`、`24`
+
+- **highlight**：文字高亮颜色
+  - 类型：`HexColor`
+  - 格式：6 位十六进制颜色值（不含 `#`）
+  - 示例：`'FFFF00'`（黄色）
+
+- **italic**：斜体样式
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **lang**：语言
+  - 类型：`string`
+  - 取值范围：ISO 639-1 标准语言代码
+  - 默认值：`'en-US'`
+  - 示例：`'fr-CA'`
+
+- **softBreakBefore**：在文字内容前添加软换行（Shift+Enter）
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+  - 始于：v3.5.0
+
+- **tabStops**：制表位
+  - 类型：`Array<{ position: number, alignment?: 'l' | 'r' | 'ctr' | 'dec' }>`
+  - 说明：PowerPoint 段落 > 制表位 > 制表位位置
+  - 示例：`[{ position: 1 }, { position: 3 }]`
+  - 子参数：
+    - **position**：制表位位置（英寸）
+    - **alignment**：对齐方式（可选），`'l'`（左）、`'r'`（右）、`'ctr'`（居中）、`'dec'`（小数点）
+
+- **textDirection**：文字方向
+  - 类型：`'horz' | 'vert' | 'vert270' | 'wordArtVert'`
+  - 取值范围：
+    - `horz` — 水平
+    - `vert` — 旋转 90 度
+    - `vert270` — 旋转 270 度
+    - `wordArtVert` — 堆叠
+  - 默认值：`'horz'`
+
+- **transparency**：透明度
+  - 类型：`number`
+  - 取值范围：`0`–`100`（百分比）
+  - 默认值：`0`
+
+- **underline**：下划线属性
+  - 类型：`{ style?: string, color?: Color }`
+  - 子参数：
+    - **underline.style**：下划线样式
+      - 类型：`string`
+      - 取值范围：
+        `'dash'` | `'dashHeavy'` | `'dashLong'` | `'dashLongHeavy'` | `'dbl'` | `'dotDash'` |
+        `'dotDashHeave'` | `'dotDotDash'` | `'dotDotDashHeavy'` | `'dotted'` | `'dottedHeavy'` |
+        `'heavy'` | `'none'` | `'sng'` | `'wavy'` | `'wavyDbl'` | `'wavyHeavy'`
+    - **underline.color**：下划线颜色
+      - 类型：`Color`
+
+- **valign**：垂直对齐
+  - 类型：`'top' | 'middle' | 'bottom'`
+  - 取值范围：`top`、`middle`、`bottom`
+  - 默认值：`'top'`
+
+---
+
+## 文字专有属性 (TextPropsOptions 特有)
+
+- **baseline**：基线偏移
+  - 类型：`number`
+
+- **charSpacing**：字符间距
+  - 类型：`number`
+
+- **fit**：文本适配方式
+  - 类型：`'none' | 'shrink' | 'resize'`
+  - 取值范围：
+    - `none` — 不自动调整
+    - `shrink` — 溢出时缩小文字
+    - `resize` — 调整形状以适配文字
+  - 默认值：`'none'`
+  - 始于：v3.3.0
+
+- **fill**：形状填充
+  - 类型：`ShapeFillProps`
+  - 子参数：
+    - **fill.color**：填充颜色
+      - 类型：`Color`
+      - 格式：`HexColor`（6 位十六进制无 `#`）或 `ThemeColor`
+    - **fill.transparency**：透明度
+      - 类型：`number`
+      - 取值范围：`0`–`100`
+      - 默认值：`0`
+    - **fill.type**：填充类型
+      - 类型：`'none' | 'solid'`
+      - 默认值：`'solid'`
+
+- **flipH**：水平翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **flipV**：垂直翻转
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **glow**：发光效果
+  - 类型：`TextGlowProps`
+  - 子参数：
+    - **glow.color**：发光颜色
+      - 类型：`HexColor`
+      - 格式：6 位十六进制（无 `#`）
+    - **glow.opacity**：不透明度
+      - 类型：`number`
+      - 取值范围：`0.0`–`1.0`
+    - **glow.size**：发光大小
+      - 类型：`number`
+      - 单位：pt
+
+- **hyperlink**：超链接
+  - 类型：`HyperlinkProps`
+  - 子参数：
+    - **hyperlink.slide**：链接到页码
+      - 类型：`number`
+    - **hyperlink.url**：链接 URL
+      - 类型：`string`
+    - **hyperlink.tooltip**：超链接提示
+      - 类型：`string`
+
+- **indentLevel**：缩进层级
+  - 类型：`number`
+
+- **isTextBox**：是否为文本框
+  - 类型：`boolean`
+
+- **line**：线条（边框/轮廓线）
+  - 类型：`ShapeLineProps`
+  - 子参数（继承 `ShapeFillProps`）：
+    - **line.color**：线条颜色
+      - 类型：`Color`
+    - **line.transparency**：线条透明度
+      - 类型：`number`
+      - 取值范围：`0`–`100`
+    - **line.type**：填充类型
+      - 类型：`'none' | 'solid'`
+    - **line.width**：线条宽度
+      - 类型：`number`
+      - 单位：pt
+      - 默认值：`1`
+    - **line.dashType**：虚线类型
+      - 类型：`string`
+      - 取值范围：`'solid' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot'`
+      - 默认值：`'solid'`
+    - **line.beginArrowType**：起点箭头类型
+      - 类型：`'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle'`
+    - **line.endArrowType**：终点箭头类型
+      - 类型：`'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle'`
+
+- **lineSpacing**：行间距（固定值）
+  - 类型：`number`
+  - 单位：pt
+  - 说明：PowerPoint 段落 > 缩进和间距 > 行距 > "固定值"
+  - 示例：`28`
+
+- **lineSpacingMultiple**：行间距（倍数）
+  - 类型：`number`
+  - 取值范围：`0.0`–`9.99`
+  - 单位：百分比倍数
+  - 说明：PowerPoint 段落 > 缩进和间距 > 行距 > "多倍行距"
+  - 示例：`1.5`（1.5 倍行距）
+  - 始于：v3.5.0
+
+- **margin**：边距
+  - 类型：`Margin`（`number | [number, number, number, number]`）
+  - 单位：pt
+  - 说明：PowerPoint 设置形状格式 > 形状选项 > 大小与属性 > 文本框 > 左右上下边距
+  - 默认值：PowerPoint 默认 "常规" 边距
+  - 示例：`0`（四边统一）、`[10, 5, 10, 5]`（上、右、下、左）
+
+- **outline**：文字轮廓
+  - 类型：`{ color: Color, size: number }`
+  - 子参数：
+    - **outline.color**：轮廓颜色
+      - 类型：`Color`
+    - **outline.size**：轮廓大小
+      - 类型：`number`
+      - 单位：pt
+
+- **paraSpaceAfter**：段后间距
+  - 类型：`number`
+
+- **paraSpaceBefore**：段前间距
+  - 类型：`number`
+
+- **placeholder**：占位符类型
+  - 类型：`string`
+  - 示例：`'body'`
+
+- **rectRadius**：圆角矩形半径
+  - 类型：`number`
+  - 取值范围：`0.0`–`1.0`
+  - 默认值：`0`
+  - 说明：仅适用于 `ROUNDED_RECTANGLE` 形状
+
+- **rotate**：旋转角度
+  - 类型：`number`
+  - 取值范围：`-360`–`360`（度）
+  - 默认值：`0`
+
+- **rtlMode**：从右向左模式
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **shadow**：阴影
+  - 类型：`ShadowProps`
+  - 子参数：
+    - **shadow.type**：阴影类型
+      - 类型：`'outer' | 'inner' | 'none'`
+      - 默认值：`'none'`
+    - **shadow.opacity**：不透明度
+      - 类型：`number`
+      - 取值范围：`0.0`–`1.0`
+    - **shadow.blur**：模糊
+      - 类型：`number`
+      - 取值范围：`0`–`100`（pt）
+      - 默认值：`0`
+    - **shadow.angle**：角度
+      - 类型：`number`
+      - 取值范围：`0`–`359`（度）
+      - 默认值：`0`
+    - **shadow.offset**：偏移距离
+      - 类型：`number`
+      - 取值范围：`0`–`200`（pt）
+      - 默认值：`0`
+    - **shadow.color**：阴影颜色
+      - 类型：`HexColor`
+      - 格式：6 位十六进制（无 `#`）
+    - **shadow.rotateWithShape**：阴影是否随形状旋转
+      - 类型：`boolean`
+      - 默认值：`false`
+
+- **shape**：形状名称
+  - 类型：`SHAPE_NAME`
+  - 说明：将文字转为指定形状
+
+- **strike**：删除线
+  - 类型：`boolean | 'dblStrike' | 'sngStrike'`
+  - 取值范围：`true`（单删除线）、`false`、`'dblStrike'`（双删除线）、`'sngStrike'`（单删除线）
+
+- **subscript**：下标
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **superscript**：上标
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`false`
+
+- **vert**：垂直文字模式
+  - 类型：`string`
+  - 取值范围：
+    `'eaVert'` | `'horz'` | `'mongolianVert'` | `'vert'` | `'vert270'` | `'wordArtVert'` | `'wordArtVertRtl'`
+
+- **wrap**：文字自动换行
+  - 类型：`boolean`
+  - 取值范围：`true` / `false`
+  - 默认值：`true`
+  - 始于：v3.3.0
+
+---
+
+## 位置属性 (PositionProps)
+
+- **x**：水平位置
+  - 类型：`Coord`（`number | `${number}%``）
+  - 单位：英寸（number）或百分比（`'50%'`）
+
+- **y**：垂直位置
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **w**：宽度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+- **h**：高度
+  - 类型：`Coord`
+  - 单位：英寸或百分比
+
+---
+
+## 对象名称属性 (ObjectNameProps)
+
+- **objectName**：对象名称
+  - 类型：`string`
+  - 说明：替代默认的 "Object N" 名称，在 PowerPoint 选择窗格中显示
+  - 默认值：`'Object 1'`
+  - 始于：v3.10.0
+
+---
+
+## TextProps
+
+- **text**：文字内容
+  - 类型：`string`
+- **options**：文字选项
+  - 类型：`TextPropsOptions`
+
+---
+
+## 已废弃参数
+
+以下参数已废弃，建议使用替代参数：
+
+| 已废弃参数 | 替代参数 | 废弃版本 |
+|---|---|---|
+| `autoFit` | `fit` | v3.3.0 |
+| `shrinkText` | `fit` | v3.3.0 |
+| `inset` | `margin` | v3.10.0 |
+| `lineDash` | `line.dashType` | v3.3.0 |
+| `lineHead` | `line.beginArrowType` | v3.3.0 |
+| `lineSize` | `line.width` | v3.3.0 |
+| `lineTail` | `line.endArrowType` | v3.3.0 |