Skład tekstu z czcionkami i wyrównaniem

W skrócie

Ten przepis pokazuje, jak umieszczać tekst i sterować jego rodziną czcionek, stylem, rozmiarem oraz wyrównaniem. Korzystasz z trzech metod: setFont(), cell() i multiCell(). Kod jest zgodny z examples/04-text-and-fonts.php.

Instalacja

composer require nextpdf/core:^3

Polecenie z tym ograniczeniem wersji instaluje pakiet nextpdf/core. Przykład wymaga PHP 8.4.

Przegląd koncepcyjny

setFont($family, $style, $size) wybiera aktywny krój dla następnego wywołania tekstu. Argument $style przyjmuje kombinację trzech flag: B (pogrubienie), I (kursywa) i U (podkreślenie). Flaga U stosuje dekorację tekstu; pozostałe flagi wybierają wariant czcionki. Rodziny Helvetica, Times i Courier są odwzorowywane na 14 standardowych czcionek Type 1 wymienionych w ISO 32000-2. Profil zgodności może zmienić to zachowanie i wymagać osadzonej czcionki zastępczej.

cell() zapisuje jeden wiersz w ramce. multiCell() zawija słowa w kolumnie o podanej szerokości i wysokości wiersza. Tekst jest najpierw określany w przestrzeni tekstu, a macierz tekstu odwzorowuje przestrzeń tekstu na przestrzeń użytkownika (ISO 32000-2). Pracujesz w jednostkach przestrzeni użytkownika, a silnik generuje macierz.

Wyrównanie ustawiaj za pomocą wyliczenia Alignment: Left, Center, Right, Justify. W przypadku multiCell() justowanie rozkłada odstępy między słowami w obrębie wiersza.

Interfejs 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 — ten sam trait.
Alignment — NextPDF\Contracts\Alignment (Left, Center, Right, Justify).

Kompletna tabela PHPDoc pochodzi z kodu źródłowego.

Przykład kodu — Szybki start

<?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');

Przykład kodu — Środowisko produkcyjne

Przykład jest samodzielny, dzięki czemu środowisko testowe może go uruchomić. Odpowiada examples/04-text-and-fonts.php i pokazuje warianty stylu, kilka rozmiarów, wyjustowany tekst zawijany po słowach oraz trzy rodzaje wyrównania.

<?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";

Oczekiwane wyjście STDOUT:

Wrote compose-text-and-fonts.pdf

Przypadki brzegowe i pułapki

Szerokość 0 oznacza pozostałą szerokość. Po przekazaniu 0 wywołania cell(0, ...) i multiCell(0, ...) wykorzystują miejsce aż do prawego marginesu. Aby uzyskać ramkę o stałej szerokości, przekaż jawną szerokość.
Kolejność znaków w ciągu stylu. 'BI' i 'IB' wybierają ten sam wariant pogrubionej kursywy, ponieważ parser ignoruje kolejność flag. Flaga 'U' oznacza dekorację, a nie wariant czcionki.
Pokrycie glifów w czcionkach standardowych. 14 standardowych czcionek renderuje pełny repertuar WinAnsiEncoding (Windows-1252). Obejmuje on zachodnioeuropejską łacinę z diakrytykami, znak euro oraz typowe znaki interpunkcyjne typograficzne — półpauzy i pauzy, cudzysłowy drukarskie, punktor, wielokropek oraz znak towarowy. W przypadku pism spoza tego zestawu, takich jak chińskie, japońskie, koreańskie, arabskie, hebrajskie, greckie, cyrylica lub tajskie, zarejestruj i wybierz krój TrueType. Zobacz Osadzanie i tworzenie podzbiorów czcionek.
Wysokość wiersza a rozmiar czcionki. Wysokość pojedynczego wiersza w multiCell() to rozmiar czcionki pomnożony przez domyślny współczynnik wysokości wiersza profilu metrycznego. Jeśli wysokość jest zbyt mała, wiersze mogą na siebie nachodzić.
Justowanie w ostatnim wierszu. Przy justowaniu multiCell() nie rozciąga ostatniego wiersza akapitu. Jest to zgodne z konwencjonalnym składem tekstu.

Wydajność

Generowanie tekstu jest liniowe względem liczby glifów, O(n). Budżet wynosi wall_ms: 1000, peak_mb: 64. To mniej niż w przepisach dotyczących HyperText Markup Language (HTML), ponieważ nie występują tu kaskada ani drzewo układu. Czcionki standardowe nie są osadzane, więc rozmiar wyniku pozostaje mały.

Uwagi dotyczące bezpieczeństwa

Zawartość tekstowa jest renderowana, a nie interpretowana. Sprawdzaj długość ciągów dostarczonych przez użytkownika, aby ograniczyć rozmiar wyniku. Ta ścieżka nie uruchamia żadnych skryptów ani nie pobiera żadnych zdalnych zasobów.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Rodziny Helvetica, Times i Courier należą do 14 standardowych czcionek Type 1.	ISO 32000-2	iso32000_2_sec9#x1.x29
Standardowe rodziny 14 czcionek obsługują pełny łaciński zestaw znaków (WinAnsiEncoding, strona kodowa Windows 1252).	ISO 32000-2	Annex D.2 (iso32000_2_annexes#x1.x17.p4)	eb9220f88dfadad27a0be2206b64e68d8ea301d6d46e08142d43859c05fac6e4
Współrzędne tekstu znajdują się w przestrzeni tekstu i są odwzorowywane na przestrzeń użytkownika przez macierz tekstu.	ISO 32000-2	iso32000_2_sec8#x1.x10.p2

Ten przepis pokazuje, jak NextPDF składa tekst z czcionkami standardowymi. Ich pokrycie glifów to pełny repertuar WinAnsiEncoding (Windows-1252) — zachodnioeuropejska łacina wraz z typowymi znakami interpunkcyjnymi typograficznymi. Tekst w innych pismach wymaga osadzonego kroju.

Kontekst komercyjny

Nie dotyczy.