Artículo técnico

HTML a PDF en PDFlibPas: decodificación en una pasada

Escape el comentario de un cliente correctamente, de modo que <b>urgent</b> entre en su plantilla HTML como &lt;b&gt;urgent&lt;/b&gt;, entrégueselo a un renderer que parsea el markup dos veces, y el PDF puede volver con la palabra urgent en negrita. El escape fue correcto. El renderer lo decodificó una vez por pasada. Cualquier camino de HTML a PDF que parsea, escribe el resultado de vuelta como HTML y parsea otra vez tiene que decodificar entidades exactamente una vez en todo el viaje

La versión de help desk de esta historia es corriente. Los tickets se exportan a PDF, el comentario del cliente se sienta dentro de un <p>, y alguien teclea ángulos en la caja de comentarios. Un nombre de etiqueta desconocido sencillamente desaparece de la página. Un anchor escapado se convierte en una anotación de enlace pulsable en un documento en el que su equipo confía. El archivo es válido y abre en todas partes; sencillamente dice algo distinto de los datos

Dónde el texto escapado vuelve a convertirse en markup

El texto escapado se convierte en markup en el punto donde un renderer de dos pasadas escribe texto ya decodificado de vuelta a HTML sin volver a escaparlo. Lo que el primer parseo decodificó queda entonces como sintaxis viva para el segundo

Las dos pasadas en DrawHTMLText y DrawHTMLTextBox de PDF Library for Delphi (PDFlibPas) existen por una buena razón. El primer parseo parte la entrada en etiquetas y palabras. El renderer resuelve luego la cascada de la hoja de estilos: las reglas de los bloques <style> se cotejan con cada etiqueta, se fusionan con los atributos style en línea, y la lista entera de elementos se escribe de vuelta como una cadena HTML normalizada con cada etiqueta llevando su estilo final. La pasada de layout parsea esa cadena. El matching de selectores, flexbox, grid y el resto del soporte CSS descrito en flexbox, CSS grid y maquetación de footnotes en el renderizado HTML de PDFlibPas dependen todos de ese paso intermedio

El peligro se sienta en cómo salen las palabras de vuelta. Las etiquetas pueden escribirse de vuelta desde su forma del fuente, pero las palabras se sostienen como texto decodificado, porque eso es lo que mide el que parte las líneas. Añada la palabra que vino de &lt;unsafe&gt; a la cadena normalizada tal cual está, y <unsafe> llega al segundo parseo como un elemento. Un diseño que decodifica una vez tiene que cerrar también tres fugas menores:

  • Si &amp; no está en el conjunto decodificado, R&amp;D se imprime literal y no hay manera alguna de poner la grafía &lt; en la página como texto
  • Si la etapa de dibujo sustituye &nbsp; otra vez después de que el parseo haya terminado, una grafía de entidad literal desaparece en el último momento
  • Si un productor HTML aguas arriba, como un conversor de Markdown o un exportador de datasets, escapa solo los ángulos, una grafía de entidad dentro de un ejemplo de código o un valor de celda se decodifica como markup
Pipeline HTML de PDFlibPas para DrawHTMLText donde el primer parseo construye elementos, NormalizeParsedHTML los serializa de vuelta a HTML y el segundo parseo maqueta el resultado; las palabras decodificadas escritas de vuelta sin escapar se volverían etiquetas vivas, así que cada palabra se re-escapa en la frontera
Las palabras decodificadas reentran en el parser como sintaxis cuando el normalizador olvida que produce markup, que es cómo un comentario escapado puede salir en negrita o brotarle un enlace

La tabla de abajo lista lo que llega a la página para un puñado de entradas, comparando un renderer de dos pasadas ingenuo con el pipeline de PDFlibPas

Entrada que llega al rendererRenderer de dos pasadas ingenuoPDFlibPas
&lt;unsafe&gt;Se parsea como etiqueta, el texto nunca llega a la página<unsafe> dibujado como texto
&lt;b&gt;x&lt;/b&gt;x dibujado en negrita<b>x</b> dibujado como texto
R&amp;DR&amp;D impreso literalR&D
&amp;lt;&amp;lt; impreso literal&lt;
Fragmento de código Markdown con &nbsp;Un espacio de no separación&nbsp; dibujado como texto
Valor de celda de dataset &lt;<&lt;

¿Cómo decodifica PDF Library for Delphi cada entidad exactamente una vez?

PDF Library for Delphi decodifica cada entidad exactamente una vez siguiendo tres reglas juntas: el parser decodifica &amp; al final, la etapa de dibujo no decodifica nada, y cada sitio que convierte palabras decodificadas de vuelta a HTML las escapa primero. Suelte cualquiera de las tres y una de las filas de la tabla de arriba pasa a la columna ingenua

Empiece por lo que se decodifica. En contenido de texto el parser reconoce &lt;, &gt;, &amp; y &nbsp;. Las referencias numéricas como &#65; y las entidades con nombre como &quot; se quedan como texto literal. Esa lista corta decide cómo debe escapar usted su propia entrada, algo que vuelve más abajo

El orden dentro del decodificador importa incluso dentro de una sola pasada. Decodifique &amp; primero y la entrada &amp;lt; se convierte en &lt;, y la siguiente sustitución la convierte en <: una doble decodificación sin segundo parseo alguno. El camino de palabras de 8 bits sustituye por eso &lt;, &gt; y &nbsp; primero y &amp; al final, de modo que el ampersand que produce jamás vuelve a mirarse. El camino de palabras UTF-16 toma otra ruta hacia el mismo resultado — un único barrido de izquierda a derecha en pasos de dos bytes que reescribe cada coincidencia en su sitio y salta más allá

Orden del decodificador de PDFlibPas ante una entidad encadenada como &amp;lt;: decodificar el ampersand primero lo colapsa en un ángulo real dentro de una misma pasada, mientras que decodificar lt, gt y nbsp antes del ampersand mantiene intacta la grafía literal y el texto llega a la página decodificado exactamente una vez
El ampersand es el carácter de escape, así que hay que decodificarlo al final y escaparlo al principio, o una misma pasada puede decodificar dos veces

La etapa de dibujo no recibe sustitución tardía de &nbsp;. Una palabra que llega al que parte las líneas es texto final, y la decodificación vive en el parser y en ningún otro sitio

La regla de la frontera lleva el mayor peso. Cuando el renderer escribe el HTML normalizado, escapa &, < y > en cada palabra decodificada antes de añadirla, y el segundo parseo la decodifica de vuelta a los mismos caracteres. Efecto neto sobre ambas pasadas: una decodificación. La cadena de continuación que DrawHTMLTextBox devuelve sigue la misma regla. Las palabras que no cupieron se escapan antes de entrar en el resto, y lo demás del resto se copia del HTML normalizado, que ya está escapado. Una caja que se lo lleva todo devuelve una cadena vacía

¿Por qué el escape UTF-16BE no puede usar una sustitución a nivel de byte?

El escape UTF-16BE no puede usar una sustitución a nivel de byte porque los dos bytes de un ampersand pueden cabalgar entre dos caracteres sin relación. La unidad de código completa de 16 bits es la única unidad de trabajo segura

El renderer guarda las palabras Unicode como UTF-16 big-endian empaquetado en cadenas de bytes, byte alto primero, así que un ampersand es 00 26. Tome U+0100 (A latina mayúscula con macrón, bytes 01 00) seguido de U+2603 (el muñeco de nieve, bytes 26 03). El buffer lee 01 00 26 03, y los bytes dos y tres se leen 00 26. Una búsqueda por byte de #0'&' encuentra un ampersand que ningún carácter contiene, empalma &amp; en medio de dos puntos de código, y desplaza cada carácter posterior un byte

Riesgo del escape UTF-16BE en PDFlibPas donde los bytes 01 00 26 03 de U+0100 y U+2603 contienen el patrón 00 26 a caballo entre dos caracteres, de modo que una búsqueda por byte del ampersand empalma una entidad en medio de un punto de código; el barrido por unidades de código solo prueba offsets pares
Una búsqueda por byte encuentra un ampersand que ningún carácter contuvo jamás; trabaje sobre unidades de código completas, nunca sobre buffers de bytes UTF-16 en crudo

Esto no es una esquina exótica. Cualquier carácter cuyo byte bajo sea cero puede aportar la primera mitad, y U+4E00, uno de los ideogramas CJK más frecuentes, es semejante carácter. Los ángulos quedan expuestos de la misma manera: 00 3C y 00 3E aparecen siempre que un carácter así va seguido de uno del rango U+3C00 a U+3EFF del anexo CJK A. Así que PDFlibPas escapa las palabras Unicode desempaquetándolas a un WideString, escapando carácter a carácter y volviendo a empaquetar el resultado. El decodificador es seguro por la razón correspondiente: solo prueba patrones en offsets pares

Su propio código puede chocar con el mismo muro. En cuanto el texto UTF-16 vive en TBytes, por ejemplo tras TEncoding.BigEndianUnicode.GetBytes, buscarlo por patrones de bytes es un bug esperando el par de caracteres correcto. Conviértalo de vuelta a string y trabaje sobre caracteres

Código Markdown y celdas de dataset: el ampersand va primero

Los dos productores HTML dentro de PDFlibPas, el conversor de Markdown y el exportador de datasets, escapan el ampersand antes de los ángulos, así que la única decodificación del renderer restaura el texto original byte a byte

En MarkdownToHTML, los fragmentos de código en línea y los bloques de código delimitados o indentados mapean & a &amp;, < a &lt; y > a &gt;. Los espacios se convierten en &nbsp; y un tabulador en cuatro de ellos, lo que mantiene la indentación intacta. La prosa corriente escapa solo los ángulos: el HTML en crudo tecleado en prosa no puede inyectar etiquetas, mientras que un autor que escribe &amp; a propósito sigue recibiendo un ampersand, como los autores de Markdown esperan. DrawMarkdownText y DrawMarkdownTextBox corren la misma conversión, así que un bloque de código aparece tal cual se tecleó:

uses
  System.SysUtils, PDFlibrary;

procedure RenderCodeSample;
var
  Lib: TPDFlib;
  Md, Html: WideString;
begin
  Md := 'Comparison helper:' + sLineBreak + sLineBreak +
        '```' + sLineBreak +
        'if (A < B) and (Flags <> 0) then' + sLineBreak +
        '  WriteLn(''&lt;tag&gt; &amp; R&amp;D'');' + sLineBreak +
        '```';
  Lib := TPDFlib.Create;
  try
    // Inspeccione el HTML: dentro de código, '&' pasa a '&amp;' y '<' pasa a '&lt;'
    Html := Lib.MarkdownToHTML(Md);
    Lib.SetOrigin(1);            // origen arriba a la izquierda, Y crece hacia abajo
    Lib.SetMeasurementUnits(0);  // puntos
    // La página muestra el código tal cual se tecleó, grafías de entidad incluidas
    Lib.DrawMarkdownText(50, 50, 495, Md);
    Lib.SaveToFile('code-sample.pdf');
  finally
    Lib.Free;
  end;
end;

El exportador de datasets es donde vive el atajo tentador. Si un renderer no decodificara &amp;, escapar el ampersand imprimiría &amp; en cada celda que contenga uno, así que escapar solo los ángulos parece la elección más amable. Se desmorona en la primera celda cuyo valor contiene por casualidad &lt;, que entonces llega a la página como <. Como el renderer sí decodifica &amp;, el exportador detrás de PDFlibExportDataSet escapa & primero, y un valor como R&D &lt; &amp; &nbsp; aterriza en el PDF verbatim. El resto de ese exportador está cubierto en exportar un TDataSet a un informe PDF en Delphi

¿Por qué primero, y no simplemente en algún punto de la cadena? Escape < primero y obtiene &lt;. Escape & segundo y eso se convierte en &amp;lt;, que una única decodificación correcta muestra como &lt; en lugar de <. Una cadena de sustituciones secuencial solo funciona cuando el carácter de escape mismo se trata antes de cualquier paso que lo introduzca

¿Cómo se escapa texto no fiable para DrawHTMLTextBox?

Escape el contenido de texto no fiable para PDFlibPas sustituyendo &, luego <, luego >, exactamente una vez, y mantenga los datos no fiables fuera de los valores de atributo por completo. El helper de abajo es suyo para añadir; es código RTL plano:

uses
  System.SysUtils, PDFlibrary;

// Su propio ayudante (no parte de la biblioteca): escapa texto no fiable
// para el contenido de texto HTML de PDFlibPas. '&' debe sustituirse
// primero; si no, el ampersand dentro de un '&lt;' recién producido
// quedaría escapado una segunda vez
function EscapeHTMLText(const S: string): string;
begin
  Result := StringReplace(S, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [rfReplaceAll]);
  Result := StringReplace(Result, '>', '&gt;', [rfReplaceAll]);
end;

procedure RenderTicket(const CustomerComment: string);
var
  Lib: TPDFlib;
  Html: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);
    Lib.SetMeasurementUnits(0);
    Html := '<p><b>Customer comment</b></p>' +
            '<p>' + EscapeHTMLText(CustomerComment) + '</p>';
    Lib.DrawHTMLText(50, 50, 495, Html);
    Lib.SaveToFile('ticket.pdf');
  finally
    Lib.Free;
  end;
end;

Aliméntelo con el comentario Try <a href="https://example.com">this</a> & &lt;b&gt; y la página muestra esos caracteres uno a uno. Bajo un renderer que decodifica dos veces, la misma entrada escapada se convierte en una anotación de enlace viva. Ese es el paso de fallo cosmético a problema de seguridad: el comentario de un ticket no debería poder plantar jamás una URL pulsable en un PDF que va a su propio equipo

Fíjese en lo que el helper deja en paz. Los escapadores de propósito general convierten además " en &quot; y ' en &#39;, que es correcto para un navegador y está mal aquí — la decodificación de texto de PDFlibPas solo conoce las cuatro entidades listadas antes, así que esas dos se imprimirían literalmente como &quot; y &#39;. No reutilice un escapador de navegador para esto. Las comillas son inofensivas en contenido de texto; solo importan dentro de valores de atributo, y el renderer no decodifica entidades en atributos en absoluto. Para los atributos preferimos una regla a un escapador más listo, porque allí no se comprueba esquema de escape alguno: mantenga los valores de usuario fuera de href, src y style. Si un destino de enlace de verdad tiene que venir de entrada de usuario, valídelo usted mismo contra una allow-list de esquemas y caracteres y rechace todo lo que contenga comillas o ángulos

Dos hábitos se deducen directamente de la decodificación en una sola pasada:

  • Escape siempre &. Sáltelo, y el texto de usuario que contenga &lt; se muestra como < — inofensivo, pero no es lo que el usuario tecleó
  • Escape en un solo punto. El texto que pasa por dos escapadores renderiza < como la grafía visible &lt;, así que encuentre el único sitio donde sus datos entran en la cadena HTML y escape allí

Paginar con LeftOverText sin romper los escapes

DrawHTMLTextBox devuelve el HTML que no cupo, llamado normalmente LeftOverText, y ese resto conserva las grafías de entidad literales y los ángulos escapados intactos cuando entra en la siguiente caja. Páseselo de vuelta exactamente como lo recibió

const
  BoxLeft = 50;
  BoxTop = 50;
  BoxWidth = 495;    // dimensionado para una página A4 en puntos
  BoxHeight = 740;
  MaxPages = 500;    // su propio tope de seguridad

procedure RenderLongHTML(Lib: TPDFlib; const Html: WideString);
var
  Rest: WideString;
  Pages: Integer;
begin
  Lib.SetOrigin(1);
  Lib.SetMeasurementUnits(0);
  Rest := Lib.DrawHTMLTextBox(BoxLeft, BoxTop, BoxWidth, BoxHeight, Html);
  Pages := 1;
  while (Rest <> '') and (Pages < MaxPages) do
  begin
    Lib.NewPage;
    Inc(Pages);
    // El resto ya es HTML escapado: jamás lo escape ni lo desescape
    Rest := Lib.DrawHTMLTextBox(BoxLeft, BoxTop, BoxWidth, BoxHeight, Rest);
  end;
  if Rest <> '' then
    raise Exception.CreateFmt('Content still left after %d pages', [MaxPages]);
end;

Trate el resto como opaco. Es HTML normalizado con los estilos ya resueltos sobre cada etiqueta, así que pasarlo por su propio escapador convierte cada &lt; en &amp;lt;, y decodificarlo entrega a la siguiente caja etiquetas vivas. Empalmar texto de usuario fresco en él tiene los mismos dos modos de fallo. El tope de páginas cuesta una comparación: si algún elemento no cabe jamás en la caja, un bucle sin tope no tiene salida natural

Markdown tiene su propia continuación. DrawMarkdownTextBox devuelve un resto que empieza con un comentario marcador, que le dice a los puntos de entrada Markdown que se salten la conversión en la siguiente llamada. Devuélvaselo a DrawMarkdownTextBox o a DrawMarkdownText, de la misma manera en que usted pasaría LeftOverText de vuelta a DrawHTMLTextBox. Un resto de Markdown pertenece a los puntos de entrada Markdown, así que manténgalo de ese lado y pase solo los restos de DrawHTMLTextBox por las llamadas HTML

La forma detrás de todo esto — parsear, escribir de vuelta a la misma sintaxis, parsear otra vez — también aparece en motores de plantillas, sanitizadores HTML y cadenas Markdown-a-HTML-a-PDF, y el fallo viene en dos direcciones. Demasiado poco re-codificado convierte datos en sintaxis. Demasiado codificado, o un decodificador que corre dos veces, muestra grafías de entidad al lector o se las come. Parchear una sola dirección tiende a romper la otra, que es por lo que el renderer de PDFlibPas trata la decodificación de &amp;, el decodificarla al final, la ausencia de decodificación tardía y el re-escape en cada frontera como un solo paquete. La dirección de exportación sigue la misma regla en la exportación semántica de PDF a Markdown y DOCX desde Delphi, donde cada carácter literal se escapa para la sintaxis destino exactamente una vez

El dibujo HTML y Markdown, el exportador de informes de dataset y el resto del motor de layout vienen como fuente Pascal nativo en PDF Library for Delphi, tanto para Delphi como para Free Pascal. Las ediciones, la cobertura de plataformas y la descarga de prueba están listadas en la página de producto de PDF Library for Delphi