Troubleshooting
Questa pagina raccoglie le correzioni per i problemi più comuni riscontrati in Aspose.PDF FOSS per le API di firma, annotazione, redazione, disegno, conversione e testo di TypeScript.
I metodi asincroni (Sign, Certify, VerifySignatures) sembrano non fare nulla
Document.Sign(), Document.Certify() e Document.VerifySignatures() restituiscono tutti un Promise. Chiamarne uno senza await consente all’esecuzione di continuare immediatamente — un successivo doc.WriteTo() o doc.Save() può essere eseguito prima che la firma sia effettivamente scritta, e un successivo console.log() sul risultato della verifica registra un Promise non risolto invece dell’array SignatureReport[]:
// Wrong — WriteTo can race ahead of Sign:
approving.Sign(identity, opts);
approving.WriteTo('signed.pdf');
// Correct:
await approving.Sign(identity, opts);
approving.WriteTo('signed.pdf');Vedi il Security guida per il flusso completo certify-then-sign.
SearchAnnotationText() e SearchAnnotations() restituiscono risultati diversi per lo stesso testo
Questi due metodi di ricerca sono disgiunti in entrambe le direzioni nella stessa pagina. SearchAnnotationText() corrisponde ai metadati letterali dell’annotazione (/Contents, /T, /Subj); SearchAnnotations() corrisponde al rendered testo disegnato dall’aspetto stesso di un’annotazione markup (ad esempio un FreeText body). Un valore memorizzato solo in /Contents è trovato da uno e mancato dall’altro:
const metadataHits = page.SearchAnnotationText('confidential'); // matches /Contents, /T, /Subj
const renderedHits = page.SearchAnnotations('confidential'); // matches rendered markup text
Nessuno dei due metodi ricerca il testo normale della pagina — usa Page.GetText() or Page.Search() per questo. Vedi il Annotations guida per l’annotazione completa API.
Un segno di redazione da solo non rimuove il contenuto
Page.AddRedact() disegna solo una RedactAnnotation sopra una regione — il contenuto sottostante rimane intatto e ancora selezionabile per copia fino a quando Page.ApplyRedactions() viene eseguito e riscrive distruttivamente il flusso di contenuto. I segni aggiunti after ApplyRedactions() che è già stato eseguito rimane non applicato indefinitamente:
page.AddRedact({ rect: [216, 548, 460, 566], fill: [0, 0, 0], overlayText: '[REDACTED]' });
page.ApplyRedactions(); // only now is the content actually destroyed
Vedi il Redaction guida per i dettagli mark-vs-apply e la redazione di text-search.
Le chiamate di disegno PageGraphics non compaiono mai sulla pagina
Page.Graphics() restituisce un PageGraphics che memorizza in buffer ogni chiamata moveTo()/rect()/circle()/stroke()/fill() fino a quando apply() non le impegna nella pagina. Una sequenza priva della sua chiamata apply() non disegna nulla:
const g = page.Graphics();
g.setStrokeColor([0.2, 0.2, 0.2]).setLineWidth(1).rect(80, 300, 200, 100).stroke();
g.apply(); // required — nothing above is visible without this call
Vedi il Images guida per il disegno completo e lo strato di contenuto opzionale API.
Document.ToHtml() e Hand-Tagging dipendono entrambi da un albero di struttura
Il Document.ToHtml() in modalità semantica riorganizza il contenuto percorrendo l’albero di struttura; su un documento non taggato torna silenziosamente a un corpo euristico e l’esportazione perde la sua struttura di intestazioni. Lo stesso albero è quello in cui il tagging scritto a mano (StructTreeRoot.Append() / StructElement.MarkContent()) scrive e ciò che Document.GetStructTree() restituisce — chiama Document.CreateStructTree() o Document.AutoTag() prima di entrambi:
const root = doc.GetStructTree();
if (!root) throw new Error('document is not tagged yet');Vedi il Conversion and Structure guide per le API di esportazione e di tagging rispettivamente.
AddTextBlock() Taglia silenziosamente il testo al suo rettangolo di delimitazione
Page.AddTextBlock(text, rect, options) avvolge il testo all’interno di rect e restituisce tutto ciò che non è stato inserito (o null se tutto è stato inserito) — non ingrandisce il rettangolo né genera eccezioni quando il contenuto trabocca. Un valore di ritorno ignorato significa che il testo in eccesso semplicemente non viene mai disegnato:
const rest = page.AddTextBlock(longText, [72, 600, 200, 150], { fontSize: 11 });
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // route the overflow somewhere
Vedi il Text guida per il posizionamento completo del testo e l’estrazione API.
