# 形状参数 (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 |