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,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 中右击图表 > "编辑替代文字"