Unterstützung für vertikale CJK-Schreibrichtung

Auf einen Blick

Per Opt-in aktivierbare Vorschau. Der vertikale Kompositor ist standardmäßig aus. Ist er aus, rendert die Engine horizontal genau wie zuvor — byte-identisch. Schalten Sie ihn nur für die Dokumente ein, die echte vertikale Zeilen benötigen, und validieren Sie das Ergebnis.

Der HTML-Renderer ergänzt einen echten vertikalen Zeilenkompositor für die CSS-Writing-Modes writing-mode: vertical-lr und writing-mode: vertical-rl. Ist der Kompositor aktiv, stapeln sich Glyphen von oben nach unten, wobei die Platzierung pro Glyphe aus den echten vertikalen Metriken der Schrift (den Tabellen vhea und vmtx) entnommen wird, wie das PDF-Vertikalschreibmodell in ISO 32000-2 §9.7.5 beschreibt. Beide vertikalen Block-Fluss-Richtungen werden unterstützt.

Installation

composer require nextpdf/core:^3

Der Kompositor wird im Core-Paket ausgeliefert. Das Opt-in CssFeatureFlags::$layoutVerticalComposer ist @since 6.1.0. Die Engine-Version bleibt unverändert; die Funktion ist additiv und standardmäßig aus.

Konzeptioneller Überblick

Die vertikale Komposition wird nur aktiv, wenn sowohl layoutVerticalLr als auch layoutVerticalComposer gesetzt sind. Sind sie aktiv, komponiert ein vertical-lr- oder vertical-rl-Run als echte vertikale Zeile: Jede Glyphe wird durch ihren vertikalen Vorschub aus den vhea/vmtx-Metriken der Schrift platziert, und Glyphen, die UAX #50 als aufrecht kennzeichnet, werden aufrecht gehalten. vertical-lr legt Spalten von links nach rechts an; vertical-rl legt Spalten von rechts nach links an.

Dies unterscheidet sich von der cmap-bewussten Encoding-Fassade, die in CJK-Text mit cmap-bewusstem Encoding setzen dokumentiert ist und den Encoding-Pfad nachweist, aber selbst keinen vertikalen Writing-Mode antreibt. Diese Seite dokumentiert den Layout-seitigen Kompositor, den das Writing-Mode-Opt-in aktiviert.

Fail-closed-Grenze — wann er komponiert und was er andernfalls tut

Der Kompositor ist von Entwurf wegen konservativ. Er komponiert einen Run nur dann vertikal, wenn jede Glyphe im Run gemäß UAX #50 aufrecht ist und über echte vertikale Metriken verfügt, kein offener Link innerhalb des Runs liegt und der Run eine einzelne Spalte ist. Wenn eines davon nicht zutrifft — das Flag ist aus oder ein Run kann nicht originalgetreu komponiert werden —, fällt die Engine auf horizontales Layout zurück und gibt eine zum Modus passende Deferred-Diagnose aus:

• HTML_WRITING_MODE_LR_DEFERRED für einen vertical-lr-Run, der nicht komponiert werden konnte.
• HTML_WRITING_MODE_RL_DEFERRED für einen vertical-rl-Run, der nicht komponiert werden konnte.

Jede Diagnose trägt einen reason, sodass eine Zurückstellung beobachtbar und erklärbar ist — niemals ein stilles horizontales Rendern von Text, den der Autor vertikal gesetzt haben wollte.

Dokumentierte Grenzen (spätere Teilmengen)

Diese Fälle liegen außerhalb des Umfangs der aktuellen Teilmenge und werden für spätere Arbeiten nachgehalten:

• Rotierte (nicht aufrechte) Glyphen innerhalb eines vertikalen Runs.
• Mehrspaltiger vertikaler Umbruch.
• Vertikale Link-Rechtecke (ein Link innerhalb eines vertikalen Runs stellt den Run zurück).
• Es gibt im Test-Korpus kein gebündeltes CJK-Schrift-Fixture mit vertikalen Metriken, sodass der visuelle Cross-Check nachgehalten und nicht durch ein gebündeltes Golden zugesichert wird.

API-Oberfläche

Symbol	Ort	Rolle
CssFeatureFlags::$layoutVerticalComposer	src/Html/CssFeatureFlags.php	Opt-in-Flag für den vertikalen Zeilenkompositor (Standard false).
CssFeatureFlags::$layoutVerticalLr	src/Html/CssFeatureFlags.php	Gate für vertical-lr; beide müssen aktiv sein, um zu komponieren.
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Hängt das Flag-Set an eine Dokumentkonfiguration an.

Die Deferred-Diagnose-Codes HTML_WRITING_MODE_LR_DEFERRED und HTML_WRITING_MODE_RL_DEFERRED treten über den Advisory-Kanal des Render-Ergebnisses zutage.

Codebeispiel — Schnellstart

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

Ein Run, der nicht originalgetreu komponiert werden kann, rendert horizontal und fügt eine HTML_WRITING_MODE_RL_DEFERRED-Meldung mit einem reason hinzu. Prüfen Sie den Advisory-Kanal, bevor Sie vertikale Ausgabe als final behandeln.

Codebeispiel — Produktion

Registrieren Sie über DocumentFactory eine Schrift, die echte vertikale Metriken trägt, sodass der Kompositor vhea/vmtx lesen kann, und aktivieren Sie dann für das Dokument den Kompositor.

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

Randfälle & Fallstricke

• Beide Flags sind erforderlich. Der Kompositor benötigt layoutVerticalLr und layoutVerticalComposer. Ist eines aus, rendert der Run horizontal.
• Echte vertikale Metriken sind erforderlich. Eine Schrift ohne vhea/vmtx kann den Kompositor nicht antreiben; der Run stellt auf horizontales Layout zurück.
• Die Zurückstellung ist beobachtbar. Ein Run, der nicht komponiert werden kann, gibt HTML_WRITING_MODE_LR_DEFERRED / HTML_WRITING_MODE_RL_DEFERRED mit einem reason aus. Er rendert nie stillschweigend seitwärts.
• Keine Konformitätsaussage aus diesem Pfad. Die vertikale Komposition ist eine Layout-Fähigkeit; sie ist keine PDF/UA-2- oder PDF/A-4-Konformitätsaussage für die erzeugte Datei. Ein Prüfer entscheidet über die Konformität.

Performance

Die Komposition fügt eine Suche des vertikalen Vorschubs pro Glyphe über den Run hinzu, linear in der Glyphenzahl. Das Budget (wall_ms: 2000, peak_mb: 128) folgt dem CJK-Profil, da Schriften mit vertikalen Metriken groß sind und die Schriftverarbeitung der dominierende Kostenfaktor ist, nicht der Kompositionsdurchlauf.

Sicherheitshinweise

Der Kompositor liest vertikale Metriken aus bereits registrierten, bereits validierten Schriften. Er öffnet keinen neuen Eingabekanal. Schriftdateien bleiben nicht vertrauenswürdige Binäreingabe, die von der bestehenden Validierung der Typografieschicht verarbeitet wird. Komponierter Text wird gerendert, nicht interpretiert.

Konformität

Aussage	Standard	Klausel
Vertikales Schreiben nutzt vertikale CIDFont-Glyphenmetriken zur Platzierung.	ISO 32000-2	§9.7.5
writing-mode: vertical-lr / vertical-rl setzen die Block-Fluss-Richtung.	W3C CSS Writing Modes Level 3	§3
Die aufrechte Orientierung pro Glyphe folgt der Unicode-Vertical-Orientation-Eigenschaft.	Unicode UAX #50	Vertical Orientation

Dies ist eine Vorschau-Implementierung einer einspaltigen, aufrechten vertikalen Teilmenge mit den oben dokumentierten Fail-closed-Grenzen. NextPDF behauptet nicht, dass die Ausgabe aus diesem Pfad einem Profil entspricht; ein Prüfer trifft diese Feststellung. Es wird kein Standardtext wiedergegeben.

Siehe auch

• CJK-Text mit cmap-bewusstem Encoding setzen
• HTML-Rendering-Subsystem
• Typografie-Modul
• Komplexschrift-Shaping (Tibetisch und Mongolisch)
• CSS-Support-Matrix