Dukungan penulisan vertikal CJK

Sekilas

Preview opt-in. Komposer vertikal default-mati. Saat mati, mesin merender secara horizontal persis seperti sebelumnya — byte-identik. Aktifkan hanya untuk dokumen yang membutuhkan baris vertikal sungguhan, dan validasi hasilnya.

Perender HTML menambahkan komposer baris vertikal sungguhan untuk mode penulisan CSS writing-mode: vertical-lr dan writing-mode: vertical-rl. Saat komposer aktif, glyph menumpuk dari atas ke bawah dengan penempatan per-glyph yang diambil dari metrik vertikal sungguhan font (tabel vhea dan vmtx), seperti yang dijelaskan model penulisan-vertikal PDF dalam ISO 32000-2 §9.7.5. Kedua arah aliran-blok vertikal didukung.

Pemasangan

composer require nextpdf/core:^3

Komposer disertakan dalam paket core. Opt-in CssFeatureFlags::$layoutVerticalComposer adalah @since 6.1.0. Versi mesin tidak berubah; fitur ini bersifat aditif dan default-mati.

Ikhtisar konseptual

Komposisi vertikal aktif hanya saat layoutVerticalLr dan layoutVerticalComposer keduanya disetel. Dengan keduanya aktif, sebuah run vertical-lr atau vertical-rl dikomposisikan sebagai baris vertikal sungguhan: setiap glyph ditempatkan menurut advance vertikalnya dari metrik vhea/vmtx font, dan glyph yang ditandai upright oleh UAX #50 dijaga tetap upright. vertical-lr menata kolom dari kiri ke kanan; vertical-rl menata kolom dari kanan ke kiri.

Ini berbeda dari fasad encoding cmap-aware yang didokumentasikan di Set teks CJK dengan encoding cmap-aware, yang membuktikan jalur encoding tetapi tidak dengan sendirinya menggerakkan mode penulisan vertikal. Halaman ini mendokumentasikan komposer sisi-tata-letak yang diaktifkan oleh opt-in mode-penulisan.

Batasan fail-closed — kapan ia mengomposisikan, dan apa yang dilakukannya selain itu

Komposer bersifat konservatif sesuai rancangan. Ia mengomposisikan sebuah run secara vertikal hanya saat setiap glyph dalam run bersifat upright UAX #50 dengan metrik vertikal sungguhan, tidak ada tautan terbuka di dalam run, dan run merupakan kolom tunggal. Saat salah satunya tidak terpenuhi — flag mati, atau sebuah run tidak dapat dikomposisikan secara setia — mesin kembali ke tata letak horizontal dan memancarkan diagnostik penangguhan yang cocok dengan mode:

• HTML_WRITING_MODE_LR_DEFERRED untuk run vertical-lr yang tidak dapat dikomposisikan.
• HTML_WRITING_MODE_RL_DEFERRED untuk run vertical-rl yang tidak dapat dikomposisikan.

Setiap diagnostik membawa sebuah reason, sehingga penangguhan dapat diamati dan dijelaskan, tidak pernah menjadi render horizontal diam dari teks yang penulis minta untuk disusun vertikal.

Batas terdokumentasi (irisan berikutnya)

Kasus-kasus ini berada di luar cakupan irisan saat ini dan dilacak untuk pekerjaan berikutnya:

• Glyph terotasi (non-upright) di dalam run vertikal.
• Pembungkusan vertikal multi-kolom.
• Persegi panjang tautan vertikal (sebuah tautan di dalam run vertikal menangguhkan run tersebut).
• Tidak ada fixture font CJK metrik-vertikal yang dibundel dalam korpus uji, sehingga pemeriksaan-silang visual dilacak alih-alih ditegaskan oleh golden yang dibundel.

Permukaan API

Simbol	Lokasi	Peran
CssFeatureFlags::$layoutVerticalComposer	src/Html/CssFeatureFlags.php	Flag opt-in untuk komposer baris vertikal (default false).
CssFeatureFlags::$layoutVerticalLr	src/Html/CssFeatureFlags.php	Gate untuk vertical-lr; keduanya harus aktif untuk mengomposisikan.
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Melampirkan kumpulan flag ke konfigurasi dokumen.

Kode diagnostik-penangguhan HTML_WRITING_MODE_LR_DEFERRED dan HTML_WRITING_MODE_RL_DEFERRED muncul melalui kanal advisory pada hasil render.

Contoh kode — Mulai cepat

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

Sebuah run yang tidak dapat dikomposisikan secara setia akan dirender horizontal dan menambahkan advisory HTML_WRITING_MODE_RL_DEFERRED dengan sebuah reason. Periksa kanal advisory sebelum memperlakukan keluaran vertikal sebagai final.

Contoh kode — Produksi

Daftarkan sebuah font yang membawa metrik vertikal sungguhan melalui DocumentFactory, sehingga komposer dapat membaca vhea/vmtx, lalu opt-in-kan dokumen ke komposer.

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

Kasus tepi & jebakan

• Kedua flag diperlukan. Komposer membutuhkan layoutVerticalLr dan layoutVerticalComposer. Dengan salah satunya mati, run dirender horizontal.
• Metrik vertikal sungguhan diperlukan. Sebuah font tanpa vhea/vmtx tidak dapat menggerakkan komposer; run ditangguhkan ke tata letak horizontal.
• Penangguhan dapat diamati. Sebuah run yang tidak dapat dikomposisikan memancarkan HTML_WRITING_MODE_LR_DEFERRED / HTML_WRITING_MODE_RL_DEFERRED dengan sebuah reason. Ia tidak pernah diam-diam merender menyamping.
• Tidak ada klaim konformitas dari jalur ini. Komposisi vertikal adalah kapabilitas tata letak; ia bukan pernyataan konformitas PDF/UA-2 atau PDF/A-4 untuk berkas yang dihasilkan. Sebuah checker yang memutuskan konformitas.

Kinerja

Komposisi menambahkan satu pencarian advance-vertikal per-glyph atas run, linear terhadap jumlah glyph. Anggaran (wall_ms: 2000, peak_mb: 128) mengikuti profil CJK, karena font metrik-vertikal berukuran besar dan biaya dominannya adalah penanganan font, bukan lintasan komposisi.

Catatan keamanan

Komposer membaca metrik vertikal dari font yang sudah terdaftar dan sudah divalidasi. Ia tidak membuka kanal masukan baru. Berkas font tetap merupakan masukan biner tak-tepercaya yang ditangani validasi yang sudah ada pada lapisan tipografi. Teks yang dikomposisikan dirender, bukan diinterpretasikan.

Konformitas

Pernyataan	Standar	Klausul
Penulisan vertikal memakai metrik glyph vertikal CIDFont untuk penempatan.	ISO 32000-2	§9.7.5
writing-mode: vertical-lr / vertical-rl menetapkan arah aliran-blok.	W3C CSS Writing Modes Level 3	§3
Orientasi upright per-glyph mengikuti properti orientasi-vertikal Unicode.	Unicode UAX #50	Vertical Orientation

Ini adalah implementasi preview dari subset vertikal upright kolom-tunggal dengan batasan fail-closed yang terdokumentasi di atas. NextPDF tidak menegaskan bahwa keluaran dari jalur ini konform terhadap profil apa pun; sebuah checker membuat penetapan itu. Tidak ada teks standar yang direproduksi.

Lihat juga

• Set teks CJK dengan encoding cmap-aware
• Subsistem rendering HTML
• Modul tipografi
• Shaping skrip-kompleks (Tibet dan Mongolia)
• Matriks dukungan CSS