首页 > 软件编程 > java > Java设置Word文档样式

Java Word文档段落与文本背景色设置的完全指南

2026-06-23 08:19:15 作者：缺点内向

在日常办公或项目文档生成中,通过编程方式控制 Word 文档的排版样式是一项常见需求,本文将介绍如何利用 Java 语言,基于开源生态中广泛使用的文档处理库,实现 Word 文档中段落与文本背景色的设置,感兴趣的小伙伴可以了解下

在日常办公或项目文档生成中，通过编程方式控制 Word 文档的排版样式是一项常见需求。其中，为特定段落或文本添加背景色，能够有效提升文档的可读性和信息层次感。本文将介绍如何利用 Java 语言，基于开源生态中广泛使用的文档处理库，实现 Word 文档中段落与文本背景色的设置。

环境配置

本文示例基于 Spire.Doc for Java 库实现。若使用 Maven 构建项目，可在 pom.xml 中添加如下依赖：

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.cn/repository/maven-public/</url>
    </repository>
</repositories>
<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.6.0</version>
    </dependency>
</dependencies>

对于非 Maven 项目，可手动下载 JAR 文件并添加到项目构建路径中。

段落背景色设置

段落的背景色会填充整个段落的矩形区域，适用于需要整段高亮或区分不同内容块的场景。实现步骤如下：

加载文档：通过 Document 类加载目标Word文件。
定位段落：获取文档中的节（Section），再从节中通过索引获取指定段落。
设置颜色：调用 Paragraph.getFormat().setBackColor() 方法，传入 java.awt.Color 对象。
保存结果：输出处理后的文档。

以下示例为文档第一个节中的第四个段落设置浅灰色背景：

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.Section;
import com.spire.doc.documents.Paragraph;
import java.awt.*;

public class SetParagraphBackground {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("示例.docx");

        Section section = document.getSections().get(0);
        Paragraph paragraph = section.getParagraphs().get(3); // 索引从0开始

        paragraph.getFormat().setBackColor(Color.LIGHT_GRAY);

        document.saveToFile("段落背景色.docx", FileFormat.Docx_2013);
        document.dispose();
    }
}

指定文本的背景色

与段落背景不同，文本背景色仅作用于选中的字符串片段。这种方法更精细，适合高亮文档中的关键词、术语或数值。核心步骤为：

加载文档：同前。
查找文本：使用 Document.findAllString() 方法定位所有匹配的目标字符串。
遍历并设置：遍历查找结果，将每个匹配项转换为 TextRange 对象，调用 TextRange.getCharacterFormat().setTextBackgroundColor() 设置颜色。
保存文档。

此方法可批量修改文档中所有特定文本的背景色，也可通过索引单独处理某一处匹配项。

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.documents.TextSelection;
import com.spire.doc.fields.TextRange;
import java.awt.*;

public class SetTextBackground {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("示例.docx");

        TextSelection[] selections = document.findAllString("目标文本", false, true);

        for (TextSelection selection : selections) {
            TextRange textRange = selection.getAsOneRange();
            textRange.getCharacterFormat().setTextBackgroundColor(Color.CYAN);
        }

        // 若仅修改第一个匹配项：
        // TextRange firstRange = selections[0].getAsOneRange();
        // firstRange.getCharacterFormat().setTextBackgroundColor(Color.CYAN);

        document.saveToFile("文本背景色.docx", FileFormat.Docx_2013);
        document.dispose();
    }
}

两种方式对比

特性	段落背景色	文本背景色
作用范围	整个段落区域	选中的连续文本片段
核心方法	`Paragraph.getFormat().setBackColor()`	`TextRange.getCharacterFormat().setTextBackgroundColor()`
适用场景	强调整段内容、代码块、引用段落	高亮关键词、术语、数据值
处理粒度	段落级别	字符级别
查找方式	直接通过段落索引定位	需通过字符串查找定位

注意事项

文档背景色（页面级）与段落/文本背景色属于不同层面的样式设置，互不影响。页面背景色可通过 Document.getBackground() 相关方法操作。
findAllString() 方法支持设置是否区分大小写及是否全字匹配，参数可根据实际需求调整。
操作完成后，建议调用 document.dispose() 释放文档对象占用的资源，避免内存泄漏。
设置背景色时，建议选择与文字颜色对比度合适的色彩，以保证阅读体验。

知识扩展

在 Java 中为 Word 文档设置段落或文本的背景色，并没有唯一的“标准”方法，主要取决于你使用的库。根据不同的项目需求和预算，通常有四种主流方案可供选择。

方案一：Apache POI（开源免费）

1. 设置段落背景色

Apache POI 本身没有提供直接设置段落背景色的高级 API，需要通过操作底层的 XML 对象 CTShd 来实现。

步骤如下：

获取要操作的 XWPFParagraph 对象。
通过 paragraph.getCTP() 获取底层的 CTP 对象。
创建或获取 CTP 的段落属性 PPr。
在 PPr 上添加一个新的 CTShd（Shading）对象。
使用 setFill 方法设置填充颜色（十六进制 RGB，如 "FF0000" 为红色）。
设置 setVal(STShd.CLEAR) 确保填充样式为纯色。

示例代码：

import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTShd;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.STShd;
public class SetParagraphBackground {
    public static void main(String[] args) {
        // ... 获取 paragraph 对象 ...
        XWPFParagraph paragraph = ...; 
        // 创建并设置段落的背景色
        CTShd cTShd = paragraph.getCTP().addNewPPr().addNewShd();
        cTShd.setFill("FF0000"); // 设置背景色为红色
        cTShd.setVal(STShd.CLEAR); // 设置背景样式为纯色
        // 更新段落的样式（可选，但推荐）
        paragraph.getCTP().getPPr().setShd(cTShd);
    }
}

2. 设置文本（Run）前景色

设置文本颜色相对简单，Apache POI 为 XWPFRun 提供了直接的 setColor 方法。

import org.apache.poi.xwpf.usermodel.XWPFRun;
// ...
XWPFRun run = paragraph.createRun();
run.setText("这是红色文字");
run.setColor("FF0000"); // 设置文字颜色为红色

注意：Apache POI 目前不直接支持为单个文本（XWPFRun）设置背景色（高亮色）。

方案二：Spire.Doc for Java（功能全面的商业库）

Spire.Doc for Java 提供了更直接、更高级的 API 来完成这些任务。

1. 设置段落背景色

使用 Paragraph.getFormat().setBackColor() 方法即可。

import com.spire.doc.Document;
import com.spire.doc.Section;
import com.spire.doc.documents.Paragraph;
import java.awt.Color;
public class SetParagraphBackground {
    public static void main(String[] args) {
        // 创建Document对象并加载文档
        Document document = new Document();
        document.loadFromFile("示例.docx");
        // 获取第一个节和其中的段落
        Section section = document.getSections().get(0);
        Paragraph paragraph = section.getParagraphs().get(0);
        // 设置段落的背景颜色为浅灰色[reference:8]
        paragraph.getFormat().setBackColor(Color.LIGHT_GRAY);
        // 保存文档
        document.saveToFile("段落背景色.docx", com.spire.doc.FileFormat.Docx_2013);
        document.dispose();
    }
}

2. 设置文本（TextRange）背景色

Spire.Doc 可以查找特定文本并为其设置背景色。

import com.spire.doc.Document;
import com.spire.doc.documents.TextSelection;
import com.spire.doc.fields.TextRange;
import java.awt.Color;
public class SetTextBackground {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("示例.docx");
        // 查找文档中所有 "目标文本"
        TextSelection[] selections = document.findAllString("目标文本", true, true);
        for (TextSelection selection : selections) {
            // 将找到的文本范围设置为黄色背景[reference:10]
            TextRange textRange = selection.getAsOneRange();
            textRange.getCharacterFormat().setTextBackgroundColor(Color.YELLOW);
        }
        document.saveToFile("文本背景色.docx", com.spire.doc.FileFormat.Docx_2013);
        document.dispose();
    }
}

方案三：Aspose.Words for Java（行业标杆）

Aspose.Words 同样提供了强大的 API 来实现这些功能。

1. 设置段落背景色

可以通过 ParagraphFormat 的 setShading 方法来实现。

import com.aspose.words.Document;
import com.aspose.words.Paragraph;
import java.awt.Color;
public class SetParagraphBackground {
    public static void main(String[] args) throws Exception {
        Document doc = new Document("示例.docx");
        Paragraph para = (Paragraph) doc.getChild(com.aspose.words.NodeType.PARAGRAPH, 0, true);
        // 设置段落背景色
        para.getParagraphFormat().getShading().setBackgroundPatternColor(Color.LIGHT_GRAY);
        doc.save("段落背景色.docx");
    }
}

2. 设置文本（Run）背景色

可以为特定的 Run 对象设置高亮色。

import com.aspose.words.Document;
import com.aspose.words.Run;
import com.aspose.words.Color;
public class SetTextBackground {
    public static void main(String[] args) throws Exception {
        Document doc = new Document("示例.docx");
        Run run = (Run) doc.getChild(com.aspose.words.NodeType.RUN, 0, true);
        // 设置文本高亮色（背景色）
        run.getFont().setHighlightColor(Color.YELLOW);
        doc.save("文本背景色.docx");
    }
}

小结

通过上述方法，开发者可以灵活地通过 setBackColor 和 setTextBackgroundColor 两个核心方法，分别控制 Word 文档中段落和文本的背景色。段落背景适合大范围内容标识，文本背景则适用于精细化关键词高亮。两者结合使用，可满足多数文档自动化生成中的样式标注需求。该方案在处理合同条款标注、技术文档关键字强调、报告重点数据高亮等场景中具有实际应用价值，能够帮助开发者在批量生成文档时保持一致的视觉规范。

到此这篇关于Java Word文档段落与文本背景色设置的完全指南的文章就介绍到这了,更多相关Java设置Word文档样式内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

Java Word文档段落与文本背景色设置的完全指南

环境配置

段落背景色设置

指定文本的背景色

两种方式对比

注意事项

知识扩展

小结

您可能感兴趣的文章: