Documentación HotPDF
Inicio Contenido Resumen

Soporte AcroForm

Visión general

Desde HotPDF v2.5.0 la biblioteca puede emitir formularios interactivos (AcroForm) según la sección 12.7 de PDF 1.7 ISO 32000-1. Cada campo de formulario se crea como anotación Widget fusionada con el diccionario de campo y se registra automáticamente en el documento, de modo que la entrada global /AcroForm se añade al Catalog cuando el documento se finaliza en EndDoc.

Tipos de campo soportados

  • Campos de texto (/FT /Tx) mediante THPDFPage.AddTextField. Soporta opciones de una línea, multilínea, contraseña, peine, selección de archivo, texto enriquecido, desplazamiento y corrección ortográfica mediante THPDFFormFieldFlags.
  • Casillas de verificación (/FT /Btn, sin marcas Pushbutton/Radio) mediante THPDFPage.AddCheckBox, con nombre de valor de exportación y estado marcado inicial configurables.
  • Botones de opción (/FT /Btn /Ff Radio) mediante THPDFPage.AddRadioButton. Varias llamadas con el mismo nombre de grupo se fusionan bajo un campo padre compartido con un array /Kids, exactamente como exige 12.7.4.2.
  • Combo boxes (/FT /Ch /Ff Combo) mediante THPDFPage.AddComboBox. Pase un array abierto de opciones.
  • List boxes (/FT /Ch) mediante THPDFPage.AddListBox. ffMultiSelect habilita la multiselección.
  • Botones de envío (/FT /Btn /Ff Pushbutton) mediante THPDFPage.AddPushButton con leyenda opcional (/MK /CA). Desde HotPDF v2.31.0, THPDFPage.AddPushButtonWithAction adjunta un diccionario de acciones PDF al widget para que al pulsar el botón se ejecute /SubmitForm (enviar valores de campos a una URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (ejecutar un fragmento JS, PDF 1.3 12.6.4.16) o /URI (abrir una URL en el navegador del sistema, PDF 1.1 12.6.4.7).
  • Campos de marcador de firma (/FT /Sig) mediante THPDFPage.AddSignatureField desde HotPDF v2.12.0. El diccionario AcroForm gana automáticamente /SigFlags 3 (SignaturesExist + AppendOnly) cuando hay al menos un campo de firma presente. El campo se deja sin firmar para que herramientas externas (Adobe Acrobat, Foxit, bibliotecas dedicadas de firmado CMS / PKCS#7) puedan adjuntar la firma criptográfica real después de guardar el archivo.
  • Flujo de firmado en el sitio mediante THPDFPage.AddSignedSignatureField + THotPDF.PreparePDFForSigning + THotPDF.InsertSignatureHex desde HotPDF v2.23.0. La primera llamada reserva un diccionario de firma /V con marcadores /ByteRange y /Contents. Tras guardar el documento, la aplicación anfitriona llama a PreparePDFForSigning para parchear el /ByteRange y saber qué rangos del archivo hay que hashear. Después de producir externamente una firma desasociada CMS / PKCS#7 (Windows CryptoAPI, OpenSSL, bibliotecas de firmado dedicadas), llama a InsertSignatureHex para depositar el hexadecimal de la firma en el marcador sin tocar ningún otro byte del archivo.

Wrappers de campos en la creación

Desde HotPDF v2.292.12, los helpers THPDFPage.CreateTextField, CreateCheckBox, CreateRadioButton, CreateComboBox y CreateListBox crean los mismos widgets AcroForm que los métodos Add... existentes y devuelven un wrapper ligero THPDFAcroFormField para configurarlo de inmediato

Desde HotPDF v2.292.26, THotPDF.SetFormFieldTooltip asigna la pista de usuario /TU del PDF por nombre de campo para los campos creados mediante los métodos Add... existentes, en paralelo con el flujo THPDFAcroFormField.SetTooltip a nivel de wrapper

Desde HotPDF v2.298.0, las APIs de campos en tiempo de creación y las APIs de creación de campos de documentos cargados rechazan nombres de campo raíz duplicados con una excepción de diagnóstico antes de registrar ningún widget. Las llamadas repetidas a AddRadioButton con el mismo nombre de grupo siguen siendo válidas porque comparten un campo padre y añaden widgets hijo adicionales bajo su array /Kids

El wrapper expone setters encadenables para tooltips /TU, flags comunes de campos (SetReadOnly, SetRequired, SetNoExport), strings de apariencia por defecto /DA, acciones adicionales a nivel de campo como /AA /K, /AA /F, /AA /V, /AA /C, y acciones de ratón o foco de widget mediante THPDFActionBuilder

Ejemplo Pascal de wrappers en tiempo de creación

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;

Inspección y actualización de campos cargados

Desde HotPDF v2.121.9, las aplicaciones pueden cargar un PDF AcroForm existente con THotPDF.LoadFromFile, enumerar sus campos, leer nombres, tipos y valores, cambiar valores de campos, conmutar el flag de solo lectura y guardar el grafo de objetos cargado con THotPDF.SaveLoadedDocument. Esta ruta está pensada para ediciones persistentes de un documento ya cargado; no llame a BeginDoc / EndDoc solo para guardar cambios de valores de campos cargados.

Los helpers de campos son GetFormFieldCount, GetFormFieldName, GetFormFieldType, GetFormFieldValue, SetFormFieldValue y SetFormFieldReadOnly. La búsqueda de campos acepta tanto un índice de campo de base cero como el nombre de campo completamente cualificado. Los valores THPDFLoadedFormFieldType devueltos son lfftText, lfftButton, lfftChoice, lfftSignature o lfftUnknown.

Ejemplo Pascal de campos cargados

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');

Acciones adicionales de campos

Los wrappers AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction y AttachFieldCalculateAction adjuntan JavaScript al diccionario /AA de un campo para los triggers PDF /K, /F, /V y /C. Use SetFormFieldAdditionalAction o sus wrappers con nombre de THPDFActionBuilder cuando el mismo trigger deba ejecutar una cadena de acción reutilizable como JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData o una acción /Next encadenada. Los triggers de ratón y foco a nivel de widget también pueden instalarse por nombre de campo mediante SetFormFieldAnnotationAction y los helpers con nombre de ratón / foco, mientras los helpers de limpieza correspondientes eliminan un trigger sin perturbar el resto del diccionario /AA

Generación de apariencias

Por defecto el diccionario /AcroForm emitido establece /NeedAppearances true y delega el renderizado de streams de apariencia al visor consumidor (Adobe Reader, Foxit, Chrome, navegadores, Apple Preview). Establezca THotPDF.AutoFormAppearances a true antes de añadir campos y HotPDF preconstruirá Form XObjects /AP /N (PDF 1.7 8.10) para cada campo de texto, botón, choice (combo / lista) y los estados Yes / Off de cada checkbox / radio hijo. El diccionario AcroForm lleva entonces /NeedAppearances false y una entrada de recursos por defecto /DR que referencia las 14 fuentes base estándar (Helv Helvetica, ZaDb ZapfDingbats), de modo que los renderizadores que ignoran /NeedAppearances siguen dibujando bien el contenido del campo. Disponible desde HotPDF v2.28.0.

Referencia de flags de campos (THPDFFormFieldFlags)

  • ffReadOnly, ffRequired, ffNoExport — flags comunes de la Tabla 227 aplicables a cualquier tipo de campo.
  • ffMultiline, ffPassword, ffFileSelect, ffDoNotSpellCheck, ffDoNotScroll, ffComb, ffRichText — Tx-specific (Table 228).
  • ffEdit, ffSort, ffMultiSelect, ffDoNotSpellCheck, ffCommitOnSelChange — Ch-specific (Table 230).

Ejemplo 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;

Limitaciones

  • The AutoFormAppearances generator currently lays out ASCII / WinAnsi-encodable values only; for fields whose /V contains multi-byte (UTF-8) text the stored /AP renders an empty rectangle until the host viewer regenerates the appearance.
  • Down (/D) and rollover (/R) sub-states are not generated; only the normal (/N) state is produced.
  • Los nombres de campo se comprueban contra entradas raíz duplicadas al crear nuevos widgets AcroForm; la construcción jerárquica de nombres parciales más allá del patrón padre de radio / widget sigue siendo responsabilidad del llamador.

Véase también