Un párrafo que empieza al final de la página 4 y termina al principio de la página 5 es un solo párrafo para quien lo lee. En un PDF etiquetado vive en dos streams de contenido, y cada página numera sus secuencias de marked content por su cuenta, así que el árbol de estructura necesita un único elemento P cuyo arreglo /K apunte, por ejemplo, al MCID 7 de la página 4 y al MCID 3 de la página 5. Dibuje las páginas con código de coordenadas y agregue el etiquetado después, y el tag tree de un accessibility checker típicamente muestra dos párrafos donde había uno, más un set de títulos de columna repetido dentro de los datos de cada tabla continuada
El enfoque de coordenadas tiene un segundo costo que llega antes. La primera versión de un informe funciona. Luego la dirección de un cliente crece a tres líneas, un encabezado localizado se parte en dos, una tabla gana cuarenta filas, y cada posición y por debajo de ese punto queda mal. Las verificaciones de salto de página terminan dispersas por la lógica de negocio, y un código que solo conoció x e y no tiene idea de dónde empieza un párrafo cuando el requisito de accesibilidad aparece dos años después
Construir un árbol de diseño HotPDF en Delphi
HotPDF responde a ambos problemas con un árbol de diseño declarativo en la unidad HPDFLayoutDOM. Un THPDFDOMDocument contiene secciones; cada THPDFDOMSection tiene un tamaño de página, márgenes, un encabezado y un pie opcionales, y una pila Body donde se agregan texto, títulos, spacers, listas, imágenes, contenedores y tablas. Nada en el árbol lleva una coordenada y. THPDFDOMRenderer mide el árbol, decide los saltos de página, dibuja el encabezado y el pie en cada página y, como GenerateStructure vale True por defecto, va escribiendo el árbol de estructura sobre la marcha
La posesión en el árbol es estricta. El documento posee sus secciones, una sección posee su cuerpo, su encabezado y su pie, y las pilas, contenedores y tablas poseen a sus hijos, así que Section.Body.Add(Table) entrega la tabla para siempre. Un componente adjunto a dos padres se mediría dos veces con restricciones distintas y se liberaría dos veces al desmontar. Las piezas repetidas, como un bloque de firma, salen entonces de Clone, de SetHeaderClone / SetFooterClone, o de una factory registrada con RegisterComponent, tras lo cual cada llamada a CreateComponent('signature') devuelve una instancia nueva
uses
SysUtils, HPDFDoc, HPDFLayoutDOM;
type
TAssetRow = record // su propio tipo de datos
Name, ServiceDate, Status: WideString;
end;
function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
Doc: THPDFDOMDocument;
Section: THPDFDOMSection;
Heading: THPDFDOMText;
Table: THPDFDOMTable;
Row: THPDFDOMTableRow;
I: Integer;
begin
Doc := THPDFDOMDocument.Create; // GenerateStructure = True, Language = 'en-US'
try
Section := Doc.AddSection; // A4 vertical, márgenes de 36 pt por defecto
Section.MarginLeft := 56;
Section.MarginRight := 56;
Section.Style.FontName := 'Helvetica';
Section.Style.FontSize := 10;
Section.Style.LineHeight := 13;
Section.Body.Style.Spacing := 6; // espacio entre los hijos del cuerpo
Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');
Heading := Section.Body.AddHeading('Annual maintenance report', 1);
Heading.Style.FontSize := 18;
Heading.Style.LineHeight := 22; // LineHeight no sigue a FontSize
Section.Body.AddText('Every asset inspected during the reporting ' +
'period is listed below, grouped by site.');
Table := THPDFDOMTable.Create('assets'); // RepeatHeaders es True por defecto
Table.AddColumn(3); // pesos, no anchos en puntos
Table.AddColumn(1);
Table.AddColumn(1);
Row := Table.AddRow(18, True); // las filas de encabezado van primero
Row[0].Text := 'Asset';
Row[1].Text := 'Last service';
Row[2].Text := 'Status';
for I := 0 to High(Assets) do
begin
Row := Table.AddRow(16);
Row[0].Text := Assets[I].Name;
Row[1].Text := Assets[I].ServiceDate;
Row[2].Text := Assets[I].Status;
end;
Section.Body.Add(Table); // el cuerpo es dueño de la tabla desde aquí
Result := Doc;
except
Doc.Free;
raise;
end;
end;
Dos valores por defecto de ese listado toman por sorpresa a más de uno. LineHeight se resuelve en 12 puntos a menos que un estilo de la cadena lo fije, sin importar lo que diga FontSize, así que un título de 18 pt sin LineHeight propio obtiene líneas de 12 pt y se encima con el siguiente. Y una fila de tabla mide exactamente lo alto que se le pasa a AddRow: el texto de la celda sale en una sola línea, así que dimensione las filas para la fuente que eligió
Render abre y cierra el documento por sí mismo
THPDFDOMRenderer.Render(Doc, Pdf) llama a BeginDoc en el destino, renderiza cada sección y llama a EndDoc antes de devolver. No lo envuelva en su propio par BeginDoc / EndDoc. Todo lo que deba fijarse antes de que el documento arranque va primero en la instancia THotPDF: FileName, Title y PDFUACompliance si la salida debe declarar PDF/UA. Con la generación de estructura activa, Render también enciende EnableTaggedPDF y copia Doc.Language a Pdf.Lang si usted lo dejó vacío
var
Doc: THPDFDOMDocument;
Pdf: THotPDF;
Renderer: THPDFDOMRenderer;
Stats: THPDFDOMRenderStatistics;
begin
Doc := BuildMaintenanceReport(Assets);
Pdf := THotPDF.Create(nil);
Renderer := THPDFDOMRenderer.Create;
try
Pdf.FileName := 'maintenance-report.pdf';
Pdf.Title := 'Annual maintenance report';
Pdf.PDFUACompliance := True; // también activa la verificación del alt text de la figura
// Aquí no hay BeginDoc / EndDoc: Render abre y cierra el documento
Stats := Renderer.Render(Doc, Pdf);
Writeln(Format('%d page(s), %d placement(s), %d split(s)',
[Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
[Stats.StructureElementCount, Stats.MarkedContentCount,
Stats.ArtifactCount]));
Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
[Stats.HeaderDrawCount, Stats.FooterDrawCount,
Stats.MaximumContinuationDepth]));
finally
Renderer.Free;
Doc.Free;
Pdf.Free;
end;
end;
Registre el record de estadísticas en cada ejecución, porque muestra regresiones de plantilla que nunca provocan una excepción. Un SplitCount que salta después de un cambio de plantilla suele significar que algún componente ahora mide más alto que el espacio en el que antes cabía. Un MaximumContinuationDepth que sube poco a poco apunta a un componente cuyo Split mueve muy poco contenido por página. ArtifactCount cubre encabezados y pies de página, bordes decorativos como el marco de 0.5 pt por defecto de la tabla, y filas de encabezado repetidas, así que compárelo entre ejecuciones de la misma plantilla en lugar de contra un target calculado a mano
¿Cómo pagina una tabla larga sin copiarse en cada página?
El renderizador divide solo lo que cruza el límite de página. La forma ingenua de paginar un árbol es clonar lo que no cupo y llevar la copia a la página siguiente; en una tabla de diez mil filas eso clona las filas restantes una vez por página y convierte un trabajo lineal en uno cuadrático. HotPDF recorre los hijos del cuerpo por índice y nunca clona una sección o un cuerpo completos. Una pila o un contenedor anidado que cruza un límite de página solo tiene clonado su subárbol afectado, y los dos tipos de hoja pesados llevan un cursor en lugar de una copia
Un párrafo continuado es una referencia al texto original más el rango de caracteres que aún debe, y reutiliza los saltos de línea ya calculados para ese ancho. Una tabla continuada es una referencia a la tabla original más la franja de filas que falta por colocar. Un párrafo de 300 líneas cuesta lo mismo ya sea que se corte una vez o cinco
La colocación en sí pasa por el THotPDF.PlaceLayoutElement público. Mide el elemento contra la altura restante del cuerpo, lo dibuja entero si cabe y, si no, le pide Split, vuelve a medir la mitad colocada, la dibuja y devuelve el resto como un objeto de overflow que el renderizador lleva a una página nueva. Measure nunca debe dibujar nada; puede ejecutarse varias veces para una sola colocación. El renderizador DOM agrega, encima de esa rutina, el mobiliario de página, el espaciado entre hijos y las decisiones de página nueva
¿Por qué una sola fila de encabezado puede detener todo el render?
Las filas de encabezado repetidas traen dos reglas, y ambas existen para impedir que un informe produzca páginas sin datos. Las filas de encabezado deben formar la primera serie de filas: AddRow(Height, True) después de cualquier fila de cuerpo levanta EInvalidOpException con “Table header rows must precede body rows”. Y la primera división de una tabla debe acomodar todas las filas de encabezado más al menos una fila de cuerpo. Una tabla que dejaría el encabezado varado al pie de una página se pasa a la página siguiente
La segunda regla tiene un filo duro. Si las filas de encabezado más una fila de cuerpo no caben ni siquiera en una página vacía, no hay ninguna página donde la tabla pueda empezar, y Render levanta “Layout component ... cannot fit an empty body page” con la ruta del componente, por ejemplo Sections[0]/Body/Items[2]/assets. Ese es el comportamiento que conviene tener. Un motor de diseño que siguiera agregando páginas con la esperanza de que la próxima fuera más espaciosa convertiría un solo encabezado sobredimensionado en un bucle que llena el disco
Los componentes personalizados reciben la misma protección. Haga una subclase de THPDFDOMComponent, implemente Clone, Measure, Draw y Split, y el renderizador cuenta cuántas continuaciones produce cada hijo del cuerpo. Por encima de THPDFDOMRenderer.MaximumContinuationDepth (100 mil por defecto) el render se detiene con “exceeded the continuation depth limit”. Un Split que sigue devolviendo una cola equivalente, y por eso nunca avanza, falla con una ruta de componente en lugar de correr hasta llenar el disco
En las páginas de continuación las filas de encabezado se dibujan de nuevo dentro de una secuencia de marked content /Artifact, y el árbol de estructura conserva el TR original una sola vez. La extracción de texto por eso no inserta una fila de encabezado duplicada entre las filas de datos, y la tecnología de asistencia no anuncia los títulos de columna otra vez en medio de la tabla. Cada celda de encabezado se etiqueta como TH con un atributo /Scope /Column
Un párrafo lógico, varios fragmentos de página
Un párrafo dividido sigue siendo un elemento de estructura P. Cada fragmento visible abre una nueva secuencia de marked content en su propia página, y HotPDF agrega un diccionario de referencia de marked content, << /Type /MCR /Pg page /MCID n >>, al arreglo /K de ese elemento y registra el MCID en la entrada del ParentTree de la página que apunta de vuelta al mismo elemento. Ese es el esquema que ISO 32000-1 §14.7.4 describe para ítems de contenido repartidos entre páginas, y es lo que permite que una vista del tag tree muestre un párrafo donde las páginas muestran dos pedazos
La identidad semántica es la razón por la que las copias de continuación se comportan distinto de sus propios clones. Llamar a Clone significa “contenido lógico nuevo”, y el resultado recibe un elemento de estructura nuevo cuando se dibuja. Las copias hechas durante la paginación heredan la identidad del componente que continúan, así que una pila partida en tres páginas sigue produciendo un Div, y una lista partida en dos sigue produciendo un L. Los encabezados y pies de página toman otro camino: se envuelven como /Artifact << /Type /Pagination /Subtype /Header >> (o /Footer) en cada página y nunca entran al árbol de estructura
Reglas de estructura verificadas mientras el árbol se renderiza
Con GenerateStructure activado, el renderizador rechaza de antemano la estructura que la validación PDF/UA reprocharía después. El primer título debe ser H1 y los títulos siguientes no pueden saltarse un nivel, así que un H3 justo después de un H1 levanta “Semantic heading levels cannot skip an intermediate level”. LI necesita un padre L, Lbl y LBody necesitan un LI, TR necesita una tabla o un grupo de filas, y TH / TD necesitan un TR. Cuando el destino tiene PDFUACompliance activo, una Figure sin texto alternativo también se rechaza. Cada violación detiene Render con una excepción
var
List: THPDFDOMList;
Bmp: TBitmap; // Vcl.Graphics
begin
Section.Body.AddHeading('Findings', 2); // el H1 vino primero, así que H2 es legal
List := THPDFDOMList.Create('Decimal'); // etiquetada como L, ListNumbering /Decimal
List.AddItem('1.', 'Replace the intake filter on pump P-14');
List.AddItem('2.', 'Re-torque the flange bolts on line 3');
Section.Body.Add(List); // AddItem construye LI, Lbl y LBody
Bmp := TBitmap.Create;
try
Bmp.LoadFromFile('site-plan.bmp');
// La imagen copia el gráfico; un alt text vacío falla bajo PDFUACompliance
Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
'Site plan of plant 3 with the inspected pumps circled'));
finally
Bmp.Free;
end;
end;
Verificar durante el render es el lugar correcto para estas reglas. El momento es la razón. Un validador que reporta un texto alternativo faltante después de que el archivo ya se escribió le dice que un lote de diez mil estados de cuenta debe regenerarse; una excepción durante Render nombra la regla que falló mientras el record que la produjo sigue en alcance. La verificación formal de conformidad sigue perteneciendo a la canalización, y como los objetos del documento siguen legibles después de que Render devuelve, puede ejecutarse de inmediato. La validación de PDF/A, PDF/X y PDF/UA cubre ese paso, y el orden de estructura y la extracción de texto muestra cómo el tag tree gobierna lo que las herramientas de extracción leen de vuelta
Cuándo conviene seguir dibujando a mano
El árbol dibuja sobre los mismos objetos THPDFPage que la API directa. Como Render es dueño del documento desde BeginDoc hasta EndDoc, el arte posicionado a mano, como la imagen de una firma, pertenece dentro del árbol: el Draw de un componente personalizado recibe la página y sus bounds y desde allí puede llamar a los métodos ordinarios de página. El cierre de página queda en AddPage y EndDoc, así que con ImmediateFlushLayout activado en la instancia THotPDF, las páginas terminadas se escriben a medida que el render avanza y el renderizador no retiene páginas completas; la memoria queda entonces gobernada por las continuaciones abiertas, los recursos de fuente y el grafo de objetos del documento
El componente de texto del DOM parte las líneas a partir de un avance promedio estimado de 0.55 × tamaño de fuente por carácter y le da a cada línea el LineHeight resuelto. Eso mantiene la medición barata e idéntica en cualquier máquina, y es de sobra para informes guiados por datos. El texto con glifos anchos, como mayúsculas sostenidas, tramos en bold o CJK, sale más ancho que la estimación, así que deje holgura en esos anchos de columna y pruebe el diseño una vez con la cadena real más larga. Las páginas compuestas con métricas de glifo exactas, fuentes mezcladas dentro de una línea o párrafos justificados quedan mejor servidas por la API directa de texto; la justificación de texto recorre ese camino, y si lo único que duele es la paginación de tablas, generar tablas en PDF es el cambio más pequeño
El árbol de diseño, su renderizador, el etiquetado descrito aquí y la API de dibujo directo se distribuyen todos en un solo componente para Delphi y C++Builder; las ediciones y la lista completa de funciones están en la página del componente PDF HotPDF para Delphi