Troubleshooting
此页面收集了在 Aspose.PDF FOSS 中针对 TypeScript 的签名、注释、编辑、绘图、转换和文本 API 所遇到的最常见问题的解决方案。
异步方法（Sign、Certify、VerifySignatures）似乎没有任何作用
Document.Sign()、Document.Certify() 和 Document.VerifySignatures() 都返回一个 Promise。在没有 await 的情况下调用其中一个会让执行立即继续——随后出现的 doc.WriteTo() 或 doc.Save() 可能在签名实际写入之前就运行，而对验证结果的随后 console.log() 会记录一个未解析的 Promise，而不是 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');请参阅 Security 完整的 certify-then-sign 流程指南。
SearchAnnotationText() 与 SearchAnnotations() 对相同文本返回不同结果
这两种搜索方法在同一页面上在两个方向上都是互不相交的。 SearchAnnotationText() 匹配字面注释元数据（/Contents, /T, /Subj); SearchAnnotations() 匹配 rendered 由标记注释自身外观绘制的文本（例如 a FreeText 正文）。仅存储在 /Contents 被一个找到而另一个错过：
const metadataHits = page.SearchAnnotationText('confidential'); // matches /Contents, /T, /Subj
const renderedHits = page.SearchAnnotations('confidential'); // matches rendered markup text
这两种方法都不会搜索普通页面文本——使用 Page.GetText() or Page.Search() 为此。参见 注释 关于完整注释 API 的指南。
仅有涂抹标记本身并不会删除内容
Page.AddRedact() 仅绘制一个 RedactAnnotation 覆盖在区域上——下面的内容保持不变，仍可复制选择，直到 Page.ApplyRedactions() 运行并破坏性地重写内容流。已添加的标记 after ApplyRedactions() 已经运行，保持未应用状态，永久有效：
page.AddRedact({ rect: [216, 548, 460, 566], fill: [0, 0, 0], overlayText: '[REDACTED]' });
page.ApplyRedactions(); // only now is the content actually destroyed
请参阅 Redaction 关于标记与应用细节以及文本搜索编辑的指南。
PageGraphics 绘图调用永不出现在页面上
Page.Graphics() 返回一个 PageGraphics，它会缓冲每个 moveTo()/rect()/circle()/stroke()/fill() 调用，直到 apply() 将它们提交到页面。缺少 apply() 调用的序列不会绘制任何内容：
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
请参阅 Images 关于完整绘图和可选内容层 API 的指南。
Document.ToHtml() 与手动标记均依赖结构树
语义模式的 Document.ToHtml() 通过遍历结构树重新排版内容；在未标记的文档上，它会悄然回退到启发式主体，导致导出时失去标题结构。相同的树就是手工标记（StructTreeRoot.Append() / StructElement.MarkContent()）写入的，以及 Document.GetStructTree() 返回的——在两者之前调用 Document.CreateStructTree() 或 Document.AutoTag()：
const root = doc.GetStructTree();
if (!root) throw new Error('document is not tagged yet');请参阅 Conversion and Structure 分别针对导出和标记 API 的指南。
AddTextBlock() 在其边界矩形内静默裁剪文本
Page.AddTextBlock(text, rect, options) 将文本包装在 rect 中，并返回所有未能容纳的内容（如果全部容纳则返回 null）——它不会扩大矩形，也不会在内容溢出时抛出异常。若返回值被忽略，则意味着溢出的文本根本不会被绘制：
const rest = page.AddTextBlock(longText, [72, 600, 200, 150], { fontSize: 11 });
if (rest) page.AddTextBlock(rest, [300, 600, 200, 150]); // route the overflow somewhere
请参阅 Text 关于完整文本放置和提取 API 的指南。
