Jak pracować z polami AcroForm w TypeScript

Ten przewodnik pokazuje, jak dodać i spłaszczyć pola AcroForm przy użyciu Aspose.PDF FOSS dla TypeScript. Document.Form udostępnia jedną metodę Add* dla każdego typu pola — tekst, pole wyboru, grupa radiowa, pole kombi, pole listy i przycisk — każda zwraca typizowany uchwyt pola. Wymaga Node.js 22 lub nowszej wersji.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

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

Zweryfikuj instalację, importując klasę Document w nowym pliku TypeScript — ta linia powinna rozwiązać się bez błędu po zainstalowaniu pakietu:

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

Krok 2: Zaimportuj wymagane klasy

Importuj Document, aby otworzyć plik i dotrzeć do doc.Form, punktu wejścia dla każdej metody pola użytej poniżej:

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

Krok 3: Dodaj pole tekstowe i pole wyboru

Form.AddTextField(init) i Form.AddCheckbox(init) przyjmują zarówno page liczbę, rect, unikalny name oraz opcje stylizacji:

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

Krok 4: Dodaj grupę przycisków radiowych, pole kombi i pole listy

Form.AddRadioGroup(init) przyjmuje pojedynczy name współdzielony przez każdą opcję w jego tablicy options, przy czym każda ma własną wartość rect i export. Form.AddComboBox(init) i Form.AddListBox(init) przyjmują tablicę options par { export, display }; pola listy dodatkowo obsługują 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' },
  ],
});

Krok 5: Dodaj przycisk

Form.AddPushButton(init) przyjmuje caption oraz action opisujące, co przycisk robi po kliknięciu — na przykład, wysyłając dane formularza pod adres URL:

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

Krok 6: Spłaszcz pola formularza

Każdy uchwyt pola zwrócony przez wywołanie Add* ma metodę Flatten(), która wstawia jego bieżącą wartość do strumienia zawartości strony i usuwa ją z interaktywnego 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');

Typowe problemy i rozwiązania

Pole nie pojawia się na przeznaczonej stronie. page w polu init obiekt jest własnym numerem strony, a nie indeksem tablicy — potwierdź to względem page.Number na docelowym Page.

Opcje przycisków radiowych nie są wzajemnie wykluczające się. Każda opcja w Form.AddRadioGroup()’s options tablica musi współdzielić pojedynczy element grupy name — mieszanie nazw pól tworzy niezależne pola wyboru zamiast grupy przycisków radiowych.

Wartość spłaszczonego pola nie pojawia się w zapisanym pliku. Zapisz dokument (doc.WriteTo() / doc.Save()) po wywołaniu Flatten() — zmiana istnieje tylko w pamięci, aż plik zostanie ponownie zapisany.

Pole kombi wyświetla wartość eksportu zamiast tekstu wyświetlanego. Wygląd rysuje display; przechowywana wartość pola (/V) jest export — potwierdź, że oba są ustawione dla każdej opcji, a nie tylko jednej.

Najczęściej zadawane pytania

Czy mogę odczytać bieżącą wartość pola po wypełnieniu formularza?

Tak — odczytaj właściwość Value uchwytu pola lub iteruj doc.Form.Fields, aby sprawdzić każde pole w dokumencie.

Jaka jest różnica pomiędzy `Flatten()` na polu a na adnotacji?

Oba wstawiają interaktywną zawartość do statycznej zawartości strony i usuwają ją z odpowiedniej kolekcji — pola Flatten() usuwa ją z /AcroForm, podczas gdy adnotacji Flatten() (omówione w Adnotacje przewodniku) usuwa ją ze strony /Annots.

Czy pole listy może umożliwiać wielokrotny wybór?

Tak — ustaw multiSelect: true na Form.AddListBox()’s init obiekcie i przekaż tablicę do value.

Czy przycisk push wymaga akcji, aby był użyteczny?

action (na przykład { type: 'submit', url, format }) to właśnie to, co sprawia, że przycisk coś robi po kliknięciu; bez niego przycisk jest renderowany, ale nie ma podłączonego zachowania.