MergeFiles

Componente: TPdf · Unidad: PDFium

Combina fuentes PDF respaldadas por archivos mediante APIs nativas de importación de páginas, al tiempo que acota los identificadores de las fuentes y expone 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 por archivo
Password se aplica antes de abrir la fuente
PageRange es una lista basada en 1 separada por comas, 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 anexa al destino
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

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

bmrpChunked divide la selección en lotes de PageChunkSize, lo que ofrece 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 un TPdf de fuente abierto a la vez y cada fuente se cierra inmediatamente después de su intento de importación

La cancelación se verifica entre operaciones de fuentes 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 lleva 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 y Issues

CancellationToken acepta el mismo contrato IPdfCancellationToken que usan las API asincrónicas y progresivas

Forms, outlines, and viewer preferences

bmfpPreserveNative conserva la importación de páginas y widgets de mejor esfuerzo de PDFium, pero no resuelve conflictos del árbol de campos AcroForm, de campos con el mismo nombre, de recursos, de apariencia predeterminada ni del orden de cálculo
bmfpFlatten genera apariencias y aplana solo las páginas de origen 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 las fuentes que contienen un esquema
Las preferencias del visor se copian de mejor esfuerzo después de importaciones de páginas exitosas desde la primera fuente exitosa cuando CopyViewerPreferences está habilitado; ViewerPreferencesSourceIndex permanece en -1 cuando esa fuente no tiene entradas compatibles

Failure and rollback

Una fuente que falla después de que uno o más lotes insertaron 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 exitosamente 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 de 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 de error de los fallos y de 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;