Attachments

Questa pagina tratta l’incorporazione di file all’interno di un PDF. Esistono due meccanismi distinti: gli allegati di livello documento, che sono file incorporati senza alcuna presenza visibile su alcuna pagina, e le annotazioni di allegato file ancorate a una pagina, che posizionano un’icona cliccabile su una pagina specifica.

Allegati di livello documento

Document.AddAttachment() incorpora bytes sotto un name, inserendolo nell’albero dei nomi dei file incorporati del documento — aggiungerlo nuovamente con lo stesso nome sovrascrive la voce esistente. Restituisce un Attachment handle. Document.GetAttachments() restituisce tutti gli allegati di livello documento come un array di Attachment handle, ordinati per nome, e Document.RemoveAttachment() ne rimuove uno per nome.

L’handle Attachment espone Name, Description, MimeType, Size, CreationDate e ModDate come proprietà, GetBytes() per leggere il contenuto grezzo del file incorporato, e GetField() / SetField() / RemoveField() per un accesso a livello più basso ai singoli campi /Filespec. L’opzionale AttachmentOptions passato a AddAttachment() accetta mimeType, description, compress, creationDate e modDate.

Nessun esempio di codice verificato è disponibile per questo API nell’attuale snapshot di conoscenza per questa piattaforma — consultare il riepilogo API Reference qui sotto per i nomi esatti di metodi e proprietà.

Allegati di file ancorati a pagina

Page.AddFileAttachment() incorpora un file e posiziona un’annotazione icona /FileAttachment in un determinato rect su una pagina specifica, restituendo un FileAttachmentAnnotation. A differenza di un allegato a livello di documento, questo è visibile e cliccabile in un visualizzatore PDF. FileAttachmentAnnotation condivide le proprietà comuni dell’annotazione (Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity) oltre ai propri Icon e FileName, e supporta GetBytes() per leggere il contenuto incorporato e Flatten() per incorporare la sua icona nel contenuto statico della pagina.

Suggerimenti e buone pratiche

Utilizza un allegato a livello di documento (Document.AddAttachment()) per un file che deve viaggiare con il PDF senza apparire su alcuna pagina; utilizza Page.AddFileAttachment() quando il file deve essere rappresentato da un’icona cliccabile in una posizione specifica.
Document.AddAttachment() sovrascrive un allegato esistente con lo stesso name — verifica prima Document.GetAttachments() se devi evitare di sostituirne uno involontariamente.
Leggi nuovamente il contenuto di un allegato con GetBytes() su entrambi i tipi di handle — il metodo è disponibile sia su Attachment che su FileAttachmentAnnotation.

Problemi comuni

Problema	Causa	Correzione
Un allegato appena aggiunto ha sostituito uno esistente	`Document.AddAttachment()` è stato chiamato con un `name` già in uso	Chiama prima `Document.GetAttachments()` per verificare una collisione di nome
L’allegato non ha alcuna icona visibile sulla pagina	`Document.AddAttachment()` è stato usato, ed è un elemento globale del documento, quindi per progettazione non è presente nella pagina	Usa `Page.AddFileAttachment()` al suo posto per un’icona visibile ancorata alla pagina
`Document.RemoveAttachment()` restituisce `false`	Nessun allegato con il `name` fornito esiste nell’albero dei nomi	Conferma il nome esatto tramite `Document.GetAttachments()` prima di rimuovere

FAQ

Qual è la differenza tra Document.AddAttachment e Page.AddFileAttachment?

Document.AddAttachment() incorpora un file a livello di documento senza alcuna icona visibile su nessuna pagina. Page.AddFileAttachment() incorpora un file e posiziona un’annotazione icona /FileAttachment cliccabile in una posizione specifica su una pagina.

Come posso elencare tutti gli allegati già incorporati in un documento?

Chiama Document.GetAttachments(), che restituisce tutti gli allegati di livello documento come un array di handle Attachment ordinati per nome.

Come posso leggere il contenuto del file di un allegato?

Chiama GetBytes() sull’handle Attachment (o FileAttachmentAnnotation) — è disponibile su entrambi.

Posso rimuovere un allegato?

Sì — Document.RemoveAttachment(name) rimuove un allegato di livello documento per nome e restituisce se è stato trovato e rimosso.

API Reference Riepilogo

Classe/Metodo	Descrizione
`Document.AddAttachment()`	Incorpora i byte come allegato nominato, nell’ambito del documento
`Document.GetAttachments()`	Elenca tutti gli allegati del documento
`Document.RemoveAttachment()`	Rimuovi un allegato del documento per nome
`Attachment`	Gestisci più di un file incorporato; `Name`, `Description`, `MimeType`, `Size`, `GetBytes()`
`Page.AddFileAttachment()`	Incorpora un file come annotazione icona cliccabile ancorata alla pagina
`FileAttachmentAnnotation`	Il gestore dell’annotazione dell’allegato ancorato alla pagina; aggiunge `Icon`, `FileName`

Vedi anche

Aspose.PDF — Enterprise Documentation