Как работать с вложениями PDF в TypeScript

В этом руководстве показано, как работать с вложенными файлами в PDF-документах с помощью Aspose.PDF FOSS для TypeScript. Document.AddAttachment() встраивает файл на уровне документа; Page.AddFileAttachment() размещает кликаемую аннотацию в виде скрепки на странице, открывающую вложенный файл. Требуется Node.js 22 или новее.

Пошаговое руководство

Шаг 1: Установите пакет

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

Проверьте установку, импортировав класс Document в новый файл TypeScript — эта строка должна успешно разрешаться без ошибок после установки пакета:

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

Шаг 2: Импортируйте необходимые классы

Импортируйте Document, чтобы открыть файл и получить доступ к обоим точкам входа вложений, используемым ниже:

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

Шаг 3: Откройте целевой документ

Оба метода вложения вызываются на открытом Document — вложения уровня Page дополнительно требуют целевой Page:

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

Шаг 4: Встроить вложение уровня документа

Document.AddAttachment(name, bytes, opts) -> Attachment встраивает файл в коллекцию вложенных файлов документа, ключом которой является name. Document.GetAttachments() -> Attachment[] выводит список всего текущего вложения, а Document.RemoveAttachment(name) -> boolean удаляет файл по имени.

Шаг 5: Добавить аннотацию вложения файла уровня страницы

Page.AddFileAttachment(opts) -> FileAttachmentAnnotation размещает кликабельный значок на странице — аналогично заметкам-липучкам и аннотациям свободного текста, рассмотренным в Аннотации руководстве — которое открывается в просмотрщике для сохранения или предварительного просмотра вложенного файла. В отличие от Document.AddAttachment(), он привязывается к конкретному месту на странице, а не просто перечислен в коллекции вложенных файлов документа.

Распространённые проблемы и решения

Вложение, добавленное с помощью Document.AddAttachment() не имеет видимого значка на какой-либо странице. Это ожидаемо — вложение уровня документа находится в коллекции вложенных файлов, а не на странице. Используйте Page.AddFileAttachment() в дополнение, если требуется кликабельный значок на конкретной странице.

Document.RemoveAttachment() returns false. Он возвращает false когда под указанным именем не зарегистрировано вложение name — выведите текущий набор с Document.GetAttachments() сначала, чтобы подтвердить точное используемое имя.

Два вложения были встроены под одним и тем же name. name in Document.AddAttachment() является ключом, с помощью которого ищут вложение RemoveAttachment() — повторное использование имени для второго вызова может затмить или конфликтовать с первым, в зависимости от того, как просмотрщик обрабатывает дубликаты. Используйте отдельное имя для каждого встроенного файла.

Часто задаваемые вопросы

В чём разница между вложением уровня документа и вложением уровня страницы?

Вложение уровня документа (Document.AddAttachment()) находится в коллекции embedded-files PDF и не привязано к какой-либо странице. Вложение уровня страницы (Page.AddFileAttachment()) представляет собой аннотацию, закреплённую в конкретном месте страницы, похожую на стикер.

Как увидеть, что сейчас встроено в документ?

Вызовите Document.GetAttachments(), который возвращает все текущие встроенные Attachment.

Можно ли удалить вложение после его добавления?

Да — Document.RemoveAttachment(name) удаляет вложение уровня документа по имени, под которым оно было добавлено, и возвращает true, если найдено и удалено.