iText7 中文字体使用教程

2026-02-06 05:02:59作者：苗圣禹Peter

项目地址：https://gitcode.com/gh_mirrors/it/itext7-chinese-font

iText7 是一款功能强大的 PDF 生成库，但在处理中文字体时可能会遇到一些挑战。itext7-chinese-font 项目提供了完整的解决方案，帮助开发者轻松在 iText7 中使用阿里巴巴普惠体、思源黑体和思源宋体等优质中文字体。

项目概述

itext7-chinese-font 是一个开源项目，专门为 iText7 提供中文字体支持。项目通过 Maven 依赖管理和示例代码，简化了在 PDF 文档中嵌入和使用中文字体的过程。

快速开始

环境准备

首先需要确保项目中包含 iText7 的依赖。通过 Maven 添加以下依赖配置：

<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext7-core</artifactId>
    <version>7.2.1</version>
    <type>pom</type>
</dependency>

<dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>html2pdf</artifactId>
    <version>4.0.1</version>
</dependency>

核心代码示例

项目提供了完整的 Java 示例代码，演示如何使用不同中文字体生成 PDF：

package com.starxg.itext7chinesefont;

import com.itextpdf.html2pdf.ConverterProperties;
import com.itextpdf.html2pdf.HtmlConverter;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.AreaBreak;
import com.itextpdf.layout.font.FontProvider;
import org.apache.commons.io.IOUtils;

import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import java.util.Objects;

public class IText7ChineseFont {
    public static void main(String[] args) throws Exception {
        // 读取 HTML 模板
        InputStream is = IText7ChineseFont.class.getResourceAsStream("/Template.html");
        String html = IOUtils.toString(is, StandardCharsets.UTF_8);
        
        // 使用不同字体生成 PDF
        html2pdf("alibaba", html, getAlibabaFontDirectory());
        html2pdf("source sans", html, getSourceHanSansFontDirectory());
        html2pdf("source serif", html, getSourceHanSerifFontDirectory());
    }
    
    private static void html2pdf(String name, String html, String fontDir) throws Exception {
        // 配置字体提供器
        ConverterProperties properties = new ConverterProperties();
        FontProvider fontProvider = new FontProvider();
        fontProvider.addDirectory(fontDir);
        properties.setFontProvider(fontProvider);
        
        // 转换 HTML 到 PDF
        try (PdfDocument pdfDocument = new PdfDocument(new PdfWriter("output.pdf"));
             Document doc = HtmlConverter.convertToDocument(html, pdfDocument, properties)) {
            doc.add(new AreaBreak());
        }
    }
}

字体管理

项目支持三种主流中文字体：

阿里巴巴普惠体 - 现代商业字体，包含 Light 和 Bold 两种字重
思源黑体 - Adobe 开发的开源黑体字体
思源宋体 - 传统宋体风格的开源字体

所有字体文件都包含在项目的资源目录中：

src/main/resources/fonts/
├── AlibabaPuHuiTi-2-45-Light.ttf
├── AlibabaPuHuiTi-2-85-Bold.ttf
├── SourceHanSansSC-ExtraLight.otf
├── SourceHanSansSC-Medium.otf
├── SourceHanSerifSC-ExtraLight.otf
└── SourceHanSerifSC-Medium.otf

HTML 模板示例

项目提供了丰富的 HTML 模板，展示中文字体的各种效果：

<!DOCTYPE html>
<html lang="zh">
<head>
    <meta charset="UTF-8">
    <title>中文字体测试</title>
    <style>
        body {
            padding: 20px;
            font-family: 'Alibaba PuHui Ti', sans-serif;
        }
        .center { text-align: center; }
        .f32px { font-size: 32px; }
    </style>
</head>
<body>
    <h1 class="center">中文测试</h1>
    <p>那只敏捷的棕色狐狸跳过了一只懒狗。</p>
    <p><b>那只敏捷的棕色狐狸跳过了一只懒狗。（加粗）</b></p>
    <p class="f32px">那只敏捷的棕色狐狸跳过了一只懒狗。（32px）</p>
</body>
</html>

最佳实践

字体嵌入策略

确保在生成 PDF 时正确嵌入字体，避免在不同设备上显示不一致的问题：

PdfFont font = PdfFontFactory.createFont(FONT_PATH, 
    PdfFontFactory.EmbeddingStrategy.PREFER_EMBEDDED);

性能优化

对于大量生成 PDF 的场景，建议重用 FontProvider 实例：

// 创建全局字体提供器
FontProvider globalFontProvider = new FontProvider();
globalFontProvider.addDirectory(fontDirectory);

// 在多个文档中重用
ConverterProperties properties = new ConverterProperties();
properties.setFontProvider(globalFontProvider);

多语言支持

项目支持简繁体中文显示，确保国际化项目的需求：

<h1 class="center">中文 简体</h1>
<p>那只敏捷的棕色狐狸跳过了一只懒狗。</p>

<h1 class="center">中文 繁體</h1>
<p>那只敏捷的棕色狐貍跳過了一只懶狗。</p>

应用场景

企业报表生成

使用阿里巴巴普惠体生成专业的商业报表和财务文档，确保中文内容的清晰可读。

学术论文排版

利用思源宋体处理学术文献和论文排版，符合中文出版规范。

多语言文档

支持在同一文档中混合使用中文和其他语言，满足国际化需求。

项目结构

itext7-chinese-font/
├── pom.xml                 # Maven 配置
├── src/main/java/
│   └── com/starxg/itext7chinesefont/
│       └── IText7ChineseFont.java  # 主程序
├── src/main/resources/
│   ├── Template.html       # HTML 模板
│   └── fonts/             # 字体文件目录
├── html2pdf.pdf           # 示例输出 PDF
└── html2pdf.png           # 效果预览图

通过这个项目，开发者可以快速上手在 iText7 中使用中文字体，生成高质量的中文 PDF 文档。项目的模块化设计和清晰的代码结构使其易于集成到现有项目中。

itext7-chinese-font

项目地址：https://gitcode.com/gh_mirrors/it/itext7-chinese-font

登录后查看全文