文字、字型與頁面基礎

在第一份教學中，您算繪了一個只有一行文字的頁面。這一次，您將掌控頁面本身，以及頁面上的文字。您會挑選頁面尺寸、撰寫標題與段落，並以引擎的內建字型為它們設定樣式。

您將建立的內容

您將撰寫兩個小型指令碼。每一個都會產生一份單頁的 Portable Document Format（PDF）檔案：

01-text-basics.php 會算繪一個 A4 直向頁面，內含一個彩色標題、會自動換行的段落，以及三個對齊範例。
02-fonts.php 會算繪一個範例頁面，比較兩個內建字型家族在數種尺寸下的樣貌。

所有內容僅靠 nextpdf/core 套件即可執行。您不需要任何字型檔、額外的擴充功能，也不需要網路。如果您還沒有設定好專案，請先依照第一份教學完成，再回到這裡。

步驟 1：在 A4 頁面上設定文字樣式

每個頁面都有尺寸與方向。A4 是國際上常見的紙張尺寸，Letter 則是它在美國的對應規格。方向不是直向（直立）就是橫向（橫躺）。當您開始一個新頁面時，會把這兩項選擇一併傳給 addPage()。

接著由三個方法負責寫入文字。setFont() 為後續文字挑選字體與尺寸。 cell() 會在一個隱形的方框內寫入一行文字。multiCell() 則會把較長的文字依需要換成多行。在這兩個方法中，寬度為 0 代表「一路延伸到右邊界為止」。

另外兩個呼叫負責外觀。setTextColor() 接受 0 到 255 的紅、綠、藍值，並會持續套用，直到您再次變更為止。Alignment enum（列舉）是一份固定的具名選項清單，提供 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' 會產生粗斜體。

內建家族涵蓋以拉丁字母為基礎的文字。若要用於其他書寫系統，或您自己的品牌字體，就要註冊一個字型檔，如嵌入並子集化字型這篇 recipe（範例）所示（子集化只會保留您實際用到的字元，因此檔案能保持精簡）。字型支援對照表列出了引擎所接受的每一種字型格式。

在第一個指令碼旁邊建立 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」或 autoload（自動載入）錯誤，通常代表指令碼找不到 vendor/autoload.php。請在含有 vendor/ 的專案資料夾內執行它。
打錯家族名稱會擲出一個例外，並指出它找不到的字型。請檢查拼字： helvetica、times、courier。
疑難排解中心彙整了常見的修正方式，而字型與標記則深入涵蓋字型相關問題。
每一個引擎例外都記載於錯誤參考，一併說明它所攜帶的情境資訊與復原動作。

下一步

現在您已經能夠有意識地形塑頁面、設定文字樣式並挑選字型。在下一份教學中，您會在頁面上放置圖片，並以表格與清單來組織內容。