# 图表参数 (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`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **catAxisLabelFrequency**：标签频率
  - 类型：`string`

- **catAxisLabelPos**：标签位置
  - 类型：`'none' | 'low' | 'high' | 'nextTo'`

- **catAxisLabelRotate**：标签旋转角度
  - 类型：`number`
  - 单位：度
  - 取值范围：无特殊约束范围
  - 无默认值

- **catAxisLineColor**：轴线颜色
  - 类型：`string`

- **catAxisLineShow**：显示轴线
  - 类型：`boolean`

- **catAxisLineSize**：轴线粗细
  - 类型：`number`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **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`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **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`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **valAxisLabelFormatCode**：数值轴标签格式代码
  - 类型：`string`

- **valAxisLabelPos**：数值轴标签位置
  - 类型：`'none' | 'low' | 'high' | 'nextTo'`

- **valAxisLabelRotate**：数值轴标签旋转
  - 类型：`number`
  - 单位：度
  - 取值范围：无特殊约束范围
  - 无默认值

- **valAxisLineColor**：数值轴线颜色
  - 类型：`string`

- **valAxisLineShow**：显示数值轴线
  - 类型：`boolean`

- **valAxisLineSize**：数值轴线粗细
  - 类型：`number`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **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`
  - 取值范围：`'box' | 'cylinder' | 'cone' | 'pyramid'`（PowerPoint 标准值），类型声明为 string，也可接受其他值
  - 默认值：`'box'`

- **barDir**：柱形方向
  - 类型：`string`
  - 取值范围：`'bar'`（水平）、`'col'`（垂直）
  - 默认值：`'col'`

- **barGapDepthPct**：3D 柱形深度间距百分比
  - 类型：`number`
  - 取值范围：`0`–`500`
  - 默认值：`150`
  - 单位：%

- **barGapWidthPct**：间距宽度百分比
  - 类型：`number`
  - 取值范围：`0`–`500`
  - 默认值：`150`

- **barGrouping**：分组方式
  - 类型：`string`
  - 取值范围：`'clustered' | 'stacked' | 'standard'`（PowerPoint 标准值），类型声明为 string，也可接受其他值
  - 默认值：`'clustered'`

- **barOverlapPct**：系列重叠百分比
  - 类型：`number`
  - 取值范围：`-100`–`100`
  - 默认值：`0`
  - 始于：v3.9.0

---

## 圆环图属性 (IChartPropsChartDoughnut)

- **dataNoEffects**：禁用数据点效果
  - 类型：`boolean`
  - 默认值：`false`

- **holeSize**：中心孔大小
  - 类型：`number`
  - 取值范围：`0`–`90`（百分比）
  - 默认值：`50`

---

## 折线图属性 (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`
  - 默认值：`false`

- **firstSliceAng**：第一扇区起始角度
  - 类型：`number`
  - 取值范围：`0`–`359`
  - 默认值：`0`
  - 始于：v3.4.0

---

## 雷达图属性 (IChartPropsChartRadar)

- **radarStyle**：雷达图样式
  - 类型：`'standard' | 'marker' | 'filled'`
  - 默认值：`'standard'`

---

## 数据标签属性 (IChartPropsDataLabel)

- **dataLabelBkgrdColors**：数据标签背景色
  - 类型：`boolean`
  - 默认值：`false`

- **dataLabelColor**：数据标签颜色
  - 类型：`string`
  - 取值范围：无特殊约束范围
  - 无默认值

- **dataLabelFontBold**：数据标签粗体
  - 类型：`boolean`

- **dataLabelFontFace**：数据标签字体
  - 类型：`string`

- **dataLabelFontItalic**：数据标签斜体
  - 类型：`boolean`

- **dataLabelFontSize**：数据标签字号
  - 类型：`number`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **dataLabelFormatCode**：数据标签格式代码
  - 类型：`string`
  - 示例：`'#%'`、`'0.00%'`、`'$0.00'`

- **dataLabelFormatScatter**：散点图标签格式
  - 类型：`'custom' | 'customXY' | 'XY'`

- **dataLabelPosition**：数据标签位置
  - 类型：`'b' | 'bestFit' | 'ctr' | 'l' | 'r' | 't' | 'inEnd' | 'outEnd'`

---

## 数据表属性 (IChartPropsDataTable)

- **dataTableFontSize**：数据表字号
  - 类型：`number`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **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`
  - 取值范围：`'l' | 'ctr' | 'r'`
  - 默认值：`'ctr'`

- **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`
  - 单位：pt
  - 取值范围：无特殊约束范围
  - 无默认值

- **style**：网格线样式
  - 类型：`'solid' | 'dash' | 'dot' | 'none'`

---

## IChartPropsFillLine

用于 `chartArea`、`plotArea` 的填充与边框基础类型。

- **border**：边框
  - 类型：`BorderProps`

- **fill**：填充
  - 类型：`ShapeFillProps`

---

## IChartOpts 附加属性

- **altText**：替代文字（无障碍）
  - 类型：`string`
  - 说明：PowerPoint 中右击图表 > "编辑替代文字"

---

## 已废弃参数

| 已废弃参数 | 替代参数 | 废弃版本 |
|---|---|---|
| `border` | `plotArea.border` | v3.11.0 |
| `fill` | `plotArea.fill` | v3.11.0 |