Documentación HotPDF
Inicio Contenido Resumen

Soporte AcroForm

Panorama

Desde HotPDF v2.5.0, la librería puede emitir formularios interactivos (AcroForm) conforme a la sección 12.7 de PDF 1.7 ISO 32000-1. Cada campo de formulario se crea como una 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) vía THPDFPage.AddTextField. Admite opciones de una línea, multilínea, contraseña, comb, selección de archivo, texto enriquecido, desplazamiento y corrección ortográfica mediante THPDFFormFieldFlags.
  • Casillas de verificación (/FT /Btn, sin bits Pushbutton/Radio) vía THPDFPage.AddCheckBox, con nombre de valor de exportación configurable y estado inicial marcado.
  • Botones de opción (/FT /Btn /Ff Radio) vía 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) vía THPDFPage.AddComboBox. Pase un open array de opciones.
  • List boxes (/FT /Ch) vía THPDFPage.AddListBox. ffMultiSelect activa la selección múltiple.
  • Botones (/FT /Btn /Ff Pushbutton) vía THPDFPage.AddPushButton, con leyenda opcional (/MK /CA). Desde HotPDF v2.31.0, THPDFPage.AddPushButtonWithAction adjunta un diccionario de acción PDF al widget para que al pulsar el botón se ejecute /SubmitForm (envía valores de campos a una URL, PDF 1.2 12.7.5.2), /ResetForm (PDF 1.2 12.7.5.3), /JavaScript (ejecuta un fragmento JS, PDF 1.3 12.6.4.16) o /URI (abre una URL en el navegador del sistema, PDF 1.1 12.6.4.7).
  • Campos de marcador de firma (/FT /Sig) vía 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. El campo se deja sin firmar para que herramientas externas (Adobe Acrobat, Foxit, librerías de firma CMS / PKCS#7 dedicadas) puedan adjuntar la firma criptográfica real después de guardar el archivo.
  • Flujo de firma in situ vía 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 ajustar /ByteRange y saber qué rangos del archivo hay que hashear. Después de producir externamente una firma detached CMS / PKCS#7 (Windows CryptoAPI, OpenSSL, librerías de firma dedicadas), llama a InsertSignatureHex para depositar la firma hexadecimal en el marcador sin alterar ningún otro byte del archivo.

Envoltorios de campos en tiempo de 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 envoltorio 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 con los métodos Add... existentes, al estilo del flujo THPDFAcroFormField.SetTooltip a nivel de envoltorio

Desde HotPDF v2.298.0, las APIs de creación de campos en tiempo de creación y de creación de campos en documentos cargados rechazan nombres de campo raíz duplicados con una excepción de diagnóstico antes de registrar cualquier 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 hijos adicionales bajo su array /Kids

El envoltorio expone setters encadenables para tooltips /TU, flags comunes de campo (SetReadOnly, SetRequired, SetNoExport), cadenas 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 del widget mediante THPDFActionBuilder

Ejemplo en Pascal de envoltorios 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 de formulario 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, alternar el flag de solo lectura y guardar el grafo de objetos cargado con THotPDF.SaveLoadedDocument. Esta vía está pensada para ediciones persistentes de un documento ya cargado; no llame a BeginDoc / EndDoc solo para guardar cambios en 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 completo del campo. Los valores THPDFLoadedFormFieldType devueltos son lfftText, lfftButton, lfftChoice, lfftSignature o lfftUnknown.

Ejemplo en 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 envoltorios AttachFieldKeyStrokeAction, AttachFieldFormatAction, AttachFieldValidateAction y AttachFieldCalculateAction adjuntan JavaScript al diccionario /AA de un campo para los disparadores PDF /K, /F, /V y /C. Use SetFormFieldAdditionalAction o sus envoltorios con nombre de THPDFActionBuilder cuando el mismo disparador deba ejecutar una cadena de acciones reutilizable como JavaScript, ResetForm, SubmitForm, URI, Hide, ImportData o una acción encadenada /Next. Los disparadores 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 que los helpers clear correspondientes eliminan un disparador sin tocar el resto del diccionario /AA

Generación de apariencias

Por defecto, el diccionario /AcroForm emitido fija /NeedAppearances true y delega el renderizado de los streams de apariencia al visor que consume el archivo (Adobe Reader, Foxit, Chrome, navegadores, Apple Preview). Fije THotPDF.AutoFormAppearances en 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, campo de elección (combo / lista) y los estados Yes / Off de cada hijo de casilla / botón de opción. 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 dibujan igualmente el contenido del campo. Disponible desde HotPDF v2.28.0.

Referencia de flags de campo (THPDFFormFieldFlags)

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

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

  • El generador AutoFormAppearances actualmente compone solo valores codificables en ASCII / WinAnsi; para campos cuyo /V contiene texto multibyte (UTF-8), el /AP guardado muestra un rectángulo vacío hasta que el visor anfitrión regenere la apariencia.
  • Los subestados Down (/D) y rollover (/R) no se generan; solo se produce el estado normal (/N).
  • Los nombres de campo se comprueban frente a 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 de quien llama.

Ver también