En PDFium Component, leer una anotación vía TPdf.Annotation[] y asignar el record de vuelta no escribe nada nuevo cuando nada cambió: el getter solo reporta una apariencia que de verdad haya leído, así que una anotación que solo lleva /N vuelve con solo /N. El detalle merece entenderse, porque un lado de lectura que sobre-reporta apariencias añade entradas /R y /D vacías al diccionario de apariencias /AP, los validadores PDF/A rechazan ese diccionario, y el disparador habitual es un arreglo pensado para hacer un archivo más conforme, no menos
¿Qué sale mal cuando reescribes una anotación sin cambios?
La respuesta corta: si el lado de lectura sobre-reporta, la anotación gana streams de apariencia que nunca tuvo, y un archivo que pasaba la validación PDF/A antes de su edición la suspende después. El escenario típico va así. Llega un archivo de cliente con anotaciones square y text sin el flag Print, PDF/A exige que toda anotación se imprima, así que se recorren las páginas, se añade afPrint y se reasigna cada record. Nada en ese código toca apariencias. El record de TPdf.Annotation[] es un TPdfAnnotation, y SetAnnotationData escribe todo campo cuyo centinela Has* esté activado, que es exactamente como funcionan las parejas HasContents / ContentsText. La trampa es un getter que pone HasAppearanceRollover y HasAppearanceDown a True con cadenas vacías para los modos que no existen; el setter entonces obedientemente escribe dos streams vacíos. El getter de PDFium Component reporta solo lo que leyó, así que el bucle de abajo escribe de vuelta solo las apariencias que el origen tenía:
procedure MarkAnnotationsPrintable(const FileName: string);
var
Pdf: TPdf;
PageNo, I: Integer;
A: TPdfAnnotation;
begin
Pdf := TPdf.Create(nil);
try
Pdf.FileName := FileName;
Pdf.Active := True;
for PageNo := 1 to Pdf.PageCount do
begin
Pdf.PageNumber := PageNo;
for I := 0 to Pdf.AnnotationCount - 1 do
begin
A := Pdf.Annotation[I];
if not (afPrint in A.Flags) then
begin
A.Flags := A.Flags + [afPrint] - [afHidden, afInvisible, afNoView];
// El getter reporta solo las apariencias que leyó, así que un origen
// con solo /AP/N se escribe de vuelta con solo /AP/N
Pdf.Annotation[I] := A;
end;
end;
end;
Pdf.SaveAs(ChangeFileExt(FileName, '.printable.pdf'));
finally
Pdf.Free;
end;
end;
ISO 32000-1 §12.5.5 define el diccionario de apariencias con tres entradas: /N para la apariencia normal, /R para rollover y /D para down. /R y /D son opcionales, y cuando faltan el visor cae de vuelta a /N. Un stream /R vacío no es una ausencia, eso sí. Es un stream válido que no pinta nada, así que un visor que honra las apariencias de rollover muestra un rectángulo en blanco en cuanto el puntero pasa sobre la anotación. PDF/A es más estricto todavía: ISO 19005-1 (con Corrigendum 2) e ISO 19005-2 / 19005-3 solo permiten /N en un diccionario de apariencias de anotación. veraPDF reporta el archivo tras el round trip bajo la regla 6.5.3-4 para PDF/A-1 y la 6.3.3-2 para PDF/A-2 y PDF/A-3, y el TPdf.ValidatePdfA integrado lo lista como pvaiAnnotationApDictViolation. La edición que añadió el flag Print para satisfacer una cláusula del estándar rompió otra
¿Por qué FPDFAnnot_GetAP devuelve 2 para una apariencia ausente?
PDFium nunca devuelve cero de FPDFAnnot_GetAP, ni siquiera cuando el stream de apariencia pedido no existe. La función sigue el patrón habitual de PDFium de dos llamadas: se pasa un buffer nil para obtener el tamaño necesario en bytes, se reserva, y se llama de nuevo para copiar el texto UTF-16LE. El tamaño siempre incluye el terminador UTF-16, así que un stream ausente reporta 2 bytes, una cadena vacía más su terminador. La puerta obvia, ByteLength >= SizeOf(FPDF_WCHAR), es una comprobación que toda llamada pasa, así que un getter construido sobre ella reporta los tres flags HasAppearance* como True para cualquier anotación con cualquier apariencia. Un round trip vía el record le pide entonces a FPDFAnnot_SetAP que guarde una cadena vacía por cada modo, y PDFium crea el stream para contenerla. Sin excepción, sin aviso, y la página visible se ve idéntica, razón por la que este error aflora en un validador PDF/A y no en un visor
Cómo decide PDFium Component que una apariencia existe
ReadAppearance, el helper dentro de GetPageAnnotation que rellena AppearanceNormal, AppearanceRollover y AppearanceDown, solo trata un resultado como contenido cuando trae al menos un carácter más allá del terminador. La primera llamada debe devolver más de SizeOf(FPDF_WCHAR) bytes y un número par de bytes, porque una longitud impar no puede ser UTF-16. La segunda llamada, la que copia de verdad el texto, se valida otra vez: una longitud devuelta de 2 o menos, o una mayor que el buffer reservado, reinicia HasValue a False y deja la cadena vacía. En el lado de escritura, SetAnnotationData llama a FPDFAnnot_SetAP solo para los modos cuyo flag HasAppearance* esté a True, así que un record leído de una anotación que solo tiene /N escribe de vuelta solo /N
Streams ausentes y vacíos se ven iguales, así que el getter se queda conservador
La API nativa no puede distinguir un stream de apariencia ausente de uno que existe pero está vacío, y PDFium Component no finge lo contrario. Ambos casos devuelven los mismos 2 bytes de FPDFAnnot_GetAP, así que ambos se leen como HasAppearanceRollover = False con un AppearanceRollover vacío. Eso tiene dos consecuencias para las que conviene diseñar. Primera, un centinela False significa «no se leyó contenido, así que una reescritura dejará este modo en paz», no «la clave /R está ausente del diccionario». Segunda, el record no puede detectar un stream vacío que ya está en el archivo: un documento que ya lleva un stream vacío, lo que sea que lo escribiera, se lee limpio, y reasignar el record ni lo repara ni lo empeora. Para encontrar esos archivos necesitas una comprobación a nivel de bytes, que es para lo que están TPdf.ValidatePdfA y el flujo de validación preflight PDF/A con PDFium Component
¿Cómo borras una apariencia a propósito?
Activas el centinela explícitamente y pasas una cadena vacía; el setter la escribe. Bloquear cadenas vacías en SetAnnotationData sería una forma contundente de evitar streams espurios, pero también rompería a quienes borran una apariencia deliberadamente, el mismo contrato que HasContents y HasAuthor siguen para texto. Así que la cautela vive en el getter, y el setter honra lo que el invocador pida:
// Sustituye la apariencia rollover y luego bórrala otra vez
A := Pdf.Annotation[0];
A.HasAppearanceRollover := True;
A.AppearanceRollover := 'q Q';
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// A.HasAppearanceRollover está a True y el texto hace round trip como 'q Q'
A.HasAppearanceRollover := True; // reafirma la intención explícitamente
A.AppearanceRollover := ''; // escribe un stream vacío a propósito
Pdf.Annotation[0] := A;
A := Pdf.Annotation[0];
// Se lee como HasAppearanceRollover = False con una cadena vacía:
// un stream vacío y uno ausente son indistinguibles aquí
Ten presente que un /R o /D vaciado explícitamente sigue contando como clave extra bajo las reglas PDF/A citadas arriba. Si el objetivo es un perfil de archivo, escribir un /N no vacío y dejar los otros dos modos intactos es la única forma que valida. Cualquier flujo que mueva anotaciones entre documentos, como la exportación e importación XFDF con PDFium Component, debería seguir la misma regla: copia los modos que el origen realmente tenía y deja los demás centinelas a False
Un patrón leer-modificar-escribir que se mantiene a salvo con PDF/A
Deja los centinelas de apariencia exactamente como los devolvió el getter, y valida el archivo guardado antes de enviarlo. Como un stream vacío obsoleto se lee como ausente, el paso de verificación tiene que mirar el documento serializado y no el record, y es lo bastante barato para ejecutarlo tras cada lote:
uses
PDFium, FPdfPdfa; // FPdfPdfa declara TPdfAValidationIssue
function AnnotationAppearancesAreClean(Pdf: TPdf): Boolean;
var
Report: TPdfAValidationResult;
begin
// Valida el documento cargado actualmente en Pdf, incluidas las ediciones
// hechas vía Pdf.Annotation[] desde que se abrió
Report := Pdf.ValidatePdfA;
Result := not (pvaiAnnotationApDictViolation in Report.Issues);
end;
La misma disciplina vale para cualquier panel que recoloree o anote páginas para revisión, un flujo que cubre montar un flujo de revisión de anotaciones en Delphi con PDFium Component: el record es una instantánea de lo que el motor pudo leer, y un centinela que no pusiste tú debe viajar de vuelta sin cambios. La API completa de anotaciones, el preflight PDF/A y el motor nativo PDFium se envían juntos en PDFium Component para Delphi, C++Builder y Lazarus