平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“C#采用Free Spire.PDF for .NET实现方法为PDF文……”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

一、背景与需求

结合项目来看，在文档管理场景里，为PDF文件添加页码是一项常用需求。无论是财务报表、项目文档还是合同协议，规范的页码都能显著提升文档的可读性和专业性。手动为每页添加页码不仅效率低下，还容易出错。对于 .NET 开发者而言，借助 C# 实现 PDF 页码的自动化插入，是提升文档处理效率的有效途径。

下面会介绍如何采用 Free Spire.PDF for .NET 免费库，借助 C# 码为现有PDF文档批量添加页码。

二、环境准备

2.1 安装方式

Free Spire.PDF for .NET 可借助NuGet直接安装：

dotnet add package FreeSpire.PDF

或在Visual Studio的包管理器控制台中执行：

Install-Package FreeSpire.PDF

2.2 命名空间引用

代码中需引入以下命名空间：

using Spire.Pdf;
using Spire.Pdf.Graphics;
using Spire.Pdf.AutomaticFields;
using System.Drawing;

三、核心实现

动态字段方式借助 PdfPageNumberField、PdfPageCountField 和 PdfCompositeField 三个类组合实现页码的自动生成与渲染。

• PdfPageNumberField：显示当前页码
• PdfPageCountField：显示文档总页数
• PdfCompositeField：将多个动态字段组合为一个复合字段

以下是完整的实现代码：

using Spire.Pdf;
using Spire.Pdf.AutomaticFields;
using Spire.Pdf.Graphics;
using System.Drawing;

namespace AddPageNumbers
{
    class Program
    {
        static void Main(string[] args)
        {
            // 1. 加载PDF文档
            PdfDocument pdf = new PdfDocument();
            pdf.LoadFromFile("示例文档.pdf");

            // 2. 创建字体（建议使用系统中存在的通用字体）
            PdfTrueTypeFont font = new PdfTrueTypeFont("宋体", 10f, PdfFontStyle.Regular, true);

            // 3. 创建页码字段和总页数字段
            PdfPageNumberField pageNumber = new PdfPageNumberField();
            PdfPageCountField pageCount = new PdfPageCountField();

            // 4. 组合字段，格式为"第X页，共Y页"（支持中文）
            PdfCompositeField compositeField = new PdfCompositeField(
                font, 
                PdfBrushes.Black, 
                "第 {0} 页 / 共 {1} 页", 
                pageNumber, 
                pageCount);

            // 5. 设置页码位置（基于第一页尺寸，通常各页尺寸一致）
            //    定位到页面底部居中靠左，距左边距72点（1英寸），距底边45点
            float leftMargin = 72f;
            float bottomMargin = 45f;
            SizeF pageSize = pdf.Pages[0].Size;   // 获取基准页面尺寸
            compositeField.Location = new PointF(leftMargin, pageSize.Height - bottomMargin);

            // 6. 遍历每一页，在页面底部绘制页码
            for (int i = 0; i < pdf.Pages.Count; i++)
            {
                PdfPageBase page = pdf.Pages[i];
                // 使用无参 Draw，自动应用 Location
                compositeField.Draw(page.Canvas);
            }

            // 7. 保存文档
            pdf.SaveToFile("添加页码后的文档.pdf");
            pdf.Close();
            pdf.Dispose();
        }
    }
}

四、高级定制

4.1 页码格式自定义

借助修改 PdfCompositeField 的格式化字符串，能够灵活调整页码的显示格式：

// 中文格式
"第 {0} 页 / 共 {1} 页"

// 英文格式
"Page {0} of {1}"

// 简单格式
"{0}/{1}"

4.2 页码位置控制

页码的位置可借助 Location 属性精确控制。

示例1：底部居中

// 需要先测量文本宽度，再计算居中坐标
string sampleText = "第 999 页 / 共 999 页";  // 最宽情况
SizeF textSize = font.MeasureString(sampleText);
float x = (pageSize.Width - textSize.Width) / 2;
float y = pageSize.Height - bottomMargin;
compositeField.Location = new PointF(x, y);

示例2：底部右侧

float rightMargin = 72f;
string sampleText = "第 999 页 / 共 999 页";
SizeF textSize = font.MeasureString(sampleText);
float x = pageSize.Width - textSize.Width - rightMargin;
float y = pageSize.Height - bottomMargin;
compositeField.Location = new PointF(x, y);

示例3：页眉居中

float topMargin = 30f;
string sampleText = "第 999 页 / 共 999 页";
SizeF textSize = font.MeasureString(sampleText);
float x = (pageSize.Width - textSize.Width) / 2;
float y = topMargin;
compositeField.Location = new PointF(x, y);

4.3 页码样式调整

字体、颜色、大小等样式均可自定义：

// 设置字体为 Arial、12号、粗体
PdfTrueTypeFont font = new PdfTrueTypeFont("Arial", 12f, PdfFontStyle.Bold, true);

// 设置颜色为蓝色
PdfBrush brush = PdfBrushes.Blue;

4.4 处理不同尺寸的页面

若PDF中各页面尺寸不一致，应逐页拿到尺寸并计算位置：

for (int i = 0; i < pdf.Pages.Count; i++)
{
    PdfPageBase page = pdf.Pages[i];
    SizeF pageSize = page.Size;
    // 根据当前页尺寸计算位置
    float x = (pageSize.Width - textWidth) / 2;
    float y = pageSize.Height - bottomMargin;
    compositeField.Location = new PointF(x, y);
    compositeField.Draw(page.Canvas);
}

五、注意事项

1. 免费版限制：Free Spire.PDF 社区版对处理页数有一定限制（通常为10页以内），适用来小型文档。

2. 字体兼容：采用 PdfTrueTypeFont 时需确保指定的字体在系统中可用，否则可能出现渲染异常。

3. 坐标系统：页面画布的坐标系原点位于左上角，X轴向右为正，Y轴向下为正。采用 Location 属性时，默认以文本的左上角为定位点。所以，Location.Y 值越大，文本位置越靠下。本文示例中借助 pageSize.Height - bottomMargin 计算底部位置，正是基于这一坐标系。

4. 文本宽度测量：当需居中或右对齐时，采用 font.MeasureString() 拿到文本宽度，建议以最长的页码格式（如“第 999 页 / 共 999 页”）为基准进行测量，避免因页码位数变化导致位置偏移。

5. 文档保存：建议采用 SaveToFile 方法保存为新文件，避免覆盖原始文档造成数据丢失。

6. 资源释放：处理完成后调用 Dispose() 方法释放文档占用的资源，确保内存安全。

六、总结

在这个场景下，借助以上示例，开发者能够用简洁的 C# 代码实现 PDF 文档的批量页码添加。采用 PdfCompositeField 动态字段方式，能够灵活定制“第X页，共Y页”等丰富格式，同时借助 Location 属性精确控制页码位置。该方式稳定可靠，适用来各类文档处理场景。在真实项目中，注意字体选择、坐标计算以及免费版的页数限制，即可更快为PDF文档添加规范的页码，提升文档的专业性和可读性。