生命周期动作 - TPdf - PDFium Delphi Component

组件: TPdf · 单元: PDFium

控制 PDF 文档与页面生命周期动作的执行时机，包括显式的保存与打印边界

类型

TPdfLifecycleActionPolicy = (lapDisabled, lapManual, lapAutomatic);

TPdfDocumentLifecycleAction = (dlaJavaScript, dlaOpen, dlaWillClose, dlaWillSave, dlaDidSave, dlaWillPrint, dlaDidPrint);

TPdfPageLifecycleAction = (plaOpen, plaClose);

执行策略

property LifecycleActionPolicy: TPdfLifecycleActionPolicy; // default lapAutomatic

lapDisabled 同时阻止自动与显式的生命周期动作执行

lapManual 抑制自动动作，同时允许两个显式执行方法

lapAutomatic 保留兼容的自动文档 JavaScript、文档打开与关闭以及页面打开与关闭行为，同时仍允许显式执行

自动模式不包装保存或打印操作，因为内部快照和转换保存绝不应意外运行文档脚本；请在宿主控制的工作流边界调用显式的文档方法

文档动作

function ExecuteDocumentLifecycleAction(Action: TPdfDocumentLifecycleAction; out ErrorMessage: string): Boolean;

dlaJavaScript 运行文档级 JavaScript 名称树动作，dlaOpen 运行目录打开动作

dlaWillClose、dlaWillSave、dlaDidSave、dlaWillPrint 和 dlaDidPrint 分发相应的文档附加动作

当策略阻止执行、表单填充环境不可用或回调抛出异常时，该方法返回 False 且 ErrorMessage 非空

页面动作

function ExecutePageLifecycleAction(PageNumber: Integer; Action: TPdfPageLifecycleAction; out ErrorMessage: string): Boolean;

PageNumber 从 1 开始，必须标识活动文档中的一个页面

当前页复用其已加载的原生句柄；其他页面会被临时打开、注册到表单环境、分发、注销并关闭，且不改变 TPdf.PageNumber

加载、注册、动作、清理和关闭失败都被隔离到返回值与 ErrorMessage 中

保存工作流示例

var
  ErrorMessage: string;
begin
  Pdf.LifecycleActionPolicy := lapManual;
  if not Pdf.ExecuteDocumentLifecycleAction(dlaWillSave, ErrorMessage) then
    raise Exception.Create(ErrorMessage);
  try
    Pdf.SaveAs(TargetFileName);
  finally
    Pdf.ExecuteDocumentLifecycleAction(dlaDidSave, ErrorMessage);
  end;
end;

安全

生命周期动作可以调用文档 JavaScript、命名动作、URI 回调以及在 TPdf 上配置的其他宿主服务

对绝不能执行动作的不可信文档使用 lapDisabled；当应用程序需要显式审批边界时使用 lapManual

参见

表单宿主回调, JavaScriptActions, PerformNamedAction