Suporte a escrita vertical CJK

Visão geral

Pré-visualização opcional. O compositor vertical é desativado por padrão. Quando ele está desativado, o motor renderiza horizontalmente exatamente como antes — idêntico byte a byte. Ative-o somente para os documentos que precisam de linhas verticais reais e valide o resultado.

O renderizador HTML adiciona um compositor de linha vertical real para os modos de escrita CSS writing-mode: vertical-lr e writing-mode: vertical-rl. Quando o compositor está ativado, os glifos se empilham de cima para baixo com posicionamento por glifo tomado das métricas verticais reais da fonte (as tabelas vhea e vmtx), conforme descreve o modelo de escrita vertical PDF em ISO 32000-2 §9.7.5. Ambas as direções verticais de fluxo de bloco são suportadas.

Instalação

composer require nextpdf/core:^3

O compositor é entregue no pacote core. O recurso opcional CssFeatureFlags::$layoutVerticalComposer é @since 6.1.0. A versão do motor permanece inalterada; o recurso é aditivo e desativado por padrão.

Visão geral conceitual

A composição vertical é ativada somente quando tanto layoutVerticalLr quanto layoutVerticalComposer estão definidos. Com eles ativados, uma sequência vertical-lr ou vertical-rl é composta como uma linha vertical real: cada glifo é posicionado por seu avanço vertical a partir das métricas vhea/vmtx da fonte, e os glifos que a UAX #50 marca como verticais (upright) são mantidos verticais. vertical-lr dispõe colunas da esquerda para a direita; vertical-rl dispõe colunas da direita para a esquerda.

Isso difere da fachada de codificação ciente de cmap documentada em Compor texto CJK com codificação ciente de cmap, que comprova o caminho de codificação, mas não dirige por si só um modo de escrita vertical. Esta página documenta o compositor do lado do layout que o recurso opcional de writing-mode habilita.

Limite de falha fechada — quando compõe e o que faz em caso contrário

O compositor é conservador por projeto. Ele compõe uma sequência verticalmente somente quando todo glifo da sequência é vertical (upright) pela UAX #50 com métricas verticais reais, não há link aberto dentro da sequência e a sequência é uma única coluna. Quando algo disso não se verifica — a flag está desativada, ou uma sequência não pode ser composta fielmente — o motor recai para o layout horizontal e emite um diagnóstico de adiamento correspondente ao modo:

• HTML_WRITING_MODE_LR_DEFERRED para uma sequência vertical-lr que não pôde ser composta.
• HTML_WRITING_MODE_RL_DEFERRED para uma sequência vertical-rl que não pôde ser composta.

Cada diagnóstico carrega um reason, então um adiamento é observável e explicável, nunca uma renderização horizontal silenciosa de um texto que o autor pediu para compor verticalmente.

Limites documentados (fatias posteriores)

Estes casos estão fora do escopo da fatia atual e são acompanhados para trabalho posterior:

• Glifos rotacionados (não verticais) dentro de uma sequência vertical.
• Quebra de linha vertical em múltiplas colunas.
• Retângulos de link verticais (um link dentro de uma sequência vertical adia a sequência).
• Não há fixture de fonte CJK com métricas verticais incluída no corpus de testes, então a verificação cruzada visual é acompanhada em vez de afirmada por um golden incluído.

Superfície da API

Símbolo	Localização	Função
CssFeatureFlags::$layoutVerticalComposer	src/Html/CssFeatureFlags.php	Flag opcional para o compositor de linha vertical (padrão false).
CssFeatureFlags::$layoutVerticalLr	src/Html/CssFeatureFlags.php	Porta para vertical-lr; ambas devem estar ativadas para compor.
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Anexa o conjunto de flags a uma configuração de documento.

Os códigos de diagnóstico de adiamento HTML_WRITING_MODE_LR_DEFERRED e HTML_WRITING_MODE_RL_DEFERRED aparecem por meio do canal de advertências do resultado de renderização.

Exemplo de código — Início rápido

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

Uma sequência que não pode ser composta fielmente é renderizada horizontalmente e adiciona uma advertência HTML_WRITING_MODE_RL_DEFERRED com um reason. Inspecione o canal de advertências antes de tratar a saída vertical como definitiva.

Exemplo de código — Produção

Registre uma fonte que carregue métricas verticais reais por meio do DocumentFactory, para que o compositor possa ler vhea/vmtx, e então opte o documento para o compositor.

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

Casos extremos e pegadinhas

• Ambas as flags são obrigatórias. O compositor precisa de layoutVerticalLr e layoutVerticalComposer. Com qualquer uma desativada, a sequência é renderizada horizontalmente.
• Métricas verticais reais são obrigatórias. Uma fonte sem vhea/vmtx não pode dirigir o compositor; a sequência adia para o layout horizontal.
• O adiamento é observável. Uma sequência que não pode ser composta emite HTML_WRITING_MODE_LR_DEFERRED / HTML_WRITING_MODE_RL_DEFERRED com um reason. Ela nunca renderiza de lado silenciosamente.
• Nenhuma reivindicação de conformidade por este caminho. A composição vertical é uma capacidade de layout; não é uma declaração de conformidade PDF/UA-2 ou PDF/A-4 para o arquivo produzido. Um validador decide a conformidade.

Desempenho

A composição adiciona uma consulta de avanço vertical por glifo ao longo da sequência, linear na contagem de glifos. O orçamento (wall_ms: 2000, peak_mb: 128) segue o perfil CJK, porque as fontes com métricas verticais são grandes e o custo dominante é o manuseio da fonte, não a passada de composição.

Notas de segurança

O compositor lê métricas verticais de fontes já registradas e já validadas. Ele não abre um novo canal de entrada. Os arquivos de fonte permanecem como entrada binária não confiável tratada pela validação existente da camada de tipografia. O texto composto é renderizado, não interpretado.

Conformidade

Declaração	Especificação	Cláusula
A escrita vertical usa as métricas verticais de glifo de CIDFont para o posicionamento.	ISO 32000-2	§9.7.5
writing-mode: vertical-lr / vertical-rl definem a direção do fluxo de bloco.	W3C CSS Writing Modes Level 3	§3
A orientação vertical (upright) por glifo segue a propriedade vertical-orientation do Unicode.	Unicode UAX #50	Vertical Orientation

Esta é uma implementação de pré-visualização de um subconjunto vertical upright de coluna única com os limites de falha fechada documentados acima. O NextPDF não afirma que a saída deste caminho está em conformidade com qualquer perfil; um validador faz essa determinação. Nenhum texto de norma é reproduzido.

Consulte também

• Compor texto CJK com codificação ciente de cmap
• Subsistema de renderização HTML
• Módulo de tipografia
• Composição de scripts complexos (tibetano e mongol)
• Matriz de suporte CSS