Preflight Cookbook

本 cookbook 將 preflight APIs 與 demos 整理為以任務為導向的 recipes。需要精確 signatures 時請使用 API reference；需要應用程式、build script 或 CI job 的可行流程時請使用本頁

Choose an output format

var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.txt');
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.json', '', pfJSON);
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.html', '', pfHTML);
    PDF.SavePreflightReport('Input.pdf', 'Input.preflight.csv', '', pfCSV);
  finally
    PDF.Free;
  end;
end;

Text output 具 byte-stable 且適合 diff。JSON 適合 pipeline ingestion。HTML 是 self-contained，可直接開啟或儲存為 CI artifact。CSV 使用穩定欄位，適合 spreadsheet 與 batch-report workflows

Validate PDF/VT documents

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    if not PDF.ValidatePDFVT('Input.pdf', Report) then
      WriteLn(string(Report));
  finally
    PDF.Free;
  end;
end;

PDF/VT report 聚焦 ISO 16612-2 identification 與 document-part structure：以 element text 或 RDF attribute 形式表示的 XMP GTS_PDFVTVersion、modification-date matching、PDF/X base marker、output intent、DPartRoot、DPartRootNode、NodeNameList，以及 page-level DPart coverage

Apply a profile

var
  PDF: THotPDF;
  Report: AnsiString;
begin
  PDF := THotPDF.Create(nil);
  try
    Report := PDF.CreatePreflightReportWithProfile(
      'Input.pdf', '', 'project-preflight.ini', pfJSON);
  finally
    PDF.Free;
  end;
end;

Profiles suppress named checks, warnings, or all hints. Use ValidatePreflightProfile before applying a user-authored profile when failing closed is more important than silently ignoring an obsolete name.

從 preset 建立可重用 profile

var
  PDF: THotPDF;
  Profile: THPDFPreflightProfile;
begin
  PDF := THotPDF.Create(nil);
  try
    Profile := PDF.GetBuiltInPreflightProfile('compact');
    Profile.DisableWarnings := 'OpenAction,JavaScript,URIAction';
    PDF.SavePreflightProfile(Profile, 'compact-no-actions.ini');
  finally
    PDF.Free;
  end;
end;

使用 MergePreflightProfiles 將 preset 與 project-specific names 合併。更新 shared configuration file 前，使用 DiffPreflightProfiles 檢視 profile drift

Archive the report with the PDF

PDF.EmbedPreflightReportInPDF('Input.pdf', 'Input-with-report.pdf');
PDF.EmbedPreflightReportAsXMP('Input.pdf', 'Input-with-xmp-report.pdf');

text embedding path 會在最終 EOF marker 之後附加可讀 comment block。XMP path 會附加 RDF-shaped payload，供掃描 metadata packets 的 archive workflows 使用

Validate an embedded report

var
  OriginalReport: AnsiString;
  CurrentReport: AnsiString;
begin
  if not PDF.LoadAndValidatePreflightReport(
    'Input-with-report.pdf', OriginalReport, CurrentReport) then
    WriteLn(string(PDF.ComparePreflightReports(OriginalReport, CurrentReport)));
end;

validation path 會比較 embedded fingerprint 與針對 source bytes 重新執行的 preflight 結果。diff helper 以行為單位，並針對 HotPDF preflight reports 調校

執行保守 repair pass

var
  RepairsApplied: AnsiString;
begin
  if PDF.RepairPDFFromPreflightReport(
    'Broken.pdf', 'Broken-repaired.pdf', RepairsApplied) then
    WriteLn(string(RepairsApplied));
end;

repair helper 有意維持狹窄範圍。它處理 final EOF marker 後的 trailing bytes 與缺少 EOF markers 的情況，但不重建 cross-reference tables，也不重寫 streams

Aggregate many reports

Reports[0] := PDF.CreatePreflightReport('A.pdf');
Reports[1] := PDF.CreatePreflightReport('B.pdf');
Summary := PDF.AggregatePreflightReports(Reports);

aggregate output 會為每個 PDF 列出一行狀態，並彙總 processed reports、failures 與 warnings。當 pipeline 需要單一摘要，但詳細 reports 仍按 input file 保留時很有用

使用 command-line tool

HotPDFPreflight Input.pdf -f json -o reports
HotPDFPreflight Input.pdf --pdfvt -o reports
HotPDFPreflight C:\Archive -r --preset compact -f text -o reports --aggregate reports\Aggregate.txt
HotPDFPreflight C:\Archive -r --profile project-preflight.ini -f html -o reports

CLI 對應 library workflow：單一檔案或遞迴目錄輸入、text / JSON / HTML 輸出、optional password、optional profile、built-in preset、verbose progress 與 aggregate summary

Build a static dashboard

PreflightDashboard C:\Archive C:\Archive\preflight-dashboard

dashboard demo 會寫出 index.html 加上每個檔案的 HTML reports。不需要 web server，因此輸出可發布為 static artifact

Adapt to veraPDF-style JSON consumers

Report := PDF.CreatePreflightReport('Input.pdf');
JSON := PDF.ConvertPreflightReportToVeraPDFStyle(Report);

adapter 保留 HotPDF semantics，同時將 failures 重塑為熟悉的 validation-result structure，方便已消費 veraPDF-like JSON 的 tooling 使用

Related Topics

• THotPDF Preflight Report Methods
• Preflight API Map
• Preflight Stress Testing