Forms

Forms

This page covers creating and managing interactive AcroForm fields. Form, reached through doc.Form, is the facade for every field type; each Add*() method creates a field tied to a page and a widget rectangle and returns a typed handle (TextField, CheckboxField, ChoiceField, ButtonField, or RadioField) that shares the common Field properties Value, ReadOnly, and Required.

Creating Fields

Form.AddTextField(), Form.AddCheckbox(), Form.AddComboBox(), and their siblings each take an options object naming the target page (0-based), the widget rect, a field name, and styling such as borderColor and backgroundColor.

const form = doc.Form;
const pageNum = page.Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.05, 0.1, 0.3], backgroundColor: [0.9, 0.93, 1], borderWidth: 1,
  font: 'Helvetica', fontSize: 12,
});

form.AddCheckbox({
  page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
  checked: true, borderColor: [0.05, 0.1, 0.3], borderWidth: 1,
});

form.AddComboBox({
  page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
  options: [
    { export: 'US', display: 'United States' },
    { export: 'UK', display: 'United Kingdom' },
    { export: 'DE', display: 'Germany' },
  ],
});

Page.AddTextField() and Page.AddCheckbox() create the same field types directly on a page, without naming doc.Form or a page number in the options object.

Reading and Modifying Fields

Form.Fields is an array of every Field on the document; Form.Get() looks one up by its fully-qualified name. Every field’s Value can be read or reassigned, and ReadOnly / Required are plain boolean properties.

const nameField = doc.Form.Get('FullName');
if (nameField) {
  console.log(nameField.Value);
  nameField.Value = 'Bob Sample';
}

Flattening Fields

Every field type’s Flatten() method bakes its current appearance into the page’s static content and removes it from the AcroForm — the same permanent, non-interactive effect Annotation.Flatten() has for annotations.

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten();

Tips and Best Practices

• Modify the field handle returned directly by the Add*() call, or one looked up fresh with Form.Get() — a stale reference does not see changes made elsewhere.
• Form.RemoveField() accepts either a Field handle or a field name string.
• Call Form.GenerateAppearances() after changing field values in bulk so every field’s on-screen appearance stays in sync with its Value.
• Combo boxes and list boxes store the selected export value in /V; the display text is what the generated appearance shows.

Common Issues

FAQ

How do I read or change a field’s value after creating it?

Look it up with Form.Get('fieldName') (or use the handle the Add*() call returned) and read or assign its Value property directly.

What field types does the Form facade support?

Text fields, checkboxes, radio groups, combo boxes, list boxes, and push buttons, via Form.AddTextField(), Form.AddCheckbox(), Form.AddRadioGroup(), Form.AddComboBox(), Form.AddListBox(), and Form.AddPushButton().

How do I remove a field?

Call Form.RemoveField() with either the field’s handle or its name.

How is a form field made permanent and non-editable?

Call Flatten() on the field handle — the same pattern used for annotations — which bakes its current appearance into the page and removes it from the AcroForm.

API Reference Summary

See Also

• Aspose.PDF — Enterprise Documentation