Εργασία με Δομημένες Ετικέτες Εγγράφου (Έλεγχοι Περιεχομένου)

Εργασία με Δομημένες Ετικέτες Εγγράφου (Περιοριστικά Στοιχεία Περιεχομένου)

Μια ετικέτα δομημένου εγγράφου (SDT), γνωστή στη διεπαφή του Word ως content control, περιβάλλει ένα τμήμα περιεχομένου εγγράφου με τυποποιημένη, περιορισμένη συμπεριφορά επεξεργασίας — ένα checkbox, ένα date picker, μια drop-down list ή έναν plain- ή rich-text placeholder. Aspose.Words FOSS για .NET μοντελοποιεί αυτά μέσω του Aspose.Words.Markup χώρο ονομάτων, με επικεφαλίδα το StructuredDocumentTag class. Αυτή η σελίδα καλύπτει την εισαγωγή content controls, τη διαμόρφωση κάθε τύπου, την εύρεση και αφαίρεσή τους, καθώς και τη σύνδεσή τους με προσαρμοσμένα δεδομένα 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 — δεν υποστηρίζονται από αυτή τη μέθοδο εισαγωγής.

Περιεχόμενο Κατά Τύπο

Η κατάσταση ενός ελέγχου τύπου checkbox είναι 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() όταν θέλετε να “flatten” έναν έλεγχο περιεχομένου — διατηρήστε το περιεχόμενό του στο έγγραφο αλλά αφαιρέστε το περιτύλιγμα του ελέγχου.
• Συμπληρώστε το 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 και ενός με εύρος;

Ένας έλεγχος περιεχομένου που εκτείνεται σε περισσότερες από μία ενότητες του εγγράφου αντιπροσωπεύεται ως ένα ζεύγος StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd αντί για έναν μόνο κόμβο· και οι δύο μορφές υλοποιούν το IStructuredDocumentTag.

API Reference Περίληψη

Δείτε επίσης

• Aspose.Words for .NET — Enterprise Documentation