如何使用DOCX4J在生成DOCX文件时添加换行符

我之前也碰到过一模一样的坑！直接把\n换成<w:br>根本没用，因为普通的字符串替换会把XML标签当成纯文本输出，Word只会显示<w:br>这几个字符，不会解析成换行。下面给你几个靠谱的解决办法：

方法一：手动拆分文本并插入换行节点（最直接） #

核心思路是放弃纯字符串替换，转而操作Word的XML节点——把带换行的字符串拆分成多段文本，在每段之间插入docx4j的Br对象（对应Word原生的<w:br>标签）。

示例代码参考：

// 假设你已经从WordprocessingMLPackage中拿到了目标段落对象P
P paragraph = ...;
String targetText = "这是第一行\n这是第二行\n这是第三行";

// 清空段落原有内容
paragraph.getContent().clear();

// 按换行符拆分文本
String[] textLines = targetText.split("\n");
for (int i = 0; i < textLines.length; i++) {
    // 创建文本节点并包裹在Run里
    Text text = new Text();
    text.setValue(textLines[i]);
    R run = new R();
    run.getContent().add(text);
    
    // 将Run添加到段落
    paragraph.getContent().add(run);
    
    // 非最后一行，插入换行节点
    if (i != textLines.length - 1) {
        Br br = new Br();
        R brRun = new R();
        brRun.getContent().add(br);
        paragraph.getContent().add(brRun);
    }
}

方法二：扩展变量替换逻辑（适合模板变量场景） #

如果你是用模板变量（比如${content}）做替换，可以自定义变量替换处理器，自动识别字符串里的\n并转换成换行节点。

示例代码参考：

// 加载模板并准备变量替换
WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(new File("template.docx"));
VariablePrepare.prepare(wordMLPackage);

// 带换行的目标内容
Map<String, Object> variables = new HashMap<>();
variables.put("content", "第一行\n第二行\n第三行");

// 自定义替换处理器，处理换行
ReplaceHandler replaceHandler = new ReplaceHandler() {
    @Override
    public List<Object> replace(String variableName, String variableValue, List<Object> existingContent) {
        List<Object> newContent = new ArrayList<>();
        String[] lines = variableValue.split("\n");
        
        for (int i = 0; i < lines.length; i++) {
            Text text = new Text(lines[i]);
            R run = new R();
            run.getContent().add(text);
            newContent.add(run);
            
            if (i != lines.length - 1) {
                Br br = new Br();
                R brRun = new R();
                brRun.getContent().add(br);
                newContent.add(brRun);
            }
        }
        return newContent;
    }
};

// 执行替换并保存
VariableReplace.replace(wordMLPackage, variables, replaceHandler);
wordMLPackage.save(new File("output.docx"));

方法三：用段落拆分替代换行（适合需要独立段落的场景） #

如果你的换行其实是要分成独立的段落（而非同一段落内的换行），可以把每个换行后的文本做成新的<w:p>节点：

String targetText = "段落1\n段落2\n段落3";
String[] paragraphs = targetText.split("\n");
P parentParagraph = ...; // 找到模板中的原段落节点
List<Object> parentContent = parentParagraph.getParent().getContent();
int index = parentContent.indexOf(parentParagraph);

// 移除原段落
parentContent.remove(index);

// 逐个添加新段落
for (String paraText : paragraphs) {
    P newPara = new P();
    Text text = new Text(paraText);
    R run = new R();
    run.getContent().add(text);
    newPara.getContent().add(run);
    parentContent.add(index++, newPara);
}

为什么直接替换<w:br>没用？ #

当你用普通字符串替换（比如replaceAll("\n", "<w:br>")）时，docx4j会把<w:br>当成纯文本内容，包裹在<w:t>标签里，Word只会把它当成普通文字显示，不会解析成换行标签。必须通过API创建对应的XML节点，才能让Word识别为换行。

内容的提问来源于stack exchange，提问作者Narendra K