| FoxitPDFSDKforWeb v11.0.4 Archives Foxit PDF SDK for Web

Public Member Functions | List of all members
PDFForm Class Reference
PDF » form

## 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:

## 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

  options | CloneWidgetOptions|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

  Will | throw 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

  options | CreateCheckBoxOptions - Options for creating the checkbox widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateComboBoxOptions - Options for creating the combo box widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateDatetimeOptions - Options for creating the date and time field form widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateImageButtonOptions - 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

  Error | if 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

  options | BasicCreateWidgetOptions - Options for creating the list box widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreatePushButtonOptions - Options for creating a push button form field.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateRadioButtonOptions - Options for creating the radio button widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateSignatureOptions - Options for creating the signature form widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  options | CreateTextFieldOptions - Options for creating the text field form widget.

Returns
  Promise<Widget> - A promise which resolves to the created form widget.

Exceptions

  Error | if 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

  fileFormat | FileFormat - The file format to export the form data to. supported formats: 'xfdf', 'fdf', 'csv', 'json', 'text' and 'xml'.
  options | ExportFormOptions - 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

  Error | if 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

  pageIndex | number - 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

  fieldName | string - The name of the field to retrieve.

Returns
  Promise<PDFFormField|undefined> - The requested field, or undefined if not found.

Exceptions

  Error | if 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

  pageIndex | number - The index of the page that contains the field.
  pos | PDFPoint - 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

  fieldNamePrefix | string - 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

  pageIndex | number - The index of the page to search for the widget.
  point | PDFPoint - 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

  data | BufferSource|Blob|string - The form data in the specified file format.
  fileFormat | FileFormat - 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

  Error | if 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

  fieldNames | string[] - 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

  isHighlight | boolean - 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

  color | number - 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

@2025 Foxit Software Incorporated. All rights reserved.