Como trabalhar com campos AcroForm em TypeScript

Este guia mostra como adicionar e achatar campos AcroForm com Aspose.PDF FOSS para TypeScript. Document.Form expõe um método Add* por tipo de campo — texto, caixa de seleção, grupo de rádio, caixa de combinação, caixa de lista e botão de envio — cada um retornando um manipulador de campo tipado. Requer Node.js 22 ou posterior.

Guia passo a passo

Etapa 1: Instalar o pacote

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

Verifique a instalação importando a classe Document em um novo arquivo TypeScript — esta linha deve ser resolvida sem erros assim que o pacote for instalado:

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

Etapa 2: Importar classes necessárias

Importe Document para abrir o arquivo e alcançar doc.Form, o ponto de entrada para cada método de campo usado abaixo:

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

Etapa 3: Adicionar um Campo de Texto e uma Caixa de Seleção

Form.AddTextField(init) e Form.AddCheckbox(init) ambos recebem um número page, um rect, um name único e opções de estilo:

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],
});

Etapa 4: Adicionar um Grupo de Botões de Rádio, Caixa de Combinação e Caixa de Lista

Form.AddRadioGroup(init) recebe um único name compartilhado por cada opção em sua matriz options, cada um com seu próprio valor rect e export. Form.AddComboBox(init) e Form.AddListBox(init) recebem uma matriz options de pares { export, display }; caixas de lista suportam adicionalmente 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' },
  ],
});

Etapa 5: Adicionar um Botão de Ação

Form.AddPushButton(init) recebe um caption e um action descrevendo o que o botão faz quando clicado — por exemplo, enviando os dados do formulário para uma URL:

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

Etapa 6: Achatar Campos de Formulário

Todo manipulador de campo retornado por uma chamada Add* possui um método Flatten() que incorpora seu valor atual no fluxo de conteúdo da página e o remove da AcroForm interativa:

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');

Problemas Comuns e Soluções

Um campo não aparece na página pretendida. page no campo init o objeto é o número da própria página, não um índice de array — confirme contra page.Number no destino Page.

As opções de botão de rádio não são mutuamente exclusivas. Cada opção em Form.AddRadioGroup()’s options array deve compartilhar o único do grupo name — misturar nomes de campo cria caixas de seleção independentes em vez de um grupo de opções.

O valor de um campo achatado não aparece no arquivo salvo. Salve o documento (doc.WriteTo() / doc.Save()) após chamar Flatten() — a alteração só existe na memória até que o arquivo seja gravado novamente.

Uma caixa de combinação mostra o valor de exportação em vez do texto exibido. A aparência desenha display; o valor armazenado do campo (/V) é export — confirme que ambos estão definidos para cada opção, não apenas um.

Perguntas Frequentes

Posso ler o valor atual de um campo depois que o formulário for preenchido?

Sim — leia a propriedade Value do manipulador de campo, ou itere doc.Form.Fields para inspecionar cada campo no documento.

Qual é a diferença entre `Flatten()` em um campo e em uma anotação?

Ambos incorporam conteúdo interativo ao conteúdo estático da página e o removem de sua respectiva coleção — o de um campo Flatten() o remove de /AcroForm, enquanto o de uma anotação Flatten() (coberto no Anotações guia) o remove da página /Annots.

Um list box pode permitir múltiplas seleções?

Sim — defina multiSelect: true no objeto init de Form.AddListBox() e passe um array para value.

Um botão push precisa de uma ação para ser útil?

Um action (por exemplo { type: 'submit', url, format }) é o que faz o botão executar algo ao ser clicado; sem ele, ele é renderizado mas não tem nenhum comportamento conectado.