Cara Bekerja dengan Field AcroForm di TypeScript

Panduan ini menunjukkan cara menambahkan dan meratakan bidang AcroForm dengan Aspose.PDF FOSS untuk TypeScript. Document.Form menyediakan satu metode Add* per tipe bidang — teks, kotak centang, grup radio, kotak kombo, kotak daftar, dan tombol dorong — masing-masing mengembalikan handle bidang yang bertipe. Memerlukan Node.js 22 atau yang lebih baru.

Panduan Langkah demi Langkah

Langkah 1: Instal Paket

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

Verifikasi instalasi dengan mengimpor kelas Document dalam file TypeScript baru — baris ini harus berhasil tanpa error setelah paket diinstal:

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

Langkah 2: Impor Kelas yang Diperlukan

Impor Document untuk membuka file dan mencapai doc.Form, titik masuk untuk setiap metode bidang yang digunakan di bawah ini:

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

Langkah 3: Tambahkan Bidang Teks dan Kotak Centang

Form.AddTextField(init) dan Form.AddCheckbox(init) keduanya menerima sebuah nomor page, sebuah rect, sebuah name unik, dan opsi gaya:

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

Langkah 4: Tambahkan Grup Radio, Kotak Kombo, dan Kotak Daftar

Form.AddRadioGroup(init) menerima satu name yang dibagikan oleh setiap opsi dalam array options-nya, masing-masing dengan nilai rect dan export sendiri. Form.AddComboBox(init) dan Form.AddListBox(init) menerima sebuah array options dari pasangan { export, display }; kotak daftar juga mendukung 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' },
  ],
});

Langkah 5: Tambahkan Tombol Tekan

Form.AddPushButton(init) menerima sebuah caption dan sebuah action yang menjelaskan apa yang dilakukan tombol saat diklik — misalnya, mengirimkan data formulir ke URL:

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

Langkah 6: Ratakan Bidang Formulir

Setiap handle bidang yang dikembalikan oleh pemanggilan Add* memiliki metode Flatten() yang menanamkan nilai saat ini ke dalam aliran konten halaman dan menghapusnya dari AcroForm interaktif:

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

Masalah Umum dan Solusinya

Sebuah bidang tidak muncul di halaman yang dimaksud. page di bidang init objek adalah nomor halaman milik halaman itu sendiri, bukan indeks array — konfirmasikan dengan page.Number pada target Page.

Opsi tombol radio tidak saling eksklusif. Setiap opsi dalam Form.AddRadioGroup()’s options array harus berbagi satu milik grup name — mencampur nama field menghasilkan kotak centang independen alih-alih grup radio.

Nilai field yang diflatten tidak muncul di file yang disimpan. Simpan dokumen (doc.WriteTo() / doc.Save()) setelah memanggil Flatten() — perubahan hanya ada di memori sampai file ditulis kembali.

Sebuah combo box menampilkan nilai ekspor alih-alih teks tampilan. Penampilan menggambar display; nilai yang disimpan pada field (/V) adalah export — pastikan keduanya diatur untuk setiap opsi, bukan hanya satu.

Pertanyaan yang Sering Diajukan

Bisakah saya membaca nilai saat ini dari sebuah field setelah formulir diisi?

Ya — baca properti Value dari handle field, atau iterasi doc.Form.Fields untuk memeriksa setiap field pada dokumen.

Apa perbedaan antara `Flatten()` pada field dan pada anotasi?

Keduanya menanam interactive content ke dalam static page content dan menghapusnya dari koleksi masing-masing — sebuah bidang Flatten() menghapusnya dari /AcroForm, sementara anotasi Flatten() (dibahas dalam Anotasi panduan) menghapusnya dari halaman /Annots.

Apakah list box dapat memungkinkan pemilihan ganda?

Ya — atur multiSelect: true pada objek init milik Form.AddListBox() dan berikan array ke value.

Apakah push button memerlukan aksi agar berguna?

Sebuah action (misalnya { type: 'submit', url, format })lah yang membuat tombol melakukan sesuatu saat diklik; tanpa itu tombol tetap ditampilkan tetapi tidak memiliki perilaku yang terhubung.