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:

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