Troubleshooting
تجمع هذه الصفحة حلولاً لأكثر المشكلات شيوعًا التي تُواجه عبر Aspose.PDF FOSS لتوقيع TypeScript، والتعليق، والحجب، والرسم، والتحويل، وواجهات برمجة التطبيقات النصية.
تبدو الأساليب غير المتزامنة (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 الدليل لتدفق الشهادة ثم التوقيع الكامل.
تُعيد 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 الدليل لتفاصيل mark-vs-apply وإزالة النصوص من البحث.
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 الأدلة لتصدير ووسم APIs على التوالي.
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.
