🤦 先说说这个需求是怎么来的

痛点一：技术文档写完后要发博客。复制粘贴进去后格式全乱、图片不见、表格变成一坨纯文本，只能手动一行行加 #**补图片链接…，半小时过去了盯着屏幕深呼吸。

痛点二：同事们常因这件事消耗掉整个下午，这种重复性的体力劳动根本不该由人来做。怎么说呢，

于是我决定用 C# 写个工具解决掉这事：不依赖 Office 组件。使用纯开源库，做成 Winform 桌面应用，拖进去、点一下、完事。

🧱 技术选型：为什么选 DocumentFormat.OpenXml

市面上解析 .docx 的 C# 方案大致有四条路：

• Interop——需要本机装 Word。部署麻烦，运行环境直接 GG。
• Aspose.Words——功能比较全面但收费，不便宜。
• NPOI——主要针对 Excel 场景，Word 支持相对弱。
• DocumentFormat.OpenXml——微软官方开源、MIT 协议、免费；.docx 本质上就是 ZIP+XML，这个库专门干这个。老实说，

选它。没什么悬念，

# NuGet 安装，一行搞定
Install-Package DocumentFormat.OpenXml
Install-Package System.Drawing.Common # .NET + 需要单独装

🗂️ .docx 的本质：一个成文件的压缩包

把任意一个 .docx 文件改后缀为 .zip 并解压。你会看到一堆 XML 文件：

document.docx
├── word/
│ ├── document.xml ← 正文内容在这里
│ ├── media/ ← 图片都在这
│ │ ├── image1.png
│ │ └── image2.jpg
│ └── _rels/
│ └── document.xml.rels← 图片关系映射
└── .xml

🏗️ 整体架构设计

工具分三层，逻辑不混：

• Designer.cs: 只负责控件布局。
• FrmMain.cs: 只管事件和转换逻辑。说起来，
• 业务层代码独立，可复用。

痛点三：很多项目把 SQL 写在 Button_Click 里维护成噩梦。说起来，这里坚持 UI 与业务分离，让后期 和维护更轻松。

🔍 主要代码拆解

从段落处理来看，识别标题层级

Word 中的标题本质是段落样式。下面的 C# 代码把不同层级映射为 Markdown 的 # 前缀：

private static string GetStyleName
{
var styleId = para.ParagraphProperties?.ParagraphStyleId?.Val，.Value?，string.Empty;return styleId.ToLowerInvariant;}
private static string HeadingPrefix => styleName switch
{
"heading1" or "" => "#","heading2" or "" => "##","heading3" or "" => "###"。"heading4" or "" => "####","heading5" or "" => "#####","heading6" or "" => "######",_ => string.Empty // 普通段落，无前缀
};

Run 级别的富文本：粗体、斜体、代码

C# 中遍历每个 Run 并根据属性生成对应的 Markdown 包装：

private static string BuildInlineText
{
var sb = new StringBuilder;foreach )
{
var rpr = run.RunProperties;var bold = rpr?.Bold，= null;话说回来，var italic = rpr?.Italic，= null;// 等宽字体 → 行内代码
var code = rpr?.RunFonts，.Ascii?.Value，.Contains?，false;var text = string.Concat.Select);if ) continue;// 装饰顺序：code> bold> italic
text = code?不过，$"`{text}`" : text;其实，text = bold?怎么说呢，$"**{text}**" : text;话说回来，text = italic?
$"*{text}*" : text;sb.Append，}
return sb.ToString;}

Pitfall: #if  而不是检查 .Value == true ——因为 OpenXml 中空标签本身就代表“启用”。踩过这个坑的举个手 🙋‍♂️。

从图片提取来看，关键在关系映射

The most interesting part: extracting images via embed relationship ID.

private string ExtractImage(
Drawing drawing。WordprocessingDocument doc,string imagesDir,string imgFmt,string baseName,ref int imgIndex)
{
// 找到 Blip
var blip = drawing.Descendants.FirstOrDefault;var relId = blip?.Embed，.Value;if ) return string.Empty;不过，// 通过关系 ID 拿到图片 Part
var part = doc.MainDocumentPart.GetPartById;// 确定输出
名
var ext = imgFmt == "原始格式"
Path.GetExtension).TrimStart
: imgFmt;imgIndex++，var fileName = $"{baseName}_img{imgIndex:D3}.{ext}";var destPath = Path.Combine;// 写出图片文件
using var stream = part.GetStream;using var ms = new MemoryStream;stream.CopyTo;// 如果要转格式则使用 System.Drawing；否则直接保存原始字节流
if
{
File.WriteAllBytes);}
else
{
using var bmp = new Bitmap;怎么说呢，var format = imgFmt == "jpg"
System.Drawing.Imaging.ImageFormat.Jpeg
: System.Drawing.Imaging.ImageFormat.Png;bmp.Save，}
AppendLog;return $"，";}

表格转换这方面，GFM 标准格式

private static string ConvertTable
{
var sb = new StringBuilder;var rows    = table.Elements.ToList;var isFirst = true;foreach
{
var cells = row.Elements
.Select(c => BuildInlineText(
c.Elements.FirstOrDefault?，new Paragraph))
.ToList;sb.AppendLine + " |");// 首行之后插入分隔行
if continue;sb.AppendLine) + " |");isFirst = false;话说回来，}
return sb.ToString.TrimEnd;}

The UI follows a pragmatic style—only essential controls。no flashy decorations.

•  信息白色、成功绿色、图片提取蓝色、警告黄色、错误橙红，一眼辨认状态。
•   让 UI 全程不卡顿；进度条采用 Marquee 动画，在完成后归位到 100%。其实，这些细节极大提高了使用体验。

• Pitfall 一：嵌套表格 - 当前实现只处理顶层表格，内层会被当作纯文本。可根据需求递归
• Pitfall 二：文本框和形状 - TextBox、艺术字等不在 `的直接子元素里会被跳过。多数文档中属于例外情况，对整体影响不大。
• Pitfall 三：复杂列表 - 有序/无序列表在 OpenXml 中通过
• Pitfall 四：System.Drawing 在 Linux 上 - 非 Windows 环境对 Syst em.Drawing.Common

A 32‑page technical document containing 18 screenshots and 6 tables:

#指标#	#手工转换#	#工具转换#>
#耗时#	#~90分钟#	#约3秒#
#图片处理#	#逐张手动保存#	#全自动提取命名#
#格式准确率#	#依赖细心程度#	#结构化解析。稳定#
#重复执行成本#	#每次都一样痛 # td> #一键，秒出 # /tr>

The tool’s core idea is simple,but turning it into a truly usable desktop app requires polishing details—async UI,colored logs,format options,overwrite protection…Each piece alone is trivial,but toger y make difference 娱乐ween “usable” and “good”. The code respects UI‑logic separation,so future extensions are straightforward—just modify business layer without touching UI.

If you have similar needs。feel free to fork this framework. Once you get comfortable with OpenXml object model,extending it becomes very smooth.

If you encounter a special Word feature that isn’t handled correctly,drop a comment—maybe next article will solve your problem.

。

---