# 23 文字样式定制：字体、间距与文本渲染模式

## 引入

合同标题、金额与风险提示需要清晰的视觉层级；同一份文档里，中文正文、英文副标题和紧凑表格对字体、间距的要求又各不相同。jquick-pdf 的 `style3.txt` 已验证一批文本样式属性，本文以“授信审批摘要”为例，串起字体、字号、颜色、字符间距、单词间距与文本渲染模式的配置方法。

环境与依赖见第 21 篇。中文项目可按 README 引入 `jquick-pdf-font` 获取内置 CJK 字体。

## 核心讲解

### 字体、字号与颜色

- `font`：字体类型，取值为枚举风格的大写标识，如 `font:HELVETICA`。
- `fontFamilyNames`：字体家族名称，逗号分隔多个候选，如 `fontFamilyNames:Helvetica,Arial`；前面的名称不可用时向后回退。
- `fontSize`：字号，直接写数值，如 `fontSize:24`。
- `fontColor`：字体颜色，取颜色名、`#RRGGBB`、`rgb()` / `rgba()`。

字号建立层级，颜色用于区分语义（正文深灰、警示红），两者配合比单靠加粗更稳定。注意 `fontSize` 与尺寸类属性不同，直接写数值而不带单位；`font`、`fontFamilyNames` 两者可以只用一个，也可以并列，实际生效的字体以运行环境能提供的字形为准。

### 字符间距与单词间距

`characterSpacing` 调整字符间距，`wordSpacing` 调整单词间距，二者不是同一概念：

- `characterSpacing`：作用于字符之间，对中文同样有效。中文没有空格分词，要让标题“疏排”只能用这个属性。
- `wordSpacing`：作用于空格分隔的单词之间，对连续中文基本无效果。
- `splitCharacters`：`characterSpacing` 的别名，两种写法等价。

### 渲染模式与装饰

`textRenderingMode` 控制文本渲染模式（填充、描边、裁剪等），与 `strokeColor`、`strokeWidth` 配合可做出描边字效果。装饰属性包括 `bold`、`italic`、`underline`、`lineThrough`，取值形态为布尔样式（`bold:true`）。`fontKerning` 控制是否启用字距调整，例如 `fontKerning:yes`。

需要强调：`textRenderingMode` 的数值不应简单等同于 CSS 或 Canvas 的取值标准，实际效果以生成后的 PDF 为准。

### 完整示例

```java
import com.github.paohaijiao.executor.JQuickPdfFactory;
import java.nio.file.Files;
import java.nio.file.Paths;

public class TextStyleDemo {
    public static void main(String[] args) throws Exception {
        String template = "<pdf><body>"
                // 标题：字号建立层级 + 深色
                + "<h1 style=\"fontSize:24;fontColor:#1f2937\">'授信审批摘要'</h1>"
                // 英文副标题：字体候选 + 字符间距
                + "<p style=\"fontFamilyNames:Helvetica,Arial;fontSize:14;characterSpacing:1\">'Customer Risk Summary'</p>"
                // 风险提示：颜色 + 描边
                + "<p style=\"fontSize:18;fontColor:red;strokeColor:#7f1d1d;strokeWidth:1\">'高风险：需要人工复核'</p>"
                // 中文正文：wordSpacing 对连续中文影响有限，仅作对照
                + "<p style=\"fontSize:12;wordSpacing:2\">'收入稳定，近十二个月无逾期记录。'</p>"
                + "</body></pdf>";
        byte[] pdf = new JQuickPdfFactory().executeContent(template);
        Files.write(Paths.get("text-style-report.pdf"), pdf);
    }
}
```

动态字段可用 `bind` / `bindAll` 注入模板。文本字面量必须放在单引号内；含逗号或空格的复杂 style 值按示例用引号包裹。
**效果如下**
![在这里插入图片描述](https://developer.qcloudimg.com/http-save/yehe-9692717/e5b725c062f1c5238950c6fdee1db6cc.png)


## 关键细节

### 字体回退与中文显示

`fontFamilyNames` 是候选列表，名称不存在时发生回退，回退到不含中文字形的字体时中文会显示方框。中文文档应通过 `jquick-pdf-font` 或已注册字体提供 CJK 字形，具体字体名称以已安装/已注册字体为准。字体决定换行宽度，同一段文本在不同字体环境下断行位置不同，必须用目标运行环境验证。

### 间距的副作用

间距是布局输入的一部分。`characterSpacing` 过大会让标题和表格列超宽，触发换行或溢出；`wordSpacing` 若被误用在中文上，不仅没有效果，还会让预期的排版调整落空。调整间距后要重新检查宽度相关样式与分页。

### 描边与装饰的取舍

描边宽度过大会覆盖字形影响可读性，小字号上尤其明显；`bold`、`italic`、`underline`、`lineThrough` 与颜色、字号组合时，样式数量要克制，同一文档保持少量层级比堆叠效果更易维护。

### 字体宽度与分页

字体不只影响外观，也决定每行容纳的字符数和总行数，进而决定分页位置。依赖字体宽度做精确版面（例如在固定高度的块里塞入固定文案）时，换字体或换运行环境可能直接导致溢出，应留出余量并用目标环境回归。字体资源、布局宽度和可读性要一起验收。

### 数值与单位

`fontSize`、`characterSpacing`、`wordSpacing`、`strokeWidth` 等文本相关属性在已验证示例中直接写数值、不跟单位；而 `margin*`、`padding*` 等尺寸属性按 `px`、`pt`、`mm`、`cm`、`in` 写单位。单位混用是常见的排版偏差来源，改动前先确认属性属于哪一类。

### 属性命名

驼峰与连字符属性名互为别名，例如 `fontSize` 与 `font-size`、`characterSpacing` 与 `character-spacing`。同一项目内保持一种写法即可，混用会增加排查成本。

## 实战说明

### 步骤

1. 先用字号建立标题层级，再设置颜色。
2. 英文内容通过 `fontFamilyNames` 提供候选字体。
3. 需要疏排的标题用 `characterSpacing` 调整字符间距。
4. 风险提示使用 `fontColor` 配 `strokeColor` / `strokeWidth`。
5. 执行 `executeContent` 并写出 PDF。

### 验证与结果预期

- 标题、英文副标题、中文正文是否形成清晰层级。
- 中文是否出现方框，出现即字体未命中。
- 调整后的标题是否与预期等宽，是否挤占相邻元素。
- 风险行的描边是否影响字形识别。
- 换行位置在目标环境是否稳定。
- 同一段文案在目标部署环境的字体差异下是否仍保持一致。

### 异常排查

- 中文方框：确认 `jquick-pdf-font` 已引入或字体已注册，再确认 `fontFamilyNames` 中的名称真实存在。
- 间距无效：核对是否写错对象，中文疏排应使用 `characterSpacing`。
- 渲染模式无效果：检查 `strokeColor`、`strokeWidth` 是否同时给了值。
- 版面被撑宽：回看间距值是否过大。

### 生产注意事项

固定字体资源与版本，启动时做字体自检；为标题、正文、警告建立少量主题样式；导出后抽样检查中文文本与页数。大量文本不要逐字拼接，模板保持可读；字体资源、布局宽度与可读性应一起验收。

### 主题样式的最小集合

把标题、正文、警示固化为少量组合——每类各自一套 `fontSize` 加 `fontColor`，必要时再叠加一个装饰属性——新增内容时只从这些组合中选择，不临时发明新写法。组合数量越多，改动字体或间距后的回归成本越高；同时控制同一段文本上生效的样式属性数量，也有助于定位排版异常。

### 适用场景

合同、票据、风控报告和标签是典型场景。`bold`、`italic`、`underline`、`lineThrough` 可以与颜色、字号组合使用，但同一文档的层级数量应保持克制。

## 总结

文字样式由四组属性构成：字体与颜色（`font`、`fontFamilyNames`、`fontSize`、`fontColor`）、间距（`characterSpacing` / `splitCharacters` 与 `wordSpacing`）、渲染模式（`textRenderingMode`、`strokeColor`、`strokeWidth`）和装饰（`bold`、`italic`、`underline`、`lineThrough`）。其中中文疏排只能用字符间距，`wordSpacing` 对连续中文基本无效果。

常见误区是假定字体名称一定存在，或用间距去修版面却忽略它对宽度和分页的连带影响。字体回退规则取决于运行环境，中文项目应显式提供字体资源。

版本基线：jquick-pdfx 4.0.0、JDK 8+，升级前请核对 README_zh.md 的版本对照表；更多示例见 [GitHub 仓库](https://github.com/paohaijiao/jquick-pdf)。

合同标题、金额与风险提示需要清晰的视觉层级；同一份文档里，中文正文、英文副标题和紧凑表格对字体、间距的要求又各不相同。jquick-pdf 的 style3.txt 已验证一批文本样式属性，本文以“授信审批摘要”为例，串起字体、字号、颜色、字符间距、单词间距与文本渲染模式的配置方法。

文字样式定制：字体、间距与文本渲染模式

编程语言

开发工具

后端

jquick-pdf文本样式定制指南：通过font、fontFamilyNames、fontSize、fontColor设置字体层级与语义色，characterSpacing调整中文疏排，textRenderingMode配合strokeColor实现描边效果。中文需引入jquick-pdf-font避免方框，注意间距对布局宽度和分页的影响，用少量主题样式维持排版一致性。

代码解释

GitHub

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

jquick-pdf文本样式定制指南：通过font、fontFamilyNames、fontSize、fontColor设置字体层级与语义色，characterSpacing调整中文疏排，textRenderingMode配合strokeColor实现描边效果。中文需引入jquick-pdf-font避免方框，注意间距...

文字样式定制：字体、间距与文本渲染模式-腾讯云开发者社区-腾讯云

文字样式定制：字体、间距与文本渲染模式

文字样式定制：字体、间距与文本渲染模式

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐