Artículo técnico

XFA dinámico en PDFium Component: el conteo es un delta

Cuando un formulario XFA dinámico en un visor Delphi agrega o quita páginas, PDFium Component reporta el nuevo total a través de TPdf.PageCount y TPdf.OnXfaPageCountChanged, leyéndolo del layout completado porque el evento de página nativo trae un delta de agregadas/quitadas en lugar de un total. Las librerías V8 de Windows también mueven las áreas de hit de entrada junto con los fields reubicados, y TPdfView recarga los page handles después de que el callback de layout devuelve. Imagine un formulario de reclamo de gastos: haga clic en Add Row dos veces y el formulario crece a dos páginas. Un visor que confía en el argumento del evento lee con orgullo 1 de 1, y uno que conserva la geometría de widgets pre-layout manda teclas para un field que se movió a la página 2 a algún lugar invisible. Nada de esto aparece con los formularios de muestra de longitud fija con los que todos prueban primero, y las razones valen la pena conocerlas si usted embebe un visor de formularios

¿Qué pasa cuando un formulario XFA dinámico se repagina?

Un formulario XFA dinámico no tiene lista de páginas fija, así que su conteo de páginas es una salida del layout y puede cambiar cada vez que el usuario edita datos. XFA 3.3 describe el formulario como un árbol de subforms; un subform repetitivo está controlado por un instanceManager, y un script como _Row.addInstance() clona una fila más. El procesador de layout entonces fluye el contenido a las áreas de página de nuevo, lo que puede agregar una página, quitar una página o empujar fields existentes a otra página. ISO 32000-1 §12.7.8 solo define cómo los packets XFA viajan dentro del PDF; todo lo que pasa después pertenece al motor XFA, que en PDFium Component es el layout XFA del propio PDFium corriendo en el proceso host. Un visor Delphi entonces lidia con un documento cuyo conteo de páginas, tamaños de página y posiciones de widgets son todos estado vivo. Tres cosas salen mal cuando el host asume lo contrario:

  • El conteo de páginas que el host cachea para navegación, rangos de scroll y spinners de página queda desactualizado, o peor, se actualiza con el número equivocado
  • Los fields que se reubican muestran su borde en la nueva posición mientras el editor y el área de hit del mouse se quedan en las coordenadas viejas
  • El visor conserva un page handle que el layout ya reemplazó, así que clics y pintados van a una página que ya no existe en ese formulario

Persistir ediciones de filas a través de guardar y reabrir es un problema separado con reglas propias; este artículo se queda con lo que pasa en runtime dentro del visor

¿Qué runtime de PDFium necesita el XFA dinámico?

El XFA dinámico en PDFium Component requiere el build V8/XFA de la librería nativa, seleccionado por la variable global EnableV8Engine de la unidad PDFium antes de que el primer documento cargue. El proceso se compromete a una sola DLL la primera vez que cualquier TPdf carga la librería, y un build plain de PDFium no puede correr el motor XFA para nada. Cuando un documento se abre, TPdf sí espía el archivo buscando marcadores XFA y cambia al build V8 automáticamente, pero solo si ninguna librería plain se ha cargado aún en ese proceso. Cuando el compromiso ya fue por el camino equivocado, TPdf.OnXfaRuntimeMissing se dispara una vez para que el host pueda decirle al usuario que reinicie. Poner el flag explícitamente al arranque elimina la adivinanza. La estructura de callbacks FPDF_FORMFILLINFO que porta los eventos XFA también debe coincidir con la DLL; el trasfondo está en FPDF_FORMFILLINFO versión 2 y el ABI de callbacks XFA, y detectar formularios XFA y leer sus packets cubre cómo distinguir los tipos de formulario antes de abrir un visor

uses
  PDFium;

procedure TClaimForm.FormCreate(Sender: TObject);
begin
  // Decida antes de que el primer TPdf cargue la librería nativa:
  // el proceso no puede cambiar de pdfium.dll a pdfium.v8.dll después
  EnableV8Engine := True;

  FPdf := TPdf.Create(nil);
  FPdf.OnXfaRuntimeMissing := PdfXfaRuntimeMissing;
  FPdf.OnXfaPageCountChanged := PdfXfaPageCountChanged;
  FPdf.FileName := 'C:\Forms\expense-claim.pdf';
  FPdf.Active := True;

  PdfView1.Pdf := FPdf;
  PdfView1.OnPageChange := PdfViewPageChange;
  PdfView1.Active := True;

  UpdatePageRange(FPdf.PageCount);
end;

procedure TClaimForm.PdfXfaRuntimeMissing(Sender: TObject);
begin
  StatusBar1.SimpleText :=
    'This XFA form needs the V8 runtime; restart the application to enable it';
end;

¿Por qué PageCount reportaría 1 para un formulario de dos páginas?

Un wrapper que guarda el argumento page_count del evento de página nativo como el total del documento se equivoca, porque ese argumento es en realidad la diferencia absoluta entre el conteo nuevo y el viejo. PDFium dispara FFI_PageEvent después de que una pasada de layout termina, con un tipo de evento de página agregada o página quitada; internamente actualiza primero su conteo almacenado y luego pasa abs(new - old). En el layout inicial el conteo viejo es cero, así que el delta iguala el total, y una muestra estática de tres páginas reporta tres páginas como se espera. Eso es exactamente por qué los formularios de prueba de longitud fija nunca exponen el error. La primera vez que un formulario dinámico crece de una página a dos, el delta es 1, y tal wrapper reporta un conteo de páginas de 1. Quitar una fila de un formulario de tres páginas produce el mismo tipo de disparate en la otra dirección

Acumular el delta sobre el valor anterior tampoco es una reparación segura. El orden de los callbacks de inicialización y layout implica que el wrapper no siempre puede confiar en su conteo anterior como baseline, así que una suma corrida puede derivar. El callback de PDFium Component por eso ignora el argumento como conteo y llama a FPDF_GetPageCount sobre el documento, que lee el total del layout recién completado. Después limpia las escenas de página cacheadas, guarda ese total como el override de conteo de páginas XFA detrás de TPdf.PageCount, y solo entonces dispara OnXfaPageCountChanged. Para cuando corre su handler, NewCount y FPdf.PageCount coinciden

Diagrama de XFA dinámico de PDFium Component donde agregar una fila repagina un formulario de una página a dos páginas y FFI_PageEvent pasa abs(new minus old) como delta, así que tratarlo como total reportaría un conteo de páginas de 1, mientras que PDFium Component lee FPDF_GetPageCount y reporta el total correcto
El evento de página nativo reporta un delta de agregada-o-quitada, no un total, así que PDFium Component ignora el argumento y lee el layout completado antes de disparar OnXfaPageCountChanged
procedure TClaimForm.PdfXfaPageCountChanged(Sender: TObject; NewCount: Integer);
begin
  // NewCount es el total del layout completado, nunca un delta.
  // Esto corre dentro del callback de layout de PDFium: actualice solo el estado de UI del host,
  // no cierre el documento ni recargue páginas desde aquí
  UpdatePageRange(NewCount);
end;

procedure TClaimForm.PdfViewPageChange(Sender: TObject);
begin
  // Se dispara después de cada recarga de página, incluido el refresh XFA diferido
  PageSpin.Value := PdfView1.PageNumber;
end;

procedure TClaimForm.UpdatePageRange(Count: Integer);
begin
  PageSpin.MinValue := 1;
  PageSpin.MaxValue := Count;
  PageLabel.Caption := Format('of %d', [Count]);
end;

El evento solo se dispara para formularios Full XFA cuyo layout cambia en runtime. Los documentos XFA estático y AcroForm nunca lo disparan, así que un visor que maneja ambos puede dejar el mismo handler asignado. Dejarlo sin asignar también es seguro; el override detrás de TPdf.PageCount se aplica de todas formas, y el evento existe para que el host refresque lo que haya cacheado

¿Por qué el cuadro de entrada se queda en la página vieja cuando un field se mueve?

El borde se mueve y el editor no cuando el notificador XFA nativo compara un rectángulo consigo mismo. Cuando el layout cambia la geometría de un widget ya cargado, se supone que PDFium nota el nuevo rectángulo y llama a PerformLayout sobre el widget, lo que recoloca el editor de texto y su área de hit. Un chequeo que compara GetWidgetRect() contra RecacheWidgetRect() nunca puede dispararse: ambas funciones devuelven una referencia const al mismo miembro, y el recache sobrescribe ese miembro en el lugar, así que la comparación siempre ve dos valores idénticos y los widgets cargados se saltan su relayout

El síntoma aparece cuando la altura de un subform cambia de modo que fields existentes cruzan a la página siguiente: el borde del field se dibuja en su nueva posición mientras el texto tipeado y el área de hit del mouse se quedan en la coordenada Y anterior. Un relayout explícito no ayuda, ni tampoco recargar la página, porque el widget sigue creyendo que su geometría está al día. Las librerías V8 de Windows que vienen con PDFium Component copian el rectángulo viejo por valor antes de recachear y comparan esa copia, así que los widgets movidos hacen relayout y el valor editado aparece exactamente donde está el borde. El chequeo vive en código nativo y viaja con las DLLs, así que distribuya pdfium.v8.dll junto con las unidades Pascal. Para comprobarlo usted mismo, edite primero una fila sobreviviente a un valor no por defecto y luego busque ese valor en la nueva ubicación del field, porque una fila reconstruida con valores por defecto parecería un pase

Diagrama de relayout de widgets de PDFium Component que contrasta una autocomparación donde GetWidgetRect y RecacheWidgetRect devuelven un mismo miembro compartido así los widgets movidos se saltan PerformLayout, con el chequeo de copia por valor de las V8 de Windows que recoloca el editor y el área de hit del mouse sobre el borde redibujado
Comparar un rectángulo consigo mismo nunca detecta un cambio, así que el borde se mueve mientras el texto tipeado y los clics se quedan atrás, salvo que el chequeo guarde primero una copia por valor

¿Cómo recarga páginas TPdfView sin arrancar un handle de debajo de PDFium?

TPdfView difiere la recarga de páginas que sigue a un cambio de layout XFA hasta que la pila de llamadas nativa se haya desenrollado. El evento de página suele dispararse mientras PDFium aún procesa entrada: el usuario hizo clic en un botón Add Row, el clic corrió un script, el script cambió el conteo de instancias, y el layout terminó dentro de esa misma llamada nativa. Cerrar y reabrir el page handle en ese momento liberaría un objeto que el llamador aún está usando. Un visor que solo se invalida en ese momento conserva un page handle que apunta a estado pre-layout, y si el usuario estaba en la última página cuando desapareció, el número de página seleccionada queda fuera de rango

El refresh diferido funciona en unos pocos pasos chicos, y explican el comportamiento que usted ve desde el host:

  1. El callback de evento de página marca la vista como con un refresh de layout XFA pendiente y postea un mensaje de ventana privado; los eventos repetidos antes de que llegue el mensaje se fusionan en un solo refresh
  2. Una vista sin handle de ventana todavía guarda el flag pendiente y postea el mensaje desde CreateWnd, mientras que cambiar de documento, desactivar la vista o destruirla limpia el flag
  3. Cuando llega el mensaje, la vista limpia la selección de texto, el resaltado de búsqueda y el índice del field con foco, porque los tres se referían al layout viejo
  4. La página seleccionada se clampea al nuevo PageCount; un número de página cambiado pasa por el cambio de página normal, si no, la página actual se recarga, y el fit mode se aplica otra vez
  5. Si el layout no deja páginas para nada, la vista descarga su page handle viejo en vez de pintar una página que ya no existe
Diagrama del refresh XFA diferido de TPdfView en PDFium Component donde un evento de página dentro de la pila de llamadas de layout nativa solo marca un refresh pendiente y postea un mensaje de ventana, que luego limpia el estado de selección desactualizado, clampea la página al nuevo PageCount y recarga o descarga el page handle
La recarga espera hasta que la pila de llamadas nativa se desenrolla: un mensaje posteado fusiona eventos repetidos, luego la vista clampea la página, la recarga y dispara OnPageChange

La misma restricción aplica a su propio código. OnXfaPageCountChanged corre dentro de ese callback de layout nativo, así que trátelo como una notificación: actualice labels, rangos de spinner y estado de toolbar ahí, y ponga en cola cualquier cosa más pesada, como cerrar el documento o abrir otro, con un mensaje posteado para que corra después de que el callback devuelva. TPdfView.OnPageChange entonces le dice cuándo la vista realmente recargó la página, y leer PdfView1.PageNumber en ese punto le da el valor clampeado. El traversal con la tecla Tab y los chequeos de FormType que un visor de formularios corre al abrir están cubiertos en navegación de form fields con PDFium Component

¿Cómo trata el visor las páginas Full XFA que no tienen capa de texto?

Las páginas Full XFA no tienen página de texto PDF, así que cualquier cosa que pida una sobre tal página falla con un error Cannot open text page. La selección de texto por defecto del visor y la detección de links consultan ambas esa capa: con TPdfView.AllowUserTextSelection en su default True, el hover le pide a la capa de texto un carácter bajo el mouse, y un clic de mouse-up corre una sonda automática de URLs sobre el texto de la página. En TPdfView ambos caminos internos devuelven sin resultado cuando TPdf.FormType es ftXfaFull y el runtime XFA está disponible, así que las configuraciones por defecto funcionan y la entrada en fields sigue disponible

Apagar AllowUserTextSelection para documentos Full XFA es una elección razonable de UI, porque no hay texto de página que seleccionar y los gestos de arrastre no deberían iniciar un modo de selección

procedure TClaimForm.ConfigureViewerForForm;
begin
  // FormType lee el documento abierto, así que llame a esto después de FPdf.Active := True
  if FPdf.XFA and (FPdf.FormType = ftXfaFull) and FPdf.XfaRuntimeAvailable then
  begin
    // No existe capa de texto PDF en las páginas Full XFA; los fields siguen editables
    PdfView1.AllowUserTextSelection := False;
    StatusBar1.SimpleText := Format('Dynamic XFA form, %d page(s)',
      [FPdf.PageCount]);
  end
  else
    PdfView1.AllowUserTextSelection := True;
end;

Tipear sobre una selección necesita su propio manejo. El editor de texto XFA nativo no reemplaza una selección cuando recibe un carácter: FORM_OnChar inserta en el caret, y Backspace borra un solo carácter, así que pasar las teclas directo pondría texto viejo y nuevo lado a lado. PDFium Component recuerda que el clic aterrizó sobre un text field XFA y enruta los caracteres tipeados, Backspace y Delete a través de FORM_ReplaceSelection siempre que exista una selección y el documento conceda permiso de llenar formularios o de modificación. Si un field XFA read-only puede cambiar lo decide el editor nativo, así que un field marcado read-only en el formulario conserva su valor incluso en un documento que por lo demás permite llenar. Poner TPdfView.AllowFormEvents en False también detiene este enrutamiento de teclado, lo que mantiene un visor read-only read-only

Referencia rápida: XFA dinámico en un visor Delphi

SíntomaCausaResuelto por
El conteo de páginas muestra 1 después de que el formulario crece a dos páginasEl evento de página nativo pasa un delta de agregadas/quitadas, no un totalTPdf.PageCount lee el layout completado
El borde del field se mueve, el texto tipeado y el área de hit se quedan atrásEl widget cargado se salta el relayout tras una autocomparaciónChequeo de copia por valor en las librerías V8 de Windows
El visor pinta o enruta entrada a estado de página pre-layoutPage handle no recargado tras la repaginaciónRefresh diferido en TPdfView
Un clic en un field pide una página de texto que no existeSelección de texto y sonda de URL en páginas sin capa de textoLos caminos de texto devuelven sin resultado en páginas ftXfaFull
Tipear sobre un valor seleccionado agrega en vez de reemplazarEl editor XFA nativo inserta en el caretTeclas enrutadas a través de FORM_ReplaceSelection
  • Ponga EnableV8Engine en True antes de que cualquier documento cargue, y maneje OnXfaRuntimeMissing para el caso en que la librería plain se cargó primero
  • Lea el total desde TPdf.PageCount o el parámetro NewCount de OnXfaPageCountChanged; nunca sume ni reste conteos de páginas por su cuenta
  • Mantenga liviano el handler de OnXfaPageCountChanged, porque corre dentro del callback de layout nativo
  • Sincronice el indicador de página actual en TPdfView.OnPageChange, que se dispara después de que la recarga diferida clampea el número de página
  • Distribuya las DLLs V8 de Windows junto con las unidades; el chequeo de relayout de widgets vive en código nativo
  • Pruebe con un formulario que de verdad cambie su conteo de páginas y mueva un field editado a través de un salto de página, porque las muestras de longitud fija esconden cada problema de esta lista

El XFA dinámico convierte el conteo de páginas y la geometría de fields en valores vivos, y un visor se mantiene correcto solo cuando los toma del layout completado y recarga páginas en un momento seguro. PDFium Component maneja ambas cosas dentro de TPdf y TPdfView, así que al host solo le queda escuchar. Detalles y descargas en la página del producto PDFium Component para Delphi