Tekst, czcionki i podstawy strony

W pierwszym samouczku wyrenderowałeś stronę z jednym wierszem tekstu. Tym razem przejmujesz kontrolę nad samą stroną i nad tekstem na niej. Wybierzesz rozmiar strony, napiszesz nagłówki i akapity oraz nadasz im styl za pomocą wbudowanych czcionek silnika.

Co zbudujesz

Napiszesz dwa małe skrypty. Każdy z nich tworzy jednostronicowy plik w formacie Portable Document Format (PDF):

• 01-text-basics.php renderuje stronę A4 w orientacji pionowej z kolorowym nagłówkiem, zawijanymi akapitami i trzema przykładami wyrównania.
• 02-fonts.php renderuje stronę z próbkami, która porównuje dwie wbudowane rodziny czcionek w kilku rozmiarach.

Wszystko działa z samym pakietem nextpdf/core. Nie potrzebujesz żadnych plików czcionek, dodatkowych rozszerzeń ani dostępu do sieci. Jeśli nie masz jeszcze skonfigurowanego projektu, wykonaj najpierw pierwszy samouczek i wróć tutaj.

Krok 1: Formatowanie tekstu na stronie A4

Każda strona ma rozmiar i orientację. A4 to popularny międzynarodowy rozmiar papieru, a Letter to jego odpowiednik w Stanach Zjednoczonych. Orientacja jest pionowa (na wysokość) lub pozioma (na szerokość). Oba wybory przekazujesz do addPage(), gdy rozpoczynasz stronę.

Następnie za pisanie odpowiadają trzy metody. setFont() wybiera krój i rozmiar dla tekstu, który po niej następuje. cell() zapisuje jeden wiersz wewnątrz niewidzialnego pola. multiCell() zawija dłuższy tekst na tylu wierszach, ile potrzeba. W obu metodach szerokość 0 oznacza „użyj całej przestrzeni aż do prawego marginesu”.

Dwa kolejne wywołania odpowiadają za wygląd. setTextColor() przyjmuje wartości czerwieni, zieleni i błękitu od 0 do 255 i obowiązuje, dopóki nie zmienisz jej ponownie. Wyliczenie Alignment, stała lista nazwanych opcji, udostępnia Left, Center, Right i Justify.

Utwórz 01-text-basics.php w folderze projektu:

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

Uruchom go poleceniem php 01-text-basics.php. Skrypt wypisuje Wrote out/text-basics.pdf, a plik pojawia się w nowym folderze out/.

Co się właśnie stało

addPage(PageSize::A4(), Orientation::Portrait) utworzyło stronę, zanim zapisano jakikolwiek tekst. Przekaż zamiast tego Orientation::Landscape, a ta sama strona obróci się w poziom. Inne nazwane rozmiary, takie jak PageSize::A5() czy PageSize::Letter(), działają tak samo.

setFont('helvetica', 'B', 20) wybrało pogrubioną czcionkę Helvetica w rozmiarze 20 punktów. Punkt (pt) to tradycyjna jednostka drukarska; 72 punkty równają się jednemu calowi. Nagłówek jest niebieski, ponieważ setTextColor(30, 64, 175) było aktywne, gdy wywołanie cell() go zapisywało. Kolejne setTextColor(0, 0, 0) przełączyło z powrotem na czerń dla wszystkiego, co następuje po nim.

Dwa wywołania multiCell() automatycznie zawinęły swoje akapity. To wyjustowane wywołanie rozciąga odstępy między słowami, tak aby obie krawędzie się wyrównały, z wyjątkiem ostatniego wiersza akapitu. Między blokami ln() przesunęło pozycję zapisu w dół, aby dodać nieco przestrzeni. Na koniec save() zbudowało plik i zapisało go w out/.

Wszystkie parametry, które przyjmują te metody, opisano w artykule Komponowanie tekstu z czcionkami i wyrównaniem.

Krok 2: Wybór spośród wbudowanych czcionek

Silnik dostarcza trzy wbudowane rodziny tekstowe: Helvetica, Times i Courier. Helvetica to krój bezszeryfowy, co oznacza, że jej litery nie mają małych zakończeń kresek (szeryfów). Times to krój szeryfowy, który dobrze czyta się w długich, przypominających druk fragmentach. Courier ma stałą szerokość, więc nadaje się do listingów kodu i paragonów. Ponieważ te rodziny są wbudowane, skrypty nie potrzebują żadnych plików czcionek.

Argument stylu w setFont() łączy jednoliterowe flagi: 'B' dla pogrubienia, 'I' dla kursywy i 'U' dla podkreślenia. Pusty ciąg znaków oznacza styl zwykły, a flagi można łączyć, więc 'BI' daje pogrubioną kursywę.

Wbudowane rodziny obejmują tekst oparty na alfabecie łacińskim. W przypadku innych systemów pisma lub własnego kroju marki rejestrujesz plik czcionki, jak pokazuje przepis Osadzanie i tworzenie podzbiorów czcionek (tworzenie podzbioru zachowuje tylko faktycznie użyte znaki, dzięki czemu pliki pozostają małe). Macierz obsługi czcionek wymienia każdy format czcionki akceptowany przez silnik.

Utwórz 02-fonts.php obok pierwszego skryptu:

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

Uruchom go poleceniem php 02-fonts.php i otwórz out/font-sampler.pdf. Zobaczysz, jak to samo przykładowe zdanie zmienia charakter między dwiema rodzinami i rośnie w trzech kolejnych rozmiarach.

Co się właśnie stało

addPage() bez argumentów użyło domyślnej konfiguracji strony w orientacji pionowej, więc nie każdy skrypt musi wprost podawać rozmiar. Każde wywołanie setFont() zmieniało aktywną rodzinę, styl lub rozmiar w trakcie strony, a czcionka pozostaje aktywna aż do następnego wywołania setFont().

Pętle rzutują rozmiar za pomocą (float), ponieważ setFont() oczekuje liczby dziesiętnej. Wysokości wierszy skalują się wraz z rozmiarem czcionki ($size * 0.8), więc większy tekst otrzymuje wyższe wiersze i nic się nie nakłada. Spróbuj zastąpić 'times' przez 'courier' i uruchom skrypt ponownie, aby zobaczyć trzecią rodzinę.

Jeśli coś poszło nie tak

• Błąd „class not found” lub błąd autoloadera zwykle oznacza, że skrypt nie znalazł vendor/autoload.php. Uruchom go w folderze projektu, który zawiera vendor/.
• Błędnie wpisana nazwa rodziny powoduje zgłoszenie wyjątku, który podaje nazwę czcionki, której nie udało się znaleźć. Sprawdź pisownię: helvetica, times, courier.
• Centrum rozwiązywania problemów gromadzi typowe rozwiązania, a Czcionki i tagowanie szczegółowo omawia problemy z czcionkami.
• Każdy wyjątek silnika jest udokumentowany w dokumentacji błędów, wraz z przenoszonym kontekstem i działaniem naprawczym.

Dalej

Potrafisz już kształtować strony, formatować tekst i świadomie wybierać czcionki. W następnym samouczku umieścisz obrazy na stronie i uporządkujesz treść za pomocą tabel i list.