Cómo trabajar con archivos adjuntos PDF en TypeScript

Esta guía muestra cómo trabajar con archivos adjuntos en documentos PDF con Aspose.PDF FOSS para TypeScript. Document.AddAttachment() incrusta un archivo a nivel del documento; Page.AddFileAttachment() coloca una anotación tipo clip de papel clickeable en una página que abre un archivo incrustado. Requiere Node.js 22 o posterior.

Guía paso a paso

Paso 1: Instalar el paquete

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

Verifique la instalación importando la clase Document en un nuevo archivo TypeScript — esta línea debería resolverse sin errores una vez que el paquete esté instalado:

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

Paso 2: Importar clases requeridas

Importa Document para abrir el archivo y acceder a ambos puntos de entrada de adjuntos utilizados a continuación:

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

Paso 3: Abrir el documento de destino

Ambos métodos de adjunto se invocan sobre un Document abierto — los adjuntos a nivel Page además requieren el Page objetivo:

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

Paso 4: Insertar un adjunto a nivel de documento

Document.AddAttachment(name, bytes, opts) -> Attachment inserta un archivo en la colección de archivos incrustados del documento, indexado por name. Document.GetAttachments() -> Attachment[] enumera todo lo que está actualmente incrustado, y Document.RemoveAttachment(name) -> boolean elimina uno por nombre.

Paso 5: Añadir una anotación de adjunto de archivo a nivel de página

Page.AddFileAttachment(opts) -> FileAttachmentAnnotation coloca un ícono clicable en la página — similar a las anotaciones sticky-note y free-text cubiertas en el Anotaciones guía — que un visor abre para guardar o previsualizar el archivo incrustado. A diferencia de Document.AddAttachment(), está anclado a una ubicación específica de la página en lugar de estar listado solo en la colección de archivos incrustados del documento.

Problemas comunes y soluciones

Un adjunto añadido con Document.AddAttachment() no tiene ningún ícono visible en ninguna página. Esto es esperado — un adjunto a nivel de documento vive en la colección de archivos incrustados, no en una página. Usa Page.AddFileAttachment() además si se requiere un ícono clicable en una página específica.

Document.RemoveAttachment() returns false. Devuelve false cuando no hay ningún adjunto registrado bajo el dado name — enumere el conjunto actual con Document.GetAttachments() primero para confirmar el nombre exacto en uso.

Dos adjuntos fueron incrustados bajo el mismo name. name in Document.AddAttachment() es la clave utilizada para buscar el adjunto con RemoveAttachment() — reutilizar un nombre para una segunda llamada puede sombrear o entrar en conflicto con la primera, dependiendo de cómo el visor resuelva los duplicados. Use un nombre distinto por archivo incrustado.

Preguntas frecuentes

¿Cuál es la diferencia entre un adjunto a nivel de documento y uno a nivel de página?

Un adjunto a nivel de documento (Document.AddAttachment()) reside en la colección embedded-files del PDF y no está vinculado a ninguna página. Un adjunto a nivel de página (Page.AddFileAttachment()) es una anotación anclada a una ubicación específica de la página, similar a una nota adhesiva.

¿Cómo puedo ver qué está actualmente incrustado en un documento?

Llame a Document.GetAttachments(), que devuelve todos los Attachment actualmente incrustados.

¿Se puede eliminar un adjunto después de haberlo añadido?

Sí — Document.RemoveAttachment(name) elimina un adjunto a nivel de documento por el nombre bajo el cual se añadió, y devuelve true si lo encontró y lo eliminó.