From 17d232dcef501ee3254045de98d5755398d90f58 Mon Sep 17 00:00:00 2001 From: oldli <48485262@qq.com> Date: Thu, 23 Jul 2026 12:36:09 +0800 Subject: [PATCH] feat: add reference docs for shape, table, image, chart, slide, master, output, coordinate Co-Authored-By: Claude Sonnet 5 --- reference/chart.md | 707 ++++++++++++++++++++++++++++++++++++++++ reference/coordinate.md | 175 ++++++++++ reference/image.md | 197 +++++++++++ reference/master.md | 127 ++++++++ reference/output.md | 156 +++++++++ reference/shape.md | 440 +++++++++++++++++++++++++ reference/slide.md | 222 +++++++++++++ reference/table.md | 203 ++++++++++++ reference/text.md | 391 ++++++++++++++++++++++ 9 files changed, 2618 insertions(+) create mode 100644 reference/chart.md create mode 100644 reference/coordinate.md create mode 100644 reference/image.md create mode 100644 reference/master.md create mode 100644 reference/output.md create mode 100644 reference/shape.md create mode 100644 reference/slide.md create mode 100644 reference/table.md create mode 100644 reference/text.md diff --git a/reference/chart.md b/reference/chart.md new file mode 100644 index 0000000..5632afb --- /dev/null +++ b/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 中右击图表 > "编辑替代文字" diff --git a/reference/coordinate.md b/reference/coordinate.md new file mode 100644 index 0000000..d3f8076 --- /dev/null +++ b/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' +``` diff --git a/reference/image.md b/reference/image.md new file mode 100644 index 0000000..ddce82f --- /dev/null +++ b/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` + - 说明：鼠标悬停时显示的文字 diff --git a/reference/master.md b/reference/master.md new file mode 100644 index 0000000..b092e49 --- /dev/null +++ b/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 | diff --git a/reference/output.md b/reference/output.md new file mode 100644 index 0000000..f338231 --- /dev/null +++ b/reference/output.md @@ -0,0 +1,156 @@ +# 输出参数 (Output Props) + +输出参数用于导出演示文稿，支持 `writeFile()`（写入文件）、`write()`（返回数据）和 `stream()`（返回流）三种方式。 + +--- + +## 输出方法 + +### pptx.writeFile() + +```ts +pptx.writeFile(props?: WriteFileProps): Promise +``` + +- **fileName**：导出文件名 + - 类型：`string` + - 默认值：`'Presentation.pptx'` + +- **compression**：是否启用压缩 + - 类型：`boolean` + - 默认值：`false` + - 说明：可显著减小文件体积，但导出耗时略长 + - 始于：v3.5.0 + +### pptx.write() + +```ts +pptx.write(props?: WriteProps): Promise +``` + +- **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 +``` + +- **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` diff --git a/reference/shape.md b/reference/shape.md new file mode 100644 index 0000000..bd5542d --- /dev/null +++ b/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 | diff --git a/reference/slide.md b/reference/slide.md new file mode 100644 index 0000000..b962f21 --- /dev/null +++ b/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 | diff --git a/reference/table.md b/reference/table.md new file mode 100644 index 0000000..29b0fe4 --- /dev/null +++ b/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 | diff --git a/reference/text.md b/reference/text.md new file mode 100644 index 0000000..d7573b4 --- /dev/null +++ b/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 |