以字型與對齊方式排版文字

重點摘要

這則 recipe（範例）示範如何放置文字，並設定字型家族、樣式、大小與對齊方式。主要透過三個方法完成這項工作：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 這幾個字型家族，會解析（resolve）為 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');

程式碼範例 — 正式環境

這個範例可獨立執行，測試載具（test harness）可以直接執行它。它對應 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 範例更低，因為沒有層疊或版面樹。標準字型不會被嵌入，因此可讓輸出檔案保持精簡。

安全性注意事項

文字內容會被繪製，而不是被解譯。請驗證使用者提供字串的長度，使輸出大小維持在可控範圍內。這條路徑不會執行任何指令稿，也不會抓取任何遠端資源。

符合性

陳述	規格	條款	參考 ID
Helvetica、Times 與 Courier 這幾個字型家族，皆屬於 14 種標準 Type 1 字型之列。	ISO 32000-2	iso32000_2_sec9#x1.x29（§9 字型）
standard-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（§8 文字定位）

這則範例示範 NextPDF 如何使用標準字型排版文字。它們的字元涵蓋範圍是完整的 WinAnsiEncoding（Windows-1252）字集——西歐拉丁字元，加上常見的排印標點。其他書寫系統的文字需要嵌入字型。

商業情境

不適用。