Troubleshooting
Esta página reúne correções para os problemas mais comuns encontrados em todo o Aspose.PDF FOSS para as APIs de assinatura, anotação, redação, desenho, conversão e texto do TypeScript.
Métodos assíncronos (Sign, Certify, VerifySignatures) parecem não fazer nada
Document.Sign(), Document.Certify() e Document.VerifySignatures() retornam todos um Promise. Chamar um deles sem await permite que a execução continue imediatamente — um doc.WriteTo() ou doc.Save() subsequente pode ser executado antes que a assinatura tenha sido realmente escrita, e um console.log() subsequente no resultado da verificação registra um Promise não resolvido em vez do 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');Veja o Security guia para o fluxo completo certify-then-sign.
SearchAnnotationText() e SearchAnnotations() retornam resultados diferentes para o mesmo texto
Esses dois métodos de pesquisa são disjuntos em ambas as direções na mesma página. SearchAnnotationText() corresponde a metadados literais de anotação (/Contents, /T, /Subj); SearchAnnotations() corresponde ao rendered texto gerado pela própria aparência de uma anotação de marcação (por exemplo um FreeText corpo). Um valor armazenado apenas em /Contents é encontrado por um e perdido pelo outro:
const metadataHits = page.SearchAnnotationText('confidential'); // matches /Contents, /T, /Subj
const renderedHits = page.SearchAnnotations('confidential'); // matches rendered markup text
Nenhum dos métodos pesquisa o texto normal da página — use Page.GetText() or Page.Search() para isso. Veja o Anotações guia para a anotação completa API.
Uma marca de redação sozinha não remove o conteúdo
Page.AddRedact() apenas desenha um RedactAnnotation sobre uma região — o conteúdo abaixo permanece intocado e ainda pode ser copiado até Page.ApplyRedactions() é executado e reescreve destrutivamente o fluxo de conteúdo. Marcas adicionadas after ApplyRedactions() já foi executado, permanece não aplicado indefinidamente:
page.AddRedact({ rect: [216, 548, 460, 566], fill: [0, 0, 0], overlayText: '[REDACTED]' });
page.ApplyRedactions(); // only now is the content actually destroyed
Veja o Redaction guia para detalhes de mark-vs-apply e redação de text-search.
Chamadas de desenho PageGraphics nunca aparecem na página
Page.Graphics() retorna um PageGraphics que faz buffer de cada chamada moveTo()/rect()/circle()/stroke()/fill() até que apply() as comprometa na página. Uma sequência que falta a chamada apply() não desenha nada:
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
Veja o Images guia para o desenho completo e optional-content-layer API.
Document.ToHtml() e a marcação manual dependem ambos de uma árvore de estrutura
O Document.ToHtml() em modo semântico reformatta o conteúdo percorrendo a árvore de estrutura; em um documento sem marcação ele recai silenciosamente para um corpo heurístico e a exportação perde sua estrutura de títulos. A mesma árvore é onde a marcação feita manualmente (StructTreeRoot.Append() / StructElement.MarkContent()) grava e o que Document.GetStructTree() devolve — chame Document.CreateStructTree() ou Document.AutoTag() antes de qualquer um deles:
const root = doc.GetStructTree();
if (!root) throw new Error('document is not tagged yet');Veja o Conversion and Structure guias para as APIs de exportação e marcação, respectivamente.
AddTextBlock() recorta silenciosamente o texto em seu retângulo delimitador
Page.AddTextBlock(text, rect, options) envolve o texto dentro de rect e devolve tudo o que não coube (ou null se tudo coube) — não aumenta o retângulo nem gera erro quando o conteúdo transborda. Um valor de retorno que é ignorado significa que o texto que transborda simplesmente nunca é desenhado:
const rest = page.AddTextBlock(longText, [72, 600, 200, 150], { fontSize: 11 });
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // route the overflow somewhere
Veja o Text guia para o text-placement completo e extração API.
