Mud Tools

Appearance

.NET 操作 PowerPoint COM 组件：从零到精通的幻灯片制作实战 ​

文本内容的写入与格式化 ​

问题 ​

给占位符赋值 TextRange.Text = "xxx" 只能解决"有文字"的问题。实际交付的 PPT 要求字号统一、重点加粗、颜色搭配、段落间距整齐。如果 50 页的正文都是默认 18pt 宋体，这个 PPT 是不可能被采用的。

这篇讲清楚两个问题：写入文本有哪些路径，以及如何精细控制每一个字符的外观。

操作占位符 vs 插入新文本框 ​

幻灯片上的每一个可见元素都是一个 Shape。文本有两种进入 PPT 的途径：

路径 A — 操作占位符（Placeholder）

适合有预设版式的幻灯片。占位符是幻灯片版式里预定义的文本框，比如标题框、正文框。

csharp
var slide = pres.AddSlide(PpSlideLayout.ppLayoutText);

// 方式 1: 通过 Shapes.Title 拿到标题占位符
var titleShape = slide.Shapes.Title;
titleShape.TextFrame.TextRange.Text = "销售趋势分析";

// 方式 2: 通过 Placeholders 集合索引
var subtitlePlaceholder = slide.Shapes.Placeholders[2];  // 正文占位符通常是 2 号
var bodyRange = subtitlePlaceholder.TextFrame.TextRange;
bodyRange.Text = "2026 年上半年度数据汇总";

路径 B — 插入新文本框（Textbox）

适合完全自定义布局，从 ppLayoutBlank 起步的场景。

csharp
var blank = pres.AddSlide(PpSlideLayout.ppLayoutBlank);

// 参数：方向、左、上、宽、高（单位：pt）
var textBox = blank.Shapes.AddTextbox(
    MsoTextOrientation.msoTextOrientationHorizontal,
    left: 50, top: 100, width: 600, height: 300);

var range = textBox.TextFrame.TextRange;
range.Text = "这是独立文本框，不受版式限制。";

两种路径的核心差异：

维度占位符独立文本框
是否继承母版样式是否
能否被母版批量更新能不能
删除后是否可恢复通过母版重置需要重新绘制
适合场景标准化模板自由排版

追加段落 ​

TextRange.Text 赋一个字面量会把内容完全覆盖。追加内容用 InsertAfter 或 \n 换行：

csharp
var range = textBox.TextFrame.TextRange;
range.Text = "第一行标题";

// 追加段落（方法一：换行符）
range.Text += "\n第二行内容";
range.Text += "\n第三行内容";

// 追加段落（方法二：InsertAfter）
var newPara = range.InsertAfter("\n这是插入的段落");

InsertAfter 返回一个新的 IPowerPointTextRange 对象，指向新插入的文本段，可以直接链式格式化它。

字体样式设置 ​

字体属性通过 TextRange.Font 访问，它返回一个 IPowerPointFont：

csharp
var titleRange = slide.Shapes.Title.TextFrame.TextRange;

// 字体名称（英文字体和中文字体分别设置）
titleRange.Font.Name = "Arial";
titleRange.Font.NameFarEast = "微软雅黑";

// 字号
titleRange.Font.Size = 36;

// 字形
titleRange.Font.Bold = true;
titleRange.Font.Italic = false;
titleRange.Font.Underline = false;

// 颜色 — 通过 Color 属性拿到 IPowerPointColorFormat
titleRange.Font.Color.RGB = 0x1A5276;  // 深蓝

// 阴影效果
titleRange.Font.Shadow = true;

IPowerPointFont 的完整属性表：

属性类型说明
Namestring西文字体
NameFarEaststring东亚字体（中文用这个）
NameAsciistringASCII 字体
Sizefloat字号（pt）
Boldbool加粗
Italicbool斜体
Underlinebool下划线
Shadowbool阴影
Embossbool浮雕
Subscriptbool下标
Superscriptbool上标
Color.RGBint颜色值（0xRRGGBB）

段落格式 ​

段落级的排版属性在 TextRange.ParagraphFormat 上：

csharp
var bodyRange = slide.Shapes[2].TextFrame.TextRange;
bodyRange.Text = "第一段内容：项目概述\n第二段内容：关键技术\n第三段内容：成果展示";

var pf = bodyRange.ParagraphFormat;

// 对齐方式
pf.Alignment = PpParagraphAlignment.ppAlignLeft;

// 段间距
pf.SpaceBefore = 6;   // 段前 6pt
pf.SpaceAfter = 10;   // 段后 10pt
pf.SpaceWithin = 1.5f; // 行距 1.5 倍

// 文字方向
pf.TextDirection = PpDirection.ppDirectionLeftToRight;

// 自动换行
pf.WordWrap = true;

PpParagraphAlignment 枚举值：

枚举说明
ppAlignLeft左对齐
ppAlignCenter居中
ppAlignRight右对齐
ppAlignJustify两端对齐
ppAlignDistribute分散对齐

链式设置不同段落的格式 ​

通过 Paragraphs(start, length) 方法可以拿到子范围，实现"一段加粗、一段灰色"的效果：

csharp
var range = textBox.TextFrame.TextRange;
range.Text = "标题行\n第一段正文\n第二段正文";

// 设置第一段（从开头到第一个换行）
var firstLine = range.Paragraphs(1, 1);
firstLine.Font.Size = 28;
firstLine.Font.Bold = true;

// 设置后续段落
var secondPara = range.Paragraphs(2, 1);
secondPara.Font.Size = 16;
secondPara.Font.Color.RGB = 0x666666;

var thirdPara = range.Paragraphs(3, 1);
thirdPara.Font.Size = 16;
thirdPara.ParagraphFormat.Alignment = PpParagraphAlignment.ppAlignRight;

避坑指南：中文乱码 ​

这是中文字符操作 PPT 最常见的坑。

原因 1：字体未设置东亚字体

Font.Name 设置的是西文字体，对中文字符不生效。必须同时设置 NameFarEast：

csharp
range.Font.Name = "Arial";          // 英文用 Arial
range.Font.NameFarEast = "微软雅黑"; // 中文用微软雅黑

原因 2：操作系统缺字体

如果你在服务器上跑（比如 Windows Server Core），可能根本没有"微软雅黑"。部署前确认系统安装了目标字体，或者改用系统自带的"宋体"（SimSun）。

原因 3：特殊字符

≤、≥、®、™ 这些符号在部分字体下会变成方框。建议统一用 Arial 或 Segoe UI Symbol 来处理符号：

csharp
// 只对包含特殊字符的段落切换字体
var special = range.Characters(5, 1);
special.Font.Name = "Segoe UI Symbol";
mermaid
flowchart TD
    A["TextRange.Text = '中文文本'"] --> B{"NameFarEast 是否设置?"}
    B -->|"否"| C["PPT 用 Name（西文字体）渲染中文"]
    C --> D{"字体是否支持 CJK?"}
    D -->|"不支持"| E["显示为方框 □□□"]
    D -->|"支持（如宋体）"| F["可正常显示"]
    B -->|"是"| G["用 NameFarEast 字体渲染中文"]
    G --> H["正常显示"]

完整示例：格式化报告正文 ​

csharp
using MudTools.OfficeInterop;
using MudTools.OfficeInterop.PowerPoint;

using var app = PowerPointFactory.BlankDocument();
var pres = app.ActivePresentation;

var slide = pres.AddSlide(PpSlideLayout.ppLayoutBlank);

var tb = slide.Shapes.AddTextbox(
    MsoTextOrientation.msoTextOrientationHorizontal,
    30, 30, 700, 500);

var range = tb.TextFrame.TextRange;
range.Text = "2026 Q2 技术总结\n\n" +
             "1. 微服务拆分完成度 85%\n" +
             "2. 线上故障率下降 60%\n" +
             "3. 团队扩展至 12 人\n\n" +
             "——技术部";

// 标题行
range.Paragraphs(1, 1).Font.Size = 32;
range.Paragraphs(1, 1).Font.Bold = true;
range.Paragraphs(1, 1).Font.Name = "Arial";
range.Paragraphs(1, 1).Font.NameFarEast = "微软雅黑";
range.Paragraphs(1, 1).Font.Color.RGB = 0x1A5276;

// 数据行
for (int i = 3; i <= 5; i++)
{
    range.Paragraphs(i, 1).Font.Size = 18;
    range.Paragraphs(i, 1).Font.Color.RGB = 0x2C3E50;
}

// 落款
range.Paragraphs(7, 1).Font.Size = 14;
range.Paragraphs(7, 1).Font.Italic = true;
range.Paragraphs(7, 1).ParagraphFormat.Alignment = PpParagraphAlignment.ppAlignRight;

Console.WriteLine("按回车退出...");
Console.ReadLine();

小结 ​

写文本入 PPT 只有两条路（占位符 vs 独立文本框），但格式化控制却可以深入到字符级别。关键在于理解 TextRange 提供的范围切片方法（Paragraphs、Sentences、Words、Characters）——它们返回的都是新的 IPowerPointTextRange 对象，各自携带独立的 Font 和 ParagraphFormat。这是实现"同一文本框内不同样式"的基础。

下一篇从文字转向图片和媒体，看怎么把本地图片、网络图片嵌入到幻灯片中，以及位置尺寸的换算逻辑。