Jak pracować z Core PDF API w TypeScript

Ten przewodnik pokazuje, jak otwierać, tworzyć, edytować, dzielić i zapisywać dokumenty PDF przy użyciu Aspose.PDF FOSS dla TypeScript. Klasy Document i Page są punktami wejścia dla każdej operacji w bibliotece — otwierania i tworzenia plików, edycji stron w miejscu, dzielenia i łączenia dokumentów oraz zapisywania wyniku. Wymaga jedynie Node.js 22 lub nowszego.

Poradnik 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 się rozwiązać bez błędu po zainstalowaniu pakietu:

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

Krok 2: Zaimportuj wymagane klasy

Zaimportuj Document, aby wczytać lub utworzyć plik PDF, oraz PageFormat, jeśli planujesz rozpocząć dokument od zera:

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

Krok 3: Otwórz istniejący PDF i edytuj strony

Document.OpenFile() otwiera PDF z ścieżki pliku; Document.Open() przyjmuje Uint8Array w pamięci. Strony mogą być przeglądane i edytowane bezpośrednio, a Document.WriteTo() zapisuje wynik z powrotem.

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

// Open from disk (or Document.Open(uint8array) for in-memory data)
const doc = Document.OpenFile('input.pdf');

// Inspect and edit pages
const pages = doc.Pages;
console.log(pages.length);
pages[0].Rotate = 90;
doc.RemovePage(2);                 // 1-based page number
doc.Reorder([3, 1, 2]);

// Save
doc.WriteTo('output.pdf');         // or: const bytes = doc.Save();

Krok 4: Utwórz nowy PDF od podstaw

Document.New() rozpoczyna pusty dokument w podanym PageFormat. Page.AddText() umieszcza tekst w określonych pozycjach, a Document.AddPage() dodaje kolejne strony.

import { Document, PageFormat } from '@asposefoss/pdf';
const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

Krok 5: Podziel, wyodrębnij i połącz strony

Document.Split() zwraca jeden Document na stronę. Document.ExtractPages() przyjmuje listę stron numerowanych od 1, z możliwością powtórzeń i zwraca nowy Document zawierający tylko te strony. Document.Append() i Document.InsertPage() kopiują strony między dokumentami, a Document.Merge() łączy kilka dokumentów w jeden.

const parts = doc.Split();                       // one Document per page
const chapter = doc.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

docA.Append(docB);                               // copy all of docB's pages onto docA
docA.InsertPage(1, docB.Pages[0]);               // copy a single page across documents

Typowe problemy i rozwiązania

Document.OpenFile() throws InvalidPasswordError. Plik PDF jest zabezpieczony hasłem i nie podano hasła (lub podano niewłaściwe). Pass { password: '...' } to Document.OpenFile() / Document.Open().

RemovePage() or ExtractPages() usuwa lub wyodrębnia niewłaściwą stronę. Te metody przyjmują numery stron liczone od 1, podczas gdy doc.Pages jest zwykłą tablicą zerowo-indeksowaną — dwa schematy indeksowania łatwo pomylić.

WriteTo() wyjście jest większe niż oczekiwano. Domyślne zapisywanie nie używa kompresji xref/object-stream. Pass { compressed: true } to Document.WriteTo() aby ją włączyć.

Edycje dokonane w doc.Pages[i] nie pojawiają się w zapisanym pliku. Modyfikacje strony muszą nastąpić przed wywołaniem Document.WriteTo() / Document.Save() — nie ma osobnego kroku “commit”, ale zmiany wprowadzone po zapisaniu nie będą odzwierciedlone w pliku już zapisanym na dysku.

Najczęściej zadawane pytania

Jak załadować PDF z bufora w pamięci zamiast z ścieżki do pliku?

Przekaż Uint8Array do Document.Open() zamiast ścieżki do Document.OpenFile().

Jak obrócić stronę?

Ustaw page.Rotate na 90, 180 lub 270, a następnie zapisz dokument za pomocą Document.WriteTo().

Czy mogę skopiować pojedynczą stronę z jednego dokumentu do drugiego?

Tak — Document.InsertPage(at, sourcePage) kopiuje jedną stronę z innego dokumentu na podanej pozycji liczbowej (liczonej od 1), bez kopiowania całego dokumentu.

Czy `Document.ExtractPages()` pozwala, aby ta sama strona pojawiła się dwa razy?

Tak. Lista numerów stron przekazana do Document.ExtractPages() dopuszcza powtórzenia, więc ta sama strona źródłowa może pojawić się więcej niż raz w wyniku.