Foxit PDF SDK

构造函数 | 属性 | 所有成员列表
FSForm类 参考
类 FSForm 继承关系图:

## 构造函数
(FSControl *) | - addControl:field_name:field_type:rect:
| 向指定表单字段添加新的表单控件。如果表单字段不存在，此函数也将 添加表单字段。（不支持签名字段） 更多...
(BOOL) | - exportToCSV:pdf_file_name:is_append:
| 将表单数据导出到CSV文件。 更多...
(BOOL) | - exportToCSVWithStreamCallback:pdf_file_name:is_append:
| 将表单数据导出到CSV文件。 更多...
(BOOL) | - exportToTXT:field_array:is_include:
| 将指定表单字段的数据导出到TXT文件。 更多...
(BOOL) | - exportToTXTWithWriterCallback:field_array:is_include:
| 将指定表单字段的数据导出到TXT文件。 更多...
(BOOL) | - exportToXML:
| 将表单数据导出到XML文件。 更多...
(BOOL) | - exportToXMLWithFieldArray:field_array:is_include:
| 将指定表单字段的数据导出到XML文件。 更多...
(BOOL) | - exportToXMLWithWriterCallback:field_array:is_include:
| 将指定表单字段的数据导出到XML文件。 更多...
(void) | - fixPageFields:
| 修复在PDF页面中但无法被当前表单对象计数的字段。 更多...
(FSControl *) | - getControl:index:
| 在指定PDF页面中通过索引获取表单控件。 更多...
(FSControl *) | - getControlAtDevicePoint:point:tolerance:type:matrix:
| 在设备坐标系统中的指定位置获取表单控件。 更多...
(FSControl *) | - getControlAtPoint:point:tolerance:type:
| 在PDF坐标系统中的指定位置获取表单控件。 更多...
(int) | - getControlCount:
| 获取指定PDF页面中的表单控件数量。 更多...
(FSPDFDictionary *) | - getDict
| 获取当前对象的字典。 更多...
(FSPDFDoc *) | - getDocument
| 获取与当前表单对象关联的PDF文档。 更多...
(FSField *) | - getField:filter:
| 通过索引获取名称满足指定名称过滤器的表单字段。 更多...
(int) | - getFieldCount:
| 获取名称满足指定名称过滤器的表单字段数量。 更多...
(FSFiller *) | - getFormFiller
| 获取表单填写器。 更多...
(BOOL) | - importFromXML:
| 从XML文件导入表单数据。 更多...
(id) | - initWithDocument:
| 构造函数，使用PDF文档。 更多...
(id) | - initWithOther:
| 构造函数，使用另一个表单对象。 更多...
(BOOL) | - isEmpty
| 检查当前对象是否为空。 更多...
(BOOL) | - moveControl:field_name:
| 将控件移动到由字段名称指定的字段。 更多...
(BOOL) | - needConstructAppearances
| 检查加载表单控件时是否构造外观。 更多...
(void) | - removeControl:
| 删除表单控件。（不支持从签名字段删除表单控件） 更多...
(void) | - removeField:
| 删除表单字段。（不支持签名字段） 更多...
(BOOL) | - renameField:new_field_name:
| 用新名称重命名字段。 更多...
(BOOL) | - reset
| 将所有字段（签名字段除外）的数据重置为其默认值。 更多...
(void) | - setConstructAppearances:
| 设置指定加载表单控件时是否构造外观的标志。 更多...
(BOOL) | - validateFieldName:field_name:
| 验证字段名称是否可用于指定字段类型的新字段。 更多...

## 属性
FSAlignment | alignment
| 获取用作文档范围默认值的对齐值。 更多...
FSDefaultAppearance * | defaultAppearance
| 获取默认外观数据。
FSFieldArray * | fieldsInCalculationOrder
| 获取按计算顺序排列的表单字段数组。 更多...

## 详细描述

交互式表单——有时称为AcroForm——是一个用于从用户交互式收集信息的字段集合。 PDF文档可能包含出现在页面任意组合上的任意数量的字段，所有这些字段构成跨越整个文档的 单一全局交互式表单。这些字段的任意子集可以从文档导入或导出。
函数FSPDFDoc::hasForm可用于判断PDF文档是否有交互式表单。
表单对象可以从指定的PDF文档构造。此类提供检索表单字段 或表单控件、导入/导出表单数据和其他功能的函数。例如：

- 要检索表单字段，请使用函数FSForm::getFieldCount:和FSForm::getField:filter:。
- 要从PDF页面检索表单控件，请使用函数FSForm::getControlCount:和 FSForm::getControl:index:。
- 要从XML文件导入表单数据，请使用函数FSForm::importFromXML:； 要导出表单数据到XML文件，请使用函数FSForm::exportToXML:。
- 要检索表单填写器对象，请使用函数FSForm::getFormFiller。

要从FDF/XFDF文件导入表单数据或将此类数据导出到FDF/XFDF文件，请参考函数 FSPDFDoc::importFromFDF:types:page_range:和FSPDFDoc::exportToFDF:types:page_range:。
要填写表单，请通过当前表单对象构造表单填写器对象，或者如果此类对象已经构造， 请通过函数FSForm::getFormFiller检索填写器对象。（一个交互式表单只应有一个表单填写器对象）。

参见
  FSPDFDoc
  FSFiller

## 函数文档

## ◆ addControl:field_name:field_type:rect:()

- (FSControl *) addControl: |  | (FSPDFPage*) | page
field_name: |  | (NSString *) | field_name
field_type: |  | (FSFieldType) | field_type
rect: |  | (FSRectF*) | rect

向指定表单字段添加新的表单控件。如果表单字段不存在，此函数也将 添加表单字段。（不支持签名字段）

应用程序可以使用此函数添加新的表单控件：

- 如果指定的表单字段存在，将创建新的表单控件并设置到字段。
- 如果指定的表单字段不存在，将根据参数field_name和field_type 创建新的表单字段并添加到表单，同时创建新的表单控件。

表单字段是否存在，将通过输入参数field_name和field_type来判断。
如果用户想要添加新的签名字段，请使用函数FSPDFPage::addSignature: 而不是当前函数。
新添加的表单控件没有外观，因此用户应该使用Control类中的设置方法 或相关PDF字段或控件注释中的设置方法来设置会影响外观的属性。 类FSControl和FSField 的一些设置方法可能 直接更新外观，但仍建议调用相关控件注释的函数 FSAnnot::resetAppearanceStream以确保外观确实会被更新。
对于按钮、复选框、单选按钮，如果用户在不设置任何属性的情况下直接调用函数 FSAnnot::resetAppearanceStream，将使用默认外观样式：

- 按钮：在相关控件注释中，背景色（在MK字典中）= 0xC0C0C0， 高亮模式 = FSAnnotHighlightingPush。
- 复选框/单选按钮：在相关控件注释中，边框宽度 = 1.0， 边框样式 = FSBorderInfoSolid， 背景色（在MK字典中）= 0xFFFFFF，边框色（在MK字典中）= 0xFFFFFF。

参数

  [in] | page | 有效的PDF页面，将在其中添加新的表单控件。它应该属于 与当前表单相同的PDF文档。
  [in] | field_name | 字段名称。它不应该是空字符串。
  [in] | field_type | 字段类型。请参考从FSFieldTypePushButton开始的值， 这应该是其中一个值，除了FSFieldTypeSignature。 如果这是FSFieldTypeSignature，此函数将抛出异常 FSErrUnsupported。
  [in] | rect | 新表单控件的矩形，指定在PDF页面中的位置。 它应该在PDF坐标系统中。

返回
  新添加的表单控件对象。

## ◆ exportToCSV:pdf_file_name:is_append:()

- (BOOL) exportToCSV: |  | (NSString *) | csv_file_path
pdf_file_name: |  | (NSString *) | pdf_file_name
is_append: |  | (BOOL) | is_append

将表单数据导出到CSV文件。

参数

  [in] | csv_file_path | CSV文件的完整文件路径。这指定了表单数据将导出到的CSV文件。 这不应该是空字符串。
  [in] | pdf_file_name | 当前PDF文档的文件名。此文件名将写入CSV文件。 这可以是空字符串。
  [in] | is_append | 布尔值，用于决定如果CSV文件存在，表单数据是否追加到CSV文件： YES 表示将表单数据追加到现有CSV文件，NO 表示不追加。

返回
  YES 表示成功，NO 表示失败。

## ◆ exportToCSVWithStreamCallback:pdf_file_name:is_append:()

- (BOOL) exportToCSVWithStreamCallback: |  | (id<FSFileStreamCallback>) | csv_file
pdf_file_name: |  | (NSString *) | pdf_file_name
is_append: |  | (BOOL) | is_append

将表单数据导出到CSV文件。

参数

  [in] | csv_file | 用户实现的FSFileStreamCallback对象，用于将表单数据保存到CSV文件。 它不应该是nil。请不要在写入回调函数中使用追加模式。
  [in] | pdf_file_name | 当前PDF文档的文件名。此文件名将写入CSV文件。 可以是空字符串。
  [in] | is_append | 用于决定如果CSV文件存在时是否将表单数据追加到CSV文件的布尔值： YES 表示将表单数据追加到现有CSV文件，NO 表示不追加。

返回
  YES means success, while NO means failure.

## ◆ exportToTXT:field_array:is_include:()

- (BOOL) exportToTXT: |  | (NSString *) | txt_file_path
field_array: |  | (FSFieldArray*) | field_array
is_include: |  | (BOOL) | is_include

将指定表单字段的数据导出到TXT文件。

参数

  [in] | txt_file_path | TXT文件的完整文件路径，指定表单字段的数据将导出到该文件。 它不应该是空字符串。
  [in] | field_array | 表单字段数组。参数is_include将决定是否导出这些表单字段的数据。 如果这是一个空数组，表示将导出所有表单字段的数据。
  [in] | is_include | 用于决定是否导出指定表单字段数据的布尔值： YES 表示将导出指定表单字段的数据，NO 表示不导出指定表单字段的数据。

返回
  YES 表示成功，NO 表示失败。

## ◆ exportToTXTWithWriterCallback:field_array:is_include:()

- (BOOL) exportToTXTWithWriterCallback: |  | (id<FSFileWriterCallback>) | txt_file
field_array: |  | (FSFieldArray*) | field_array
is_include: |  | (BOOL) | is_include

将指定表单字段的数据导出到TXT文件。

参数

  [in] | txt_file | 用户实现的FSFileWriterCallback对象， 用于将指定表单字段的数据保存到TXT文件。它不应该是nil。
  [in] | field_array | 表单字段数组。参数is_include将决定是否导出这些表单字段的数据。 如果这是一个空数组，表示将导出所有表单字段的数据。
  [in] | is_include | 用于决定是否导出指定表单字段数据的布尔值： YES 表示将导出指定表单字段的数据，NO 表示不导出指定表单字段的数据。

返回
  YES 表示成功，NO 表示失败。

## ◆ exportToXML:()

- (BOOL) exportToXML: |  | (NSString *) | file_path |

将表单数据导出到XML文件。

参数

  [in] | file_path | XML文件的完整文件路径。 这指定了表单数据将导出到的XML文件。

返回
  YES 表示成功，NO 表示失败。

## ◆ exportToXMLWithFieldArray:field_array:is_include:()

- (BOOL) exportToXMLWithFieldArray: |  | (NSString *) | file_path
field_array: |  | (FSFieldArray*) | field_array
is_include: |  | (BOOL) | is_include

将指定表单字段的数据导出到XML文件。

参数

  [in] | file_path | XML文件的完整文件路径，指定表单字段的数据将导出到此文件。
  [in] | field_array | 表单字段数组。参数is_include将决定是否 导出这些表单字段的数据。如果这是空数组，意味着将导出所有表单字段的数据。
  [in] | is_include | 布尔值，用于决定是否导出指定表单字段的数据： YES 表示导出指定表单字段的数据，NO 表示 不导出指定表单字段的数据。

返回
  YES 表示成功，NO 表示失败。

## ◆ exportToXMLWithWriterCallback:field_array:is_include:()

- (BOOL) exportToXMLWithWriterCallback: |  | (id<FSFileWriterCallback>) | xml_file
field_array: |  | (FSFieldArray*) | field_array
is_include: |  | (BOOL) | is_include

将指定表单字段的数据导出到XML文件。

参数

  [in] | xml_file | 用户实现的FSFileWriterCallback对象， 用于将指定表单字段的数据保存到XML文件。这不应该是nil。
  [in] | field_array | 表单字段数组。参数is_include将决定是否 导出这些表单字段的数据。如果这是空数组，意味着将导出所有表单字段的数据。
  [in] | is_include | 布尔值，用于决定是否导出指定表单字段的数据： YES 表示导出指定表单字段的数据，NO 表示 不导出指定表单字段的数据。

返回
  YES 表示成功，NO 表示失败。

## ◆ fixPageFields:()

- (void) fixPageFields: |  | (int) | page_index |

修复在PDF页面中但无法被当前表单对象计数的字段。

如果指定页面中有许多字段，可能会花费很长时间。

参数

  [in] | page_index | 页面索引。有效范围：从0到(count-1)。 count由函数FSPDFDoc::getPageCount返回。

返回
  无。

## ◆ getControl:index:()

- (FSControl *) getControl: |  | (FSPDFPage*) | page
index: |  | (int) | index

在指定PDF页面中通过索引获取表单控件。

参数

  [in] | page | 有效的PDF页面对象。它应该属于与当前表单相同的PDF文档。
  [in] | index | 要检索的表单控件索引。有效范围：从0到(count-1)。 count由函数FSField::getControlCount使用 相同参数page返回。

返回
  表单控件对象。

## ◆ getControlAtDevicePoint:point:tolerance:type:matrix:()

- (FSControl *) getControlAtDevicePoint: |  | (FSPDFPage*) | page
point: |  | (FSPointF*) | point
tolerance: |  | (float) | tolerance
type: |  | (FSFieldType) | type
matrix: |  | (FSMatrix2D*) | matrix

在设备坐标系统中的指定位置获取表单控件。

参数

  [in] | page | 有效的PDF页面对象。它应该与当前表单在同一文档中。
  [in] | point | 设备坐标系统中的位置。
  [in] | tolerance | 容差值。有效范围：0.0f到30.0f。
  [in] | type | 将检索其表单控件的字段类型。请参考从 FSFieldTypeUnknown开始的值，这应该是其中一个值。 FSFieldTypeUnknown表示不关心字段类型， 只检索指定位置的第一个表单控件。
  [in] | matrix | 变换矩阵。通常这由函数 FSPDFPage::getDisplayMatrix:top:width:height:rotate:返回。如果这是nil， 当前函数将具有与函数FSForm::getControlAtPoint:point:tolerance:type:相同的功能。 默认值：nil。

返回
  表单控件对象。如果返回的表单控件对象的函数FSControl::isEmpty的返回值 为YES，则意味着指定位置周围没有合适的表单控件。

## ◆ getControlAtPoint:point:tolerance:type:()

- (FSControl *) getControlAtPoint: |  | (FSPDFPage*) | page
point: |  | (FSPointF*) | point
tolerance: |  | (float) | tolerance
type: |  | (FSFieldType) | type

在PDF坐标系统中的指定位置获取表单控件。

参数

  [in] | page | 有效的PDF页面对象。它应该与当前表单在同一文档中。
  [in] | point | PDF坐标系统中的位置。
  [in] | tolerance | 容差值。有效范围：0.0f到30.0f。
  [in] | type | 将检索其表单控件的字段类型。请参考从 FSFieldTypeUnknown开始的值，这应该是其中一个值。 FSFieldTypeUnknown表示不关心字段类型， 只检索指定位置的第一个表单控件。

返回
  表单控件对象。如果返回的表单控件对象的函数FSControl::isEmpty的返回值 为YES，则意味着指定位置周围没有合适的表单控件。

## ◆ getControlCount:()

- (int) getControlCount: |  | (FSPDFPage*) | page |

获取指定PDF页面中的表单控件数量。

参数

  [in] | page | 有效的PDF页面对象。它应该属于与当前表单相同的PDF文档。

返回
  指定PDF页面中表单控件的数量。

## ◆ getDict()

- (FSPDFDictionary *) getDict |  |  |

获取当前对象的字典。

返回
  当前对象的字典。如果有任何错误，此函数将返回nil。

## ◆ getDocument()

- (FSPDFDoc *) getDocument |  |  |

获取与当前表单对象关联的PDF文档。

返回
  PDF文档对象。

## ◆ getField:filter:()

- (FSField *) getField: |  | (int) | index
filter: |  | (NSString *) | filter

通过索引获取名称满足指定名称过滤器的表单字段。

参数

  [in] | index | 要检索的表单字段索引。有效范围：从0到(count-1)。 count由函数FSForm::getFieldCount:使用 相同参数filter返回。
  [in] | filter | 过滤器字符串。如果这是空字符串，意味着 计算所有表单字段；如果这是有效的，意味着计算那些名称 部分匹配参数filter的表单字段。例如， 如果参数filter是"text1"，过滤器将匹配text1.0、text1.2.0等； 但不匹配test10或test11.

## ◆ getFieldCount:()

- (int) getFieldCount: |  | (NSString *) | filter |

获取名称满足指定名称过滤器的表单字段数量。

参数

  [in] | filter | 过滤器字符串。如果这是空字符串，意味着 计算所有表单字段；如果这是有效的，意味着计算那些名称 部分匹配参数filter的表单字段。例如， 如果参数filter是"text1"，过滤器将匹配text1.0、text1.2.0等； 但不匹配test10或test11.1。 默认值：空字符串。

返回
  具有指定名称过滤器的表单字段数量。

## ◆ getFormFiller()

- (FSFiller *) getFormFiller |  |  |

获取表单填写器。

返回
  填写器对象。如果返回的填写器对象的函数FSFiller::isEmpty的返回值 为YES，则意味着表单填写器尚未构造。 对于这种情况，请使用当前表单构造填写器。

## ◆ importFromXML:()

- (BOOL) importFromXML: |  | (NSString *) | file_path |

从XML文件导入表单数据。

参数

  [in] | file_path | 现有XML文件的完整文件路径。 这指定了将从中导入表单数据的XML文件。

返回
  YES 表示成功，NO 表示失败。

## ◆ initWithDocument:()

- (id) initWithDocument: |  | (FSPDFDoc*) | document |

构造函数，使用PDF文档。

如果PDF文档没有AcroForm，此构造函数将向PDF文档添加一个空的AcroForm， 以便稍后可以向PDF文档添加新字段。

参数

  [in] | document | 有效的PDF文档。

## ◆ initWithOther:()

- (id) initWithOther: |  | (FSForm*) | other |

构造函数，使用另一个表单对象。

参数

  [in] | other | 另一个表单对象。

## ◆ isEmpty()

- (BOOL) isEmpty |  |  |

检查当前对象是否为空。

当当前对象为空时，意味着当前对象无用。

返回
  YES 表示当前对象为空，NO 表示非空。

## ◆ moveControl:field_name:()

- (BOOL) moveControl: |  | (FSControl*) | control
field_name: |  | (NSString *) | field_name

将控件移动到由字段名称指定的字段。

当前函数对不同情况的操作：

- 如果由字段名称指定的字段不存在，将使用字段名称创建新字段， 控件将移动到此新字段。
- 如果由字段名称指定的字段存在且字段类型与控件当前所属的字段相同， 控件将合并到此字段。
- 如果由字段名称指定的字段存在但字段类型与控件当前所属的字段不同， 此函数将抛出异常FSErrConflict。

参数

  [in] | control | 有效的表单控件对象。
  [in] | field_name | 字段名称。它不应该是空字符串。

返回
  YES 表示成功，NO 表示失败。

## ◆ needConstructAppearances()

- (BOOL) needConstructAppearances |  |  |

检查加载表单控件时是否构造外观。

返回
  YES 表示加载表单控件时构造外观，NO 表示不构造。

## ◆ removeControl:()

- (void) removeControl: |  | (FSControl*) | control |

删除表单控件。（不支持从签名字段删除表单控件）

如果指定的表单控件是相关表单字段的唯一表单控件，相关表单字段也将被删除。

参数

  [in] | control | 要删除的表单控件。如果相关表单字段的字段类型是 FSFieldTypeSignature，此函数将抛出异常FSErrUnsupported。

返回
  无。

## ◆ removeField:()

- (void) removeField: |  | (FSField*) | field |

删除表单字段。（不支持签名字段）

如果表单字段出现在多个PDF页面上，所有表示都将被删除。
如果用户想要删除签名字段，请使用函数FSPDFDoc::removeSignature: 而不是当前函数。

参数

  [in] | field | 要删除的表单字段。如果字段类型是FSFieldTypeSignature， 此函数将抛出异常FSErrUnsupported。

返回
  无。

## ◆ renameField:new_field_name:()

- (BOOL) renameField: |  | (FSField*) | field
new_field_name: |  | (NSString *) | new_field_name

用新名称重命名字段。

参数

  [in] | field | 有效的表单字段对象。
  [in] | new_field_name | 新的字段名称。它不应该是空字符串。

返回
  YES 表示成功，NO 表示失败。

## ◆ reset()

- (BOOL) reset |  |  |

将所有字段（签名字段除外）的数据重置为其默认值。

返回
  YES 表示成功，NO 表示失败。

## ◆ setConstructAppearances:()

- (void) setConstructAppearances: |  | (BOOL) | need_construct |

设置指定加载表单控件时是否构造外观的标志。

参数

  [in] | need_construct | YES 表示加载表单控件时构造外观， NO 表示不构造。

返回
  无。

## ◆ validateFieldName:field_name:()

- (BOOL) validateFieldName: |  | (FSFieldType) | type
field_name: |  | (NSString *) | field_name

验证字段名称是否可用于指定字段类型的新字段。

此方法可用于检查字段名称是否可用于指定字段类型的新字段。 建议用户在使用函数FSForm::addControl:field_name:field_type:rect:添加带有新控件的新字段之前 调用此函数。

参数

  [in] | type | 字段类型，将为其验证输入的字段名称。
  [in] | field_name | 字符串值。它不应该是空字符串。

返回
  YES 表示输入的字段名称对指定字段类型有效，NO 表示无效。

## 属性说明

## ◆ alignment

- (FSAlignment) alignment
| read write nonatomic assign

获取用作文档范围默认值的对齐值。

对齐是可变文本的属性。仅适用于文本字段、列表框和组合框， 这些字段可能包含可变文本作为其内容。
如果文本字段或列表框有自己的对齐值，则将忽略文档范围的默认对齐值； 否则，将为文本字段或列表框使用文档范围的默认值。

## ◆ fieldsInCalculationOrder

- (FSFieldArray *) fieldsInCalculationOrder
| read write nonatomic weak

获取按计算顺序排列的表单字段数组。

计算顺序定义当任何字段的值更改时，字段值将重新计算的顺序。 通常，这些字段具有计算操作。