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

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

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 |