HotPDF Docs
Início Conteúdo Visão geral

AcroForm Support

Visão geral

Desde o HotPDF v2.5.0 a biblioteca pode emitir formulários interativos (AcroForm) conforme a seção 12.7 da ISO 32000-1 do PDF 1.7. Cada campo de formulário é criado como uma anotação Widget mesclada com o dicionário do campo e é registrado automaticamente no documento, de modo que a entrada global de /AcroForm é adicionada ao Catalog quando o documento é finalizado em EndDoc.

Tipos de campos suportados

  • Text fields (/FT /Tx) via THPDFPage.AddTextField. Suporta opções de linha única, multi-linha, senha, comb, file-select, rich text, scroll e verificação ortográfica por meio de THPDFFormFieldFlags.
  • Check boxes (/FT /Btn, sem bits Pushbutton/Radio) via THPDFPage.AddCheckBox, com nome de valor de export configurável e estado marcado inicial.
  • Radio buttons (/FT /Btn /Ff Radio) via THPDFPage.AddRadioButton. Múltiplas chamadas com o mesmo nome de grupo são fundidas sob um campo pai compartilhado com um array /Kids, exatamente como exigido pela 12.7.4.2.
  • Combo boxes (/FT /Ch /Ff Combo) via THPDFPage.AddComboBox. Passe um open array de opções.
  • List boxes (/FT /Ch) via THPDFPage.AddListBox. ffMultiSelect habilita multi-seleção.
  • Push buttons (/FT /Btn /Ff Pushbutton) via THPDFPage.AddPushButton com caption opcional (/MK /CA). Desde o HotPDF v2.31.0, THPDFPage.AddPushButtonWithAction anexa um dicionário de ação PDF ao widget, de modo que clicar no botão execute /SubmitForm (envia valores de campos a uma URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (roda um snippet JS, PDF 1.3 12.6.4.16) ou /URI (abre uma URL no browser do sistema, PDF 1.1 12.6.4.7).
  • Signature placeholder fields (/FT /Sig) via THPDFPage.AddSignatureField desde o HotPDF v2.12.0. O dicionário AcroForm ganha automaticamente /SigFlags 3 (SignaturesExist + AppendOnly) quando ao menos um campo de assinatura está presente. O campo fica sem assinar, para que ferramentas externas (Adobe Acrobat, Foxit, bibliotecas dedicadas de assinatura CMS / PKCS#7) possam anexar a assinatura criptográfica real depois que o arquivo for salvo.
  • In-place signing workflow via THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex desde o HotPDF v2.23.0. A primeira chamada reserva um dicionário de assinatura /V com placeholders de /ByteRange e /Contents. Depois de salvar o documento, a aplicação hospedeira chama PreparePDFForSigning para aplicar patch em /ByteRange e saber quais faixas do arquivo fazer hash. Depois de produzir uma assinatura destacada CMS / PKCS#7 externamente (CryptoAPI do Windows, OpenSSL, bibliotecas dedicadas de assinatura), ela chama InsertSignatureHex para colocar o hex da assinatura no placeholder sem perturbar nenhum outro byte do arquivo.

Wrappers de campos na criação

Desde o HotPDF v2.292.12, os helpers THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox e CreateListBox criam os mesmos widgets AcroForm que os métodos existentes de Add... e retornam um wrapper leve de THPDFAcroFormField para configuração imediata

Desde o HotPDF v2.292.26, THotPDF.SetFormFieldTooltip atribui a dica de usuário PDF /TU por nome de campo para campos criados pelos métodos existentes de Add..., correspondendo ao fluxo no nível de wrapper de THPDFAcroFormField.SetTooltip

Desde o HotPDF v2.298.0, as APIs de criação de campos em tempo de criação e as APIs de criação de campos de documentos carregados rejeitam nomes de campos raiz duplicados com uma exceção de diagnóstico antes de qualquer widget ser registrado. Chamadas repetidas de AddRadioButton com o mesmo nome de grupo permanecem válidas, porque compartilham um campo pai e adicionam widgets filhos adicionais sob o array /Kids dele

O wrapper expõe setters encadeáveis para tooltips de /TU, flags comuns de campos (SetReadOnly, SetRequired, SetNoExport), strings de aparência padrão de /DA, additional actions no nível do campo como /AA /K, /AA /F, /AA /V, /AA /C, e ações de mouse ou foco de widget por meio de THPDFActionBuilder

Exemplo Pascal de wrappers na criação

Field := HPDF.CurrentPage.CreateTextField('Email', '', Rect(50, 80, 250, 104));
Action := THPDFActionBuilder.JavaScript('event.rc = event.value.indexOf("@") > 0;');
try
  Field.SetTooltip('Email address');
  Field.SetRequired(True);
  Field.SetReadOnly(False);
  Field.SetAdditionalAction(fatValidate, Action);
finally
  Action.Free;
  Field.Free;
end;

Inspeção e atualização de campos de formulários carregados

Desde o HotPDF v2.121.9, aplicações podem carregar um PDF AcroForm existente com THotPDF.LoadFromFile, enumerar seus campos, ler nomes, tipos e valores deles, mudar valores de campos, alternar a flag somente leitura e salvar o grafo de objetos carregado com THotPDF.SaveLoadedDocument Este caminho se destina a edições persistidas em um documento já carregado; não chame BeginDoc / EndDoc apenas para salvar mudanças de valores de campos carregados.

Os helpers de campos são GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue e SetFormFieldReadOnly. A consulta de campos aceita tanto um índice de campo de base zero quanto o nome de campo totalmente qualificado. Os valores THPDFLoadedFormFieldType retornados são lfftText, lfftButton, lfftChoice, lfftSignature ou lfftUnknown.

Exemplo Pascal de campos carregados

HPDF.LoadFromFile('InputForm.pdf');
for I := 0 to HPDF.GetFormFieldCount - 1 do
  Writeln(HPDF.GetFormFieldName(I), ' = ', HPDF.GetFormFieldValue(I));

HPDF.SetFormFieldValue('CustomerName', 'Bob');
HPDF.SetFormFieldValue('Plan', 'Premium');
HPDF.SetFormFieldReadOnly('CustomerName', True);
HPDF.SaveLoadedDocument('UpdatedForm.pdf');

Additional actions de campos

Os wrappers AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction e AttachFieldCalculateAction anexam JavaScript ao dicionário /AA de um campo para os gatilhos PDF /K, /F, /V e /C. Use SetFormFieldAdditionalAction ou os wrappers nomeados de THPDFActionBuilder dele quando o mesmo gatilho precisar rodar uma cadeia de ações reutilizável como JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData ou uma ação encadeada de /Next. Gatilhos de mouse e foco no nível de widget também podem ser instalados por nome de campo por meio de SetFormFieldAnnotationAction e dos helpers nomeados de mouse / foco, enquanto os helpers de clear correspondentes removem um gatilho sem perturbar o restante do dicionário /AA

Geração de aparências

Por padrão, o dicionário /AcroForm emitido define /NeedAppearances true e delega a renderização de appearance streams ao viewer consumidor (Adobe Reader, Foxit, Chrome, browsers, Apple Preview). Defina THotPDF.AutoFormAppearances como true antes de adicionar campos e o HotPDF pré-construirá Form XObjects de /AP /N (PDF 1.7 8.10) para cada campo de texto, push button, choice (combo / list) e os estados Yes / Off de cada checkbox / filho de radio. O dicionário AcroForm então carrega /NeedAppearances false e uma entrada de recursos padrão de /DR referenciando as 14 fontes base padrão (Helv Helvetica, ZaDb ZapfDingbats), de modo que renderizadores que ignoram /NeedAppearances ainda desenhem o conteúdo do campo corretamente. Disponível desde o HotPDF v2.28.0.

Referência de flags de campos (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — common Table 227 flags applicable to every field type.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx-specific (Table 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch-specific (Table 230).

Exemplo Pascal

HPDF.BeginDoc;
HPDF.AddPage;
HPDF.CurrentPage.AddTextField('Name', '', Rect(50, 100, 250, 120));
HPDF.SetFormFieldTooltip('Name', 'Customer name');
HPDF.CurrentPage.AddCheckBox('Agree', 'Yes', Rect(50, 130, 70, 145), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Red',   Rect(50, 160, 70, 175), True);
HPDF.CurrentPage.AddRadioButton('Color', 'Green', Rect(80, 160, 100, 175));
HPDF.CurrentPage.AddRadioButton('Color', 'Blue',  Rect(110, 160, 130, 175));
HPDF.CurrentPage.AddComboBox('Country', 'CN',
                             ['CN', 'US', 'JP'], Rect(50, 190, 250, 210));
HPDF.EndDoc;

Limitations

  • O gerador de AutoFormAppearances atualmente dispõe apenas valores codificáveis em ASCII / WinAnsi; para campos cujo /V contém texto multi-byte (UTF-8), o /AP armazenado renderiza um retângulo vazio até o viewer hospedeiro regenerar a aparência.
  • Os subestados Down (/D) e rollover (/R) não são gerados; apenas o estado normal (/N) é produzido.
  • Os nomes de campos são checados quanto a entradas raiz duplicadas quando novos widgets AcroForm são criados; a construção hierárquica de nomes parciais além do padrão pai de radio / widget permanece responsabilidade do chamador.

See Also