Jak pracować z załącznikami PDF w TypeScript

Ten przewodnik pokazuje, jak pracować z załącznikami plików w dokumentach PDF przy użyciu Aspose.PDF FOSS dla TypeScript. Document.AddAttachment() osadza plik na poziomie dokumentu; Page.AddFileAttachment() umieszcza klikalną adnotację w stylu spinacza na stronie, która otwiera osadzony plik. 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 zostać rozwiązana bez błędów po zainstalowaniu pakietu:

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

Krok 2: Zaimportuj wymagane klasy

Importuj Document, aby otworzyć plik i uzyskać dostęp do obu punktów wejścia załączników używanych poniżej:

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

Krok 3: Otwórz dokument docelowy

Obie metody załączania są wywoływane na otwartym Document — załączniki poziomu Page dodatkowo wymagają docelowego Page:

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

Krok 4: Osadź załącznik na poziomie dokumentu

Document.AddAttachment(name, bytes, opts) -> Attachment osadza plik w kolekcji osadzonych plików dokumentu, klucząc go za pomocą name. Document.GetAttachments() -> Attachment[] wyświetla wszystko, co jest obecnie osadzone, a Document.RemoveAttachment(name) -> boolean usuwa jeden po nazwie.

Krok 5: Dodaj adnotację załącznika pliku na poziomie strony

Page.AddFileAttachment(opts) -> FileAttachmentAnnotation umieszcza klikalną ikonę na stronie — podobną do adnotacji w postaci karteczki samoprzylepnej i wolnego tekstu opisanych w Adnotacjach przewodniku — który otwiera się w przeglądarce, aby zapisać lub wyświetlić osadzony plik. W przeciwieństwie do Document.AddAttachment(), jest przypięty do określonego miejsca na stronie, a nie wyświetlany wyłącznie w kolekcji osadzonych plików dokumentu.

Typowe problemy i rozwiązania

Załącznik dodany za pomocą Document.AddAttachment() nie ma widocznej ikony na żadnej stronie. Jest to zamierzone — załącznik na poziomie dokumentu znajduje się w kolekcji osadzonych plików, a nie na stronie. Użyj Page.AddFileAttachment() dodatkowo, jeśli wymagana jest klikalna ikona na konkretnej stronie.

Document.RemoveAttachment() returns false. Zwraca false gdy żadne załącznik nie jest zarejestrowany pod podanym name — wyświetl bieżący zestaw za pomocą Document.GetAttachments() najpierw, aby potwierdzić dokładną nazwę używaną.

Dwa załączniki zostały osadzone pod tym samym name. name in Document.AddAttachment() jest kluczem używanym do odszukania załącznika z RemoveAttachment() — ponowne użycie nazwy przy drugim wywołaniu może zacienić lub spowodować konflikt z pierwszą, w zależności od tego, jak przeglądarka rozwiązuje duplikaty. Użyj unikalnej nazwy dla każdego osadzonego pliku.

Najczęściej zadawane pytania

Jaka jest różnica między załącznikiem na poziomie dokumentu a załącznikiem na poziomie strony?

Załącznik na poziomie dokumentu (Document.AddAttachment()) znajduje się w kolekcji embedded-files pliku PDF i nie jest powiązany z żadną stroną. Załącznik na poziomie strony (Page.AddFileAttachment()) jest adnotacją zakotwiczoną w konkretnym miejscu na stronie, podobnie jak przypisek.

Jak mogę zobaczyć, co jest aktualnie osadzone w dokumencie?

Wywołaj Document.GetAttachments(), który zwraca wszystkie aktualnie osadzone Attachment.

Czy załącznik może zostać usunięty po jego dodaniu?

Tak — Document.RemoveAttachment(name) usuwa załącznik na poziomie dokumentu według nazwy, pod którą został dodany, i zwraca true, jeśli go znalazł i usunął.