# OpenXmlTools

**Repository Path**: lovelydouble/open-xml-tools

## Basic Information

- **Project Name**: OpenXmlTools
- **Description**: 基于OpenXml封装的一套处理Word文本、书签、表格、字体等的工具类库
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-09-02
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenXmlTools

## 介绍

OpenXmlTools 是一个基于 [OpenXML SDK](https://github.com/OfficeDev/Open-XML-SDK) 封装的 .NET 类库，专门用于处理 Word 文档。该工具库提供了丰富的 API 来简化 Word 文档的创建、编辑和格式化操作，包括文本替换、书签处理、表格操作（样式设置、合并单元格、锁定内容）、字体控制、段落对齐等功能，大大提升了 OpenXML 的使用效率。

## 软件架构

- 基于 .NET Standard 2.0/2.1 和 .NET Framework 4.72/4.8 构建
- 使用 C# 8.0 语言特性
- 依赖 DocumentFormat.OpenXml 3.3.0
- 支持跨平台使用（Windows、Linux、macOS）

## 功能特性

- **文本处理**：支持精确的文本查找和替换，包括跨 Run 元素的文本替换
- **书签操作**：通过书签名称快速定位并替换内容
- **表格操作**：
  - 动态填充表格数据
  - 合并单元格
  - 设置边框样式
  - 控制对齐方式（水平和垂直）
  - 设置字体格式
  - 锁定表格内容防止编辑
- **文档生成**：提供 WordDocumentBuilder 静态类，支持创建段落、标题、表格、图片、超链接等元素
- **文档比较**：内置 WordDocumentComparer 工具，可比较两个 Word 文档的差异
- **样式控制**：支持设置字体、字号、加粗、斜体等格式

## 安装教程

### NuGet 包管理器
```powershell
Install-Package OpenXmlTools
```

### .NET CLI
```bash
dotnet add package OpenXmlTools
```

### PackageReference
```xml
<PackageReference Include="OpenXmlTools" Version="2.0.0" />
```

## 使用说明

### 1. 基本文本替换

```csharp
using OpenXmlTools.OpenXML;
using System.Collections.Generic;
using System.IO;

// 准备替换字典
var replacements = new Dictionary<string, string>
{
    { "姓名", "张三" },
    { "日期", "2025-01-01" }
};

// 读取模板文件
using var fileStream = File.OpenRead("template.docx");
// 执行文本替换
var resultStream = OpenXMLWordHelper.WriteData(fileStream, replacements);

// 保存结果
using var outputFile = File.Create("output.docx");
resultStream.CopyTo(outputFile);
```

### 2. 表格数据填充

```csharp
using OpenXmlTools.OpenXML;
using OpenXmlTools.OpenXML.Word;
using System.Collections.Generic;

// 准备表格数据
var tablesData = new Dictionary<string, List<List<string>>>
{
    {
        "0", // 表格索引（从0开始）
        new List<List<string>>
        {
            new List<string> { "产品名称", "数量", "单价" },
            new List<string> { "产品A", "10", "¥100" },
            new List<string> { "产品B", "5", "¥200" }
        }
    }
};

// 读取模板文件
using var fileStream = File.OpenRead("template.docx");
// 填充表格数据
var resultStream = OpenXMLWordHelper.WriteData(fileStream, tablesData);

// 保存结果
using var outputFile = File.Create("output.docx");
resultStream.CopyTo(outputFile);
```

### 3. 表格单元格合并

```csharp
using OpenXmlTools.OpenXML;
using OpenXmlTools.OpenXML.Word;
using System.Collections.Generic;

// 准备表格数据和合并区域
var wordTables = new List<WordTable>
{
    new WordTable
    {
        TableIdentifier = "0", // 表格索引
        TableDatas = new List<List<string>>
        {
            new List<string> { "项目", "子项目", "描述" },
            new List<string> { "项目A", "子项目1", "描述1" },
            new List<string> { "项目A", "子项目2", "描述2" },
            new List<string> { "项目B", "子项目3", "描述3" }
        },
       MergeRegions = new List<(int startRow, int startCol, int endRow, int endCol)>
		{
			// 合并第2-3行的第一列
			(1,2,0,0)
		}
    }
};

// 读取模板文件
using var fileStream = File.OpenRead("template.docx");
// 填充表格数据并合并单元格
var resultStream = OpenXMLWordHelper.WriteData(fileStream, wordTables);

// 保存结果
using var outputFile = File.Create("output.docx");
resultStream.CopyTo(outputFile);
```

### 4. 书签内容替换

```csharp
using OpenXmlTools.OpenXML.Word;
using System.Collections.Generic;
using System.IO;

// 准备书签替换字典
var bookmarks = new Dictionary<string, string>
{
    { "BookmarkName1", "替换内容1" },
    { "BookmarkName2", "替换内容2" }
};

// 读取模板文件
using var fileStream = File.OpenRead("template.docx");
// 替换书签内容
var resultStream = WordBookmarkHelper.ReplaceDocumentBookmarks(fileStream, bookmarks);

// 保存结果
using var outputFile = File.Create("output.docx");
resultStream.CopyTo(outputFile);
```

### 5. 创建新的 Word 文档

```csharp
using OpenXmlTools.OpenXML.Word;
using DocumentFormat.OpenXml.Wordprocessing;
using System.IO;

// 创建文档流
using var stream = new MemoryStream();
// 创建 Word 文档
var document = WordDocumentBuilder.CreateWordDocument(stream);
var body = document.MainDocumentPart.Document.Body;

// 添加段落
WordDocumentBuilder.AddParagraph(body, "这是一个段落", isBold: true);

// 添加标题
WordDocumentBuilder.AddHeading(body, "这是标题", 1);

// 添加表格
var tableData = new List<List<string>>
{
    new List<string> { "列1", "列2", "列3" },
    new List<string> { "数据1", "数据2", "数据3" }
};
WordDocumentBuilder.AddTable(body, tableData);

// 保存文档
document.Save();

// 保存到文件
using var outputFile = File.Create("new_document.docx");
stream.Position = 0;
stream.CopyTo(outputFile);
```

### 6. 比较两个 Word 文档

```csharp
using OpenXmlTools.OpenXML.Word;
using System.IO;

// 读取两个要比较的文档
using var doc1Stream = File.OpenRead("document1.docx");
using var doc2Stream = File.OpenRead("document2.docx");

// 比较文档
var comparisonResult = WordDocumentComparer.CompareWordDocuments(doc1Stream, doc2Stream);

// 保存比较结果
using var outputFile = File.Create("comparison_result.docx");
comparisonResult.CopyTo(outputFile);
```

## API 参考

### 主要类和方法

#### OpenXMLWordHelper
- `WriteData()`: 填充 Word 文档中的文本和表格数据
- `WriteDataAndLockTables()`: 填充数据并锁定表格内容

#### WordBookmarkHelper
- `ReplaceDocumentBookmarks()`: 替换文档中的书签内容

#### WordTextHelper
- `ReplaceText()`: 替换文档中的文本
- `AdvancedReplaceText()`: 支持正则表达式的高级文本替换

#### WordTableHelper
- `FillTables()`: 填充表格数据
- `CreateTableWithData()`: 创建带数据的表格

#### WordTableMergeHelper
- `BatchMergeCells()`: 批量合并单元格

#### WordTableLocker
- `LockTable()`: 锁定表格内容
- `LockTables()`: 批量锁定表格内容

#### WordDocumentBuilder
- `CreateWordDocument()`: 创建新的 Word 文档
- `AddParagraph()`: 添加段落
- `AddHeading()`: 添加标题
- `AddTable()`: 添加表格
- `AddImage()`: 添加图片
- `AddHyperlink()`: 添加超链接

#### WordDocumentComparer
- `CompareWordDocuments()`: 比较两个 Word 文档

## 支持的平台

- .NET Framework 4.72
- .NET Framework 4.8
- .NET Standard 2.0
- .NET Standard 2.1

## 参与贡献

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

## 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情