איך לעבוד עם Structured Document Tags ב-.NET
מדריך זה מציג כיצד להכניס, להגדיר, למצוא, להסיר ולקשר נתונים לתגיות מסמכים מובנות (בקרי תוכן) ב Aspose.Words FOSS עבור .NET, באמצעות StructuredDocumentTag מחלקה ב Aspose.Words.Markup מרחב שמות. הוא מכסה אילו סוגי בקרי-תוכן DocumentBuilder יכולים להכניס, להגדיר תוכן ספציפי לסוג כגון מצב תיבת סימון או אפשרויות בתפריט נפתח, לאתר בקרים לפי תגית או כותרת, להסיר בקר עם או בלי התוכן שלו, ולמפות בקר לנתוני XML מותאמים אישית.
מדריך שלב אחר שלב
שלב 1: התקנת החבילה
Aspose.Words FOSS for .NET עדיין לא מפרסם חבילה של NuGet – במקום זאת יש לבנות את הספרייה מהמקור. שכפלו את https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, ואז בנו את Aspose.Words.sln בתצורת Release עם ערכת הפיתוח .NET והפנו למרכיב Aspose.Words שנוצר מהפרויקט שלכם. הספרייה ממוקדת ל-.NET Standard 2.0, ולכן היא פועלת על .NET Framework 4.6.2+ ו-.NET 6/8/10.
שלב 2: ייבוא המחלקות הנדרשות
הוסיפו הנחייה using Aspose.Words; עבור Document ו-DocumentBuilder, והנחייה using Aspose.Words.Markup; עבור StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, וכן עבור שאר מחלקות בקרי התוכן שמדריך זה מכסה.
שלב 3: בדוק אילו סוגי בקרת-תוכן ניתן להכניס
לפני ההוספה, בדוק אם ה-SdtType المستهدف הוא אחד משבעת הסוגים שה-DocumentBuilder.InsertStructuredDocumentTag(SdtType) מקבל: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ו-Date. RepeatingSection ו-RepeatingSectionItem אינם ניתנים להוספה בעזרת סמן טקסט עם שיטה זו – הם עוטפים פסקאות שלמות או שורות טבלה במקום זאת. ערכי ה-SdtType הנותרים שיכולים להופיע בקובץ Word אך אינם מוצגים בממשק המשתמש של Word כסוגים שניתן להכניס – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group ו-EntityPicker – אינם מתקבלים על ידי שיטת ההוספה הזו בכלל.
שלב 4: הכנס בקרת-תוכן במיקום הסמן
קרא ל-DocumentBuilder.InsertStructuredDocumentTag(SdtType) עם אחד משבעת הסוגים הנתמכים כדי להכניס בקרה חדשה במיקום הסמן הנוכחי של הבונה; הקריאה מחזירה את ה-StructuredDocumentTag החדש. הגדר Tag ו-Title על הבקרה שהוחזרה כדי לתת לה את מחרוזות הזיהוי שהמחברים רואים ב-Word, והגדר את PlaceholderName (נתמך על-ידי Placeholder BuildingBlock) עבור טקסט הפתיחה שמציג Word כאשר הבקרה ריקה – IsShowingPlaceholderText מדווח אם הפתיחה מוצגת כעת.
שלב 5: הגדר תוכן ספציפי לסוג
בקרת תיבה מסומנת: קרא או הגדר את StructuredDocumentTag.Checked, וקרא ל-SetCheckedSymbol() / SetUncheckedSymbol() כדי להתאים את הסמלים המוצגים עבור כל מצב. בבקרת תאריך, הגדר את FullDate, כאשר DateDisplayFormat ו-DateDisplayLocale שולטות באופן הצגת התאריך, DateStorageFormat (SdtDateStorageFormat) שולטות באופן אחסון כאשר הוא קשור לנתוני XML, ו-CalendarType (SdtCalendarType) בוחרות את מערכת הלוח. ברשימה נפתחת או בתיבת קומבו, מלא את ListItems – SdtListItemCollection של SdtListItem (DisplayText, Value) – לפני הגדרת SelectedValue לבחירת האפשרות הפעילה. בבקרת טקסט פשוט, Multiline היא תכונת bool על StructuredDocumentTag שניתן להגדיר כדי לתצורת הבקרה.
שלב 6: שלוט במראה ובנעילה של הבקרה
הגדר את Appearance (SdtAppearance) כדי לשלוט באופן שבו הבקרה מופרדת חזותית ב-Word, ואת Color כדי לקבוע את צבע ההדגשה שלה. ContentsFont ו-EndCharacterFont שולטות בגופן שמיושם על תוכן הבקרה והתו הסופי שלה. LockContentControl ו-LockContents הם מתגים עצמאיים – הגדר את LockContentControl כדי לחסום מחיקת הבקרה עצמה, ואת LockContents כדי לחסום עריכה של מה שנמצא בתוכה, מבלי להשפיע על השני.
צעד 7: מצא והסר פקדי תוכן
קרא Range.StructuredDocumentTags – StructuredDocumentTagCollection המתאים לטווח הזה – וקרא ל-GetById(), GetByTag() או GetByTitle() כדי לאתר פקד ספציפי, או ל-Remove() / RemoveAt() על האוסף כדי להסיר אחד בהתבסס על הפנייה או אינדקס. על פקד בודד, קרא ל-Remove() כדי למחוק את הפקד יחד עם תוכנו, ל-RemoveSelfOnly() כדי למחוק רק את העטיפה תוך שמירת התוכן שלו במסמך, או ל-Clear() כדי לרוקן את תוכנו בעוד הפקד עצמו נשאר במקומו.
צעד 8: קשר פקד לנתוני XML מותאמים
קרא StructuredDocumentTag.XmlMapping – מופע של XmlMapping – וקרא ל-SetMapping(customXmlPart, xPath, prefixMapping) כדי לקשר את הפקד לחלק מותאם XML קיים שכבר נמצא באחסון הנתונים המותאמים XML של המסמך, תוך שימוש בביטוי XPath לבחירת האלמנט המקושר. XmlMapping.IsMapped מדווח האם קישור פעיל כרגע, CustomXmlPart ו-StoreItemId מזהים את חלק הנתונים המקושר, ו-Delete() מסיר את המיפוי.
צעד 9: טיפול בפקדי תוכן המשתרעים על פני מספר מקטעים
פקד תוכן המשתרע על פני יותר ממקטע מסמך אחד – מדווח על ידי IsMultiSection – מיוצג לא על ידי צומת StructuredDocumentTag יחיד אלא על ידי זוג StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, המחובר דרך StructuredDocumentTagRangeStart.RangeEnd. תכנת נגד הממשק המשותף IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) כאשר הקוד צריך להתמודד עם הצורה החד-צומת והצורה בטווח באופן אחיד, במקום להסתעף על סוג קונקרטי.
בעיות נפוצות ותיקונים
InsertStructuredDocumentTag מטיל NotImplementedException המתבקש SdtType – לדוגמה Citation, Equation, או BuildingBlockGallery – אינו אחד משבעת סוגי ההכנסה. השתמש PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, או Date במקום.
InsertStructuredDocumentTag זורק InvalidOperationException RepeatingSection or RepeatingSectionItem התבקש במצב סמן טקסט. שני הסוגים הללו עוטפים פסקאות שלמות או שורות טבלה במקום להיות מוכנסים במיקום הסמן.
הסרת פקודת תוכן מוחקת גם את הטקסט שבתוכה Remove() מוחק את הפקד ואת התוכן שלו יחד. קרא RemoveSelfOnly() במקום זאת כדי לשמור על התוכן במסמך ולהוריד רק את העטיפה.
תיבת הסימון אינה מציגה את הסמל הצפוי גליפים מותאמים לסימון ולביטול הסימון מעולם לא הוגדרו. קרא SetCheckedSymbol() and SetUncheckedSymbol() על הפקד.
תפריט נפתח או תיבת קומבו לא מציגים אפשרויות ListItems מעולם לא הושלמה האכלתו. הוסף SdtListItem רשומות לפקד של ListItems אוסף לפני הציפייה שהאפשרויות יופיעו, ואז להגדיר SelectedValue לבחור את הפעיל.
שאלות נפוצות
אילו סוגי פקדי תוכן ניתן להוסיף ישירות עם DocumentBuilder?
PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, ו-Date. ערכי SdtType אחרים אינם נתמכים על ידי InsertStructuredDocumentTag().
איך אני מוצא את כל בקרי התוכן עם תגית ספציפית?
קרא את Range.StructuredDocumentTags וקרא ל-GetByTag(), או GetByTitle() / GetById() אם תואם למזהים האלה במקום זאת.
איך אני מסיר בקר תוכן אבל משאיר את התוכן שלו במסמך?
קרא ל-StructuredDocumentTag.RemoveSelfOnly() במקום Remove().
איך אני קושר בקר תוכן לנתוני XML מותאמים?
קרא ל-XmlMapping.SetMapping() על ה-XmlMapping של הבקר, מצביע אותו לחלק XML מותאם קיים ולביטוי XPath בתוכו.
איך בקר תוכן שמקיף מספר מקטעים שונה מבקר רגיל?
הוא מיוצג כזוג StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd במקום צומת StructuredDocumentTag יחיד; שני הצורות מממשות את IStructuredDocumentTag, ולכן IsMultiSection מודיע לך איזו צורה אתה עובד איתה.
