Un conjunto de plantillas de facturas 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 北京示例科技有限公司 desaparecieron, porque Arial no tiene ninguno de ellos. El respaldo automático de fuentes en PDF Library for Delphi viene activado por defecto y toma esos caracteres de caras instaladas, AddFontFallback define su propio orden de búsqueda, y una política de glifos faltantes con reporte JSON se encarga de lo que ninguna cara pueda dibujar
Lo silencioso es lo que vuelve esto caro. Un PDF con un espacio en blanco donde debería estar el nombre de una parte pasa todas las verificaciones estructurales, abre en todos los visores, y normalmente lo nota el cliente en lugar de su suite de pruebas
¿Por qué el texto no soportado desaparece en lugar de generar un error?
PDF no tiene el concepto de una fuente que rechaza un carácter, así que un glifo faltante no es un error a nivel de archivo. Una fuente simple mapea códigos de un byte a nombres de glifo mediante una codificación; una fuente compuesta mapea códigos a través de un CMap hacia CIDs y de ahí a índices de glifo. Pida a una cara algo que no contiene y cae en el índice de glifo cero, .notdef, que ISO 32000-1 §9.7.6.3 trata como el resultado estándar para caracteres indefinidos. La mayoría de las caras dibuja .notdef como nada absoluto. Algunas dibujan un recuadro vacío
En cualquier caso el content stream está bien formado y la página se renderiza. Nada en la especificación le pide a un productor verificar la cobertura antes de escribir un operador de texto, así que un generador que se salta la verificación produce un archivo conforme que perdió contenido en silencio. Por eso el respaldo y el reporte van juntos. Resolver lo que se puede resolver es la mitad del trabajo; avisarle del resto es la otra mitad, y a nuestro juicio la más importante para cualquier cosa que lleve un nombre o un monto
Activar la cadena de respaldo en PDF Library for Delphi
El respaldo entra solo cuando la fuente seleccionada de verdad carece de un carácter en la cadena, así que el texto solo latino conserva su ruta normal y no cuesta nada extra. Una instancia nueva de TPDFlib ya tiene el respaldo automático activado, así que el código de dibujo no necesita ninguna llamada adicional:
var
Lib: TPDFlib;
begin
Lib := TPDFlib.Create;
try
// El respaldo automático viene activado 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 el respaldo automático activado, la librería elige candidatos según la escritura de cada carácter sin resolver. La tabla es fija y está orientada a Windows: emoji y pictogramas prueban Segoe UI Emoji, luego Segoe UI Symbol, 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 con Nirmala UI y Segoe UI
Las caras que usted registra con AddFontFallback se prueban antes de esa tabla incorporada, en el orden en que las agregó. SetAutomaticFontFallback(0) apaga solo la tabla incorporada: la cadena explícita sigue activa, que es la configuración a elegir cuando quiere que la salida use sus caras aprobadas y nada más. AddFontFallback ignora un nombre que ya está en la lista y devuelve su posición con base 1, y ClearFontFallbacks, RemoveFontFallback y GetFontFallbackCount le permiten reconstruir la cadena entre documentos
La trampa de la unificación Han: ¿quién gana los caracteres compartidos?
Chino, japonés y coreano comparten la mayoría de los ideógrafos Han de Unicode, pero cada locale espera formas de letra distintas para muchos de ellos. El code point de 直 o 骨 es el mismo en una dirección de Tokio y una de Beijing; la forma que espera ver un lector nativo no lo es. Una cadena de respaldo solo responde "qué cara instalada tiene un glifo para este code point", y todas las caras CJK tienen uno, así que la cara que vaya primero gana cada carácter compartido
La tabla automática pone Microsoft YaHei primero para Han. Eso está bien para chino simplificado y 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 a la cara japonesa primero) y los kanji dibujados por YaHei con formas chinas, todo en una línea. No falta nada, el reporte queda vacío, y un lector japonés ve de inmediato que algo no cuadra
Nuestra recomendación es dejar de depender del orden automático para Han y construir la cadena explícita a partir del locale del documento. Usted normalmente ya lo sabe, por el registro del 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 toda escritura no cubierta arriba todavía van
// por los candidatos incorporados; pase 0 aquí para prohibirlo
Lib.SetAutomaticFontFallback(1);
end;
Llámelo una vez por documento, antes del primer DrawText. El orden dentro de la lista explícita importa igual: la primera cara que cubre un carácter gana, así que una cara panunicode como Arial Unicode MS pertenece al final, si es que a alguna parte. Póngala primero y dibujará casi todo, y las caras específicas de escritura que usted eligió con cuidado jamás serán consultadas
El respaldo funciona en clústeres completos
PDF Library for Delphi decide el respaldo por clúster de grafema, así que un clúster siempre lo dibuja una sola cara. Una sílaba devanagari, un emoji con un modificador de tono de piel, una letra base con acentos combinantes: cada uno es una sola unidad en pantalla, y las decisiones de shaping dentro de él vienen de tablas de una fuente en particular. Medio clúster de Arial y medio de una cara de respaldo pondría en la página un glifo que técnicamente está presente y visiblemente roto, lo cual es discutiblemente peor que un espacio en blanco
La fuente seleccionada da forma a la cadena primero. Solo los clústeres que regresaron como glifo cero salen a buscar otra cara, y los clústeres vecinos que resuelven a la misma cara se dibujan juntos como una corrida, así que un nombre chino de diez caracteres se vuelve una sola corrida YaHei en lugar de diez cambios de fuente separados. El orden de derecha a izquierda también se conserva: una corrida de respaldo dentro de texto árabe o hebreo se queda donde el algoritmo bidireccional la puso. La misma maquinaria de shaping 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 le deja elegir con SetMissingGlyphPolicy. PDF_MISSING_GLYPH_REPORT es el valor predeterminado: la operación de texto continúa, los caracteres que ninguna cara puede dibujar se descartan de la salida, y cada uno queda registrado. PDF_MISSING_GLYPH_ABORT rechaza la operación de texto completa antes de que algo se escriba en la página, DrawText devuelve 0, y el código de error es 521 (PDFLIB_ERROR_MISSING_GLYPH)
Para reportes internos por lotes, tome la política de reporte y registre los vacíos; un reporte ligeramente incompleto hoy vence a ningún reporte. Para contratos, facturas, certificados y cualquier otra cosa que lleve el nombre de una persona o empresa, tome abort. Un carácter descartado en el nombre de una parte es un defecto que usted quiere encontrar en su propio pipeline, 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 restablece 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;
Note la variable local. LastErrorCode se limpia solo al leerse, así que un código que revisa Lib.LastErrorCode = 0 en un lugar y luego registra Lib.LastErrorCode en otro registrará 0. Léalo una vez, conserve el valor
Cada evento del reporte trae la página, el índice UTF-16 dentro de la cadena, el code point en decimal y en forma U+XXXX, la fuente que fue seleccionada, su tipo y la llamada de API que topó con el problema. Con eso, un ticket de soporte nombra el carácter exacto en lugar de describir un síntoma. El flag valid vale true solo cuando no se registraron eventos, lo cual lo vuelve una compuerta barata en un trabajo por lotes
La librería conserva los 256 eventos más recientes y descarta 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 a través de documentos en la misma instancia de TPDFlib; llame a ClearMissingGlyphReport antes de cada documento si quiere un reporte por archivo, o use el campo documentIndex para distinguirlos
Abortar con letras, tolerar decoración
Una sola 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 usted preferiría perder el emoji antes que rechazar la etiqueta. El evento OnMissingGlyph se dispara por cada carácter que ninguna cara de la cadena pudo dibujar, recibe la política como su acción predeterminada, y puede sobrescribirla por code point:
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ártelos y regístrelos
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 deben desaparecer
end;
// Conectándolo
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;
El evento corre después de que el respaldo tuvo su oportunidad, así que solo ve caracteres verdaderamente irresolubles en esta máquina. Cada uno de ellos aun así aterriza en el reporte JSON, escoja lo que escoja el handler
Medir, incrustar y desplegar
GetTextWidth pasa por las mismas decisiones de respaldo clúster por clúster que DrawText. Suena obvio, y sin embargo es exactamente donde las capas de respaldo caseras suelen fallar: parchan la llamada de dibujo, dejan la medición en la fuente primaria, y cada total alineado a la derecha y cada columna de tabla queda calculado a partir de anchos que no coinciden con lo que termina en la página. Aquí una cadena medida antes de dibujarse ocupa el ancho al que fue medida, corridas de respaldo incluidas, que es lo que hace razonable dejar el respaldo activado en todas partes en lugar de solo en las plantillas que usted auditó a mano
Una consecuencia bajo la política de aborto: cuando la medición topa con un carácter irresoluble, GetTextWidth devuelve 0 y fija el error 521. El código de layout que divide entre un ancho o lo usa para dimensionar una celda debería revisar eso antes de usar el número
Las caras de respaldo se incrustan solo cuando dibujan algo. Una cara de la cadena que nunca resolvió un 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 carga un glifo Han, no una fuente CJK de varios megabytes; optimización de tamaño de archivo y subconjunto de fuentes cubre cómo se construye ese subconjunto. Por eso una cadena larga que cubre cada locale que usted atiende es barata de configurar, y cada PDF paga solo por lo que usó. Los archivos producidos en otro lado que referencian fuentes que nunca incrustaron son una reparación distinta, descrita en incrustación de fuentes faltantes en un PDF existente
La advertencia de despliegue es fácil de perder. El respaldo se resuelve contra las fuentes instaladas en la máquina que ejecuta su 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 a dónde recurrir. Corra un documento con un nombre Han, un nombre Hangul y un emoji en el servidor objetivo y lea el reporte JSON: un arreglo events vacío ahí le dice más que cualquier prueba en su propio escritorio. Distribuya las fuentes de las que depende, y verifique que sus licencias permitan incrustarlas
La misma cadena de respaldo, política de glifos faltantes y reporte están expuestos a través de las ediciones DLL y ActiveX, así que llamadores en 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