PPTX
形状与文本
创建带格式文本、段落、对齐、列表和文本自适应的形状
形状是幻灯片的主要构建块。一个形状可以通过 textBody 属性来包含文本内容。
基本形状
import { generatePresentation } from "@office-open/pptx";
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "13.2cm",
"height": "7.9cm",
"textBody": { "text": "Simple text" }
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "13.2cm",
height: "7.9cm",
textBody: { text: "Simple text" },
},
},
],
}
几何预设
使用 geometry 选项设置形状类型：
{
"slides": [
{
"children": [
{
"shape": {
"x": "2.6cm",
"y": "2.6cm",
"width": "5.3cm",
"height": "4.0cm",
"geometry": "ellipse",
"fill": "4472C4",
"outline": { "color": "2E74B5", "width": 12700 },
"textBody": { "text": "椭圆" }
}
},
{
"shape": {
"x": "10.6cm",
"y": "2.6cm",
"width": "5.3cm",
"height": "4.0cm",
"geometry": "triangle",
"fill": "ED7D31",
"outline": { "color": "C5504B", "width": 12700 },
"textBody": { "text": "三角形" }
}
}
]
}
]
}
[
{ shape: { geometry: "ellipse", fill: "4472C4", outline: { color: "2E74B5", width: 2 } } },
{ shape: { geometry: "triangle", fill: "ED7D31", outline: { color: "C5504B", width: 2 } } },
];
可用的几何类型：
| Geometry | 形状 |
|---|---|
"rect" | 矩形（默认） |
"ellipse" | 椭圆/圆形 |
"roundRect" | 圆角矩形 |
"triangle" | 三角形 |
"diamond" | 菱形 |
"star5" | 五角星 |
"hexagon" | 六边形 |
"chevron" | V 形箭头 |
"arrow" | 箭头 |
使用 outline 添加边框：{ "color": "2E74B5", "width": 12700 }。不要使用 strokeColor 或 strokeWidth，这些不是有效的属性。
段落和文本片段
使用 textBody.paragraphs 完全控制文本格式：
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "15.9cm",
"height": "6.6cm",
"textBody": {
"paragraphs": [
{
"children": [{ "text": "Bold title", "bold": true, "size": 28, "fill": "2E74B5" }]
},
{
"children": [
{ "text": "Normal text with " },
{ "text": "italic", "italic": true },
{ "text": " and " },
{ "text": "colored", "fill": "FF0000", "underline": "single" }
]
}
]
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "15.9cm",
height: "6.6cm",
textBody: {
paragraphs: [
{
children: [{ text: "Bold title", bold: true, size: 28, fill: "2E74B5" }],
},
{
children: [
"Normal text with ",
{ text: "italic", italic: true },
" and ",
{ text: "colored", fill: "FF0000", underline: "single" },
],
},
],
},
},
},
],
}
TextRun 格式选项
{
text: "Formatted text",
size: 24, // 字号（磅）
bold: true,
italic: true,
underline: "single", // "single" | "double" | "none"
strike: "sngStrike", // "sngStrike" | "dblStrike" | "noStrike"
fill: "4472C4", // 十六进制颜色，不带 #
font: "Calibri", // 字符串设 latin + eastAsia；对象可分别设置各文种
// font: { latin: "Calibri", eastAsia: "宋体", complexScript: "Arial", symbol: "Symbol" },
highlight: { value: "FFFF00" }, // 文本高亮颜色（a:highlight）
kern: 12, // 字距调整阈值（磅）
outline: true, // a:ln — true 使用默认线条；OutlineOptions 对象可完整往返
shadow: true, // a:effectLst — true 使用默认外阴影；EffectListOptions 对象可完整往返
hyperlink: { url: "https://example.com" }, // 外部链接
// hyperlink: { slide: 2 }, // 内部幻灯片跳转（从 1 开始）
}
outline 与 shadow 接受 true（使用合理默认）或完整选项对象——完整字段见 轮廓与效果。hyperlink（外部 url 或内部 slide 跳转）见 链接。
对齐方式
{
properties: { alignment: "left" }, // "left" | "center" | "right" | "justify"
children: [{ text: "Aligned text" }],
}
段落属性
除对齐外，段落 properties 还承载缩进、间距、方向、制表位和默认 run 格式（a:defRPr）：
{
paragraph: {
properties: {
indentLevel: 1, // 大纲层级（a:pPr @lvl）
indent: 457200, // 首行缩进，EMU（a:pPr @indent）
marginIndent: 457200, // 左边距，EMU（@marL）
marginRight: 457200, // 右边距，EMU（@marR）
lineSpacingPercent: 150, // 单倍行距的 150%（a:lnSpc）
spaceBefore: 457, // 段前间距，磅（a:spcBef）
spaceAfter: 457, // 段后间距，磅（a:spcAft）
rightToLeft: true, // 从右到左文字流向（@rtl）
eastAsianLineBreak: true, // 东亚换行（@eaLnBrk）
latinLineBreak: true, // 拉丁文换行（@latinLnBrk）
tabStops: [{ position: 914400, alignment: "l" }], // @pos EMU，"l"|"ctr"|"r"|"dec"
fontAlignment: "base", // "auto" | "t" | "ctr" | "b" | "base"（@fontAlgn）
defaultRunProperties: { size: 24, font: "Calibri" }, // a:defRPr — 默认 run 格式
},
children: [{ text: "段落文本" }],
},
}
项目符号列表
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "15.9cm",
"height": "9.3cm",
"textBody": {
"paragraphs": [
{
"properties": { "bullet": { "type": "char", "char": "●" } },
"children": [{ "text": "First item" }]
},
{
"properties": { "bullet": { "type": "char", "char": "●" } },
"children": [{ "text": "Second item" }]
},
{
"properties": { "bullet": { "type": "autoNum", "format": "arabicPeriod" } },
"children": [{ "text": "Numbered item" }]
}
]
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "15.9cm",
height: "9.3cm",
textBody: {
paragraphs: [
{
properties: { bullet: { type: "char", char: "●" } },
children: [{ text: "First item" }],
},
{
properties: { bullet: { type: "char", char: "●" } },
children: [{ text: "Second item" }],
},
{
properties: { bullet: { type: "autoNum", format: "arabicPeriod" } },
children: [{ text: "Numbered item" }],
},
],
},
},
},
],
}
文本锚点（垂直对齐）
控制文本在形状内的垂直位置：
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "13.2cm",
"height": "7.9cm",
"textBody": {
"anchor": "t",
"text": "Top-aligned text"
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "13.2cm",
height: "7.9cm",
textBody: {
anchor: "t", // "t" | "ctr" | "b" | "just" | "dist"
text: "Top-aligned text",
},
},
},
],
}
文本自适应
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "10.6cm",
"height": "5.3cm",
"textBody": {
"text": "This text will shrink to fit the shape",
"autoFit": "normal"
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "10.6cm",
height: "5.3cm",
textBody: {
text: "This text will shrink to fit the shape",
autoFit: "normal", // 自动缩小文本以适应形状
// 或 autoFit: "shape" 自动调整形状大小
},
},
},
],
}
旋转和翻转
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "7.9cm",
"height": "5.3cm",
"rotation": 45,
"flipHorizontal": true,
"textBody": { "text": "Rotated shape" }
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "7.9cm",
height: "5.3cm",
rotation: 45, // 角度
flipHorizontal: true, // 水平镜像
textBody: { text: "Rotated shape" },
},
},
],
}
文本分栏
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "1.3cm",
"width": "21.2cm",
"height": "9.3cm",
"textBody": {
"columns": 2,
"columnSpacing": 0.5,
"paragraphs": [
{ "children": [{ "text": "Column 1 content..." }] },
{ "children": [{ "text": "Column 2 content..." }] }
]
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "1.3cm",
width: "21.2cm",
height: "9.3cm",
textBody: {
columns: 2,
columnSpacing: 0.5,
paragraphs: [
{ children: ["Column 1 content..."] },
{ children: ["Column 2 content..."] },
],
},
},
},
],
}
文本边距
{
"slides": [
{
"children": [
{
"shape": {
"x": "1.3cm",
"y": "2.6cm",
"width": "15.9cm",
"height": "7.9cm",
"textBody": {
"margins": { "top": 0.2, "bottom": 0.2, "left": 0.3, "right": 0.3 },
"text": "Text with custom margins"
}
}
}
]
}
]
}
{
children: [
{
shape: {
x: "1.3cm",
y: "2.6cm",
width: "15.9cm",
height: "7.9cm",
textBody: {
margins: { top: 0.2, bottom: 0.2, left: 0.3, right: 0.3 },
text: "Text with custom margins",
},
},
},
],
}