InsertFormObjectFromXObject 方法

组件: TPdf · 单元: PDFium

将由 TPdfXObject 包裹的页面的一个副本插入到此文档当前页面，并返回 FPDF_PAGEOBJECT，便于调用方进行定位、缩放或旋转

Syntax

function InsertFormObjectFromXObject(XObject: TPdfXObject): FPDF_PAGEOBJECT;

Description

InsertFormObjectFromXObject 是 v1.25.0 Form XObject 重用 API 的后半部分。它接受一个 TPdfXObject 句柄（由 CreateXObjectFromPage 构建），并将一个引用该 XObject 的 FPDF_PAGEOBJECT 插入本文档的当前页面。每次调用都会插入一个新的页面对象，因此同一个 XObject 可以在目标的多个页面上盖印多次 — 每次盖印都共享底层页面内容缓存，即使水印 / 模板很密集也能控制文件大小

返回的 FPDF_PAGEOBJECT 句柄允许调用方调用 FPDFPageObj_SetMatrix 或 TPdfMatrix 辅助工具在页面上任意位置定位 / 缩放 / 旋转图章。没有显式变换时，插入的页面以 1:1 比例位于左下角，这几乎从来不是你想要的；务必在调用 UpdatePage 之前设置矩阵

失败时返回 nil（XObject 为 nil、此 TPdf 未 Active、没有当前页）。插入后，页面对象由页面拥有，而非 XObject — 释放 XObject 不会使插入的页面对象失效

Remarks

目标页面由此 TPdf 的 PageNumber 标识。先设置 PageNumber，然后调用 InsertFormObjectFromXObject
定位图章后调用 UpdatePage，使 PDFium 重新渲染页面内容流
将同一个 XObject 盖印到 N 个页面会产生 N 个页面内容流中的 N 个 FPDF_PAGEOBJECT 引用，全部指向单个 XObject 定义 — 比复制底层内容 N 次便宜得多
XObject 的生命周期可以比目标页面对象的生命周期更短；一旦插入，页面拥有其引用

Example

uses FPdfMatrix;

var
  PageObj: FPDF_PAGEOBJECT;
  M: TPdfMatrix;
begin
  Pdf1.PageNumber := 3;
  PageObj := Pdf1.InsertFormObjectFromXObject(XObj);
  if PageObj <> nil then
  begin
    M := TPdfMatrix.Create;
    try
      M.Translate(100, 200);
      M.Scale(0.5, 0.5);
      M.Rotate(15);
      FPDFPageObj_SetMatrix(PageObj, M.AsMatrix);
    finally
      M.Free;
    end;
    Pdf1.UpdatePage;
  end;
end;

组件: TPdf · 单元: PDFium

Syntax

Description

Remarks

Example

See Also