Supporto della scrittura verticale CJK

In sintesi

Anteprima opt-in. Il compositore verticale è disattivato per impostazione predefinita. Quando è spento, il motore rende orizzontalmente esattamente come prima — byte-identico. Attivalo solo per i documenti che necessitano di vere righe verticali e convalida il risultato.

Il renderer HTML aggiunge un vero compositore di riga verticale per le modalità di scrittura CSS writing-mode: vertical-lr e writing-mode: vertical-rl. Quando il compositore è attivo, i glifi si impilano dall’alto verso il basso con la collocazione per glifo presa dalle metriche verticali reali del font (le tabelle vhea e vmtx), come descrive il modello di scrittura verticale PDF in ISO 32000-2 §9.7.5. Entrambe le direzioni di block-flow verticale sono supportate.

Installazione

composer require nextpdf/core:^3

Il compositore è incluso nel pacchetto core. L’opt-in CssFeatureFlags::$layoutVerticalComposer è @since 6.1.0. La versione del motore è invariata; la funzionalità è additiva e disattivata per impostazione predefinita.

Panoramica concettuale

La composizione verticale si attiva solo quando sono impostati sia layoutVerticalLr sia layoutVerticalComposer. Con entrambi attivi, un tratto vertical-lr o vertical-rl si compone come una vera riga verticale: ogni glifo è collocato in base al suo avanzamento verticale dalle metriche vhea/vmtx del font, e i glifi che UAX #50 contrassegna come dritti vengono mantenuti dritti. vertical-lr dispone le colonne da sinistra a destra; vertical-rl dispone le colonne da destra a sinistra.

Questo differisce dalla facciata di codifica cmap-aware documentata in Impostare testo CJK con codifica cmap-aware, che dimostra il percorso di codifica ma non guida di per sé una modalità di scrittura verticale. Questa pagina documenta il compositore lato layout che l’opt-in del writing-mode abilita.

Confine fail-closed — quando compone e cosa fa altrimenti

Il compositore è conservativo per progettazione. Compone un tratto verticalmente solo quando ogni glifo nel tratto è dritto secondo UAX #50 con metriche verticali reali, non c’è alcun link aperto all’interno del tratto e il tratto è una singola colonna. Quando una di queste condizioni non vale — il flag è spento, o un tratto non può essere composto fedelmente — il motore ricade nel layout orizzontale ed emette una diagnostica di rinvio corrispondente alla modalità:

• HTML_WRITING_MODE_LR_DEFERRED per un tratto vertical-lr che non è stato possibile comporre.
• HTML_WRITING_MODE_RL_DEFERRED per un tratto vertical-rl che non è stato possibile comporre.

Ogni diagnostica porta un reason, quindi un rinvio è osservabile e spiegabile, mai un render orizzontale silenzioso di testo che l’autore ha chiesto di impostare verticalmente.

Confini documentati (fette successive)

Questi casi sono fuori ambito per la fetta attuale e sono tracciati per un lavoro successivo:

• Glifi ruotati (non dritti) all’interno di un tratto verticale.
• A capo verticale su più colonne.
• Rettangoli di link verticali (un link all’interno di un tratto verticale rinvia il tratto).
• Non c’è un fixture di font CJK con metriche verticali incluso nel corpus di test, perciò il controllo incrociato visivo è tracciato anziché asserito da un golden incluso.

Superficie API

Simbolo	Posizione	Ruolo
CssFeatureFlags::$layoutVerticalComposer	src/Html/CssFeatureFlags.php	Flag opt-in per il compositore di riga verticale (predefinito false).
CssFeatureFlags::$layoutVerticalLr	src/Html/CssFeatureFlags.php	Gate per vertical-lr; entrambi devono essere attivi per comporre.
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Collega l’insieme di flag alla configurazione di un documento.

I codici di diagnostica di rinvio HTML_WRITING_MODE_LR_DEFERRED e HTML_WRITING_MODE_RL_DEFERRED emergono attraverso il canale di avviso del risultato di render.

Esempio di codice — Avvio rapido

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

Un tratto che non può essere composto fedelmente viene reso orizzontalmente e aggiunge un avviso HTML_WRITING_MODE_RL_DEFERRED con un reason. Ispeziona il canale di avviso prima di considerare definitivo l’output verticale.

Esempio di codice — Produzione

Registra un font che porta metriche verticali reali tramite DocumentFactory, affinché il compositore possa leggere vhea/vmtx, poi fai optare il documento nel compositore.

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

Casi limite e insidie

• Entrambi i flag sono richiesti. Il compositore necessita di layoutVerticalLr e layoutVerticalComposer. Con uno dei due spento, il tratto viene reso orizzontalmente.
• Sono richieste metriche verticali reali. Un font senza vhea/vmtx non può guidare il compositore; il tratto viene rinviato al layout orizzontale.
• Il rinvio è osservabile. Un tratto che non può comporre emette HTML_WRITING_MODE_LR_DEFERRED / HTML_WRITING_MODE_RL_DEFERRED con un reason. Non rende mai silenziosamente di lato.
• Nessuna rivendicazione di conformità da questo percorso. La composizione verticale è una capacità di layout; non è una dichiarazione di conformità PDF/UA-2 o PDF/A-4 per il file prodotto. È un checker a decidere la conformità.

Prestazioni

La composizione aggiunge una ricerca di avanzamento verticale per glifo sul tratto, lineare nel conteggio dei glifi. Il budget (wall_ms: 2000, peak_mb: 128) segue il profilo CJK, perché i font con metriche verticali sono grandi e il costo dominante è la gestione del font, non il passaggio di composizione.

Note sulla sicurezza

Il compositore legge le metriche verticali da font già registrati e già convalidati. Non apre un nuovo canale di input. I file di font restano input binario non attendibile gestito dalla convalida esistente del livello tipografico. Il testo composto viene reso, non interpretato.

Conformità

Affermazione	Standard	Clausola
La scrittura verticale usa le metriche verticali dei glifi CIDFont per la collocazione.	ISO 32000-2	§9.7.5
writing-mode: vertical-lr / vertical-rl impostano la direzione di block-flow.	W3C CSS Writing Modes Level 3	§3
L’orientamento dritto per glifo segue la proprietà Unicode vertical-orientation.	Unicode UAX #50	Vertical Orientation

Questa è un’implementazione di anteprima di un sottoinsieme verticale dritto a singola colonna con i confini fail-closed documentati sopra. NextPDF non asserisce che l’output di questo percorso sia conforme ad alcun profilo; è un checker a stabilirlo. Nessun testo normativo è riprodotto.

Vedere anche

• Impostare testo CJK con codifica cmap-aware
• Sottosistema di rendering HTML
• Modulo Typography
• Shaping di script complessi (tibetano e mongolo)
• Matrice di supporto CSS