Attachments

Esta página cobre a incorporação de arquivos dentro de um PDF. Existem dois mecanismos distintos: anexos a nível de documento, que são arquivos incorporados sem presença visível em nenhuma página, e anotações de anexos de arquivo ancoradas à página, que colocam um ícone clicável em uma página específica.

Anexos a Nível de Documento

Document.AddAttachment() incorpora bytes sob um name, inserindo-o na árvore de nomes de arquivos incorporados do documento — adicioná-lo novamente com o mesmo nome sobrescreve a entrada existente. Ele retorna um manipulador Attachment. Document.GetAttachments() retorna todos os anexos a nível de documento como um array de manipuladores Attachment, ordenados por nome, e Document.RemoveAttachment() remove um pelo nome.

O manipulador Attachment expõe Name, Description, MimeType, Size, CreationDate e ModDate como propriedades, GetBytes() para ler o conteúdo bruto do arquivo incorporado, e GetField() / SetField() / RemoveField() para acesso de nível inferior a campos individuais /Filespec. O opcional AttachmentOptions passado para AddAttachment() aceita mimeType, description, compress, creationDate e modDate.

Nenhum exemplo de código verificado está disponível para este API na captura de conhecimento atual para esta plataforma — veja o Resumo API Reference abaixo para os nomes exatos de métodos e propriedades.

Anexos de Arquivo Ancorados à Página

Page.AddFileAttachment() incorpora um arquivo e coloca uma anotação de ícone /FileAttachment em um determinado rect em uma página específica, retornando um FileAttachmentAnnotation. Ao contrário de um anexo ao nível do documento, este é visível e clicável em um visualizador de PDF. FileAttachmentAnnotation compartilha as propriedades comuns de anotação (Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity) além de seus próprios Icon e FileName, e suporta GetBytes() para ler o conteúdo incorporado e Flatten() para incorporar seu ícone no conteúdo estático da página.

Dicas e Melhores Práticas

Use um anexo ao nível do documento (Document.AddAttachment()) para um arquivo que deve viajar com o PDF sem aparecer em nenhuma página; use Page.AddFileAttachment() quando o arquivo deve ser representado por um ícone clicável em um local específico.
Document.AddAttachment() sobrescreve um anexo existente com o mesmo name — verifique Document.GetAttachments() primeiro se precisar evitar substituir um inadvertidamente.
Leia o conteúdo de um anexo de volta com GetBytes() em qualquer tipo de manipulador — o método existe tanto em Attachment quanto em FileAttachmentAnnotation.

Problemas Comuns

Problema	Causa	Correção
Um anexo recém-adicionado substituiu um existente	`Document.AddAttachment()` foi chamado com um `name` já em uso	Chame `Document.GetAttachments()` primeiro para verificar colisão de nomes
O anexo não tem ícone visível na página	`Document.AddAttachment()` foi usado, que é a nível de documento e não tem presença na página por design	Use `Page.AddFileAttachment()` em vez disso para um ícone visível, ancorado na página
`Document.RemoveAttachment()` retorna `false`	Nenhum anexo com o `name` fornecido existe na árvore de nomes	Confirme o nome exato via `Document.GetAttachments()` antes de remover

FAQ

Qual é a diferença entre Document.AddAttachment e Page.AddFileAttachment?

Document.AddAttachment() incorpora um arquivo ao nível do documento sem ícone visível em nenhuma página. Page.AddFileAttachment() incorpora um arquivo e coloca uma anotação de ícone /FileAttachment clicável em um local específico em uma página.

Como listar todos os anexos já incorporados em um documento?

Chame Document.GetAttachments(), que retorna todos os anexos ao nível do documento como uma matriz de Attachment ordenados por nome.

Como ler o conteúdo do arquivo de um anexo de volta?

Chame GetBytes() no Attachment (ou FileAttachmentAnnotation) — ele está disponível em ambos.

Posso remover um anexo?

Sim — Document.RemoveAttachment(name) remove um anexo ao nível do documento pelo nome e retorna se algum foi encontrado e removido.

API Reference Resumo

Classe/Método	Descrição
`Document.AddAttachment()`	Incorpore bytes como um anexo nomeado, ao nível do documento
`Document.GetAttachments()`	Liste todos os anexos de nível de documento
`Document.RemoveAttachment()`	Remova um anexo de nível de documento pelo nome
`Attachment`	Manipule mais de um arquivo incorporado; `Name`, `Description`, `MimeType`, `Size`, `GetBytes()`
`Page.AddFileAttachment()`	Incorpore um arquivo como uma anotação de ícone clicável ancorada na página
`FileAttachmentAnnotation`	O manipulador de anotação do anexo ancorado na página; adiciona `Icon`, `FileName`

Ver também

Aspose.PDF — Enterprise Documentation