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) را صدا بزنید، یا overload 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)متطابق که از همان نام استفاده می‌کند، جفت کنید — جفت نامتناسب نشانک را ناقص می‌گذارد. - قبل از خواندن
FirstColumnیاLastColumn،Bookmark.IsColumnرا بررسی کنید — این دو ویژگی فقط برای نشانک‌های ستونی که باStartColumnBookmark/EndColumnBookmarkایجاد شده‌اند، معنا دارند. Bookmark.Remove()فقط علامت‌های نشانک را حذف می‌کند، نه متن درون‌دار، بنابراین حذف یک نشانک هرگز محتوای سند را حذف نمی‌کند.- از
DocumentBuilder.MoveToBookmark()استفاده کنید تا مکان‌نمای سازنده را به یک مکان شناخته‌شده بپرید، به جای اینکه به‌صورت دستی در درخت گره‌ها برای یکBookmarkStartجستجو کنید.
مشکلات رایج
| مشکل | دلیل | راه‌حل |
|---|---|---|
نمایه‌ساز BookmarkCollection برای جستجوی نام، null را برمی‌گرداند | نام نشانک در بازه‌ای که جستجو می‌شود وجود ندارد | ابتدا نام‌ها را از طریق GetEnumerator() فهرست کنید تا نام دقیق و حساس به حروف بزرگ/کوچک را تأیید کنید |
| محتوای وارد شده نشانک‌گذاری نشده است | EndBookmark() هرگز فراخوانی نشده است، یا با نامی متفاوت از StartBookmark() فراخوانی شده است | همیشه StartBookmark(name) را با EndBookmark(name) با استفاده از رشته نام یکسان مطابقت دهید |
| داده‌های نشانک ستون به‌نظر نادرست می‌آیند | FirstColumn/LastColumn بدون بررسی IsColumn ابتدا خوانده می‌شود | فقط زمانی که Bookmark.IsColumn برابر با true باشد، FirstColumn/LastColumn را تفسیر کنید |
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() | مکان‌نمای سازنده را بر روی یک نشانک موجود قرار می‌دهد |
