文本、字体与页面基础

在第一篇教程中，你渲染了一个只有一行文本的页面。这一次，你将掌控页面本身以及页面上的文本。你会选择页面尺寸，撰写标题与段落，并用引擎的内置字体为它们设置样式。

你将构建什么

你将编写两个小脚本。每个脚本都会生成一个单页的可移植文档格式（Portable Document Format，PDF）文件：

01-text-basics.php 渲染一个 A4 纵向页面，其中包含一个彩色标题、自动换行的段落，以及三个对齐方式示例。
02-fonts.php 渲染一个样张页面，在若干字号下对比两个内置字体族。

所有内容仅依靠 nextpdf/core 包即可运行。你不需要任何字体文件、额外扩展，也不需要网络。如果你还没有搭建好项目，请先完成第一篇教程，然后再回到这里。

第 1 步：在 A4 页面上设置文本样式

每个页面都有尺寸和方向。A4 是常见的国际纸张尺寸，Letter 则是它在美国的对应规格。方向要么是纵向（portrait，竖直），要么是横向（landscape，横放）。开始一个页面时，你要把这两个选择都传给 addPage()。

接下来由三个方法负责写入文本。setFont() 为随后的文本选择字体和字号。 cell() 在一个不可见的方框内写入一行。multiCell() 把较长的文本自动换行为所需的行数。在这两个方法中，宽度为 0 表示“一直用到右边距为止”。

另外两个调用负责外观。setTextColor() 接受 0 到 255 的红、绿、蓝值，并会一直生效，直到你再次更改。Alignment 枚举是一组固定的具名选项，提供 Left、Center、Right 和 Justify。

在项目文件夹中创建 01-text-basics.php：

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Contracts\Orientation;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Text basics');
$document->addPage(PageSize::A4(), Orientation::Portrait);

// A colored heading. The values are red, green, and blue, each 0 to 255.
$document->setFont('helvetica', 'B', 20);
$document->setTextColor(30, 64, 175);
$document->cell(0, 14, 'Project kickoff notes', newLine: true);
$document->ln(4);

// Back to black for the body text.
$document->setTextColor(0, 0, 0);
$document->setFont('helvetica', '', 11);
$document->multiCell(
    0,
    7,
    'Welcome to the second tutorial. This paragraph is written with '
        . 'multiCell(), so the engine wraps the words onto as many lines '
        . 'as the page width requires.',
);
$document->ln(4);

$document->multiCell(
    0,
    7,
    'Justified text stretches the spaces so both edges line up. It is a '
        . 'good fit for report bodies and other long passages.',
    align: Alignment::Justify,
);
$document->ln(6);

// One line each: left, centered, and right.
$document->setFont('helvetica', 'I', 11);
$document->cell(0, 8, 'Left-aligned line', newLine: true, align: Alignment::Left);
$document->cell(0, 8, 'Centered line', newLine: true, align: Alignment::Center);
$document->cell(0, 8, 'Right-aligned line', newLine: true, align: Alignment::Right);

$document->save(__DIR__ . '/out/text-basics.pdf');

echo "Wrote out/text-basics.pdf\n";

用 php 01-text-basics.php 运行它。脚本会打印 Wrote out/text-basics.pdf，文件则出现在新建的 out/ 文件夹中。

刚刚发生了什么

addPage(PageSize::A4(), Orientation::Portrait) 在写入任何文本之前先创建了页面。若改为传入 Orientation::Landscape，同一个页面就会横过来。其他具名尺寸，例如 PageSize::A5() 或 PageSize::Letter()，用法完全相同。

setFont('helvetica', 'B', 20) 选择了 20 磅的粗体 Helvetica。磅（pt）是传统的印刷单位；72 磅等于一英寸。标题之所以是蓝色，是因为 cell() 调用写入它时，setTextColor(30, 64, 175) 正处于生效状态。随后的 setTextColor(0, 0, 0) 又把其后的所有内容切换回黑色。

这两个 multiCell() 调用自动为各自的段落换行。两端对齐的那一段会拉伸词间距，使两侧边缘对齐——段落的最后一行除外。在各块之间，ln() 把写入位置向下移动，以留出一些空间。最后，save() 构建文件并把它写入 out/。

关于这些方法接受的每个参数，请参阅用字体和对齐方式排布文本。

第 2 步：在内置字体中做选择

引擎内置了三个文本字体族：Helvetica、Times 和 Courier。Helvetica 是无衬线（sans-serif）字体，也就是说字母末端没有细小的收笔（衬线，serif）。 Times 是衬线字体，适合阅读较长的、类似印刷品的段落。Courier 是等宽字体，因此适合代码清单和收据。由于这些字体族是内置的，你的脚本完全不需要任何字体文件。

setFont() 的样式参数由单字母标志组合而成：'B' 表示粗体，'I' 表示斜体，'U' 表示下划线。空字符串表示常规，且这些标志可以组合，因此 'BI' 会得到粗斜体。

这些内置字体族覆盖以拉丁字母书写的文本。对于其他书写系统或你自己的品牌字体，你需要注册一个字体文件，做法见嵌入与子集化字体一文（子集化只保留你实际用到的字符，因此文件能保持较小）。字体支持矩阵列出了引擎接受的每一种字体格式。

在第一个脚本旁边创建 02-fonts.php：

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Font sampler');
$document->addPage();

$document->setFont('helvetica', 'B', 20);
$document->cell(0, 14, 'Built-in font sampler', newLine: true);
$document->ln(4);

// Helvetica: a sans-serif face, a solid default for labels and headings.
$document->setFont('helvetica', 'B', 14);
$document->cell(0, 10, 'Helvetica', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('helvetica', '', (float) $size);
    $document->cell(0, $size * 0.8, "Helvetica sample at {$size}pt.", newLine: true);
}
$document->setFont('helvetica', 'BI', 12);
$document->cell(0, 9, 'Helvetica bold italic for emphasis.', newLine: true);
$document->ln(6);

// Times: a serif face that suits long, print-like passages.
$document->setFont('times', 'B', 14);
$document->cell(0, 10, 'Times', newLine: true);
foreach ([10, 12, 16] as $size) {
    $document->setFont('times', '', (float) $size);
    $document->cell(0, $size * 0.8, "Times sample at {$size}pt.", newLine: true);
}
$document->setFont('times', 'I', 12);
$document->cell(0, 9, 'Times italic for quotations.', newLine: true);

$document->save(__DIR__ . '/out/font-sampler.pdf');

echo "Wrote out/font-sampler.pdf\n";

用 php 02-fonts.php 运行它，然后打开 out/font-sampler.pdf。你会看到同一句示例文本在两个字体族之间呈现出不同的样貌，并随三种字号逐级变大。

刚刚发生了什么

不带参数的 addPage() 使用了纵向的默认页面设置，因此并非每个脚本都要显式写出尺寸。每次 setFont() 调用都会在页面中途切换当前生效的字体族、样式或字号，而一种字体会一直生效，直到下一次 setFont() 调用。

循环用 (float) 转换字号，因为 setFont() 需要一个小数。行高随字号缩放（$size * 0.8），因此文本越大，行也越高，任何内容都不会重叠。试着把 'times' 替换为 'courier' 并再次运行脚本，看看第三个字体族。

如果出了问题

出现“找不到类”（class not found）或自动加载错误，通常意味着脚本没有找到 vendor/autoload.php。请在包含 vendor/ 的项目文件夹内运行它。
拼错的字体族名称会抛出一个异常，指明它找不到的字体。请检查拼写： helvetica、times、courier。
疑难解答中心汇集了常见的修复方法，而字体与标记则深入讲解字体问题。
每个引擎异常都记录在错误参考中，包含它携带的上下文和恢复操作。

下一步

现在，你已经能够有意识地塑造页面、设置文本样式并挑选字体。在下一篇教程中，你将在页面上放置图像，并用表格和列表来组织内容。