Mud Tools

Appearance

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

幻灯片的增删改查 ​

问题 ​

一片空白的演示文稿没有意义。真实的业务场景里，我们需要按逻辑组织页面：封面在前、目录其次、然后是内容页、最后是封底。过程中可能还要调整顺序、删除废弃页面、复制已有页面。

PowerPoint 的 COM 模型把幻灯片集合暴露为 Slides，但它是个 1-based 索引的集合，Add 方法签名也藏了不少陷阱。

添加幻灯片 ​

IPowerPointPresentation 上有两个入口可以添加幻灯片：

  • AddSlide(layout, position) — 快捷方法，直接在 IPowerPointPresentation 上调用
  • Slides.Add(index, layout) — 通过幻灯片集合添加

两者的行为完全一致：

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

// 方式一：通过 Presentation 的快捷方法（推荐）
var cover = pres.AddSlide(PpSlideLayout.ppLayoutTitle, position: 1);
cover.Shapes.Title.TextFrame.TextRange.Text = "季度销售报告";

// 方式二：通过 Slides 集合
var dataSlide = pres.Slides.Add(2, PpSlideLayout.ppLayoutText);
dataSlide.Shapes.Title.TextFrame.TextRange.Text = "数据概览";

// 添加多张内容页
for (int i = 0; i < 3; i++)
{
    pres.AddSlide(PpSlideLayout.ppLayoutText);
}

// 封底 — 位置传 -1 或省略代表追加到末尾
var closing = pres.AddSlide(PpSlideLayout.ppLayoutTitleOnly);
closing.Shapes.Title.TextFrame.TextRange.Text = "谢谢";

position 参数是从 1 开始的数字，-1 表示追加到末尾。如果你传 1，新幻灯片会插入到第一页的位置，原本的第一页往后挪。

PpSlideLayout 的常用变体：

布局用途
ppLayoutTitle封面 / 大标题
ppLayoutTitleOnly只有标题，内容全用自定义形状
ppLayoutText标题 + 一段正文
ppLayoutTwoColumnText标题 + 两栏对比
ppLayoutBlank完全空白，一切手动添加
ppLayoutSectionHeader章节分隔页
mermaid
flowchart LR
    Start["开始"] --> Add{"AddSlide<br/>position 参数"}
    Add -->|"position == -1"| End["追加到最后<br/>(SlideCount + 1)"]
    Add -->|"position == N"| Insert["插入到第 N 页<br/>原有 N 页往后移"]
    Insert --> End
    End --> Done["返回 IPowerPointSlide"]

移动与复制 ​

IPowerPointSlide 提供了 MoveTo 和 Duplicate 两个方法。

csharp
// 把第 3 页移到第 1 页
var slide3 = pres.GetSlide(3);
slide3.MoveTo(1);

// 复制第 2 页，返回值是 SlideRange（但通常只包含一张）
var duplicated = pres.GetSlide(2).Duplicate();

MoveTo 的时间复杂度是 O(n) — COM 后端会做实际的重排索引。批量移动时建议从前往后处理，避免索引偏移。

删除幻灯片 ​

csharp
// 删除第 4 页
pres.RemoveSlide(4);

// 或者通过 Slide 对象删除
var slide = pres.GetSlide(1);
slide.Delete();

RemoveSlide 内部做了边界检查（1 ≤ index ≤ SlideCount），越界会抛 ArgumentOutOfRangeException。

全局属性设置 ​

页面尺寸（宽高比） ​

PowerPoint 默认是 16:9。要切到 4:3，需要设置 PageSetup：

csharp
// 切到 4:3（标准）
// 通过 Presentations 集合拿到 PageSetup 进行设置
var pageSetup = pres.Slides[1]; // 只是获取 slides 引用
// 注意：PageSetup 是 Presentation 级别的属性

MudTools 对 PageSetup 没有暴露独立的接口，但可以通过 Presentations 集合的底层对象操作。如果需要控制页面尺寸，建议在创建演示文稿后直接用原生的 PageSetup 调用。这个能力在后期的库版本中可能会补充。

背景色 ​

每张幻灯片的 Background 属性返回一个 IPowerPointShapeRange，可以修改填充：

csharp
var slide = pres.GetSlide(1);

// 设置纯色背景（需要访问 Fill 属性）
slide.Background.Fill.ForeColor.RGB = 0x2E4057;  // 深蓝背景
slide.Background.Fill.Visible = true;

// 或者用 BackgroundStyle 枚举设置预设样式
slide.BackgroundStyle = MsoBackgroundStyleIndex.msoBackgroundStylePreset1;

MsoBackgroundStyleIndex 是 Office Core 命名空间的枚举，MudTools 通过 [ComPropertyWrap(ComNamespace = "MsCore")] 自动处理了跨命名空间的参数传递。

主题应用 ​

csharp
// 对整个幻灯片应用主题
slide.ApplyTheme("Office Theme");

// 对单个幻灯片应用主题颜色方案
slide.ApplyThemeColorScheme("Median");

主题名是 PowerPoint 内置主题的名称字符串，比如 "Office Theme"、"Ion"、"Retrospect"。传不存在的主题名会抛出 COM 异常。

遍历与查询 ​

IPowerPointPresentation 的 GetAllSlides() 返回 IEnumerable<IPowerPointSlide>，可以配合 LINQ 使用：

csharp
// 遍历所有幻灯片
foreach (var s in pres.GetAllSlides())
{
    Console.WriteLine($"#{s.SlideNumber}: {s.Name ?? "(无名称)"}, 版式: {s.Layout}");
}

// 按版式筛选
var blankSlides = pres.GetAllSlides()
    .Where(s => s.Layout == PpSlideLayout.ppLayoutBlank);

Console.WriteLine($"空白页数量: {blankSlides.Count()}");

SlideIndex 和 SlideNumber 的区别：SlideIndex 是幻灯片在 Slides 集合中的序数位置（从 1 开始），SlideNumber 是显示在 PPT 界面上的页码。如果第一页被隐藏了，SlideNumber 可能从 2 开始。

完整示例：生成一份 5 页的演示文稿 ​

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

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

// 第1页：封面
var cover = pres.AddSlide(PpSlideLayout.ppLayoutTitle, 1);
cover.Shapes.Title.TextFrame.TextRange.Text = "2026 Q2 技术总结";
cover.ApplyThemeColorScheme("Median");

// 第2页：目录
var toc = pres.AddSlide(PpSlideLayout.ppLayoutText);
toc.Shapes.Title.TextFrame.TextRange.Text = "目录";
var tocBody = toc.Shapes[2].TextFrame.TextRange;  // 正文占位符
tocBody.Text = "1. 项目进展\n2. 关键技术决策\n3. 下半年规划";

// 第3-4页：内容
for (int i = 0; i < 2; i++)
{
    var content = pres.AddSlide(PpSlideLayout.ppLayoutText);
    content.Shapes.Title.TextFrame.TextRange.Text = $"第 {i + 1} 部分";
}

// 第5页：封底
var end = pres.AddSlide(PpSlideLayout.ppLayoutTitleOnly);
end.Shapes.Title.TextFrame.TextRange.Text = "谢谢";
end.BackgroundStyle = MsoBackgroundStyleIndex.msoBackgroundStylePreset2;

Console.WriteLine($"最终页数: {pres.SlideCount}");
Console.WriteLine("按回车保存并退出...");
Console.ReadLine();

pres.SaveAs(@"C:\Temp\Q2-Review.pptx", PpSaveAsFileType.ppSaveAsOpenXMLPresentation);

常见陷阱 ​

  • 索引从 1 开始：COM 原罪。Slides[0] 会抛出异常，不要用 C# 的习惯去写。
  • AddSlide 的位置参数：position 是插入点，不是目标索引。AddSlide(layout, 1) 插入到第一页，不会覆盖第一页。
  • 删除后索引重排：RemoveSlide(2) 执行后，原本第 3 页变成新的第 2 页。循环删除时要从后往前删，或者用 GetAllSlides() 先拿到列表。
  • Duplicate 返回值是 SlideRange：即使只复制了一张幻灯片，返回的也是 IPowerPointSlideRange 而不是 IPowerPointSlide。需要从中索引出实际的 slide。

下一篇文章我们进入形状内部，看怎么控制文本内容的字体、段落和对齐方式。