Una plantilla de factura compuesta en Arial imprime «Invoice for» y después nada. La llamada de texto devolvió 1, el archivo validó, y la extracción de texto venía diez caracteres corta: todos los caracteres Han de 北京示例科技有限公司 habían desaparecido, porque Arial no tiene ninguno de ellos. La reserva automática de fuentes en PDF Library for Delphi está activa por defecto y saca esos caracteres de tipografías instaladas, AddFontFallback define tu propio orden de búsqueda, y una política de glifos faltantes con informe JSON se encarga de lo que ninguna fuente pueda dibujar
Lo silencioso es lo que hace esto caro. Un PDF con un blanco donde debería estar el nombre de una parte pasa todas las comprobaciones estructurales, se abre en todos los visores, y normalmente lo nota el cliente en lugar de tu suite de tests
¿Por qué desaparece el texto no soportado en lugar de dar un error?
PDF no tiene concepto de una fuente que se niegue a dibujar un carácter, así que un glifo faltante no es un error a nivel de archivo. Una fuente simple asigna códigos de un byte a nombres de glifo mediante una codificación; una fuente compuesta asigna códigos a CIDs a través de un CMap y de ahí a índices de glifo. Pide a una tipografía algo que no contiene y acabas en el índice de glifo cero, .notdef, que la ISO 32000-1 §9.7.6.3 trata como el resultado estándar para caracteres indefinidos. La mayoría de las fuentes dibujan .notdef como nada. Algunas dibujan una caja vacía
En cualquier caso el content stream está bien formado y la página se renderiza. Nada en la especificación pide a un productor que compruebe la cobertura antes de escribir un operador de texto, así que un generador que se salta la comprobación produce un archivo conforme que ha perdido contenido en silencio. Por eso la reserva y el informe van juntos. Resolver lo que se puede resolver es la mitad del trabajo; avisarte de lo demás es la otra mitad, y a nuestro juicio la más importante para cualquier cosa que lleve un nombre o un importe encima
Activar la cadena de reserva en PDF Library for Delphi
La reserva solo entra en juego cuando la fuente seleccionada de verdad no tiene un carácter de la cadena, así que el texto solo latino mantiene su camino normal y no cuesta nada extra. Una instancia nueva de TPDFlib ya tiene la reserva automática activada, así que el código de dibujo no necesita ninguna llamada adicional:
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create;
try
// La reserva automática está activa por defecto: emoji, kana, Hangul,
// Han y símbolos se buscan en una tabla de candidatos incorporada
Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);
Lib.AddTrueTypeFont('Arial', 2); // 2 = incrustar como subconjunto
Lib.SetTextSize(11);
Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
Lib.DrawText(72, 700, 'Delivery status: on time ✅');
Lib.SaveToFile('invoice.pdf');
finally
Lib.Free;
end;
end;
Con la reserva automática activada, la biblioteca elige candidatos por la escritura de cada carácter sin resolver. La tabla es fija y está orientada a Windows: los emoji y pictogramas prueban Segoe UI Emoji, luego Segoe UI Symbol y luego Arial Unicode MS; el kana prueba primero Yu Gothic; el Hangul prueba primero Malgun Gothic; el bloque Han unificado prueba Microsoft YaHei, luego Microsoft JhengHei, Yu Gothic, Malgun Gothic y SimSun; los símbolos matemáticos y técnicos van a Segoe UI Symbol y Cambria Math. Todo lo demás cae en una lista amplia que empieza por Nirmala UI y Segoe UI
Las tipografías que registras con AddFontFallback se prueban antes de esa tabla incorporada, en el orden en que las añadiste. SetAutomaticFontFallback(0) apaga solo la tabla incorporada: la cadena explícita sigue activa, que es la opción a elegir cuando quieres que la salida use tus fuentes aprobadas y nada más. AddFontFallback ignora un nombre que ya está en la lista y devuelve su posición base 1, y ClearFontFallbacks, RemoveFontFallback y GetFontFallbackCount te permiten reconstruir la cadena entre documentos
La trampa de la unificación Han: ¿quién se lleva los caracteres compartidos?
Chino, japonés y coreano comparten la mayoría de los ideogramas Han de Unicode, pero cada locale espera formas de letra distintas para muchos de ellos. El punto de código de 直 o 骨 es el mismo en una dirección de Tokio y una de Pekín; la forma que espera ver un lector nativo no lo es. Una cadena de reserva solo responde a «qué tipografía instalada tiene un glifo para este punto de código», y todas las fuentes CJK tienen uno, así que la primera fuente de la cadena se lleva cada carácter compartido
La tabla automática pone Microsoft YaHei primero para Han. Está bien para chino simplificado y está mal para japonés. Una dirección japonesa en esa factura sale con el kana dibujado por Yu Gothic (el kana manda la búsqueda primero a la fuente japonesa) y el kanji dibujado por YaHei con formas chinas, todo en una línea. No falta nada, el informe se queda vacío, y un lector japonés ve inmediatamente que algo no encaja
Nuestra recomendación es dejar de fiarse del orden automático para Han y construir la cadena explícita a partir del locale del documento. Normalmente ya lo sabes, por la ficha de cliente o por el idioma de la plantilla:
procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
Lib.ClearFontFallbacks;
if Locale = 'ja' then
begin
Lib.AddFontFallback('Yu Gothic');
Lib.AddFontFallback('Meiryo');
end
else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
Lib.AddFontFallback('Microsoft JhengHei')
else if Locale = 'ko' then
Lib.AddFontFallback('Malgun Gothic')
else
Lib.AddFontFallback('Microsoft YaHei');
// Emoji, símbolos y cualquier escritura no cubierta arriba todavía
// pasan por los candidatos incorporados; pasa 0 aquí para prohibirlo
Lib.SetAutomaticFontFallback(1);
end;
Llámalo una vez por documento, antes del primer DrawText. El orden dentro de la lista explícita importa igual: gana la primera fuente que cubra un carácter, así que una fuente pan-Unicode como Arial Unicode MS va al final, si es que va. Ponla primera y dibujará casi todo, y las fuentes específicas de cada escritura que elegiste con cuidado nunca se consultan
La reserva funciona por clústeres completos
PDF Library for Delphi decide la reserva por clúster de grafema, así que un clúster siempre lo dibuja una sola fuente. Una sílaba devanagari, un emoji con modificador de tono de piel, una letra base con acentos combinantes: cada uno es una unidad única en pantalla, y las decisiones de composición dentro de él salen de las tablas de una tipografía concreta. Medio clúster desde Arial y medio desde una fuente de reserva pondría en la página un glifo técnicamente presente y visiblemente roto, que es discutiblemente peor que un blanco
La fuente seleccionada compone primero la cadena. Solo los clústeres que vuelven como glifo cero salen a buscar otra fuente, y los clústeres vecinos que resuelven a la misma fuente se dibujan juntos como un solo run, de modo que un nombre chino de diez caracteres se convierte en un único run de YaHei en lugar de diez cambios de fuente separados. El orden de derecha a izquierda también se conserva: un run de reserva dentro de texto árabe o hebreo se queda donde el algoritmo bidireccional lo puso. La misma maquinaria de composición impulsa la escritura vertical para japonés y chino
¿Debe un glifo faltante detener el documento?
Depende de para qué es el documento, y PDF Library for Delphi te deja elegir con SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT es el valor por defecto: la operación de texto sigue adelante, los caracteres que ninguna fuente pueda dibujar se descartan de la salida y cada uno queda registrado. PDF_MISSING_GLYPH_ABORT rechaza la operación de texto entera antes de escribir nada en la página, DrawText devuelve 0, y el código de error es 521 (PDFLIB_ERROR_MISSING_GLYPH)
Para informes por lotes internos, toma la política de informe y registra los huecos; un informe ligeramente incompleto hoy es mejor que ningún informe. Para contratos, facturas, certificados y cualquier otra cosa que lleve el nombre de una persona o empresa, toma abortar. Un carácter descartado en el nombre de una parte es un defecto que quieres encontrar en tu propia canalización, y como el aborto ocurre antes de escribir, no queda ninguna línea a medio dibujar en la página
var
Lib: TPDFlib;
Err: Integer;
Report: WideString;
begin
Lib := TPDFlib.Create;
try
Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
Lib.AddTrueTypeFont('Arial', 2);
Lib.SetTextSize(11);
if Lib.DrawText(72, 660, CustomerName) <> 1 then
begin
Err := Lib.LastErrorCode; // leerlo también lo resetea a 0
if Err = PDFLIB_ERROR_MISSING_GLYPH then
begin
Report := Lib.GetMissingGlyphReportJSON;
// {"valid":false,"policy":1,"eventCount":1,"events":[
// {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
// "codePoint":983041,"unicode":"U+F0001",
// "fontName":...,"fontType":...,"operation":"DrawText"}]}
EscalateToOperator(Report);
end;
end;
finally
Lib.Free;
end;
end;
Fíjate en la variable local. LastErrorCode se limpia al leerse, así que un código que comprueba Lib.LastErrorCode = 0 en un sitio y luego registra Lib.LastErrorCode en otro registrará 0. Léelo una vez, quédate el valor
Cada evento del informe lleva la página, el índice UTF-16 dentro de la cadena, el punto de código en decimal y en forma U+XXXX, la fuente que se seleccionó, su tipo y la llamada de API que se topó con el problema. Con eso, una incidencia de soporte nombra el carácter exacto en vez de describir un síntoma. El flag valid es true solo cuando no se registró ningún evento, lo que lo hace una puerta barata en un trabajo por lotes
La biblioteca guarda los 256 eventos más recientes y suelta los más viejos, así que un documento lleno de texto irrenderizable no puede convertir el diagnóstico en un problema de memoria. Los eventos se acumulan entre documentos en la misma instancia de TPDFlib; llama a ClearMissingGlyphReport antes de cada documento si quieres un informe por archivo, o usa el campo documentIndex para distinguirlos
Abortar con letras, tolerar decoración
Una única política para todo el documento a veces es demasiado burda. Una etiqueta de envío puede llevar un emoji decorativo junto al nombre del destinatario, y prefieres perder el emoji a rechazar la etiqueta. El evento OnMissingGlyph se dispara para cada carácter que ninguna fuente de la cadena pudo dibujar, recibe la política como acción por defecto y puede sobreescribirla por punto de código:
type
TGlyphGate = class
procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
UTF16Index, Page: Integer; const FontName, Operation: WideString;
var Action: Integer);
end;
procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
UTF16Index, Page: Integer; const FontName, Operation: WideString;
var Action: Integer);
begin
// Los pictogramas y dingbats son decoración: descártalos y regístralos
if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
((CodePoint >= $2600) and (CodePoint <= $27BF)) then
Action := PDF_MISSING_GLYPH_REPORT
else
Action := PDF_MISSING_GLYPH_ABORT; // letras y dígitos no pueden desaparecer
end;
// Conexión del evento
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;
El evento corre después de que la reserva haya tenido su oportunidad, así que solo ve caracteres realmente sin solución en esta máquina. Todos acaban igualmente en el informe JSON, elijas la acción que elijas en el handler
Medir, incrustar y desplegar
GetTextWidth pasa por las mismas decisiones de reserva clúster a clúster que DrawText. Suena obvio, y es exactamente donde las capas de reserva caseras suelen fallar: parchean la llamada de dibujo, dejan la medición sobre la fuente principal, y cada total alineado a la derecha y columna de tabla acaba calculado a partir de anchos que no coinciden con lo que acaba en la página. Aquí una cadena medida antes de dibujarse ocupa el ancho con el que se midió, runs de reserva incluidos, que es lo que hace razonable dejar la reserva activa en todas partes y no solo en las plantillas que auditaste a mano
Una consecuencia con la política de aborto: cuando la medición se topa con un carácter sin solución, GetTextWidth devuelve 0 y fija el error 521. El código de layout que divide por un ancho o lo usa para dimensionar una celda debería comprobarlo antes de usar el número
Las fuentes de reserva solo se incrustan cuando dibujan algo. Una fuente de la cadena que nunca resolvió ningún clúster no aporta nada al archivo, y una que sí lo hizo se incrusta como subconjunto de los glifos que dibujó. Un documento con un carácter chino entre 5.000 latinos lleva un glifo Han, no una fuente CJK de varios megas; la optimización del tamaño de archivo y el subconjunto de fuentes cubre cómo se construye ese subconjunto. Por eso una cadena larga que cubra todos los locales a los que das servicio sale barata de configurar, y cada PDF solo paga por lo que usó. Los archivos producidos en otro sitio que referencian fuentes que nunca incrustaron son otra reparación, descrita en cómo incrustar fuentes faltantes en un PDF existente
La advertencia de despliegue es fácil de perder. La reserva se resuelve contra las fuentes instaladas en la máquina que ejecuta tu código, y una estación de trabajo de desarrollo con un Office completo tiene muchas más que una imagen de servidor recortada o un contenedor. Si Yu Gothic o Microsoft YaHei no están ahí, la cadena no tiene donde apoyarse. Ejecuta un documento con un nombre Han, un nombre Hangul y un emoji en el servidor de destino y lee el informe JSON: un array events vacío ahí te dice más que cualquier test en tu propio escritorio. Distribuye las fuentes de las que dependes y comprueba que sus licencias permiten incrustar
La misma cadena de reserva, política de glifos faltantes e informe están expuestos en las ediciones DLL y ActiveX, así que quienes llaman desde C#, C++ o scripting los configuran con las mismas llamadas. La documentación de referencia y las descargas están en la página de producto de PDF Library for Delphi