通过 NextPDF Connect 控制字体与文字样式

概览

通过在文本区块之间切换字体，创建具有多种样式的文档。set_font 会设置当前使用的字体、样式与尺寸。直到你变更之前，该状态都会持续应用于后续每一次 add_text。你需要的工具是 create_pdf、set_font、add_text 与 output_pdf — 全部都属于 Core。文本状态参数决定字形如何渲染（ISO 32000-2 §9）。

安装

composer require nextpdf/server

绑定一个传输。有三种内置字体系列可用，不需要额外的字体文件：helvetica、times 与 courier。

概念总览

set_font 接受 family、style（""、"B"、"I"、"BI"、"U"）与 size。你设置的字体会应用到后续每一次 add_text 调用，直到下一次 set_font 为止。它不会自动重置。当 add_text 带有 font_size 时，该值会覆盖当前尺寸，仅限于那一次调用；下一次调用会恢复为 set_font 的尺寸。文本由显示文本的运算符按内容流顺序输出（ISO 32000-2 §9.4）。add_text 没有颜色参数。文字颜色来自文档图形状态中的墨水颜色。

API 接口

工具	角色	风险层级
`create_pdf`	开启会话	安全
`set_font`	设置当前使用的 typeface/style/size	注意
`add_text`	使用当前字体写入文字	注意
`output_pdf`	渲染并返回 PDF	需要批准/审查（base64）

工具目录是正式的目录依据。你可以使用的工具取决于已安装的层级。

代码示例 — 快速开始

create_pdf（A4 纵向）→ document_id。
set_font（helvetica、B、24），然后 add_text（标题，居中）。
set_font（helvetica、""、12），然后 add_text（两端对齐的正文）。
set_font（courier、I、10），然后 add_text（一段代码片段）。
output_pdf。

代码示例 — 生产环境

在每个排版要求较高的区块之前，都要明确设置字体。切勿在不同逻辑区段之间依赖继承来的状态。单次调用的 font_size 覆盖只适合一次性强调，因为它不会持续保留。逐段构建，并验证每一次 add_text 都会返回一个 position。

边界情况与陷阱

未知的字体系列。 helvetica/times/courier 以外的任何值（例如 arial）都会被拒绝。
空的字体系列。 family 必须是非空字符串。
无效的样式。 请使用大写代码。 "bold" 会被拒绝。
非正数的尺寸。 size 必须是正数。
单次调用的尺寸是临时的。 它不会改变 set_font 状态。

效能

内置字体几乎不会增加体积，输出仅有几 KB。本页的可复现性配置为 structural。

安全性注意事项

在 base64 模式下，没有任何文件系统副作用。内置字体不会导入任何外部字体文件，因此本示例没有字体解析攻击面。

符合性

陈述	规格	条款	reference_id
文本由文本显示运算符按内容流顺序显示。	ISO 32000-2	§9.4
文本状态参数决定字形渲染。	ISO 32000-2	§9

商业场景

不适用 — 所有工具都属于 Core。

传输可用性

传输	可用	备注
MCP（stdio）	是	每个工具对应一次 `tools/call`。
REST	是	每个工具对应一个操作。
gRPC	是	每个工具对应一次一元调用。

HITL 风险层级

create_pdf 为安全；set_font/add_text 为注意；output_pdf 为需要批准，在 base64 模式下降级为审查（HITL 风险层级）。

确认门控 JSON 包

Base64 输出：

{ "allowed": true }