FoxitPDFSDKforWeb v11.0.1
Foxit PDF SDK for Web
PDFForm Class Reference

Represents a PDF form within a document.

This class provides various methods for interacting with and manipulating form fields within a PDF document. It integrates with the underlying document and form APIs to perform operations such as submitting, importing, and resetting form fields. The PDFForm class is also responsible for managing form field events and maintaining the form's state. More...

Inheritance diagram for PDFForm:
Disposable

Public Member Functions

async cloneWidgets (options:CloneWidgetOptions|CloneWidgetOptions[])
 Clones widgets from one page to another based on the provided options. More...
 
 createCheckbox (options:CreateCheckBoxOptions)
 Create a checkbox form widget. More...
 
 createComboBox (options:CreateComboBoxOptions)
 Create a combo box form widget. More...
 
 createDatetime (options:CreateDatetimeOptions)
 Create a date and time field form widget. More...
 
 createImageButton (options:CreateImageButtonOptions)
 Create an image button form field. More...
 
 createListBox (options:CreateListBoxOptions)
 Create a list box form widget. More...
 
 createPushButton (options:CreatePushButtonOptions)
 Create a push button form field. More...
 
 createRadioButton (options:CreateRadioButtonOptions)
 Create a radio button form widget. More...
 
 createSignature (options:CreateSignatureOptions)
 Create a signature form widget. More...
 
 createTextField (options:CreateTextFieldOptions)
 Create a text field form widget. More...
 
async exportToFile (fileFormat:FileFormat, options:ExportFormOptions={})
 Exports the form data to a specified file format. More...
 
 fixPageFields (pageIndex:number)
 Fix the fields which are in a PDF page but cannot be counted by current form object. More...
 
async getField (fieldName:FieldName)
 Retrieves a field by its name. More...
 
async getFieldAtPosition (pageIndex:number, pos:PDFPoint, fieldType?:FieldType)
 Retrieves a field by its position on a page. If there are multiple fields at this position, only return the top-level field. More...
 
async getFields ()
 Retrieves all fields in the PDF document. More...
 
async getFieldsByNamePrefix (fieldNamePrefix:string)
 Retrieves all fields in the PDF document with names matching the given prefix. More...
 
 getFieldsInCalculationOrder ()
 Get an array of form fields in calculation order. The calculation order defines the order in which the values of fields will be recalculated when value of any field is changed. Usually, these fields have calculation actions. More...
 
 getHighlightColor ()
 Gets the highlight color of the form fields. More...
 
async getWidgetAtPoint (pageIndex:number, point:PDFPoint, fieldType?:FieldType)
 Retrieves a widget located at a specific point on a given page. More...
 
 hasFieldsInCalculationOrder ()
 Determines if there are any form fields with calculation actions. This function checks whether any form fields have been set up with calculation actions, which require recalculations when the values of certain fields change. More...
 
 importFromFile (data:BufferSource|Blob|string, fileFormat:FileFormat, options?:ImportFormOptions)
 Imports form data from a specified file format. More...
 
 isHighlight ()
 Gets whether the form fields are highlighted. More...
 
 onHighlightChanged (callback:(isHighlight:boolean, highlightColor:number, requiredColor:number)=> void)
 Registers a callback function to be called when the form fields highlighting is changed. More...
 
async resetForm (fieldNames?:FieldName[], isExclude=true)
 Resets the value of the specified form fields to their default values. More...
 
 setDefaultFieldNameGenerator (generator:(type:ExtFieldType)=> Promise< string >|string)
 Sets the default field name generator for form fields. More...
 
async setFieldsInCalculationOrder (fieldNames:FieldName[])
 Sets the calculation order of form fields. More...
 
 setHighlight (isHighlight:boolean)
 Sets whether the form fields should be highlighted. More...
 
 setHighlightColor (color:number)
 Sets the highlight color of the form fields. More...
 
- Public Member Functions inherited from Disposable
 addDestroyHook (...hooks)
 Add a function to destroyHooks list, which will be called during destroy. More...
 
 destroy ()
 
 ownsTo (owner)
 Establishes an ownership relationship where this instance will be destroyed when the owner is destroyed. Additionally, the owner will be automatically removed from the destroyHooks list when this instance is destroyed. More...
 

Detailed Description

Represents a PDF form within a document.

This class provides various methods for interacting with and manipulating form fields within a PDF document. It integrates with the underlying document and form APIs to perform operations such as submitting, importing, and resetting form fields. The PDFForm class is also responsible for managing form field events and maintaining the form's state.

Since
11.0.0

Member Function Documentation

◆ cloneWidgets()

async PDFForm::cloneWidgets ( options:CloneWidgetOptions|  CloneWidgetOptions[])
inline

Clones widgets from one page to another based on the provided options.

Parameters
optionsCloneWidgetOptions|CloneWidgetOptions[] - A single or an array of options specifying the widgets to be cloned and their target positions.
Returns
Promise<AnnotId[]> - A promise that resolve with an array of AnnotId objects representing the cloned widgets, each containing the page index and object number of the new widget.
Exceptions
Willthrow an error if the target page does not exist or if the source widget is not found. Also throws if an invalid field name is provided.

◆ createCheckbox()

PDFForm::createCheckbox (   options:CreateCheckBoxOptions)
inline

Create a checkbox form widget.

This method creates a checkbox form widget in the PDF document using the specified options.

Parameters
optionsCreateCheckBoxOptions - Options for creating the checkbox widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createComboBox()

PDFForm::createComboBox (   options:CreateComboBoxOptions)
inline

Create a combo box form widget.

This method creates a combo box form widget in the PDF document using the specified options.

Parameters
optionsCreateComboBoxOptions - Options for creating the combo box widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createDatetime()

PDFForm::createDatetime (   options:CreateDatetimeOptions)
inline

Create a date and time field form widget.

This method creates a date and time field form widget in the PDF document. The date and time format will be set to the given timeformat.

Parameters
optionsCreateDatetimeOptions - Options for creating the date and time field form widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createImageButton()

PDFForm::createImageButton (   options:CreateImageButtonOptions)
inline

Create an image button form field.

This method creates a push button form field with an image icon. The image path is specified in the options and is used to set the button's icon. Additionally, it sets up a mouse button release action to import the icon on button click.

Parameters
optionsCreateImageButtonOptions - Options for creating an image button form field, including the image path and any additional actions.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createListBox()

PDFForm::createListBox (   options:CreateListBoxOptions)
inline

Create a list box form widget.

This method creates a list box form widget in the PDF document using the specified options.

Parameters
optionsBasicCreateWidgetOptions - Options for creating the list box widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createPushButton()

PDFForm::createPushButton (   options:CreatePushButtonOptions)
inline

Create a push button form field.

Parameters
optionsCreatePushButtonOptions - Options for creating a push button form field.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createRadioButton()

PDFForm::createRadioButton (   options:CreateRadioButtonOptions)
inline

Create a radio button form widget.

This method creates a radio button form widget in the PDF document using the specified options.

Parameters
optionsCreateRadioButtonOptions - Options for creating the radio button widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createSignature()

PDFForm::createSignature (   options:CreateSignatureOptions)
inline

Create a signature form widget.

This method creates a signature form widget in the PDF document using the specified options.

Parameters
optionsCreateSignatureOptions - Options for creating the signature form widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ createTextField()

PDFForm::createTextField (   options:CreateTextFieldOptions)
inline

Create a text field form widget.

This method creates a text field form widget in the PDF document.

Parameters
optionsCreateTextFieldOptions - Options for creating the text field form widget.
Returns
Promise<Widget> - A promise which resolves to the created form widget.
Exceptions
Errorif the document is not open or is closed.
Since
11.0.0

◆ exportToFile()

async PDFForm::exportToFile (   fileFormat:FileFormat,
  options:ExportFormOptions = {} 
)
inline

Exports the form data to a specified file format.

Parameters
fileFormatFileFormat - The file format to export the form data to. supported formats: 'xfdf', 'fdf', 'csv', 'json', 'text' and 'xml'.
optionsExportFormOptions - Additional options for exporting the form data.
Returns
Promise<Blob> - A promise that resolves with a blob object containing the exported form data in the specified format.
Exceptions
Errorif the specified file format is not supported.
Since
11.0.0

◆ fixPageFields()

PDFForm::fixPageFields (   pageIndex:number)
inline

Fix the fields which are in a PDF page but cannot be counted by current form object.

It may cost much time if there are many fields in the specified page.

Parameters
pageIndexnumber - Valid range: from 0 to (count-1). count is returned by function PDFDoc.getPageCount
Returns
Promise<void> - A promise that resolves once the fields are fixed.

◆ getField()

async PDFForm::getField (   fieldName:FieldName)
inline

Retrieves a field by its name.

Parameters
fieldNamestring - The name of the field to retrieve.
Returns
Promise<PDFFormField|undefined> - The requested field, or undefined if not found.
Exceptions
Errorif the field specified by fieldName is not found.
Since
11.0.0

◆ getFieldAtPosition()

async PDFForm::getFieldAtPosition (   pageIndex:number,
  pos:PDFPoint,
  fieldType?:FieldType 
)
inline

Retrieves a field by its position on a page. If there are multiple fields at this position, only return the top-level field.

Parameters
pageIndexnumber - The index of the page that contains the field.
posPDFPoint - The position of the field.
[fieldType]FieldType - The type of form field to consider when searching. If not specified, it will retrieve the first form control at the specified position regardless of the field type.
Returns
Promise<PDFFormField|undefined> - The requested field, or undefined if not found.
Since
11.0.0

◆ getFields()

async PDFForm::getFields ( )
inline

Retrieves all fields in the PDF document.

This method returns an array of PDFFormField objects, which represent the form fields in the document.

Returns
Promise<PDFFormField[]> - An array of PDFFormField objects.
Since
11.0.0

◆ getFieldsByNamePrefix()

async PDFForm::getFieldsByNamePrefix (   fieldNamePrefix:string)
inline

Retrieves all fields in the PDF document with names matching the given prefix.

This method returns an array of PDFFormField objects, which represent the form fields in the document with names matching the given prefix.

Field names are separated by a dot (.) character.

Parameters
fieldNamePrefixstring - The prefix to match against the field names.
Returns
Promise<PDFFormField[]> - An array of PDFFormField objects.
Since
11.0.0

◆ getFieldsInCalculationOrder()

PDFForm::getFieldsInCalculationOrder ( )
inline

Get an array of form fields in calculation order. The calculation order defines the order in which the values of fields will be recalculated when value of any field is changed. Usually, these fields have calculation actions.

Returns
Promise<string[]> - The form field names in the calculation order.
Since
11.0.0

◆ getHighlightColor()

PDFForm::getHighlightColor ( )
inline

Gets the highlight color of the form fields.

Returns
number - The highlight color of the form fields. The color is represented as a 24-bit integer in the format 0xRRGGBB.
Since
11.0.0

◆ getWidgetAtPoint()

async PDFForm::getWidgetAtPoint (   pageIndex:number,
  point:PDFPoint,
  fieldType?:FieldType 
)
inline

Retrieves a widget located at a specific point on a given page.

This function queries the PDF document to find a widget that is situated at the specified coordinates on the designated page, considering the field type provided. The coordinates should be in PDF units.

Parameters
pageIndexnumber - The index of the page to search for the widget.
pointPDFPoint - The x and y coordinates on the page where the widget is expected.
[fieldType]FieldType - The type of form field to consider when searching. If not specified, it will retrieve the first form control at the specified position regardless of the field type.
Returns
Promise<Widget | undefined> - The widget found at the specified point, or undefined if no widget is found at that location.
Since
11.0.0

◆ hasFieldsInCalculationOrder()

PDFForm::hasFieldsInCalculationOrder ( )
inline

Determines if there are any form fields with calculation actions. This function checks whether any form fields have been set up with calculation actions, which require recalculations when the values of certain fields change.

Returns
Promise<boolean> - Resolves to true if any fields have calculation actions, otherwise false.
Since
11.0.0

◆ importFromFile()

PDFForm::importFromFile ( data:BufferSource|Blob|  string,
  fileFormat:FileFormat,
  options?:ImportFormOptions 
)
inline

Imports form data from a specified file format.

This function imports the form data from a specified file format into the PDF document. It supports importing from XFDF, FDF, CSV, JSON, Text and XML files.

Parameters
dataBufferSource|Blob|string - The form data in the specified file format.
fileFormatFileFormat - The file format of the data to be imported. supported formats: 'xfdf', 'fdf', 'csv', 'json', 'text' and 'xml'.
[options]ImportFormOptions - Additional options for importing the form data.
Returns
Promise<void> - A promise that resolves when the import process is complete.
Exceptions
Errorif the specified file format is not supported.
Since
11.0.0

◆ isHighlight()

PDFForm::isHighlight ( )
inline

Gets whether the form fields are highlighted.

Returns
boolean - Whether the form fields are highlighted.
Since
11.0.0

◆ onHighlightChanged()

PDFForm::onHighlightChanged (   callback:(isHighlight:boolean, highlightColor:number, requiredColor:number),
  void 
)
inline

Registers a callback function to be called when the form fields highlighting is changed.

Parameters
callback(isHighlight:boolean,highlightColor:number,requiredColor:number)=>void - The callback function to be called when the form fields highlighting is changed. The callback function takes three parameters, isHighlight, highlightColor and requiredColor. isHighlight is a boolean indicating whether the form fields are highlighted. highlightColor is a number indicating the highlight color of the form fields. The color is represented as a 24-bit integer in the format 0xRRGGBB. requiredColor is a number indicating the required color of the form fields. The color is represented as a 24-bit integer in the format 0xRRGGBB.
Returns
()=>void - A function that can be used to unsubscribe the callback function.
Since
11.0.0

◆ resetForm()

async PDFForm::resetForm (   fieldNames?:FieldName[],
  isExclude = true 
)
inline

Resets the value of the specified form fields to their default values.

Parameters
[fieldNames]string[] - The names of the fields to reset.
[isExclude=true]boolean - If true, the fields specified in fieldNames will be excluded from the reset. If false, only the fields specified in fieldNames will be reset. You can reset all fields by setting fieldNames to an empty array and isExclude to true.
Returns
Promise<void> - Resolves once the fields are reset.
Since
11.0.0

◆ setDefaultFieldNameGenerator()

PDFForm::setDefaultFieldNameGenerator (   generator:(type:ExtFieldType),
Promise< string >|  string 
)
inline

Sets the default field name generator for form fields.

This method sets a custom generator function to determine the default field name based on the extended field type.

Parameters
generator(type:ExtFieldType)=>Promise<string>|string - A function that takes an extended field type and returns a string representing the default field name. The function can return a promise to allow for asynchronous name generation.
Since
11.0.0

◆ setFieldsInCalculationOrder()

async PDFForm::setFieldsInCalculationOrder (   fieldNames:FieldName[])
inline

Sets the calculation order of form fields.

Parameters
fieldNamesstring[] - An array of field names that define the calculation order.
Returns
Promise<void> -
Since
11.0.0

◆ setHighlight()

PDFForm::setHighlight (   isHighlight:boolean)
inline

Sets whether the form fields should be highlighted.

Note
This method needs to be used in conjunction with PDFViewer.redraw or PDFUI.redraw methods to make it effective.
Parameters
isHighlightboolean - Whether the form fields should be highlighted.
Returns
Promise<void> - A promise that resolves when the highlighting is set.
Since
11.0.0

◆ setHighlightColor()

PDFForm::setHighlightColor (   color:number)
inline

Sets the highlight color of the form fields.

Note
This method needs to be used in conjunction with PDFViewer.redraw or PDFUI.redraw methods to make it effective.
Parameters
colornumber - The highlight color of the form fields. The color is represented as a 24-bit integer in the format 0xRRGGBB.
Returns
Promise<void> - A promise that resolves when the highlight color of the form fields is set.
Since
11.0.0

Foxit Software Corporation Logo
@2025 Foxit Software Incorporated. All rights reserved.