Aspose.PDF FOSS
TypeScript
Developer Guide
Forms

Forms

Forms

本页介绍如何创建和管理交互式 AcroForm 字段。通过 doc.Form 访问的 Form 是所有字段类型的外观；每个 Add*() 方法都会创建一个绑定到页面和小部件矩形的字段，并返回一个类型化句柄（TextField、CheckboxField、ChoiceField、ButtonField 或 RadioField），该句柄共享通用的 Field 属性 Value、ReadOnly 和 Required。

创建字段

Form.AddTextField()、Form.AddCheckbox()、Form.AddComboBox() 以及它们的兄弟函数各自接受一个选项对象，用于指定目标 page（从 0 开始计数）、小部件 rect、字段 name，以及诸如 borderColor 和 backgroundColor 的样式。

const form = doc.Form;
const pageNum = page.Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.05, 0.1, 0.3], backgroundColor: [0.9, 0.93, 1], borderWidth: 1,
  font: 'Helvetica', fontSize: 12,
});

form.AddCheckbox({
  page: pageNum, rect: [200, 630, 218, 648], name: 'Subscribe',
  checked: true, borderColor: [0.05, 0.1, 0.3], borderWidth: 1,
});

form.AddComboBox({
  page: pageNum, rect: [200, 550, 350, 570], name: 'Country', value: 'US',
  options: [
    { export: 'US', display: 'United States' },
    { export: 'UK', display: 'United Kingdom' },
    { export: 'DE', display: 'Germany' },
  ],
});

Page.AddTextField() 和 Page.AddCheckbox() 在页面上直接创建相同的字段类型，无需在选项对象中指定 doc.Form 或 page 编号。

读取和修改字段

Form.Fields 是文档中所有 Field 的数组；Form.Get() 可通过其完全限定名称查找单个对象。每个字段的 Value 可以读取或重新赋值，且 ReadOnly / Required 是普通的布尔属性。

const nameField = doc.Form.Get('FullName');
if (nameField) {
  console.log(nameField.Value);
  nameField.Value = 'Bob Sample';
}

展平字段

每种字段类型的 Flatten() 方法会将其当前外观烘焙到页面的静态内容中，并从 AcroForm 中移除——这与 Annotation.Flatten() 对注释产生的永久、非交互式效果相同。

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten();

技巧与最佳实践

  • 修改由 Add*() 调用直接返回的字段句柄，或通过 Form.Get() 新检索的句柄——陈旧的引用看不到其他地方所做的更改。
  • Form.RemoveField() 接受 Field 句柄或字段名称字符串两者之一。
  • 在批量更改字段值后调用 Form.GenerateAppearances()，使每个字段的屏幕显示外观与其 Value 保持同步。
  • 组合框和列表框在 /V 中存储选中的 export 值；display 文本则是生成的外观所显示的内容。

常见问题

问题原因修复
使用 Form.AddTextField() 添加的字段未在页面上显示rect 坐标超出目标页面的尺寸确认矩形位于页面边界内
在 Flatten() 之后字段仍然显示为可交互Flatten() 在副本上被调用，而不是返回的句柄 Add*() / Form.Get()在直接从表单获取的对象上调用 Flatten()
字段值的更改在屏幕上不可见值更改后，字段的外观未重新生成调用 Form.GenerateAppearances()，或字段自身的 GenerateAppearance()

FAQ

创建后，如何读取或更改字段的值？

使用 Form.Get('fieldName') 查找（或使用 Add*() 调用返回的句柄），直接读取或赋值其 Value 属性。

Form facade 支持哪些字段类型？

文本字段、复选框、单选组、下拉框、列表框和按钮，分别通过 Form.AddTextField()、Form.AddCheckbox()、Form.AddRadioGroup()、Form.AddComboBox()、Form.AddListBox() 和 Form.AddPushButton()。

如何删除字段？

使用字段的句柄或名称调用 Form.RemoveField()。

如何将表单字段设为永久且不可编辑？

在字段句柄上调用 Flatten()——与注释使用的相同模式——它会将当前外观烘焙到页面中并从 AcroForm 中移除。

API Reference 摘要

类/方法描述
FormAcroForm 门面，通过 doc.Form 访问
Form.AddTextField() / Form.AddCheckbox() / Form.AddRadioGroup() / Form.AddComboBox() / Form.AddListBox() / Form.AddPushButton()创建对应类型的字段
Form.Fields文档中每个 Field，作为数组
Form.Get()按全限定名称查找字段
Form.RemoveField()按句柄或名称删除字段
Form.GenerateAppearances()为每个字段重新生成屏幕显示外观
TextField / CheckboxField / ChoiceField / ButtonField / RadioField已键入的字段处理共享 Value, ReadOnly, Required
Page.AddTextField() / Page.AddCheckbox()在页面上直接创建字段

另请参阅

 中文