设置字体与对齐方式来排版文本

速览

本示例会放置文本，并设置字体族、样式、大小与对齐方式。这项工作由三个方法完成：setFont()、cell() 与 multiCell()。代码对应 examples/04-text-and-fonts.php。

安装

composer require nextpdf/core:^3

该版本约束会安装 nextpdf/core 包。本示例在 PHP 8.4 上运行。

概念总览

setFont($family, $style, $size) 会选定当前字样，也就是下一次文本调用所使用的字体。$style 参数会组合三个标志：B（粗体）、I（斜体）与 U（下划线）。U 是文本装饰标志，其余标志用于选择字体变体。Helvetica、Times 与 Courier 这几个字体族会解析为 ISO 32000-2 中列出的 14 种标准 Type 1 字体。一致性配置文件可以覆盖这一行为，强制嵌入替代字体。

cell() 会在一个方框中写入单行文本。multiCell() 会按给定的宽度与行高，将文本自动换行并排入一个栏中。文本位于文本空间，而文本矩阵会把文本空间映射到用户空间（ISO 32000-2）。你只需按用户单位操作，矩阵会由引擎为你输出。

使用 Alignment 枚举设置对齐方式：Left、Center、Right、Justify。在 multiCell() 中，两端对齐会把词与词之间的空白均匀分布到整行。

API 接口

setFont(string $family, string $style = '', float $size = 12.0): static — NextPDF\Core\Concerns\HasTypography。
cell(float $width, float $height, string $text = '', bool|string $border = false, bool $newLine = false, Alignment $align = Alignment::Left, bool $fill = false): static — NextPDF\Core\Concerns\HasTextOutput。
multiCell(float $width, float $height, string $text, bool|string $border = false, Alignment $align = Alignment::Left): static — 同一 trait。
Alignment — NextPDF\Contracts\Alignment（Left、Center、Right、Justify）。

完整 PHPDoc 表格由源代码生成。

代码示例 — 快速上手

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Heading', newLine: true);

$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Word-wrapped justified body text.', align: Alignment::Justify);

$doc->save(__DIR__ . '/out.pdf');

代码示例 — 生产环境

该示例自包含，测试框架可以直接运行。它对应 examples/04-text-and-fonts.php，并演示样式变体、多种大小、自动换行的两端对齐文本，以及三种对齐方式。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Text and Fonts');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Text and Font Styles', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', '', 12);
$doc->cell(0, 8, 'Normal text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, 'Bold text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'I', 12);
$doc->cell(0, 8, 'Italic text in Helvetica 12pt.', newLine: true);
$doc->setFont('helvetica', 'BI', 12);
$doc->cell(0, 8, 'Bold-Italic text in Helvetica 12pt.', newLine: true);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Font Sizes', newLine: true);
foreach ([8, 10, 12, 14, 18] as $size) {
    $doc->setFont('helvetica', '', (float) $size);
    $doc->cell(0, $size * 0.8, "This is {$size}pt text.", newLine: true);
}
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Multi-Line Text (Word Wrap)', newLine: true);
$doc->setFont('helvetica', '', 11);
$paragraph = 'NextPDF is a modern PDF 2.0 library for PHP. It provides a '
    . 'fluent API for document creation. This paragraph demonstrates '
    . 'automatic word wrapping and justified alignment with multiCell().';
$doc->multiCell(0, 7, $paragraph, align: Alignment::Justify);
$doc->ln(5);

$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Text Alignment', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->cell(0, 8, 'Left-aligned text', newLine: true, align: Alignment::Left);
$doc->cell(0, 8, 'Center-aligned text', newLine: true, align: Alignment::Center);
$doc->cell(0, 8, 'Right-aligned text', newLine: true, align: Alignment::Right);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/compose-text-and-fonts.pdf');

echo "Wrote compose-text-and-fonts.pdf\n";

预期的 STDOUT：

Wrote compose-text-and-fonts.pdf

边界情况与陷阱

宽度 0 表示剩余宽度。 当你传入 0 时，cell(0, ...) 与 multiCell(0, ...) 会把宽度设为直到右边距为止的剩余空间。若要固定宽度的方框，请传入明确的宽度值。
样式字符串的顺序。 'BI' 与 'IB' 会选择相同的粗斜体变体，因为解析器会忽略标志的顺序。'U' 是装饰标志，而非字体变体。
标准字体的字形覆盖范围。 这 14 种标准字体可呈现完整的 WinAnsiEncoding（Windows-1252）字集。它涵盖西欧带重音符号的拉丁字符、欧元符号，以及常见的排版标点——半角与全角破折号、弯引号、项目符号、省略号与商标符号。对于该字集之外的文字系统，例如中文、日文、韩文、阿拉伯文、希伯来文、希腊文、西里尔文或泰文，请注册并选用 TrueType 字样。请参阅嵌入与子集化字体一节。
行高与字体大小的关系。 multiCell() 每一行的高度等于字体大小乘以度量配置文件的默认行高比例。如果高度设得太小，可能让各行重叠。
最后一行的两端对齐。 两端对齐的 multiCell() 不会拉伸段落的最后一行。这符合传统排版惯例。

性能

文本输出的时间复杂度与字形数量成线性关系，为 O(n)。预算为 wall_ms: 1000, peak_mb: 64。该预算低于 HTML 示例，因为没有层叠或布局树。标准字体不会被嵌入，因此可让输出文件保持精简。

安全性注意事项

文本内容会被渲染，而非被解释。请校验用户提供字符串的长度，使输出大小保持在可控范围内。该路径不会运行任何脚本，也不会获取任何远程资源。

一致性

陈述	规范	条款	reference_id
Helvetica、Times 与 Courier 这几个字体族，属于 14 种标准 Type 1 字体之列。	ISO 32000-2	iso32000_2_sec9#x1.x29
标准 14 字体族支持完整的拉丁字符集（WinAnsiEncoding，Windows code page 1252）。	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
文本坐标位于文本空间，并由文本矩阵映射到用户空间。	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

本示例演示 NextPDF 如何使用标准字体排版文本。它们的字形覆盖范围是完整的 WinAnsiEncoding（Windows-1252）字集——西欧拉丁字符外加常见的排版标点。其他文字系统的文本需要嵌入字样。

商业情境

不适用。