使用C#创建PDF文档的完整教程(文本、图片、形状与表格插入)_Asp.net

引言

在企业级应用和信息系统中，pdf 一直是最常见、也是最稳定的文档输出格式之一。无论是财务报表、合同文档、业务统计报告，还是系统自动生成的通知文件，pdf 都具备版式固定、跨平台一致、不可随意修改等优势。因此，在后端代码中动态生成 pdf 文档，几乎是每一个 .net 项目都会涉及的需求。

相比于依赖 office 环境或手工拼接 pdf，使用专业的 pdf 组件可以显著降低开发复杂度。本文将围绕 free spire.pdf for .net，系统地介绍如何在 c# 中创建 pdf 文档，并逐步实现以下常见功能：

从零创建 pdf 页面、绘制结构化文本内容、插入业务相关图片、绘制图形元素，以及生成支持分页和样式控制的复杂表格。通过完整示例，你可以快速将这些能力应用到实际项目中。

一、创建 pdf 文档并绘制结构化文本内容

在实际业务中，pdf 的第一页通常用于展示标题、说明性文字或报告概览，因此文本排版能力尤为重要。free spire.pdf 提供了灵活的文本绘制 api，可以同时控制字体、颜色、对齐方式以及行距等样式。

下面的示例演示了如何创建一个 pdf 文档，并在页面中绘制标题与正文说明。

using spire.pdf;
using spire.pdf.graphics;
using system.drawing;

namespace pdfgenerationtutorial
{
    class addtext
    {
        static void main(string[] args)
        {
            pdfdocument doc = new pdfdocument();
            pdfpagebase page = doc.pages.add();

            // 报告标题
            pdftruetypefont titlefont = new pdftruetypefont(
                new font("微软雅黑", 16f, fontstyle.bold), true);
            pdfbrush titlebrush = pdfbrushes.darkslateblue;

            page.canvas.drawstring(
                "2025 年度销售数据分析报告",
                titlefont,
                titlebrush,
                60,
                40
            );

            // 报告正文说明
            string description =
                "本报告用于汇总展示公司 2025 年度的核心销售数据，" +
                "内容涵盖主要产品的销售数量、单价及总金额统计。" +
                "通过系统自动生成 pdf 文档，可以确保数据的一致性和可追溯性，" +
                "同时减少人工整理报表的工作量，适用于内部汇报、管理决策及归档场景。";

            pdftruetypefont bodyfont = new pdftruetypefont(
                new font("宋体", 11f), true);
            pdfbrush bodybrush = pdfbrushes.black;

            rectanglef textarea = new rectanglef(
                60,
                90,
                page.canvas.clientsize.width - 120,
                page.canvas.clientsize.height - 160
            );

            pdfstringformat textformat = new pdfstringformat();
            textformat.alignment = pdftextalignment.justify;
            textformat.linespacing = 18f;

            page.canvas.drawstring(
                description,
                bodyfont,
                bodybrush,
                textarea,
                textformat
            );

            doc.savetofile("report_text.pdf");
            doc.dispose();
        }
    }
}

运行该代码，将生成如下 pdf 文档：

在这个示例中，标题与正文使用了不同的字体大小和颜色，并通过 rectanglef 明确限定了文本绘制区域。这样做的好处是，无论文本内容长度如何变化，布局都能保持稳定，同时自动处理换行问题。

二、在 pdf 中插入图片并作为页面视觉元素或水印

除了文本内容，图片在 pdf 中同样扮演着重要角色。例如企业 logo、产品示意图、审批章或背景水印，都会频繁出现在正式文档中。

下面的代码展示了三种常见图片使用方式：普通插入、缩放展示以及半透明水印。

using spire.pdf;
using spire.pdf.graphics;
using system.drawing;

namespace pdfgenerationtutorial
{
    class addimage
    {
        static void main(string[] args)
        {
            pdfdocument doc = new pdfdocument();
            pdfpagebase page = doc.pages.add();

            image image = image.fromfile("company_logo.png");
            pdfimage pdfimage = pdfimage.fromimage(image);

            // 左上角插入公司 logo
            page.canvas.drawimage(pdfimage, 50, 50, 120, 60);

            // 页面中部插入示意图
            rectanglef imagearea = new rectanglef(50, 150, 220, 140);
            page.canvas.drawimage(pdfimage, imagearea);

            // 页面居中水印
            float pagewidth = page.canvas.clientsize.width;
            float pageheight = page.canvas.clientsize.height;

            float wmwidth = pdfimage.width * 0.4f;
            float wmheight = pdfimage.height * 0.4f;
            float x = (pagewidth - wmwidth) / 2;
            float y = (pageheight - wmheight) / 2;

            page.canvas.save();
            page.canvas.settransparency(0.25f, 0.25f, pdfblendmode.multiply);
            page.canvas.drawimage(pdfimage, x, y, wmwidth, wmheight);
            page.canvas.restore();

            doc.savetofile("report_image.pdf");
            doc.dispose();
        }
    }
}

生成文档示例：

通过 settransparency 方法，可以轻松实现 pdf 水印效果。这在合同、报价单和内部资料中非常常见，既能体现品牌，又不会影响正文内容的可读性。

三、绘制图形元素用于结构划分和视觉强调

在报表类 pdf 中，线条、矩形或简单图形常用于分隔内容区域，增强页面结构感。free spire.pdf 提供了与 gdi+ 类似的绘图接口，使用起来非常直观。

using spire.pdf;
using spire.pdf.graphics;
using system.drawing;

namespace pdfgenerationtutorial
{
    class shapes
    {
        static void main(string[] args)
        {
            pdfdocument doc = new pdfdocument();
            pdfpagebase page = doc.pages.add();

            // 分割线
            pdfpen linepen = new pdfpen(color.darkgray, 1.5f);
            page.canvas.drawline(linepen, 50, 80, 500, 80);

            // 信息块背景
            pdfpen rectpen = new pdfpen(color.steelblue, 1f);
            pdfbrush rectbrush = new pdfsolidbrush(color.aliceblue);
            page.canvas.drawrectangle(rectpen, rectbrush, 50, 100, 200, 90);

            // 高亮标识
            pdfpen circlepen = new pdfpen(color.orange, 2f);
            pdfbrush circlebrush = new pdfsolidbrush(color.moccasin);
            page.canvas.drawellipse(circlepen, circlebrush, 300, 120, 60, 60);

            doc.savetofile("report_shapes.pdf");
            doc.close();
        }
    }
}

运行该代码，将生成如下 pdf 文档：

这些基础图形虽然简单，但在实际报表中可以用于突出重点数据区域或增强整体排版层次。

四、生成支持分页和样式控制的业务数据表格

pdf 表格是业务系统中最常见、也是最复杂的输出形式之一。下面的示例模拟了一个“产品销售明细表”，并演示如何设置表头样式、隔行背景以及跨页重复表头。

using spire.pdf;
using spire.pdf.graphics;
using spire.pdf.tables;
using system.data;
using system.drawing;

namespace pdfgenerationtutorial
{
    class datatableexample
    {
        static void main(string[] args)
        {
            pdfdocument doc = new pdfdocument();
            pdfpagebase page = doc.pages.add();

            datatable tabledata = new datatable();
            tabledata.columns.add("编号");
            tabledata.columns.add("产品名称");
            tabledata.columns.add("单价（元）");
            tabledata.columns.add("销量");
            tabledata.columns.add("销售额（元）");

            for (int i = 0; i < 25; i++)
            {
                decimal price = 49.9m + i;
                int qty = i + 2;
                tabledata.rows.add(
                    i + 1,
                    $"智能设备型号-{i + 1}",
                    price,
                    qty,
                    price * qty
                );
            }

            pdftable table = new pdftable();
            table.datasource = tabledata;

            table.style.borderpen = new pdfpen(color.gray, 0.5f);
            table.style.defaultstyle.font =
                new pdftruetypefont(new font("微软雅黑", 10f), true);
            table.style.defaultstyle.stringformat =
                new pdfstringformat(pdftextalignment.left, pdfverticalalignment.middle);

            table.style.headersource = pdfheadersource.rows;
            table.style.headerrowcount = 1;
            table.style.showheader = true;
            table.style.headerstyle.backgroundbrush =
                new pdfsolidbrush(color.lightskyblue);
            table.style.headerstyle.font =
                new pdftruetypefont(new font("微软雅黑", 11f, fontstyle.bold), true);
            table.style.repeatheader = true;

            table.style.alternatestyle = new pdfcellstyle();
            table.style.alternatestyle.backgroundbrush =
                new pdfsolidbrush(color.whitesmoke);
            table.style.alternatestyle.stringformat =
                new pdfstringformat(pdftextalignment.left, pdfverticalalignment.middle);

            table.columns[0].width = 50;
            table.columns[1].width = 160;
            table.columns[2].width = 90;
            table.columns[3].width = 70;
            table.columns[4].width = 100;

            table.draw(page, new pointf(40, 50));

            doc.savetofile("sales_table.pdf");
            doc.close();
        }
    }
}

生成的 pdf 文档如下：

在这个场景中，即使数据行数超过一页，表格也会自动分页，并在每一页顶部重复显示表头，非常适合正式业务报表的生成需求。

关键类、属性与方法总结

类 / 属性 / 方法	说明
`pdfdocument`	表示一个 pdf 文档对象，所有页面和内容都基于该对象创建
`pdfdocument.pages.add()`	向文档中添加一个新的 pdf 页面
`pdfpagebase`	表示 pdf 中的单个页面，所有绘制操作都在此进行
`page.canvas`	页面画布对象，用于绘制文本、图片、图形等元素
`pdftruetypefont`	使用系统字体创建 pdf 字体，支持中文显示
`pdfbrush` / `pdfpen`	分别用于填充颜色和描边绘制
`canvas.drawstring()`	在指定位置或区域绘制文本内容
`pdfstringformat`	控制文本对齐方式、行距、段落布局
`rectanglef`	定义文本或图片的绘制区域，用于布局控制
`pdfimage.fromimage()`	将 `system.drawing.image` 转换为 pdf 可用图片
`canvas.drawimage()`	在页面中绘制图片，支持缩放和定位
`canvas.settransparency()`	设置绘制内容透明度，常用于水印效果
`pdftable`	用于创建 pdf 表格并绑定数据源
`pdftable.datasource`	绑定 `datatable` 或其他数据集合
`pdftable.style`	统一控制表格边框、字体、背景等样式
`pdftable.draw()`	将表格绘制到指定页面位置
`pdfdocument.savetofile()`	将 pdf 文档保存为文件
`pdfdocument.dispose()` / `close()`	释放资源，结束文档操作