מדריך מפתחים של PDFium Delphi Component

Component: TPdf · Unit: PDFium

ממזג מקורות PDF מבוססי קובץ דרך ה-API המקוריים לייבוא עמודים, תוך הגבלת מספר ה-handles של המקורות וחשיפת מדיניות פעולה מפורשת

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 מזהה מקור PDF אחד מבוסס קובץ
Password מוחל לפני פתיחת המקור
PageRange הוא רשימה מופרדת בפסיקים המבוססת על 1, למשל 1,3,5-7
PageRange ריק מייבא את כל העמודים
סדר הבחירה ומספרי עמודים חוזרים נשמרים

Default options

ErrorPolicy	`bmepStop`
FormPolicy	`bmfpPreserveNative`
OutlinePolicy	`bmopDiscard`
ResourcePolicy	`bmrpSourceScoped`
PageChunkSize	`PdfBatchMergeDefaultPageChunkSize`, נכון לעכשיו 128 עמודים
InsertAt	-1, כלומר צירוף לסוף היעד
CreateDestination	`True`
CopyViewerPreferences	`True`
RollbackOnCancelOrFailure	`True`

Resource and cancellation policy

bmrpSourceScoped מבצע ייבוא מקורי אחד לכל מקור, ומאפשר ל-PDFium לעשות שימוש חוזר במפת האובייקטים המשוכפלים שלו על פני כל העמודים הנבחרים מאותו מקור

bmrpChunked מחלק את הבחירה לאצוות בגודל PageChunkSize, מספק נקודות ביטול עדינות יותר וקריאות מקוריות קטנות יותר, במחיר שכפול משאבים אפשרי בין אצוות

בכל רגע נתון פתוח מקור TPdf אחד לכל היותר, וכל מקור נסגר מיד לאחר ניסיון הייבוא שלו

הביטול נבדק בין פעולות מקור ובין אצוות מקוריות; קריאת ייבוא בודדת של PDFium אינה ניתנת להפרעה

OnProgress מקבל את השלבים started, opening, importing, source, rollback, cancellation, failure ו-completion, ויכול להגדיר את הפרמטר Cancel שלו; כל צילום TPdfBatchMergeProgress נושא את Stage, SourceIndex, SourceCount, FileName, SourcePageCount, ImportedSourceCount, ImportedPageCount ו-NativeImportCallCount

TPdfBatchMergeReport מחזיר את Status, SourceCount, AttemptedSourceCount, ImportedSourceCount, SkippedSourceCount, FailedSourceCount, ImportedPageCount, CommittedPageCount, RolledBackPageCount, PageCountBefore, PageCountAfter, NativeImportCallCount, LargestNativeImportPageCount, PeakOpenSourceCount, FormSourceCount, OutlineSourceCount, DestinationCreated, ViewerPreferencesSourceIndex, ErrorMessage ו-Issues

CancellationToken מקבל את אותו חוזה IPdfCancellationToken שבו משתמשים ה-API האסינכרוניים והמדורגים

Forms, outlines, and viewer preferences

bmfpPreserveNative שומר על ייבוא העמודים וה-widgetים המיטבי של PDFium, אך אינו פותר התנגשויות של עץ שדות AcroForm, שדות בשם זהה, משאבים, מראה ברירת מחדל או סדר חישוב
bmfpFlatten מייצר מראות (appearances) ומשטח רק את עמודי המקור הנבחרים לפני הייבוא
bmfpReject דוחה מקורות AcroForm ו-XFA
bmopDiscard מייבא עמודים מבלי לבנות מחדש את ה-outline של המקור, בעוד ש-bmopReject דוחה מקורות שמכילים outline
העדפות מציג מועתקות על בסיס מיטבי לאחר ייבוא עמודים מוצלח, מהמקור המוצלח הראשון, כאשר CopyViewerPreferences מופעל; ViewerPreferencesSourceIndex נשאר -1 כאשר לאותו מקור אין רשומות נתמכות

Failure and rollback

מקור שנכשל לאחר שאצווה אחת או יותר הכניסה עמודים תמיד מתגלגל אחורה לגבול המקור שלו לפני טיפול בעצירה או בדילוג

bmepSkip מתעד את הבעיה וממשיך למקור הבא, בעוד ש-bmepStop מסיים את הפעולה

עם RollbackOnCancelOrFailure=True, כשלי עצירה וביטול מסירים את כל העמודים שהוכנסו על ידי הפעולה; יעד שנוצר על ידי הפעולה נסגר

כאשר rollback מנוטרל, מקורות שיובאו בהצלחה נשארים מחויבים ומשתקפים ב-CommittedPageCount

rollback מסיר עמודים שהוכנסו, אך אינו יכול להבטיח ביטול של כל תופעת לוואי מקורית בקטלוג, כגון מטא-נתוני producer

Report

Status הוא bmrsCompleted, bmrsCompletedWithErrors, bmrsCancelled או bmrsFailed

הדוח מפריד בין מקורות שנוסו, יובאו, דולגו ונכשלו לבין עמודים שיובאו, מחויבו והתגלגלו אחורה

NativeImportCallCount, LargestNativeImportPageCount ו-PeakOpenSourceCount הופכים את מדיניות התזמון שנבחרה למדידה

Issues שומר אינדקס מקור, שם קובץ וטקסט שגיאה עבור כשלים ושגיאות callback סופיות שאינן קטלניות

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;

MergeFiles