Compatibilidad con el modelado de sistemas de escritura complejos

De un vistazo

Vista previa opcional. El modelado de sistemas de escritura complejos está desactivado por defecto. Cuando está desactivado, el motor representa a través de la ruta existente de punto de código a cmap —idéntico byte a byte a una compilación sin la característica—. Actívelo solo cuando tenga libharfbuzz y una fuente con capacidad de modelado, y valide el resultado.

El renderizador de HTML añade un modelador de sistemas de escritura complejos opcional para tibetano y mongol. Cuando el modelador está activado, una secuencia tibetana o mongola dentro del alcance que se detecte se modela a través de libharfbuzz y se emite como códigos de glifo Identity-H. El modelador cubre el tibetano horizontal en caras TrueType y CFF/OTTO, incluido el ajuste de línea, y el mongol vertical dispuesto de arriba abajo (TTB).

Instalación

composer require nextpdf/core:^3

El modelador se incluye en el paquete core. La opción CssFeatureFlags::$complexTextShaping es @since 6.1.0. libharfbuzz es un requisito de tiempo de ejecución cuando el indicador está activado: el modelador llama a libharfbuzz a través de la extensión FFI de PHP. Cuando el indicador está desactivado, la biblioteca no tiene ninguna dependencia de libharfbuzz.

Panorama conceptual

Los sistemas de escritura complejos reordenan, sustituyen y reposicionan glifos según el contexto. Una asignación ingenua de punto de código a glifo los representa visiblemente mal. El modelador entrega una secuencia dentro del alcance a libharfbuzz, que aplica las tablas de modelado OpenType de la fuente, y el motor emite la secuencia de glifos resultante como una fuente compuesta Type 0 con codificación Identity-H (ISO 32000-2 §9.7.4: la cadena mostrada son CID de dos bytes).

El alcance es deliberado. El modelador reconoce las secuencias en tibetano y mongol y las modela; no reclama cobertura general de sistemas de escritura complejos. El tibetano horizontal se modela en caras TrueType y CFF/OTTO, con ajuste de línea. El mongol se modela verticalmente, de arriba abajo.

Límite de cierre seguro — firme y tipado

El modelador nunca emite como repliegue glifos sin modelar y visualmente rotos. Una secuencia que no puede modelarse con fidelidad lanza en su lugar una excepción tipada:

• ComplexScriptShapingException: la secuencia no puede modelarse con fidelidad: a la fuente le faltan los glifos necesarios (resultaría un .notdef), se le pide a una cara CFF que modele en la ruta vertical, la secuencia contiene un enlace, o una columna mongola necesita ajuste de línea (un caso fuera de alcance).
• HarfBuzzUnavailableException: el indicador está activado pero libharfbuzz no es accesible a través de FFI en tiempo de ejecución.

Con el indicador desactivado, una secuencia dentro del alcance se representa a través de la ruta existente de punto de código a cmap. Eso es una limitación documentada, no una reclamación de modelado: la ruta desactivada no aplica el modelado OpenType, por lo que las formas contextuales no están garantizadas. No describa la salida de la ruta desactivada como “modelada”.

Límite de honestidad — paridad objetiva, no aprobación estética

La fidelidad del modelado se valida objetivamente frente a HarfBuzz: los identificadores de glifo emitidos, la asignación de clústeres y las posiciones de los glifos coinciden con la salida de referencia de HarfBuzz (paridad de glifo, clúster y posición). Una revisión estética por un hablante nativo —que juzgue si el resultado se lee de forma natural para un lector fluido— es un seguimiento posterior al lanzamiento ya registrado. NextPDF no hace ninguna reclamación de calidad lingüística en esta API ni en esta documentación. Se afirma la paridad objetiva; la calidad estética no.

Superficie de la API

Símbolo	Ubicación	Función
CssFeatureFlags::$complexTextShaping	src/Html/CssFeatureFlags.php	Indicador opcional para el modelador tibetano/mongol (false por defecto).
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Adjunta el conjunto de indicadores a la configuración de un documento.
ComplexScriptShapingException	src/Font/Shaper/ComplexScriptShapingException.php	Se lanza cuando una secuencia dentro del alcance no puede modelarse con fidelidad.
HarfBuzzUnavailableException	src/Font/Shaper/HarfBuzzUnavailableException.php	Se lanza cuando el indicador está activado pero libharfbuzz no está disponible.

Ejemplo de código — Inicio 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(complexTextShaping: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>',
);
$doc->save(__DIR__ . '/tibetan.pdf');

Ejemplo de código — Producción

Registre una fuente con capacidad de modelado, opte por el modelador y maneje los dos modos de fallo tipados de forma explícita. Una representación fiel o una excepción clara, nunca una secuencia de glifos rota en silencio.

<?php

declare(strict_types=1);

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

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

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

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

$factory = new DocumentFactory($fontRegistry, new ImageRegistry(maxCacheBytes: 0));
$doc = $factory->create($config);
$doc->setLanguage('bo');
$doc->addPage();

try {
    $doc->writeHtml('<div style="font-family: NotoSerifTibetan;">བོད་སྐད་</div>');
} catch (HarfBuzzUnavailableException $e) {
    // The flag is on but libharfbuzz is not reachable. Install it, or turn the
    // flag off to fall back to the unshaped cmap path.
    throw $e;
} catch (ComplexScriptShapingException $e) {
    // The run cannot be shaped faithfully (missing glyphs, link in run,
    // out-of-scope case). Fix the font or the content; do not ship broken glyphs.
    throw $e;
}

$doc->save($out);

Casos límite y trampas

• libharfbuzz es obligatorio cuando está activado. Con el indicador activado y libharfbuzz ausente, el motor lanza HarfBuzzUnavailableException. No se degrada en silencio.
• Desactivado no es “modelado”. Con el indicador desactivado, una secuencia dentro del alcance se representa a través de la ruta cmap sin modelado OpenType. Esto es una limitación documentada; no lo llame salida modelada.
• El alcance es tibetano y mongol. Otros sistemas de escritura complejos quedan fuera del alcance de esta porción.
• Un enlace en la secuencia se cierra de forma segura. Una secuencia que contiene una anotación de enlace lanza ComplexScriptShapingException, porque el rectángulo del enlace no puede seguir el reordenamiento del modelado.
• Ninguna reclamación de calidad lingüística. Se afirma la paridad con HarfBuzz; la calidad estética para un hablante nativo es un seguimiento registrado y no se reclama.

Rendimiento

El modelado añade una llamada a libharfbuzz por secuencia dentro del alcance, más la pasada de emisión de glifos, lineal en el recuento de glifos. El presupuesto (wall_ms: 2000, peak_mb: 128) sigue el perfil CJK/de sistemas de escritura complejos, porque las fuentes de modelado son grandes y el manejo de fuentes domina el coste.

Notas de seguridad

Habilitar el modelador introduce una llamada FFI a libharfbuzz, una biblioteca nativa. Los archivos de fuente siguen siendo entrada binaria no confiable manejada por la validación existente de la capa de tipografía antes de llegar al modelador. El modelador consume caras ya registradas y ya validadas. Trate la procedencia de las fuentes proporcionadas por el usuario final como no confiable, y aprovisione libharfbuzz desde una fuente de confianza.

Conformidad

Afirmación	Especificación	Cláusula
Las secuencias modeladas se emiten como CID Identity-H de dos bytes en una fuente compuesta Type 0.	ISO 32000-2	§9.7.4
El modelador aplica la sustitución y el posicionamiento de glifos OpenType de la fuente.	OpenType Specification	GSUB / GPOS
La formación de clústeres sigue las propiedades de sistema de escritura del tibetano y el mongol.	Unicode Standard Annex	Tibetan and Mongolian

Esta es una implementación de vista previa acotada al tibetano y el mongol, validada para la paridad objetiva con HarfBuzz. No hace ninguna reclamación de calidad lingüística y no afirma ninguna conformidad PDF de extremo a extremo para el archivo producido. No se reproduce ningún texto de las normas.

Consulte también

• Subsistema de representación de HTML
• Módulo de tipografía
• Composición de líneas en modo de escritura vertical
• Matriz de compatibilidad de CSS