Java文档中实现竖排文字的完整指南

在Java文档处理中，竖排文字（垂直文本）常用于中文古籍排版、日式文档设计或特殊视觉效果。本文将系统介绍如何在Java生成的PDF文档中实现竖排文字，涵盖核心库使用、代码实现和优化技巧。

一、竖排文字的实现原理

竖排文字的实现本质是文本方向控制和布局调整的结合。与横排文字从左到右的排列方式不同，竖排文字需要：

1. 旋转文本方向：将字符垂直排列
2. 调整行进方向：从上到下或从右到左
3. 处理字符间距：特别是中文标点符号的定位

在PDF文档中，这需要通过专门的库函数控制文本矩阵变换，而非简单调整字体方向。

二、使用iText库实现竖排文字

iText是Java生态中最流行的PDF操作库，其7.x版本提供了灵活的文本布局控制。

1. 基础竖排实现

import com.itextpdf.kernel.pdf.*;
import com.itextpdf.layout.*;
import com.itextpdf.layout.element.*;
import com.itextpdf.layout.property.*;
public class VerticalTextExample {
    public static void main(String[] args) throws Exception {
        PdfDocument pdf = new PdfDocument(new PdfWriter("vertical_text.pdf"));
        Document document = new Document(pdf);
        // 创建竖排段落
        Paragraph verticalPara = new Paragraph("竖排文字示例")
            .setProperty(Property.ROTATION, 90) // 旋转90度
            .setFixedPosition(100, 500, 20) // x,y坐标和宽度
            .setFontSize(12);
        document.add(verticalPara);
        document.close();
    }
}

关键点解析：

• setProperty(Property.ROTATION, 90) 实现文本旋转
• setFixedPosition 必须指定固定位置，因为旋转后布局系统无法自动计算
• 宽度参数实际控制竖排文本的显示高度

2. 高级竖排布局

对于多行竖排文本，需要结合Table或自定义布局：

// 创建竖排表格（每列实际为竖排行）
Table table = new Table(1); // 单列表格
table.setWidth(20); // 列宽控制竖排高度
for (String line : "这是多行竖排文本示例".split("")) {
    table.addCell(new Cell().add(new Paragraph(line)
        .setProperty(Property.ROTATION, 90)));
}
document.add(table);

优化建议：

• 使用TextAlignment.RIGHT处理从右到左的竖排
• 对中文标点添加特殊处理（如全角符号）

三、Apache PDFBox的替代方案

PDFBox提供了更底层的PDF操作能力，适合需要精细控制的场景。

1. 基本竖排实现

import org.apache.pdfbox.pdmodel.*;
import org.apache.pdfbox.pdmodel.font.*;
import org.apache.pdfbox.pdmodel.common.*;
import org.apache.pdfbox.pdmodel.edit.*;
public class PDFBoxVerticalText {
    public static void main(String[] args) throws Exception {
        PDDocument doc = new PDDocument();
        PDPage page = new PDPage();
        doc.addPage(page);
        PDFont font = PDType1Font.HELVETICA;
        PDPageContentStream content = new PDPageContentStream(doc, page);
        // 设置文本矩阵（旋转+平移）
        content.beginText();
        content.setFont(font, 12);
        content.setTextMatrix(
            0, 1,  // 旋转矩阵部分
            -1, 0, // 90度旋转
            100, 500 // 平移坐标
        );
        content.showText("竖排文本");
        content.endText();
        content.close();
        doc.save("vertical_pdfbox.pdf");
        doc.close();
    }
}

矩阵变换原理：
文本矩阵通过[a b c d e f]实现仿射变换：

• 竖排90度旋转矩阵：[0 1 -1 0 e f]
• 其中e,f控制文本基点位置

2. 多行竖排处理

PDFBox需要手动计算每行位置：

String text = "多行竖排示例";
float yPos = 700; // 起始Y坐标
float lineHeight = 15;
content.beginText();
for (int i = 0; i < text.length(); i++) {
    // 每个字符单独处理
    content.setTextMatrix(0, 1, -1, 0, 100, yPos - i * lineHeight);
    content.showText(String.valueOf(text.charAt(i)));
}
content.endText();

四、中文竖排的特殊处理

中文竖排需要特别注意：

1. 标点符号定位：全角标点应居中或悬挂在文字右侧
2. 从右到左顺序：传统中文竖排从右页开始
3. 行首行尾规则：避免标点出现在行首

优化实现方案

// 中文竖排专用方法
public static void addChineseVerticalText(Document doc, String text, 
        float x, float y, float width) {
    String[] lines = text.split("(?<=\\n)"); // 按换行符分割
    float currentY = y;
    for (String line : lines) {
        Paragraph p = new Paragraph();
        for (int i = 0; i < line.length(); i++) {
            char c = line.charAt(i);
            // 处理标点符号特殊定位
            if (isFullWidthPunctuation(c)) {
                p.add(new Text(String.valueOf(c))
                    .setProperty(Property.ROTATION, 90)
                    .setMarginRight(5)); // 标点右缩进
            } else {
                p.add(new Text(String.valueOf(c))
                    .setProperty(Property.ROTATION, 90));
            }
        }
        doc.add(new AreaBreak()); // 换页处理
        doc.add(p.setFixedPosition(x, currentY, width)
            .setProperty(Property.VERTICAL_ALIGNMENT, VerticalAlignment.TOP));
        currentY -= 100; // 调整行高
    }
}
private static boolean isFullWidthPunctuation(char c) {
    // 全角标点判断逻辑
    return c == '。' || c == '，' || c == '！' || c == '？';
}

五、性能优化建议

1. 批量处理：将多个竖排元素合并为单个文本对象
2. 缓存矩阵：重复使用的旋转矩阵应缓存复用
3. 字体子集化：对中文文档使用字体子集减少PDF体积
4. 异步渲染：长文档竖排处理采用分块异步方式

六、常见问题解决方案

1. 文字显示不全：检查固定位置的宽度/高度参数
2. 旋转后位置偏移：注意PDF坐标系原点在左下角的特性
3. 中文乱码：确保使用支持中文的字体（如NotoSansCJK）
4. 性能瓶颈：避免在循环中频繁创建文本对象

七、扩展应用场景

1. 古籍数字化：实现传统线装书竖排格式
2. 日式文档：符合日本工业标准的竖排报告
3. 艺术排版：结合路径文本实现曲线竖排效果
4. 多语言混合：在同一文档中混合横竖排文本

通过系统掌握上述技术方案，开发者可以灵活应对各种竖排文字需求。建议在实际项目中先进行小规模测试，验证文本旋转精度和布局效果后再进行大规模文档生成。