MergeFiles

Componente: TPdf · Unidad: PDFium

Combina fuentes PDF respaldadas en archivos mediante API nativas de importación de páginas, acotando los manejadores de fuentes y exponiendo políticas de operación explícitas

Syntax

function MergeFiles(const Sources: TPdfBatchMergeSources; out Report: TPdfBatchMergeReport): Boolean; overload;

function MergeFiles(const Sources: TPdfBatchMergeSources; const Options: TPdfBatchMergeOptions; out Report: TPdfBatchMergeReport): Boolean; overload;

class function TPdfBatchMergeSource.FromFile(const AFileName: string; const APageRange: string = ''; const APassword: string = ''): TPdfBatchMergeSource; static;

class function TPdfBatchMergeOptions.Default: TPdfBatchMergeOptions; static;

Source selection

FileName identifica una fuente PDF respaldada en archivo
Password se aplica antes de abrir la fuente
PageRange es una lista separada por comas basada en uno, como 1,3,5-7
Un PageRange vacío importa todas las páginas
El orden de selección y los números de página repetidos se conservan

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, actualmente 128 páginas
InsertAt	-1, que añade al final del destino
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped realiza una importación nativa por fuente, permitiendo que PDFium reutilice su mapa de objetos clonados en todas las páginas seleccionadas de esa fuente

bmrpChunked divide la selección en lotes de PageChunkSize, ofreciendo puntos de cancelación más finos y llamadas nativas más pequeñas a costa de una posible duplicación de recursos entre lotes

Como máximo hay una fuente TPdf abierta a la vez y cada fuente se cierra inmediatamente después de su intento de importación

La cancelación se comprueba entre operaciones de fuente y lotes nativos; una llamada individual de importación de PDFium no puede interrumpirse

OnProgress recibe las etapas de inicio, apertura, importación, fuente, reversión, cancelación, fallo y finalización, y puede establecer su parámetro Cancel; cada instantánea TPdfBatchMergeProgress transporta Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount y NativeImportCallCount

El TPdfBatchMergeReport devuelve Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage e Issues

CancellationToken acepta el mismo contrato IPdfCancellationToken usado por las API asíncronas y progresivas

Forms, outlines, and viewer preferences

bmfpPreserveNative mantiene la importación de páginas y widgets de mejor esfuerzo de PDFium, pero no resuelve conflictos de árbol de campos AcroForm, campos con el mismo nombre, recursos, apariencia predeterminada u orden de cálculo
bmfpFlatten genera apariencias y aplana solo las páginas de fuente seleccionadas antes de la importación
bmfpReject rechaza fuentes AcroForm y XFA
bmopDiscard importa páginas sin reconstruir el esquema de la fuente, mientras que bmopReject rechaza fuentes que contienen un esquema
Las preferencias del visor se copian de manera de mejor esfuerzo tras las importaciones de páginas exitosas desde la primera fuente exitosa cuando CopyViewerPreferences está habilitada; ViewerPreferencesSourceIndex permanece en -1 cuando esa fuente no tiene entradas admitidas

Failure and rollback

Una fuente que falla después de que uno o más lotes hayan insertado páginas siempre se revierte a su límite de fuente antes del manejo de detención u omisión

bmepSkip registra el problema y continúa con la siguiente fuente, mientras que bmepStop termina la operación

Con RollbackOnCancelOrFailure=True, los fallos de detención y la cancelación eliminan todas las páginas insertadas por la operación; un destino creado por la operación se cierra

Con la reversión deshabilitada, las fuentes importadas con éxito permanecen confirmadas y se reflejan en CommittedPageCount

La reversión elimina las páginas insertadas, pero no puede garantizar la reversión de cada efecto secundario nativo del catálogo, como los metadatos del productor

Report

Status es bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled o bmrsFailed

El informe separa las fuentes intentadas, importadas, omitidas y fallidas de las páginas importadas, confirmadas y revertidas

NativeImportCallCount, LargestNativeImportPageCount y PeakOpenSourceCount hacen medible la política de programación elegida

Issues conserva el índice de la fuente, el nombre del archivo y el texto del error para los fallos y los errores no fatales de devoluciones de llamada terminales

Example

var
  Sources: TPdfBatchMergeSources;
  Options: TPdfBatchMergeOptions;
  Report: TPdfBatchMergeReport;
begin
  SetLength(Sources, 2);
  Sources[0] := TPdfBatchMergeSource.FromFile('part-a.pdf', '1-10');
  Sources[1] := TPdfBatchMergeSource.FromFile('part-b.pdf', '3,1', Password);
  Options := TPdfBatchMergeOptions.Default;
  Options.ErrorPolicy := bmepSkip;
  Options.FormPolicy := bmfpFlatten;
  if not Pdf.MergeFiles(Sources, Options, Report) then
    Log(Report.ErrorMessage);
end;