Artículo técnico

XFA en PDFium Component: newlines, emoji y restoreState

Un cuadro de Comments vacío en un formulario de reclamos XFA reabre conteniendo un line feed. Guárdelo y reábralo otra vez y el cuadro contiene dos. Un nombre de cliente tecleado con U+1F642, la carita sonriente ligera, vuelve como U+F642, un code point de private use que la mayoría de las fuentes dibujan como un rectángulo vacío. Los tres efectos viven en el XML que un guardado XFA escribe en el paquete datasets, y una ruta de guardado que los resuelve bien tiene que mantener el espacio en blanco del layout fuera de los valores de los fields, transportar los caracteres del plano suplementario como surrogate pairs completos, y reportar una escritura fallida a través del resultado del guardado en lugar de a través de un archivo dañado

¿Qué runtime de PDFium guarda los valores XFA?

Solo pdfium.v8.dll guarda valores XFA, porque es el único build de PDFium Component que trae tanto el engine JavaScript V8 como el runtime de formularios XFA. Una vez que una edición queda comprometida (el field perdió el foco, o ClearFormFieldFocus forzó el commit), ese runtime exporta los datos XFA vivos al paquete datasets al guardar, sin edición de paquetes en su código. Cada arquitectura Windows también trae un pdfium.dll, compilado sin V8 ni XFA, que reescribe los paquetes almacenados exactamente como los leyó. Lo que pasa con un valor escrito mientras el field todavía tiene el foco está cubierto en por qué las ediciones de fields XFA desaparecen al guardar

El wrapper Delphi intenta elegir la librería correcta por usted. Cuando EnableV8Engine sigue en False y todavía no se cargó ninguna librería PDFium, TPdf mira el archivo que está por abrir y, si encuentra marcadores XFA (una entrada /XFA en el diccionario AcroForm, o /NeedsRendering true en el catálogo), activa EnableV8Engine antes de cargar. Ese switch solo funciona una vez por proceso. Si un pdfium.dll ordinario ya está residente porque el primer documento de la sesión fue un PDF simple, el proceso queda comprometido con él, y TPdf.OnXfaRuntimeMissing se dispara cuando llega más tarde un documento XFA

El orden de búsqueda por defecto es la otra mitad del problema. Sin un directorio en LibraryName, el loader arranca por una carpeta DLLs\Win32 o DLLs\Win64 bajo la carpeta de la aplicación o una de sus padres, así que un pdfium.v8.dll más viejo puede aparecer primero. Un LibraryName que contiene un directorio fija exactamente ese archivo, y si falta, la carga falla

uses
  System.SysUtils, PDFium;

procedure SelectXfaRuntime;
begin
  // Un directorio en LibraryName fija este archivo exacto;
  // si el archivo falta, la carga lanza en vez de hacer fallback
{$IFDEF WIN64}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win64\pdfium.v8.dll';
{$ELSE}
  PDFium.LibraryName := ExtractFilePath(ParamStr(0)) + 'DLLs\Win32\pdfium.v8.dll';
{$ENDIF}
  PDFium.EnableV8Engine := True;
  PDFium.LoadLibrary;  // fallar al arranque, no en el primer guardado
end;

Después de abrir un documento, TPdf.XFA le dice que el archivo contiene XFA y TPdf.XfaRuntimeAvailable le dice que la DLL cargada puede de verdad ejecutarlo. Si además necesita distinguir formularios estáticos de dinámicos, TPdf.FormType devuelve ftXfaFull o ftXfaForeground; el artículo sobre detectar formularios XFA y extraer paquetes XFA en Delphi cubre ese sondeo en detalle

¿Por qué los fields XFA guardados ganan line feeds extra?

Los fields XFA guardados ganan line feeds cuando el writer hace pretty-print de su XML con un newline después de cada start tag. En un guardado XFA participan dos writers, el writer genérico de elementos XML y el serializador del form packet, y ambos tienen la costumbre de formatear la salida así. En la mayoría de los documentos XML ese espacio en blanco es cosmético. En datos XFA es el valor: cuando el paquete datasets se parsea de nuevo, cada carácter entre <Comments> y </Comments> pertenece al field, newline incluido

Diagrama del ciclo de guardado XFA de PDFium Component donde el writer agrega un newline después de los start tags, el parser al reabrir lee el LF entre los tags Comments como el valor del field, y cada guardado adicional agrega otro line feed a menos que el writer elimine solo el espacio en blanco que él sintetizó
Un ciclo de guardado y reapertura siembra el primer line feed y cada ronda siguiente agrega otro, razón por la cual la deriva muestra su forma completa solo en la segunda generación

Un field vacío por lo tanto reabre conteniendo un solo LF. Cada guardado siguiente formatea alrededor del LF que ya está ahí, así que un field que nadie tocó crece una línea por ronda de revisión

La reparación obvia, recortar los valores al cargar, estaría mal. Los usuarios teclean espacios al inicio, espacios al final y texto multilínea deliberado en los fields XFA, y un bloque de dirección o un código de ancho fijo debe sobrevivir byte por byte. Los writers XFA de PDFium Component por lo tanto eliminan solo el espacio en blanco que el propio serializador sintetiza alrededor de los tags. Los valores del usuario, los text nodes existentes y las secciones CDATA pasan intactos, así que " indented" sigue indentado y un field intencionalmente vacío sigue vacío

Emoji, surrogate pairs y un wchar_t de 16 bits

Un emoji vuelve como un carácter distinto cuando una ruta de decodificación guarda un valor escalar Unicode completo en un solo wchar_t, que en Windows es de 16 bits. Dos lugares de una carga XFA están expuestos a esto: el decoder del stream UTF-8, y el parser de referencias de caracteres numéricas como &#x1F642;. U+1F642 necesita 17 bits. Metido a la fuerza en 16, el bit alto se cae y queda U+F642 en el Private Use Area

Un serializador de formulario puede fallar en la dirección opuesta. Filtrando caracteres de a un wchar_t por vez, ve dos code units surrogate, D83D y DE42, cada una de las cuales es inválida por separado, y descarta ambas. El emoji desaparece del form packet, sin dejar ningún carácter de reemplazo

Diagrama de manejo de surrogates de PDFium Component donde U+1F642 llega como el par UTF-16 D83D DE42 y dos rutas ingenuas pueden corromperlo: los decoders wchar_t de 16 bits truncan el escalar a U+F642 en el private use area, mientras que un serializador que filtra surrogates solitarios descarta el emoji por completo
El wchar_t de Windows es de 16 bits, así que un escalar que necesita un surrogate pair pierde su mitad alta o desaparece del paquete, salvo que ambas rutas mantengan los pares juntos

En PDFium Component el decoder consume cada valor escalar por completo y emite un surrogate pair apropiado, incluso cuando el buffer de salida solo tiene lugar para una unidad más y cuando una secuencia UTF-8 de cuatro bytes queda partida entre dos bloques de lectura. En la salida, el exportador del formulario mantiene juntos los surrogate pairs válidos, y las referencias de caracteres numéricas también decodifican a pares correctos

Los datos de prueba Latin-1 nunca tocan ninguna de estas rutas. Una prueba de round trip para un formulario XFA necesita al menos un carácter por encima de U+FFFF en un text field, y revisar los bytes guardados buscando la secuencia UTF-8 de cuatro bytes F0 9F 99 82 dice más que mirar el field renderizado

XFA de stream único y el resultado del guardado

Un documento XFA de stream único pierde sus ediciones cuando un helper nativo de guardado rechaza ese layout de almacenamiento y quien lo llama ignora el fallo. ISO 32000-1 §12.7.8 permite que la entrada /XFA del diccionario de formulario interactivo sea tanto un array de nombres de paquetes y streams como un stream único que contenga el documento XDP completo. Los arrays de paquetes son el caso común, pero los streams únicos son perfectamente legales, y en esa situación el guardado del PDF se completa como si nada hubiera pasado mientras los datos del formulario se quedan en sus valores viejos

El runtime V8 de PDFium Component maneja un subconjunto definido de stream único en tres pasos. Exporta ambos paquetes vivos, datasets y form, a un área de staging y los valida. Solo entonces reemplaza los paquetes correspondientes dentro del XDP original, conservando los demás paquetes y las declaraciones de namespace de la raíz. Si el staging falla, el stream XFA persistente nunca se toca y el documento conserva su marca de modificación, así que un guardado posterior puede intentarlo de nuevo

Pipeline de guardado XFA de stream único de PDFium Component donde los paquetes vivos datasets y form se exportan a staging, se validan, y luego se reemplazan dentro del XDP original con comentarios conservados por medio de marcadores, mientras que los fallos de staging e inputs como DTD o XMLDSig rechazan el guardado explícitamente
El export a staging se valida antes de que algo se reemplace, así que un guardado fallido deja el stream XFA persistente intacto y el documento conserva su marca de modificación

Los comentarios XML y las instrucciones de procesamiento necesitan cuidado extra, porque el parser usado para la reescritura los descarta. Cada uno se cambia por un marcador único antes de parsear y se repone después, y el stream solo se escribe si cada marcador aparece exactamente una vez, así que los comentarios fuera de los paquetes vivos conservan su texto y su orden

Algunos inputs se rechazan a propósito, y cada rechazo es un fallo de guardado explícito:

  • Comentarios o instrucciones de procesamiento dentro de los paquetes vivos datasets o form, ya que sus posiciones originales no se pueden mapear a contenido recién exportado
  • Declaraciones DTD y firmas XMLDSig, ya que reescribir el XDP no puede mantener válida una firma XML
  • Codificación UTF-8 o UTF-16 inválida, tags incompletos, referencias de caracteres inválidas, entidades desconocidas e instrucciones de procesamiento mal formadas, que se rechazan en vez de repararse en silencio

Rechazar es el mejor intercambio acá. Un guardado que devuelve False se puede reintentar, registrar o entregarle a una persona, mientras que un XDP normalizado en silencio puede romper una firma o un importador aguas abajo semanas después, lejos del código que lo cambió. Lo que la ruta de stream único sí preserva es el modelo de contenido XML, escrito como UTF-8; el layout de bytes original y la declaración de codificación del stream fuente no se trasladan

El último bloque buferado

La trampa final está por debajo del XFA, en el writer PDF genérico. Un writer de archivos que bufera la salida en bloques de tamaño fijo tiene que empujar el último bloque parcial al final. Si eso pasa en código de limpieza después de que el writer del documento ya reportó éxito, un disco lleno o un error de I/O en el último bloque nunca llega a quien llamó, y el archivo en disco queda corto. En ambos runtimes de PDFium Component el flush final es parte del resultado del guardado, y la marca de modificación XFA se limpia solo después de que la escritura de verdad tuvo éxito

El lado Delphi agrega una capa más. TPdf.SaveAs escribe en un archivo temporal junto al objetivo y lo mueve sobre el objetivo solo cuando el guardado del stream devuelve True. Un resultado False deja el archivo anterior exactamente como estaba, y un fallo del reemplazo final lanza un error del sistema operativo en lugar de volver en silencio

¿Por qué un formulario XFA dinámico reabre con menos páginas?

Un formulario XFA dinámico reabre con menos páginas cuando su subform raíz no declara restoreState="auto", y eso es una decisión de autoría del formulario y no algo que el runtime controle. En XFA 3.3, restoreState en el subform raíz queda en manual por defecto. Bajo manual, el procesador XFA restaura solo un estado limitado desde el form packet guardado y deja el resto a los scripts del autor. Los valores de fields guardados y los conteos de instancias de subforms repetitivos igual vuelven, pero las propiedades geométricas fijadas en runtime no

Suponga un formulario de tres páginas cuyo script crece un subform a h="450pt" mientras el usuario lo llena. El form packet guardado contiene la altura nueva, los valores de los fields y los conteos de instancias. Al reabrir, el layout se reconstruye desde las alturas del template, el subform se encoge, y el contenido refluye a dos páginas. Ese es el comportamiento que la especificación XFA pide cuando el template nunca pidió restauración automática. Declararlo en el subform raíz cambia la reapertura:

<template xmlns="http://www.xfa.org/schema/xfa-template/3.3/">
  <subform name="form1" layout="tb" restoreState="auto">
    <pageSet>
      <pageArea name="Page1">
        <contentArea x="0.25in" y="0.25in" w="8in" h="10.5in"/>
        <medium stock="letter"/>
      </pageArea>
    </pageSet>
    <subform name="Details" layout="tb" w="7.5in">
      <!-- fields; los scripts pueden cambiar h o agregar instancias en runtime -->
    </subform>
  </subform>
</template>

Si el template no es suyo, déjelo tranquilo: un formulario construido para el modo manual espera que sus propios scripts de inicialización reconstruyan el estado, y cambiar el modo por debajo de ellos altera aquello para lo que esos scripts fueron escritos. La repaginación viva mientras el usuario teclea es un mecanismo distinto, descrito en cómo rastrea PDFium Component los conteos de páginas XFA dinámicas y los fields movidos

Verificar un round trip XFA desde Delphi

Un guardado XFA se verifica reabriendo el archivo guardado en una instancia TPdf nueva y leyendo los datos almacenados de vuelta, porque un True de SaveAs solo dice que el archivo se escribió. TPdf.GetXfaDatasets devuelve el paquete datasets tal como está almacenado en el documento, no el modelo de datos vivo, así que leerlo antes del guardado muestra los valores de la última carga. Después de una reapertura muestra exactamente lo que se escribió. Un documento de stream único no tiene paquetes con nombre separado: PDFium reporta el XDP completo como un paquete con nombre vacío, así que GetXfaPacketByName('datasets') y GetXfaDatasets devuelven ambos un array vacío, y el código de abajo cae al stream completo de GetXfaFormPackets

uses
  System.SysUtils, PDFium, FPdfXfa;

function ReadSavedXfaData(const FileName: string): string;
var
  Pdf: TPdf;
  Packets: TXfaPacketList;
  Bytes: TBytes;
begin
  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    Bytes := Pdf.GetXfaDatasets;          // layout de array de paquetes
    if Length(Bytes) = 0 then
    begin
      Packets := Pdf.GetXfaFormPackets;   // stream único: un paquete sin nombre
      if Length(Packets) = 1 then
      begin
        SetLength(Bytes, Length(Packets[0].Content));
        if Length(Bytes) > 0 then
          Move(Packets[0].Content[0], Bytes[0], Length(Bytes));
      end;
    end;
    Result := TEncoding.UTF8.GetString(Bytes);  // la salida XDP guardada es UTF-8
  finally
    Pdf.Free;
  end;
end;

La rutina de guardado hace el commit de la edición pendiente, verifica el resultado de SaveAs y compara el valor reabierto. TPdf.ClearFormFieldFocus quita el foco del formulario, que es el momento en que PDFium hace commit del edit buffer del field con foco. TPdf.SetFocusedFormFieldText puede llenar el field con foco desde código, pero se apoya en un foco rastreado a través de anotaciones de widget, que una página XFA dinámica normalmente no tiene; ahí devuelve False, y el texto normalmente llega por input de teclado en TPdfView

// XmlText is a helper you add yourself; it is not part of PDFium Component
function XmlText(const S: string): string;
begin
  Result := StringReplace(S, '&', '&amp;', [rfReplaceAll]);
  Result := StringReplace(Result, '<', '&lt;', [rfReplaceAll]);
end;

procedure SaveXfaAndVerify(Pdf: TPdf; const FileName, FieldTag,
  Expected: string);
var
  Saved: string;
begin
  // Llenado scriptado opcional; False significa que ningún field rastreado tiene foco
  if (Pdf.FocusedFormFieldIndex >= 0) and
     not Pdf.SetFocusedFormFieldText(Expected) then
    raise EPdfError.Create('Could not write the focused field');

  Pdf.ClearFormFieldFocus;              // commit del edit buffer
  if not Pdf.SaveAs(FileName) then      // False: el archivo anterior queda en su lugar
    raise EPdfError.CreateFmt('Saving %s failed', [FileName]);

  // Reabra en un TPdf nuevo y busque el texto exacto del elemento
  Saved := ReadSavedXfaData(FileName);
  if Pos('<' + FieldTag + '>' + XmlText(Expected) + '</' + FieldTag + '>',
    Saved) = 0 then
    raise EPdfError.CreateFmt('%s did not survive the round trip', [FieldTag]);
end;

Trate la prueba de substring como una prueba de humo. Un elemento vacío puede serializarse como <Tag/>, los atributos pueden aparecer en elementos de datos, y el escapado más allá de & y < es una elección del serializador. Para chequeos de producción, cargue el XML reabierto con un parser XML de verdad y compare el text node del elemento de datos enlazado. Corra el chequeo dos veces seguidas también, porque la deriva del newline solo muestra su forma completa en la segunda generación

Las aplicaciones anfitrionas que manejan el runtime XFA directamente también necesitan el layout de callbacks que él espera, que es el tema de FPDF_FORMFILLINFO versión 2 y el ABI XFA en Delphi. Ambos runtimes Windows para Win32 y Win64, el wrapper Delphi y C++Builder y el control de visor TPdfView vienen con PDFium Component para Delphi y C++Builder