如何在 TypeScript 中使用 AcroForm 字段

本指南展示了如何使用 Aspose.PDF FOSS 为 TypeScript 添加并扁平化 AcroForm 字段。Document.Form 为每种字段类型（文本、复选框、单选组、组合框、列表框和按钮）公开一个 Add* 方法——每个方法返回一个已类型化的字段句柄。它需要 Node.js 22 或更高版本。

分步指南

步骤 1：安装软件包

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

通过在新的 TypeScript 文件中导入 Document 类来验证安装——一旦软件包安装完成，此行应该可以解析而不会出现错误：

import { Document } from '@asposefoss/pdf';

步骤 2：导入所需的类

导入 Document 以打开文件并到达 doc.Form，这是下面使用的每个字段方法的入口点：

import { Document } from '@asposefoss/pdf';

步骤 3：添加文本字段和复选框

Form.AddTextField(init) 和 Form.AddCheckbox(init) 都接受一个 page 数字、一个 rect、一个唯一的 name，以及样式选项：

const doc = Document.OpenFile('form-template.pdf');
const form = doc.Form;
const pageNum = doc.Pages[0].Number;

form.AddTextField({
  page: pageNum, rect: [200, 670, 450, 690], name: 'FullName', value: 'Alice Sample',
  borderColor: [0.1, 0.15, 0.4], font: 'Helvetica', fontSize: 12,
});

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

步骤 4：添加单选组、组合框和列表框

Form.AddRadioGroup(init) 接受一个由其 options 数组中每个选项共享的单个 name，每个选项都有各自的 rect 和 export 值。Form.AddComboBox(init) 和 Form.AddListBox(init) 接受一个 options 数组的 { export, display } 对；列表框还支持 multiSelect：

form.AddRadioGroup({
  name: 'Plan', selected: 'Pro',
  options: [
    { page: pageNum, rect: [200, 590, 218, 608], export: 'Basic' },
    { page: pageNum, rect: [290, 590, 308, 608], export: 'Pro' },
  ],
});

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

form.AddListBox({
  page: pageNum, rect: [200, 410, 350, 510], name: 'Interests',
  multiSelect: true, value: ['pdf'],
  options: [
    { export: 'pdf', display: 'PDF Engineering' },
    { export: 'crypto', display: 'Cryptography' },
  ],
});

步骤 5：添加推送按钮

Form.AddPushButton(init) 接受一个 caption 和一个 action，描述按钮被点击时的行为——例如，将表单数据提交到 URL：

form.AddPushButton({
  page: pageNum, rect: [200, 320, 320, 388], name: 'Submit',
  caption: 'Submit',
  action: { type: 'submit', url: 'https://example.com/submit', format: 'fdf' },
});

步骤 6：扁平化表单字段

每个由 Add* 调用返回的字段句柄都有一个 Flatten() 方法，它会将当前值烘焙到页面的内容流中，并从交互式 AcroForm 中移除：

const tb = form.AddTextField({
  page: pageNum, rect: [210, 660, 460, 680], name: 'FlattenName', value: 'Alice Sample',
});
tb.Flatten(); // -> number; bakes the value, unwires the field from /AcroForm

doc.WriteTo('flattened.pdf');

常见问题及解决方案

字段未出现在预期页面上。 page 在字段的 init 对象是该页面自己的页码，而不是数组索引——请与 page.Number 在目标上 Page.

单选按钮选项不是互斥的。 每个选项在 Form.AddRadioGroup()的 options 数组必须共享该组的单一 name — 混合字段名称会创建独立的复选框，而不是单选按钮组。

扁平化字段的值不会出现在已保存的文件中。 保存文档（doc.WriteTo() / doc.Save()）调用后 Flatten() — 更改仅存在于内存中，直到文件被写回。

组合框显示的是导出值，而不是显示文本。 外观绘制 display; 字段的存储值（/V) 是 export — 确认每个选项都已设置，而不仅仅是一个。

常见问题

在表单填写后，我可以读取字段的当前值吗？

可以 — 读取字段句柄的 Value 属性，或遍历 doc.Form.Fields 来检查文档中的每个字段。

字段上的 `Flatten()` 与注释上的 `Flatten()` 有何区别？

两者都会将交互式内容烘焙到静态页面内容中，并从其各自的集合中移除——字段的 Flatten() 从中移除 /AcroForm，而注释的 Flatten() （在…中涵盖注释指南）将其从页面的 /Annots.

列表框可以允许多选吗？

可以 — 在 Form.AddListBox() 的 init 对象上设置 multiSelect: true，并将数组传递给 value。

推按钮需要一个动作才能发挥作用吗？

一个 action（例如 { type: 'submit', url, format }）使按钮在点击时能够执行操作；如果没有，它虽然会渲染出来，但没有任何行为绑定。