在开发办公自动化（OA）系统、报表生成工具或文档处理脚本时，我们经常需要操作 Word 文档。其中，“插入超链接”是一个高频需求：无论是将文档内的技术术语关联到在线帮助文档，还是让公司的 Logo 图片点击后跳转至官网，都能显著提升文档的交互体验和信息价值。
本文将介绍如何使用 C# 在 Word 文档中添加文本和图片超链接的具体实现方式。你可以直接将代码复制到你的项目中进行调整使用。
环境准备与库安装
在开始编写代码之前，你需要确保开发环境已准备好。本示例基于 .NET (Core 或 Framework) 平台。
1. 安装 NuGet 包
打开 Visual Studio 的“程序包管理器控制台”，运行以下命令安装 Spire.Doc：
Install-Package Spire.Doc
- 引入命名空间
在代码文件顶部，确保引入以下核心命名空间，以便使用文档操作类：
using Spire.Doc;
using Spire.Doc.Documents;
using Spire.Doc.Fields;
using Spire.Doc.Interface;
using System.Drawing; // 用于处理颜色和图像
注意：
System.Drawing 在 .NET Core / .NET 5+ 中可能需要额外安装 System.Drawing.Common 包，或在非 Windows 平台上注意兼容性配置。
场景一：将文档中的现有文本转换为超链接
需求背景： 假设你有一个现有的 Word 报告，里面多次提到了“.NET Framework”。你希望找到第二次出现的地方，把它变成一个蓝色的、带下划线的超链接，点击后跳转到维基百科的介绍页面，同时保留原有的字体格式。
技术难点： 在 Word 的底层结构中，超链接本质上是一个 Field（域）。如果直接修改文本属性，是无法添加跳转功能的。我们需要手动创建一个完整的超链接域结构，它包含四个部分：
- 域开始标记 (
FieldStart) - 域分隔符 (
FieldSeparator) - 显示文本 (即我们看到的蓝色文字)
- 域结束标记 (
FieldEnd)
代码实现
using Spire.Doc;
using Spire.Doc.Documents;
using Spire.Doc.Fields;
using Spire.Doc.Interface;
using System.Drawing;
using System.IO;
namespace AddHyperlinksToExistingText
{
class Program
{
static void Main(string[] args)
{
// 1. 初始化文档并加载本地文件
Document document = new Document();
// 请根据实际情况修改文件路径
string inputPath = @"C:\Users\Administrator\Desktop\sample.docx";
if (!File.Exists(inputPath))
{
System.Console.WriteLine("未找到源文件，请检查路径。");
return;
}
document.LoadFromFile(inputPath);
// 2. 查找目标字符串 ".NET Framework"
// 参数：搜索词，区分大小写，全字匹配
TextSelection[] selections = document.FindAllString(".NET Framework", true, true);
// 确保至少找到了两次，我们要操作的是第二次
if (selections.Length > 1)
{
// 获取第二次出现的文本范围
TextRange range = selections[1].GetAsOneRange();
// 获取该文本所在的段落
Paragraph paragraph = range.OwnerParagraph;
// 获取该文本在段落元素集合中的索引位置
int index = paragraph.Items.IndexOf(range);
// 3. 移除原始纯文本，准备替换为超链接域
paragraph.Items.Remove(range);
// 4. 创建超链接域对象
Field field = new Field(document);
field.Type = FieldType.FieldHyperlink;
// 配置超链接的具体地址
Hyperlink hyperlink = new Hyperlink(field);
hyperlink.Type = HyperlinkType.WebLink;
hyperlink.Uri = "https://en.wikipedia.org/wiki/.NET_Framework";
// 将域的起始部分插入到原位置
paragraph.Items.Insert(index, field);
// 5. 插入域分隔符 (FieldSeparator)
// 这是告诉 Word："前面是命令，后面是显示内容"
IParagraphBase startMark = document.CreateParagraphItem(ParagraphItemType.FieldMark);
(startMark as FieldMark).Type = FieldMarkType.FieldSeparator;
paragraph.Items.Insert(index + 1, startMark);
// 6. 插入显示的文本内容
ITextRange textRange = new TextRange(document);
textRange.Text = ".NET Framework";
// 关键：保留原文本的字体设置，并应用超链接样式（蓝色 + 下划线）
textRange.CharacterFormat.Font = range.CharacterFormat.Font;
textRange.CharacterFormat.TextColor = Color.Blue;
textRange.CharacterFormat.UnderlineStyle = UnderlineStyle.Single;
paragraph.Items.Insert(index + 2, textRange);
// 7. 插入域结束标记 (FieldEnd)
IParagraphBase endMark = document.CreateParagraphItem(ParagraphItemType.FieldMark);
(endMark as FieldMark).Type = FieldMarkType.FieldEnd;
paragraph.Items.Insert(index + 3, endMark);
// 8. 保存结果
string outputPath = "Result_TextLink.docx";
document.SaveToFile(outputPath, FileFormat.Docx);
System.Console.WriteLine($"处理完成！文件已保存至：{outputPath}");
}
else
{
System.Console.WriteLine("文档中未找到足够的匹配项。");
}
}
}
}
代码解析： 这段代码的核心在于“拆解与重组”。我们不能简单地给 TextRange 加个属性，而是必须按照 Word 内部规范，依次插入 Field -> Separator -> Text -> End。虽然步骤看起来多一点，但这能让我们完全控制链接的样式（比如这里我们手动设置了蓝色和下划线），并确保替换位置的精准性。
场景二：为图片添加超链接
需求背景： 在生成公司简报或产品手册时，我们通常会在页眉或正文中插入公司 Logo。为了让文档更具互动性，我们希望用户点击图片就能直接访问公司官网。
技术优势： 与处理现有文本不同，当我们在代码中动态插入图片并添加链接时，库提供了更便捷的封装方法。你不需要关心底层的域代码，只需要调用 AppendHyperlink 方法，将图片对象和 URL 传进去即可。
代码实现
using Spire.Doc;
using Spire.Doc.Documents;
using Spire.Doc.Fields;
using System.Drawing;
using System.IO;
namespace CreateImageLink
{
class Program
{
static void Main(string[] args)
{
// 1. 创建新文档
Document doc = new Document();
Section section = doc.AddSection();
Paragraph paragraph = section.AddParagraph();
// 设置段落对齐方式（可选，让图片居中更好看）
paragraph.Format.HorizontalAlignment = HorizontalAlignment.Center;
string imagePath = "logo.png"; // 请确保项目目录下有此图片
if (File.Exists(imagePath))
{
// 2. 加载图片并转换为 DocPicture 对象
Image image = Image.FromFile(imagePath);
DocPicture picture = new DocPicture(doc);
picture.LoadImage(image);
// 3. 一行代码搞定：添加图片超链接
// 参数说明：目标网址，图片对象，链接类型
paragraph.AppendHyperlink("https://www.e-iceblue.com", picture, HyperlinkType.WebLink);
// 4. 保存文档
string outputPath = "Result_ImageLink.docx";
doc.SaveToFile(outputPath, FileFormat.Docx);
System.Console.WriteLine($"图片链接添加成功！文件已保存至：{outputPath}");
}
else
{
System.Console.WriteLine($"未找到图片文件：{imagePath}");
}
}
}
}
代码解析： 可以看到，处理图片的逻辑非常直观。AppendHyperlink 方法内部自动处理了域结构的创建。你只需要关注业务逻辑：哪张图片指向哪个网址。此外，代码中还顺便演示了如何设置段落居中，这在实际排版中很常用，能让生成的文档更加美观。
总结与避坑指南
通过以上两个示例，我们可以总结出在 C# 中操作 Word 超链接的两个核心思路：
- 对于现有文本的修改：由于涉及到样式的继承和精确的位置替换，通常需要手动创建域（Field） 。记得顺序是：
FieldStart (由 Field 对象隐含) -> Separator -> Text -> FieldEnd。这种方式虽然代码量稍大，但灵活性最高。 - 对于新插入内容（如图片） ：直接使用
AppendHyperlink
几个开发小贴士：
- 路径问题：示例中的文件路径（如
C:... 或相对路径 logo.png）在复制运行时请务必根据你的实际环境修改，否则会报 FileNotFoundException。建议在测试时使用绝对路径，发布时改为相对路径或配置文件读取。 - 样式冲突：在示例一中，我们特意保留了
range.CharacterFormat.Font。如果你不这样做，新生成的链接文本可能会变成默认的宋体或等线体，导致文档排版不一致。
