Como trabalhar com anexos PDF em TypeScript

Este guia mostra como trabalhar com anexos de arquivos em documentos PDF com Aspose.PDF FOSS para TypeScript. Document.AddAttachment() incorpora um arquivo ao nível do documento; Page.AddFileAttachment() coloca uma anotação clicável no estilo de clipe de papel em uma página que abre um arquivo incorporado. Requer Node.js 22 ou posterior.

Guia passo a passo

Etapa 1: Instalar o pacote

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 a instalação importando a classe Document em um novo arquivo TypeScript — esta linha deve ser resolvida sem erro assim que o pacote for instalado:

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

Etapa 2: Importar classes necessárias

Importe Document para abrir o arquivo e acessar ambos os pontos de entrada de anexos usados abaixo:

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

Etapa 3: Abra o Documento de Destino

Ambos os métodos de anexo são chamados em um Document aberto — anexos de nível Page precisam adicionalmente do Page de destino:

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

Etapa 4: Incorporar um Anexo de Nível de Documento

Document.AddAttachment(name, bytes, opts) -> Attachment incorpora um arquivo na coleção de arquivos incorporados do documento, indexado por name. Document.GetAttachments() -> Attachment[] lista tudo o que está atualmente incorporado, e Document.RemoveAttachment(name) -> boolean remove um pelo nome.

Etapa 5: Adicionar uma Anotação de Anexo de Arquivo de Nível de Página

Page.AddFileAttachment(opts) -> FileAttachmentAnnotation coloca um ícone clicável na página — semelhante às anotações de nota adesiva e texto livre abordadas no Anotações guia — que um visualizador abre para salvar ou visualizar o arquivo incorporado. Ao contrário Document.AddAttachment(), ele está ancorado a uma localização específica da página ao invés de estar listado apenas na coleção de arquivos incorporados do documento.

Problemas Comuns e Soluções

Um anexo adicionado com Document.AddAttachment() não tem ícone visível em nenhuma página. Isso é esperado — um anexo ao nível do documento reside na coleção de arquivos incorporados, não em uma página. Use Page.AddFileAttachment() adicionalmente se for necessário um ícone clicável em uma página específica.

Document.RemoveAttachment() returns false. Ele retorna false quando nenhum anexo está registrado sob o dado name — liste o conjunto atual com Document.GetAttachments() primeiro para confirmar o nome exato em uso.

Dois anexos foram incorporados sob o mesmo name. name in Document.AddAttachment() é a chave usada para procurar o anexo novamente com RemoveAttachment() — reutilizar um nome para uma segunda chamada pode sombrear ou entrar em conflito com a primeira, dependendo de como o visualizador resolve duplicatas. Use um nome distinto por arquivo incorporado.

Perguntas Frequentes

Qual é a diferença entre um anexo de nível de documento e um anexo de nível de página?

Um anexo de nível de documento (Document.AddAttachment()) reside na coleção embedded-files do PDF e não está vinculado a nenhuma página. Um anexo de nível de página (Page.AddFileAttachment()) é uma anotação ancorada a uma localização específica da página, semelhante a um post-it.

Como vejo o que está atualmente incorporado em um documento?

Chame Document.GetAttachments(), que retorna todos os Attachment atualmente incorporados.

Um anexo pode ser removido depois de ser adicionado?

Sim — Document.RemoveAttachment(name) remove um anexo ao nível do documento pelo nome sob o qual foi adicionado, e retorna true se encontrou e removeu um.