עבודה עם תגיות מסמכים מובנות (בקרי תוכן)

עבודה עם תגים של מסמכים מובנים (בקרי תוכן)

תג מסמך מובנה (SDT), הידוע בממשק המשתמש של Word כפקד תוכן, עוטף קטע של תוכן מסמך עם התנהגות עריכה מסוגת ומוגבלת — תיבת סימון, בורר תאריכים, רשימת נפתחת, או מציין מקום של טקסט רגיל או עשיר. Aspose.Words FOSS עבור .NET מודל את אלה דרך Aspose.Words.Markup מרחב שם, בראשות StructuredDocumentTag מחלקה. דף זה מתאר הוספת פקדי תוכן, קביעת תצורה לכל סוג, מציאת והסרתם, וקישורם לנתונים מותאמים של XML.

מודל האובייקטים של תג המסמך המובנה

StructuredDocumentTag הוא CompositeNode שגם מיישם את IMarkupNode, ITrackableNode, ו-IStructuredDocumentTag. SdtType מזהה את סוג הבקר. Tag ו-Title מחזיקים את המחרוזות המזהות שהמחברים הגדירו ב-Word; Placeholder (‏BuildingBlock) ו-PlaceholderName מספקים את טקסט ההנחיה שמוצג כאשר הבקר ריק, מדווח דרך IsShowingPlaceholderText. LockContentControl מונע מחיקת הבקר, ו-LockContents מונע עריכת תוכנו, באופן עצמאי זה מזה.

הוספת בקרים לתוכן

DocumentBuilder.InsertStructuredDocumentTag(SdtType) מוסיף בקר חדש במיקום הסמן, אך רק עבור שבעה ערכי SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ו-Date. לא ניתן להכניס את RepeatingSection ו-RepeatingSectionItem במיקום סמן טקסט בצורה זו – הם עוטפים פסקאות שלמות או שורות בטבלה במקום זאת. שאר הערכים של SdtType המופיעים בקבצי Word אך אינם קיימים בממשק ה-Word כסוגים שניתן להוסיף – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group ו-EntityPicker – אינם נתמכים על ידי שיטת הוספה זו.

תוכן לפי סוג

מצב של פקד תיבת סימון הוא StructuredDocumentTag.Checked; SetCheckedSymbol() ו-SetUncheckedSymbol() קובעים את הסמלים המוצגים עבור כל מצב. פקד תאריך מאחסן את ערכו ב-FullDate, כאשר DateDisplayFormat ו-DateDisplayLocale שולטות באופן הצגתו, DateStorageFormat (‏SdtDateStorageFormat) שולט איך הוא מאוחסן כאשר קשור לנתוני XML, ו-CalendarType (‏SdtCalendarType) בוחר את מערכת הלוח השנה. רשימת נפתחת או תיבת משולבת מציגה את האפשרויות שלה דרך ListItems, ‏SdtListItemCollection של SdtListItem (DisplayText, Value) עם SelectedValue. המאפיין Multiline של פקד טקסט פשוט מאפשר או מונע שבירות שורה בתוכו.

מראה ונעילה

Appearance (SdtAppearance) שולט כיצד הפקד מוגדר חזותית ב-Word. Color מגדיר את צבע ההדגשה שלו, ו-ContentsFont / EndCharacterFont שולטות בגופן המיושם על התוכן ובתו הסופי שלו. LockContentControl ו-LockContents הם מתגים עצמאיים – הראשון חוסם מחיקת הפקד עצמו, השני חוסם עריכה של מה שנמצא בתוכו.

מציאת והסרת בקרי תוכן

Range.StructuredDocumentTags מחזיר StructuredDocumentTagCollection המוגדר לטווח זה, עם GetById(), GetByTag(), ו-GetByTitle() לחיפוש ממוקד לצד Remove() ו-RemoveAt(). על StructuredDocumentTag בודד, Remove() מוחק את הפקד ואת תוכנו יחד, RemoveSelfOnly() מוחק רק את העטיפה ומשאיר את התוכן במסמך, ו-Clear() מרוקן את תוכן הפקד תוך שמירה על הפקד עצמו.

XML קישור נתונים

StructuredDocumentTag.XmlMapping הוא מופע של XmlMapping המתאר קישור לחלק XML מותאם אישית במסמך: CustomXmlPart, XPath, PrefixMappings, StoreItemId, ו-IsMapped. SetMapping() מקים את הקישור לחלק XML מותאם אישית קיים ו-Delete() מסיר אותו.

בקרי תוכן מרובי-מקטעים (טווחיים)

בקרת תוכן המתפרסת על יותר ממקטע אחד – מדווחת על ידי IsMultiSection – מיוצגת לא על-ידי צומת StructuredDocumentTag יחיד אלא על-ידי זוג צמתים StructuredDocumentTagRangeStart ו-StructuredDocumentTagRangeEnd, המחוברים דרך StructuredDocumentTagRangeStart.RangeEnd. הן הצורה עם צומת יחיד והן הצורה בטווח מממשות את הממשק המשותף IStructuredDocumentTag, ולכן קוד שזקוק רק ל-Tag, Title, SdtType, Placeholder ולתכונות זיהוי דומות יכול לפעול עם כל אחת מהצורות באופן אחיד.

טיפים ושיטות עבודה מומלצות

• בדוק את רשימת סוגי-הקוד הנתמכים של DocumentBuilder.InsertStructuredDocumentTag() לפני שאתה מסתמך עליו – רק PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ו-Date ניתנים להוספה במצביע; סוגים אחרים זורקים חריגה.
• השתמש ב-RemoveSelfOnly() במקום Remove() כאשר ברצונך “לשטח” בקרת תוכן – שמור את התוכן שלה במסמך אך הורד את עטיפת הבקרה.
• מלא את ListItems לפני שאתה מצפה שבקרת DropDownList או ComboBox תציג אפשרויות, והגדר את SelectedValue כדי לבחור את הפעילה.
• תכנת כנגד IStructuredDocumentTag במקום StructuredDocumentTag ישירות אם הקוד שלך צריך להתמודד עם בקרות תוכן רגילות ובקרות מרובות-מקטעים (בטווח) באותו האופן.
• XmlMapping.SetMapping() נקשר לחלק מותאם אישית XML שחייב כבר להיות קיים במאגר הנתונים המותאם אישית XML של המסמך – הוסף או טען את נתוני XML לפני שממפים בקרה אליו.

בעיות נפוצות

FAQ

אילו סוגי בקרת תוכן ניתן להכניס ישירות באמצעות DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ו-Date. ערכי SdtType אחרים אינם נתמכים על-ידי InsertStructuredDocumentTag().

איך למצוא את כל בקרות התוכן עם תגית ספציפית?

השתמש ב-Range.StructuredDocumentTags.GetByTag(), או ב-GetByTitle() / GetById() אם אתה משווה אליהם במקום זאת.

איך להסיר בקרת תוכן אך לשמור על התוכן שלה?

השתמש ב-StructuredDocumentTag.RemoveSelfOnly() במקום Remove().

איך לקשר בקרת תוכן לנתוני XML מותאמים אישית?

קרא לXmlMapping.SetMapping() על הבקרה, תוך הפנייה אל חלק XML מותאם אישית קיים וביטוי XPath בתוכו.

מה ההבדל בין StructuredDocumentTag רגיל לStructuredDocumentTag בטווח?

בקרת תוכן המתפרסת על יותר ממקטע מסמך אחד מיוצגת כזוג StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd במקום צומת בודד; שני הצורות מיישמות את IStructuredDocumentTag.

API Reference סיכום

ראה גם

• Aspose.Words for .NET — Enterprise Documentation