Jak pracovat s poli AcroForm v TypeScript

Tento návod ukazuje, jak přidat a zploštit AcroForm pole pomocí Aspose.PDF FOSS pro TypeScript. Document.Form poskytuje jednu Add* metodu pro každý typ pole — text, zaškrtávací políčko, skupinu přepínačů, rozbalovací seznam, seznamové pole a tlačítko — každá vrací typově definovaný odkaz na pole. Vyžaduje Node.js 22 nebo novější.

Průvodce krok za krokem

Krok 1: Nainstalujte balíček

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

Ověřte instalaci importováním třídy Document v novém souboru TypeScript — tento řádek by měl být vyřešen bez chyby po instalaci balíčku:

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

Krok 2: Importujte požadované třídy

Importujte Document pro otevření souboru a dosažení doc.Form, vstupního bodu pro každou metodu pole použité níže:

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

Krok 3: Přidejte textové pole a zaškrtávací políčko

Form.AddTextField(init) a Form.AddCheckbox(init) oba přijímají číslo page, rect, jedinečný name a možnosti stylování:

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: Přidejte skupinu přepínačů, Combo Box a List Box

Form.AddRadioGroup(init) přijímá jedno name sdílené všemi možnostmi v jeho poli options, každé s vlastní hodnotou rect a export. Form.AddComboBox(init) a Form.AddListBox(init) přijímají options pole { export, display } párů; list boxy navíc podporují 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: Přidejte tlačítko

Form.AddPushButton(init) přijímá caption a action, který popisuje, co tlačítko provede po kliknutí — například odeslání dat formuláře na 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: Zploštit pole formuláře

Každá manipulace s polem vrácená voláním Add* má metodu Flatten(), která vkládá její aktuální hodnotu do obsahového proudu stránky a odstraňuje ji z interaktivního 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');

Běžné problémy a opravy

Pole se nezobrazuje na zamýšlené stránce. page v poli init objekt je číslo stránky samotné stránky, nikoli index pole — potvrďte to oproti page.Number na cílovém Page.

Možnosti radio button nejsou vzájemně výlučné. Každá možnost v Form.AddRadioGroup()’s options pole musí sdílet jediné skupiny name — míchání názvů polí vytváří nezávislé zaškrtávací políčka místo skupiny přepínačů.

Hodnota zploštělého pole se v uloženém souboru neobjeví. Uložte dokument (doc.WriteTo() / doc.Save()) po zavolání Flatten() — změna existuje pouze v paměti, dokud není soubor znovu zapsán.

Rozbalovací seznam zobrazuje exportní hodnotu místo zobrazovaného textu. Vzhled vykresluje display; uložená hodnota pole (/V) export — potvrďte, že jsou oba nastaveny pro každou možnost, ne jen pro jednu.

Často kladené otázky

Mohu přečíst aktuální hodnotu pole po vyplnění formuláře?

Ano — přečtěte si vlastnost Value objektu pole, nebo iterujte doc.Form.Fields a prohlédněte si každé pole v dokumentu.

Jaký je rozdíl mezi `Flatten()` u pole a u anotace?

Obě vloží interaktivní obsah do statického obsahu stránky a odstraní jej z příslušné kolekce — pole Flatten() odstraňuje jej z /AcroForm, zatímco anotace Flatten() (pokryto v Anotace průvodce) odstraňuje ho ze stránky /Annots.

Může seznamový box povolit více výběrů?

Ano — nastavte multiSelect: true na objekt init u Form.AddListBox() a předávejte pole do value.

Potřebuje push button akci, aby byl užitečný?

action (například { type: 'submit', url, format }) je to, co způsobí, že tlačítko po kliknutí něco provede; bez něj se vykreslí, ale nemá žádné napojené chování.