acroform

package
v2.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package acroform provides action support for form fields

Package acroform provides appearance stream creation for form fields

Package acroform provides AcroForm extraction functions

Package acroform provides AcroForm field filling functionality

Package acroform provides form filling with object stream support

Package acroform provides AcroForm (standard PDF form) parsing and manipulation

Package acroform provides object replacement for form filling

Package acroform provides utilities to find object streams

Package acroform provides object stream rebuilding for form filling

Package acroform provides AcroForm field validation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddAcroFormToCatalog 

func AddAcroFormToCatalog(w *write.PDFWriter, catalogNum, acroFormNum int) error

AddAcroFormToCatalog adds AcroForm reference to catalog (kept for compatibility).

func AddActionToField 

func AddActionToField(fieldObjNum int, action *Action, w *write.PDFWriter) error

AddActionToField adds an action to a field

func AddAppearanceToField 

func AddAppearanceToField(fieldObjNum, appearanceNum int, w *write.PDFWriter) error

AddAppearanceToField adds an appearance stream to a field object

func AddMouseAction 

func AddMouseAction(fieldObjNum int, event string, action *Action, w *write.PDFWriter) error

AddMouseAction adds a mouse-triggered action (e.g., onClick)

func ExtractAndFill 

func ExtractAndFill(pdfBytes []byte, formData types.FormData, password []byte, verbose bool) ([]byte, error)

ExtractAndFill extracts AcroForm, validates, and fills.

func ExtractFormSchema 

func ExtractFormSchema(pdfBytes []byte, password []byte, verbose bool) (*types.FormSchema, error)

ExtractFormSchema extracts AcroForm and converts it to FormSchema

func FillFieldValue 

func FillFieldValue(pdfBytes []byte, field *Field, value interface{}, encryptInfo *types.PDFEncryption, verbose bool) ([]byte, error)

FillFieldValue fills a field with a value by replacing the object

func FillForm 

func FillForm(pdfBytes []byte, formData types.FormData, password []byte, verbose bool) ([]byte, error)

FillForm fills AcroForm fields with values from FormData Returns modified PDF bytes This is a convenience wrapper around FillFormFields

func FillFormFields 

func FillFormFields(pdfBytes []byte, formData types.FormData, password []byte, verbose bool) ([]byte, error)

FillFormFields fills multiple fields in a PDF using an incremental update so that existing xref offsets are never invalidated.

func FillFormFieldsWithStreams 

func FillFormFieldsWithStreams(pdfBytes []byte, formData types.FormData, password []byte, verbose bool) ([]byte, error)

FillFormFieldsWithStreams fills form fields, handling both direct objects and object streams

func FillFormFromSchema 

func FillFormFromSchema(pdfBytes []byte, schema *types.FormSchema, formData types.FormData, password []byte, verbose bool) ([]byte, error)

FillFormFromSchema fills a form from FormSchema and FormData.

func FlattenForm 

func FlattenForm(pdfBytes []byte, password []byte, verbose bool) ([]byte, error)

FlattenForm converts all filled AcroForm widget annotations to static page content. For each widget that has a normal appearance stream (/AP/N):

  • The appearance is placed on the page as a Form XObject reference.
  • The page /Resources /XObject dict is updated to include the AP stream.
  • Widget annotations are removed from /Annots.

After flattening, the PDF has no interactive form fields — /AcroForm is removed from the catalog. Unfilled fields (no AP stream) are silently dropped; they leave no visual trace.

Both inline and indirect /Resources dicts are handled.

func RebuildObjectStream 

func RebuildObjectStream(pdfBytes []byte, streamObjNum int, updates []StreamObjectUpdate, encryptInfo *types.PDFEncryption, verbose bool) ([]byte, error)

RebuildObjectStream rebuilds an object stream with updated objects

func ReplaceFieldObject 

func ReplaceFieldObject(pdfBytes []byte, objNum, genNum int, newContent []byte, encryptInfo *types.PDFEncryption, verbose bool) ([]byte, error)

ReplaceFieldObject replaces a field object in a PDF

func ValidateField 

func ValidateField(field *Field, value interface{}) error

ValidateField validates a single field value against its constraints

func ValidateFieldValue 

func ValidateFieldValue(question *types.Question, value interface{}) error

ValidateFieldValue validates a field value using FormSchema validation rules

func ValidateFormData 

func ValidateFormData(acroForm *AcroForm, formData types.FormData) []error

ValidateFormData validates all fields in form data against the AcroForm

func ValidateFormSchema 

func ValidateFormSchema(schema *types.FormSchema, formData types.FormData) []error

ValidateFormSchema validates form data against a FormSchema

Types

type AcroForm 

type AcroForm struct {
	Fields          []*Field
	NeedAppearances bool
	SignatureFields []int // Object numbers of signature fields
	XFA             bool  // True if XFA is present (hybrid form)
}

AcroForm represents an AcroForm dictionary structure

func ExtractAcroForm 

func ExtractAcroForm(pdfBytes []byte, password []byte, verbose bool) (*AcroForm, error)

ExtractAcroForm extracts AcroForm structure from a PDF This is the main entry point for AcroForm extraction

func ParseAcroForm 

func ParseAcroForm(pdfBytes []byte, encryptInfo *types.PDFEncryption, verbose bool) (*AcroForm, error)

ParseAcroForm extracts AcroForm structure from a PDF

func (*AcroForm) FindFieldByName 

func (af *AcroForm) FindFieldByName(name string) *Field

FindFieldByName finds a field by its name

func (*AcroForm) GetFieldValues 

func (af *AcroForm) GetFieldValues() map[string]interface{}

GetFieldValues extracts current values from all AcroForm fields

func (*AcroForm) ToFormSchema 

func (af *AcroForm) ToFormSchema() *types.FormSchema

ToFormSchema converts AcroForm to FormSchema

type Action 

type Action struct {
	Type        ActionType
	URI         string // For URI actions
	JavaScript  string // For JavaScript actions
	Destination string // For GoTo actions (e.g., "1 0 R" or page number)
	PageNum     int    // For GoTo actions (page number)
}

Action represents a PDF action

type ActionType 

type ActionType string

ActionType represents the type of PDF action 

const (
	ActionTypeGoTo       ActionType = "GoTo"       // Navigate to a page/destination
	ActionTypeURI        ActionType = "URI"        // Open a URI
	ActionTypeJavaScript ActionType = "JavaScript" // Execute JavaScript
	ActionTypeSubmit     ActionType = "SubmitForm" // Submit form
	ActionTypeReset      ActionType = "ResetForm"  // Reset form
)

type AppearanceBuilder 

type AppearanceBuilder struct {
	// contains filtered or unexported fields
}

AppearanceBuilder helps create appearance streams for form fields

func NewAppearanceBuilder 

func NewAppearanceBuilder(w *write.PDFWriter) *AppearanceBuilder

NewAppearanceBuilder creates a new appearance builder

func (*AppearanceBuilder) CreateButtonAppearance 

func (ab *AppearanceBuilder) CreateButtonAppearance(label string, width, height, fontSize float64) (int, error)

CreateButtonAppearance creates an appearance stream for a button

func (*AppearanceBuilder) CreateCheckboxAppearance 

func (ab *AppearanceBuilder) CreateCheckboxAppearance(checked bool, width, height float64) (int, error)

CreateCheckboxAppearance creates an appearance stream for a checkbox

func (*AppearanceBuilder) CreateTextAppearance 

func (ab *AppearanceBuilder) CreateTextAppearance(text string, width, height, fontSize float64, fontName string) (int, error)

CreateTextAppearance creates an appearance stream for a text field

type Field 

type Field struct {
	ObjectNum  int
	Generation int
	FT         string                 // Field type: Tx (text), Btn (button), Ch (choice), Sig (signature)
	Parent     *Field                 // Parent field (for fields in a hierarchy)
	Kids       []*Field               // Child fields
	T          string                 // Field name (partial name)
	TU         string                 // Alternate field name
	TM         string                 // Mapping name
	Ff         int                    // Field flags (/Ff)
	F          int                    // Widget annotation flags (/F); bit 2 (0x2) = Hidden
	V          interface{}            // Field value
	DV         interface{}            // Default value
	AA         map[string]interface{} // Additional actions
	DA         string                 // Default appearance string
	Q          int                    // Quadding (justification)
	MaxLen     int                    // Maximum length (for text fields)
	Opt        []interface{}          // Options (for choice fields)
	TI         int                    // Top index (for choice fields)
	I          []int                  // Selected indices (for choice fields)
	Rect       []float64              // Field rectangle [llx lly urx ury]
	Page       int                    // Page number (0-indexed)
}

Field represents a single AcroForm field

func (*Field) GetFullName 

func (f *Field) GetFullName() string

GetFullName returns the full field name (handles hierarchical names)

func (*Field) ToQuestion 

func (f *Field) ToQuestion() *types.Question

ToQuestion converts a Field to a Question

type FieldBuilder 

type FieldBuilder struct {
	// contains filtered or unexported fields
}

FieldBuilder helps build AcroForm fields

func NewFieldBuilder 

func NewFieldBuilder(w *write.PDFWriter) *FieldBuilder

NewFieldBuilder creates a new field builder

func (*FieldBuilder) AddButton 

func (fb *FieldBuilder) AddButton(name string, rect []float64, page int) *FieldDef

AddButton adds a push button

func (*FieldBuilder) AddCheckbox 

func (fb *FieldBuilder) AddCheckbox(name string, rect []float64, page int) *FieldDef

AddCheckbox adds a checkbox field

func (*FieldBuilder) AddChoiceField 

func (fb *FieldBuilder) AddChoiceField(name string, rect []float64, page int, options []string) *FieldDef

AddChoiceField adds a combo-box (dropdown) field

func (*FieldBuilder) AddListBox 

func (fb *FieldBuilder) AddListBox(name string, rect []float64, page int, options []string) *FieldDef

AddListBox adds a list box (scrollable selection, always visible). Unlike a combo box, a list box displays multiple options simultaneously.

func (*FieldBuilder) AddRadioButton 

func (fb *FieldBuilder) AddRadioButton(name string, rect []float64, page int) *FieldDef

AddRadioButton adds a radio button field

func (*FieldBuilder) AddTextField 

func (fb *FieldBuilder) AddTextField(name string, rect []float64, page int) *FieldDef

AddTextField adds a text field to the form

func (*FieldBuilder) AddUnderlineTextField 

func (fb *FieldBuilder) AddUnderlineTextField(name string, rect []float64, page int) *FieldDef

AddUnderlineTextField adds a text field with only a bottom border (underline style).

func (*FieldBuilder) Build 

func (fb *FieldBuilder) Build() (int, error)

Build creates all field objects without page linkage (useful for unit testing). Returns the AcroForm dict object number.

type FieldDef 

type FieldDef struct {
	Name         string
	Type         string // Tx, Btn, Ch
	Value        interface{}
	DefaultValue interface{}
	Rect         []float64 // [llx lly urx ury]
	Page         int       // 0-based page index
	Flags        int
	Options      []string // For choice fields
	MaxLen       int      // For text fields
	Required     bool
	ReadOnly     bool
	FontSize     float64 // 0 = auto
	BorderStyle  string  // PDF /BS /S value: "S" solid (default), "U" underline, "D" dashed, "B" beveled, "I" inset
}

FieldDef represents a field definition for creation

func (*FieldDef) SetBorderStyle 

func (fd *FieldDef) SetBorderStyle(style string) *FieldDef

SetBorderStyle sets the PDF border style for a text field. Common values: "S" solid (default), "U" underline (bottom line only), "D" dashed, "B" beveled, "I" inset.

func (*FieldDef) SetDefault 

func (fd *FieldDef) SetDefault(value interface{}) *FieldDef

func (*FieldDef) SetFontSize 

func (fd *FieldDef) SetFontSize(pt float64) *FieldDef

func (*FieldDef) SetMaxLength 

func (fd *FieldDef) SetMaxLength(maxLen int) *FieldDef

func (*FieldDef) SetMultiline 

func (fd *FieldDef) SetMultiline(v bool) *FieldDef

SetMultiline makes a text field multi-line (wraps text, shows scrollbar).

func (*FieldDef) SetPassword 

func (fd *FieldDef) SetPassword(v bool) *FieldDef

SetPassword makes a text field a password field (input is obscured with •).

func (*FieldDef) SetReadOnly 

func (fd *FieldDef) SetReadOnly(readonly bool) *FieldDef

func (*FieldDef) SetRequired 

func (fd *FieldDef) SetRequired(required bool) *FieldDef

func (*FieldDef) SetValue 

func (fd *FieldDef) SetValue(value interface{}) *FieldDef

type FormBuilder 

type FormBuilder struct {
	// contains filtered or unexported fields
}

FormBuilder integrates AcroForm creation with SimplePDFBuilder. Typical usage: 

builder := write.NewSimplePDFBuilder()
page := builder.AddPage(write.PageSizeLetter)
// ... add page content ...
builder.FinalizePage(page)

fb := acroform.NewFormBuilder(builder)
fb.AddTextField("name", []float64{72, 700, 300, 720}, 0)
fb.BuildForm()

pdfBytes, _ := builder.Bytes()

func NewFormBuilder 

func NewFormBuilder(builder *write.SimplePDFBuilder) *FormBuilder

NewFormBuilder creates a new FormBuilder backed by the given SimplePDFBuilder.

func (*FormBuilder) AddButton 

func (fb *FormBuilder) AddButton(name string, rect []float64, page int) *FieldDef

func (*FormBuilder) AddCheckbox 

func (fb *FormBuilder) AddCheckbox(name string, rect []float64, page int) *FieldDef

func (*FormBuilder) AddChoiceField 

func (fb *FormBuilder) AddChoiceField(name string, rect []float64, page int, options []string) *FieldDef

func (*FormBuilder) AddListBox 

func (fb *FormBuilder) AddListBox(name string, rect []float64, page int, options []string) *FieldDef

AddListBox adds a list box (scrollable multi-option selection, always visible). Unlike AddChoiceField (combo/dropdown), a list box shows multiple options at once.

func (*FormBuilder) AddRadioButton 

func (fb *FormBuilder) AddRadioButton(name string, rect []float64, page int) *FieldDef

func (*FormBuilder) AddTextField 

func (fb *FormBuilder) AddTextField(name string, rect []float64, page int) *FieldDef

func (*FormBuilder) AddUnderlineTextField 

func (fb *FormBuilder) AddUnderlineTextField(name string, rect []float64, page int) *FieldDef

func (*FormBuilder) BuildForm 

func (fb *FormBuilder) BuildForm() (int, error)

BuildForm writes all field+widget objects, wires them into the correct page /Annots arrays, builds the /AcroForm dict, and registers it with the SimplePDFBuilder so Bytes() includes /AcroForm in the catalog.

Call this AFTER all pages have been finalized with FinalizePage().

type StreamObjectUpdate 

type StreamObjectUpdate struct {
	ObjNum     int
	Index      int
	NewContent []byte
}

StreamObjectUpdate tracks updates to objects in a stream

type ValidationError 

type ValidationError struct {
	FieldName string
	Message   string
	Value     interface{}
}

ValidationError represents a validation error for a field

func (*ValidationError) Error 

func (e *ValidationError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.