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 indexer מחזיר 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() | ממקם את סמן הבונה בסימנייה קיימת |
