Obsługa pionowego pisma CJK

W skrócie

Opcjonalny podgląd. Kompozytor pionowy jest domyślnie wyłączony. Gdy jest wyłączony, silnik renderuje poziomo dokładnie jak wcześniej — bajtowo identycznie. Włączaj go tylko dla dokumentów wymagających prawdziwych wierszy pionowych i waliduj wynik.

Renderer HTML dodaje prawdziwy kompozytor pionowych wierszy dla pionowych trybów pisma CSS writing-mode: vertical-lr i writing-mode: vertical-rl. Gdy kompozytor jest włączony, glify układają się z góry na dół, z rozmieszczeniem każdego glifu opartym na prawdziwych metrykach pionowych czcionki (tablice vhea i vmtx), zgodnie z modelem pisma pionowego PDF opisanym w ISO 32000-2 §9.7.5. Obsługiwane są oba pionowe kierunki przepływu blokowego.

Instalacja

composer require nextpdf/core:^3

Kompozytor jest dostarczany w pakiecie core. Opcja CssFeatureFlags::$layoutVerticalComposer to @since 6.1.0. Wersja silnika pozostaje bez zmian; funkcja jest addytywna i domyślnie wyłączona.

Przegląd koncepcyjny

Komponowanie pionowe włącza się tylko wtedy, gdy ustawione są zarówno layoutVerticalLr, jak i layoutVerticalComposer. Przy ich włączeniu ciąg vertical-lr lub vertical-rl komponuje się jako prawdziwy wiersz pionowy: każdy glif jest rozmieszczany według swojego pionowego rozsunięcia z metryk vhea/vmtx czcionki, a glify, które UAX #50 oznacza jako pionowe, pozostają pionowe. vertical-lr układa kolumny od lewej do prawej; vertical-rl układa kolumny od prawej do lewej.

Różni się to od fasady kodowania świadomej cmap udokumentowanej w Składaniu tekstu CJK z kodowaniem świadomym cmap, która dowodzi ścieżki kodowania, ale sama nie steruje pionowym trybem pisma. Ta strona dokumentuje kompozytor po stronie układu, który włącza opcja trybu pisma.

Granica fail-closed — kiedy komponuje, a co robi w przeciwnym razie

Kompozytor jest z założenia zachowawczy. Komponuje ciąg pionowo tylko wtedy, gdy każdy glif w ciągu jest pionowy według UAX #50 i ma prawdziwe metryki pionowe, w ciągu nie ma otwartego łącza, a ciąg jest pojedynczą kolumną. Gdy któryś z tych warunków nie jest spełniony — flaga jest wyłączona albo ciągu nie da się skomponować wiernie — silnik wraca do układu poziomego i emituje diagnostykę odroczenia dopasowaną do trybu:

• HTML_WRITING_MODE_LR_DEFERRED dla ciągu vertical-lr, którego nie dało się skomponować.
• HTML_WRITING_MODE_RL_DEFERRED dla ciągu vertical-rl, którego nie dało się skomponować.

Każda diagnostyka niesie reason, dzięki czemu odroczenie jest obserwowalne i wyjaśnialne, a nigdy nie jest cichym poziomym renderowaniem tekstu, który autor chciał złożyć pionowo.

Udokumentowane granice (późniejsze warstwy)

Te przypadki są poza zakresem bieżącej warstwy i są śledzone do dalszej pracy:

• Obrócone (niepionowe) glify wewnątrz pionowego ciągu.
• Wielokolumnowe zawijanie pionowe.
• Pionowe prostokąty łączy (łącze wewnątrz pionowego ciągu odracza ten ciąg).
• W korpusie testowym nie ma dołączonej osadzonej czcionki CJK z metrykami pionowymi, więc wizualna kontrola krzyżowa jest śledzona, a nie potwierdzana dołączonym wzorcem golden.

Powierzchnia API

Symbol	Lokalizacja	Rola
CssFeatureFlags::$layoutVerticalComposer	src/Html/CssFeatureFlags.php	Opcjonalna flaga kompozytora pionowych wierszy (domyślnie false).
CssFeatureFlags::$layoutVerticalLr	src/Html/CssFeatureFlags.php	Bramka dla vertical-lr; obie muszą być włączone, aby komponować.
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Dołącza zestaw flag do konfiguracji dokumentu.

Kody diagnostyk odroczenia HTML_WRITING_MODE_LR_DEFERRED i HTML_WRITING_MODE_RL_DEFERRED wypływają przez kanał doradczy wyniku renderowania.

Przykład kodu — szybki start

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    layoutVerticalLr: true,
    layoutVerticalComposer: true,
));

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<div style="writing-mode: vertical-rl; font-family: NotoSerifJP;">'
    . '日本語の縦書き'
    . '</div>',
);
$doc->save(__DIR__ . '/vertical.pdf');

Ciąg, którego nie da się skomponować wiernie, renderuje się poziomo i dodaje ostrzeżenie HTML_WRITING_MODE_RL_DEFERRED z reason. Sprawdź kanał doradczy, zanim potraktujesz wynik pionowy jako ostateczny.

Przykład kodu — produkcja

Zarejestruj czcionkę niosącą prawdziwe metryki pionowe przez DocumentFactory, tak aby kompozytor mógł odczytać vhea/vmtx, a następnie włącz kompozytor dla dokumentu.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\DocumentFactory;
use NextPDF\Graphics\ImageRegistry;
use NextPDF\Html\Css\CssFeatureFlags;
use NextPDF\Typography\FontRegistry;

$fontRegistry = new FontRegistry();
$fontRegistry->register('/path/to/NotoSerifJP-Regular.otf', alias: 'NotoSerifJP');

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    layoutVerticalLr: true,
    layoutVerticalComposer: true,
));

$factory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $factory->create($config);
$doc->setLanguage('ja');
$doc->addPage();
$doc->writeHtml(
    '<div style="writing-mode: vertical-rl; font-family: NotoSerifJP;">'
    . '縦書きの本文。'
    . '</div>',
);
$doc->save($out);

Przypadki brzegowe i pułapki

• Wymagane są obie flagi. Kompozytor potrzebuje layoutVerticalLr i layoutVerticalComposer. Przy którejkolwiek wyłączonej ciąg renderuje się poziomo.
• Wymagane są prawdziwe metryki pionowe. Czcionka bez vhea/vmtx nie może napędzać kompozytora; ciąg odracza się do układu poziomego.
• Odroczenie jest obserwowalne. Ciąg, którego nie da się skomponować, emituje HTML_WRITING_MODE_LR_DEFERRED / HTML_WRITING_MODE_RL_DEFERRED z reason. Nigdy nie renderuje po cichu w bok.
• Brak twierdzenia o zgodności z tej ścieżki. Komponowanie pionowe to zdolność układu; nie jest to twierdzenie o zgodności z PDF/UA-2 ani PDF/A-4 dla wytworzonego pliku. O zgodności decyduje walidator.

Wydajność

Komponowanie dodaje wyszukanie pionowego rozsunięcia dla każdego glifu w ciągu, liniowo względem liczby glifów. Budżet (wall_ms: 2000, peak_mb: 128) podąża za profilem CJK, ponieważ czcionki z metrykami pionowymi są duże, a dominującym kosztem jest obsługa czcionek, a nie przebieg komponowania.

Uwagi dotyczące bezpieczeństwa

Kompozytor odczytuje metryki pionowe z już zarejestrowanych, już zweryfikowanych czcionek. Nie otwiera nowego kanału wejściowego. Pliki czcionek pozostają niezaufanym wejściem binarnym obsługiwanym przez istniejącą walidację warstwy typografii. Skomponowany tekst jest renderowany, a nie interpretowany.

Zgodność

Twierdzenie	Norma	Klauzula
Pismo pionowe używa pionowych metryk glifów CIDFont do rozmieszczania.	ISO 32000-2	§9.7.5
writing-mode: vertical-lr / vertical-rl ustawiają kierunek przepływu blokowego.	W3C CSS Writing Modes Level 3	§3
Pionowa orientacja każdego glifu podąża za właściwością vertical-orientation Unicode.	Unicode UAX #50	Vertical Orientation

To podglądowa implementacja jednokolumnowego, pionowego podzbioru pisma stojącego z udokumentowanymi powyżej granicami fail-closed. NextPDF nie twierdzi, że wynik z tej ścieżki jest zgodny z jakimkolwiek profilem; o tym rozstrzyga walidator. Nie odtwarza się żadnego tekstu normatywnego.

Zobacz także

• Składanie tekstu CJK z kodowaniem świadomym cmap
• Podsystem renderowania HTML
• Moduł typografii
• Kształtowanie pism złożonych (tybetańskie i mongolskie)
• Macierz wsparcia CSS