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 workflowsruleId plus a structured location with logical scope, path, PDF key, and exact object, page, or byte coordinates when available. HTML displays the same identifiers and locations, while CSV retains its stable columns for spreadsheet and 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 coverageGTS_PDFVTVersion in element text or RDF attribute form, modification-date matching, PDF/X base marker, output intent, DPartRoot, DPartRootNode, NodeNameList, and 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.

Create a reusable profile from a preset

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;

Use MergePreflightProfiles to combine a preset with project-specific names. 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 summaryindex.html plus per-file HTML reports. No web server is required, so the output can be published as a static artifact.

Build a static dashboard

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

dashboard demo 會寫出 index.html 加上每個檔案的 HTML reports。不需要 web server，因此輸出可發布為 static artifactReport := PDF.CreatePreflightReport('Input.pdf'); JSON := PDF.ConvertPreflightReportToVeraPDFStyle(Report);location values as the native JSON report

Related Topics

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