Comment travailler avec les champs AcroForm en TypeScript

Ce guide montre comment ajouter et aplatir les champs AcroForm avec Aspose.PDF FOSS pour TypeScript. Document.Form expose une méthode Add* par type de champ — texte, case à cocher, groupe radio, zone combinée, zone de liste et bouton poussoir — chacune renvoyant un handle de champ typé. Il nécessite Node.js 22 ou version ultérieure.

Guide étape par étape

Étape 1 : installer le paquet

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

Vérifiez l’installation en important la classe Document dans un nouveau fichier TypeScript — cette ligne devrait se résoudre sans erreur une fois le paquet installé :

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

Étape 2 : importer les classes requises

Importez Document pour ouvrir le fichier et atteindre doc.Form, le point d’entrée de chaque méthode de champ utilisée ci-dessous :

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

Étape3: Ajouter un champ texte et une case à cocher

Form.AddTextField(init) et Form.AddCheckbox(init) prennent tous deux un nombre page, un rect, un name unique, ainsi que des options de style :

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

Étape4: Ajouter un groupe radio, une boîte combinée et une boîte de liste

Form.AddRadioGroup(init) prend un seul name partagé par chaque option de son tableau options, chacune avec sa propre valeur rect et export. Form.AddComboBox(init) et Form.AddListBox(init) prennent un tableau options de paires { export, display }; les boîtes de liste prennent en plus en charge 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' },
  ],
});

Étape5: Ajouter un bouton poussoir

Form.AddPushButton(init) prend un caption et un action décrivant ce que le bouton fait lorsqu’il est cliqué — par exemple, envoyer les données du formulaire à une URL :

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

Étape6: Aplatir les champs du formulaire

Chaque poignée de champ renvoyée par un appel Add* possède une méthode Flatten() qui intègre sa valeur actuelle dans le flux de contenu de la page et la supprime de l’AcroForm interactif :

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

Problèmes courants et correctifs

Un champ n’apparaît pas sur la page prévue. page dans le champ init l’objet est le numéro de page propre à cette page, pas un indice de tableau — vérifiez-le par rapport à page.Number sur la cible Page.

Les options des boutons radio ne sont pas mutuellement exclusives. Chaque option dans Form.AddRadioGroup()de options le tableau doit partager le seul du groupe name — le mélange des noms de champs crée des cases à cocher indépendantes au lieu d’un groupe radio.

La valeur d’un champ aplati n’apparaît pas dans le fichier sauvegardé. Enregistrez le document (doc.WriteTo() / doc.Save()) après l’appel Flatten() — la modification n’existe en mémoire que jusqu’à ce que le fichier soit réécrit.

Une zone combinée affiche la valeur d’exportation au lieu du texte affiché. L’apparence dessine display; la valeur stockée du champ (/V) est export — confirmez que les deux sont définis pour chaque option, pas seulement l’un.

Foire aux questions

Puis-je lire la valeur actuelle d’un champ après que le formulaire a été rempli?

Oui — lisez la propriété Value de la poignée du champ, ou itérez doc.Form.Fields pour inspecter chaque champ du document.

Quelle est la différence entre `Flatten()` sur un champ et sur une annotation?

Les deux incorporent le contenu interactif dans le contenu de la page statique et le suppriment de leur collection respective — un champ Flatten() le supprime de /AcroForm, tandis que l’annotation Flatten() (couverts dans le Annotations guide) le supprime de la page /Annots.

Une boîte de liste peut-elle autoriser plusieurs sélections?

Oui — définissez multiSelect: true sur l’objet init de Form.AddListBox() et transmettez un tableau à value.

Un bouton poussoir a-t-il besoin d’une action pour être utile?

Un action (par exemple { type: 'submit', url, format }) est ce qui fait que le bouton fait quelque chose lorsqu’il est cliqué; sans celui-ci, il s’affiche mais n’a aucun comportement associé.