Bookmarks
Bookmarks
يوضح هذا الدليل كيفية قراءة وإدراج والتنقل إلى وإزالة الإشارات المرجعية في مستند Word باستخدام Aspose.Words FOSS لـ .NET. تُعد الإشارة المرجعية علامة على موقع مُسمى أو نطاق من المحتوى بحيث يمكن البحث عنه أو التنقل إليه أو استخدامه كنقطة إدراج لتعديلات إضافية. تمثّل Aspose.Words FOSS لـ .NET الإشارات المرجعية باستخدام الفئات Bookmark، BookmarkStart، وBookmarkEnd، وتوفر طرق DocumentBuilder لإنشاءها وتحديد موقعها أثناء تأليف أو تحرير المستند.
قراءة الإشارات المرجعية
كل Range يعرض الإشارات المرجعية التي يحتويها عبر خاصية Bookmarks، التي تُعيد BookmarkCollection. بما أن Document نفسه يعرض Range، فإن doc.Range.Bookmarks يُعيد كل إشارة مرجعية في المستند. ابحث عن إشارة مرجعية محددة بالاسم باستخدام الفهرس BookmarkCollection — bookmarks[bookmarkName] — تحقق من عددها باستخدام Count، أو استعرض المجموعة بأكملها باستخدام GetEnumerator(). كل Bookmark يعرض Name والنص الذي يحيطه عبر Text.
إدراج الإشارات المرجعية باستخدام DocumentBuilder
DocumentBuilder هو الطريقة المعتادة لإنشاء الإشارات المرجعية أثناء كتابة مستند. استدعِ StartBookmark(bookmarkName) قبل إدراج المحتوى، ثم EndBookmark(bookmarkName) بعده — يقوم المُنشئ بلف كل ما كُتب بينهما كنطاق مُشار إليه. لنطاق من أعمدة الجدول، استخدم StartColumnBookmark(bookmarkName) وEndColumnBookmark(bookmarkName) بدلاً من ذلك؛ Bookmark.IsColumn الناتج هو true، مع FirstColumn وLastColumn لتحديد نطاق العمود المُعلم. لإعادة تموضع المُنشئ عند إشارة مرجعية موجودة لتعديلات إضافية، استدعِ MoveToBookmark(bookmarkName)، أو الإصدار الزائد MoveToBookmark(bookmarkName, isStart, isAfter) للتحكم في أي طرف من الإشارة المرجعية يضع المؤشر.
هيكل الإشارة المرجعية في شجرة المستند
يتم تمثيل العلامة المرجعية في شجرة المستند كزوج من العقد: BookmarkStart و BookmarkEnd، كلاهما مُنشأ كـ BookmarkStart(doc, name) / BookmarkEnd(doc, name). كل واحدة ترتبط مرة أخرى بكائنها المنطقي Bookmark — BookmarkStart.Bookmark يعيده، و Bookmark بدورها تكشف عن خصائص BookmarkStart و BookmarkEnd التي تشير إلى عقدتي الحد الخاصتين بها. لأن BookmarkStart و BookmarkEnd هما عقد عادية، فإنهما يدعمان عمليات العقد القياسية مثل GetText() و Clone(isCloneChildren) و GetAncestor(ancestorType)، ويمكن العثور عليهما بالتجول في الشجرة مثل أي نوع آخر من العقد.
إزالة العلامات المرجعية
استدعِ Bookmark.Remove() لحذف علامات البداية والنهاية لعلامة مرجعية واحدة — هذا يزيل العلامة المرجعية نفسها، وليس محتوى المستند الذي تحويه. لإزالة العلامات المرجعية بشكل جماعي، استخدم BookmarkCollection.Remove(bookmark) أو Remove(bookmarkName) أو RemoveAt(index) أو Clear() لإسقاط جميع العلامات المرجعية في النطاق دفعة واحدة.
نصائح وأفضل الممارسات
- يفضل استخدام فهرس
BookmarkCollection(bookmarks["BookmarkName"]) بدلاً من التكرار اليدوي عندما تكون بالفعل على علم باسم العلامة المرجعية المستهدفة. - دائمًا قم بزوج استدعاء
StartBookmark(name)مع استدعاءEndBookmark(name)المطابق باستخدام نفس الاسم — الزوج غير المتطابق يترك العلامة المرجعية غير مكتملة. - تحقق من
Bookmark.IsColumnقبل قراءةFirstColumnأوLastColumn— هاتان الخاصيتان ذات معنى فقط للعلامات المرجعية العمودية التي تم إنشاؤها باستخدامStartColumnBookmark/EndColumnBookmark. Bookmark.Remove()يحذف فقط علامات العلامة المرجعية، وليس النص المحاط، لذا فإن إزالة علامة مرجعية لا تحذف محتوى المستند أبدًا.- استخدم
DocumentBuilder.MoveToBookmark()للقفز بمؤشر المُنشئ إلى موقع معروف بدلاً من البحث يدويًا في شجرة العقد عنBookmarkStart.
المشكلات الشائعة
| المشكلة | السبب | الإصلاح |
|---|---|---|
مفهرس BookmarkCollection يُعيد null عند البحث عن اسم | اسم الإشارة المرجعية غير موجود في النطاق الذي يتم البحث فيه | اعرض الأسماء أولاً عبر GetEnumerator() لتأكيد الاسم الدقيق، حسّاس لحالة الأحرف |
| المحتوى المُدرج غير مُشار إليه | لم يتم استدعاء EndBookmark() أبداً، أو تم استدعاؤه باسم مختلف عن StartBookmark() | دائمًا قارن StartBookmark(name) مع EndBookmark(name) باستخدام سلسلة الاسم المتطابقة |
| بيانات إشارة العمود تبدو خاطئة | تم قراءة FirstColumn/LastColumn دون التحقق من IsColumn أولًا | فقط فسر FirstColumn/LastColumn عندما يكون Bookmark.IsColumn هو true |
FAQ
كيف أحصل على جميع العلامات المرجعية في المستند؟
اقرأ doc.Range.Bookmarks، والذي يُعيد BookmarkCollection يغطي المستند بأكمله.
هل يمكنني وضع علامة مرجعية لجزء من جدول حسب العمود بدلاً من حسب نطاق النص؟
نعم — استخدم DocumentBuilder.StartColumnBookmark(bookmarkName) و EndColumnBookmark(bookmarkName). العلامة المرجعية الناتجة لديها IsColumn مُعيَّن إلى true، مع FirstColumn/LastColumn لتحديد نطاق العمود.
هل يؤدي حذف العلامة المرجعية إلى حذف النص الذي تُشير إليه؟
لا. Bookmark.Remove() يزيل فقط عقد علامات BookmarkStart/BookmarkEnd؛ يظل محتوى المستند بينهما دون تعديل.
كيف يمكنني نقل المؤشر DocumentBuilder إلى إشارة مرجعية موجودة؟
استدعِ DocumentBuilder.MoveToBookmark(bookmarkName) أو MoveToBookmark(bookmarkName, isStart, isAfter) للتحكم فيما إذا كان المؤشر سيقع في بداية أو نهاية الإشارة المرجعية.
ما الفرق بين التحميلات المتعددة لـ BookmarkCollection.Remove()؟
Remove(bookmark) يأخذ كائن Bookmark، وRemove(bookmarkName) يأخذ اسمه، وRemoveAt(index) يأخذ موقعه في المجموعة — الثلاثة جميعاً يزيلون إشارة مرجعية واحدة، بينما Clear() يزيل كل الإشارات المرجعية في المجموعة.
API Reference ملخص
| فئة / طريقة | وصف |
|---|---|
Bookmark | يمثل إشارة مرجعية واحدة؛ يتيح Name، Text، IsColumn، FirstColumn، LastColumn، وRemove() |
BookmarkCollection | الإشارات المرجعية في Range; فهرس حسب الاسم، Remove()، RemoveAt()، Clear()، Count |
BookmarkStart / BookmarkEnd | عقد الوثيقة التي تحدد حدود الإشارة المرجعية; الرجوع عبر Bookmark.BookmarkStart/Bookmark.BookmarkEnd |
Range.Bookmarks | يعيد BookmarkCollection للنطاق المحدد، بما في ذلك doc.Range.Bookmarks للمستند بالكامل |
DocumentBuilder.StartBookmark() / EndBookmark() | غلف المحتوى المُدرج في علامة مرجعية مسماة |
DocumentBuilder.StartColumnBookmark() / EndColumnBookmark() | ضع علامة على نطاق من أعمدة الجدول كعلامة مرجعية |
DocumentBuilder.MoveToBookmark() | يضع مؤشر المُنشئ عند إشارة مرجعية موجودة |
