Lucrul cu Etichete Structurate de Document (Controale de conținut)

Lucrul cu etichetele de document structurat (controale de conținut)

Un tag de document structurat (SDT), cunoscut în interfața Word ca un control de conținut, învelește o bucată de conținut al documentului cu comportament de editare tipizat și restricționat – o căsuță de bifare, un selector de dată, o listă derulantă sau un substituent de text simplu sau îmbogățit. Aspose.Words FOSS pentru .NET le modelează prin Aspose.Words.Markup spațiu de nume, condus de StructuredDocumentTag Această pagină acoperă inserarea controalelor, configurarea fiecărui tip, găsirea și eliminarea lor, și legarea acestora de date personalizate XML.

Modelul de obiecte al etichetelor de document structurat

StructuredDocumentTag este un CompositeNode care implementează, de asemenea, IMarkupNode, ITrackableNode și IStructuredDocumentTag. SdtType identifică tipul de control. Tag și Title conțin șirurile de identificare setate de autori în Word; Placeholder (un BuildingBlock) și PlaceholderName furnizează textul de indiciu afișat când elementul este gol, raportat prin IsShowingPlaceholderText. LockContentControl împiedică ștergerea controlului, iar LockContents blochează editarea conținutului său, independent una de cealaltă.

Inserarea controalelor

DocumentBuilder.InsertStructuredDocumentTag(SdtType) inserează un nou control la cursor, dar numai pentru șapte dintre valorile SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture și Date. RepeatingSection și RepeatingSectionItem nu pot fi introduse la un cursor de text în acest mod — ele înconjoară paragrafe întregi sau rânduri de tabel. Valorile SdtType rămase, care apar în fișierele Word, dar nu sunt prezente în interfața Word ca tipuri inserabile — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group și EntityPicker — nu sunt suportate prin această metodă de inserție.

Conținut specific tipului

Starea unui control de tip checkbox este StructuredDocumentTag.Checked; SetCheckedSymbol() și SetUncheckedSymbol() definesc simbolurile afișate pentru fiecare stare. Un control de tip dată își stochează valoarea în FullDate, cu DateDisplayFormat și DateDisplayLocale care controlează modul de redare, DateStorageFormat (un SdtDateStorageFormat) care controlează modul de stocare când este legat de datele XML, și CalendarType (un SdtCalendarType) care selectează sistemul de calendar. O listă derulantă sau o casetă combo expune opțiunile prin ListItems, un SdtListItemCollection de SdtListItem (DisplayText, Value) cu un SelectedValue. Proprietatea Multiline a unui control de tip text simplu permite sau interzice întreruperi de linie în interiorul său.

Aspect și blocare

Appearance (SdtAppearance) determină modul în care este delimitat vizual în Word. Color stabilește culoarea de evidențiere, iar ContentsFont / EndCharacterFont controlează fontul aplicat conținutului și caracterul final. LockContentControl și LockContents sunt comutatoare independente — primul împiedică ștergerea acestui element, al doilea blochează editarea conținutului său.

Găsirea și eliminarea controalelor de tip conținut

Range.StructuredDocumentTags returnează un StructuredDocumentTagCollection cu domeniu de aplicare la acel interval, cu GetById(), GetByTag() și GetByTitle() pentru căutare țintită alături de Remove() și RemoveAt(). Pentru un StructuredDocumentTag individual, Remove() șterge elementul și conținutul său simultan, RemoveSelfOnly() elimină doar învelișul păstrând conținutul în document, iar Clear() golește conținutul în timp ce păstrează elementul.

Legarea datelor XML

StructuredDocumentTag.XmlMapping este o instanță XmlMapping care descrie o legătură către o parte XML personalizată în document: CustomXmlPart, XPath, PrefixMappings, StoreItemId și IsMapped. SetMapping() stabilește legătura cu o parte XML personalizată existentă, iar Delete() o elimină.

Controale de conținut multi-secțiune (cu interval)

Un control al conținutului care se întinde pe mai multe secțiuni — raportat de IsMultiSection — nu este reprezentat printr-un singur nod StructuredDocumentTag, ci printr-o pereche de noduri StructuredDocumentTagRangeStart și StructuredDocumentTagRangeEnd, legate prin StructuredDocumentTagRangeStart.RangeEnd. Atât forma cu un singur nod, cât și cea cu interval, implementează interfața comună IStructuredDocumentTag, astfel încât codul care are nevoie doar de Tag, Title, SdtType, Placeholder și alte proprietăți de identificare similare poate lucra uniform cu ambele variante.

Sfaturi și practici recomandate

• Verificați lista de tipuri acceptate de DocumentBuilder.InsertStructuredDocumentTag() înainte de a vă baza pe ea — doar PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture și Date pot fi inserate la cursor; alte tipuri generează o excepție.
• Utilizați RemoveSelfOnly() în loc de Remove() când doriţi să „aplatizaţi” un control al conținutului — păstraţi conţinutul în document, dar eliminaţi învelitoarea de control.
• Populaţi ListItems înainte de a aştepta ca un control DropDownList sau ComboBox să afișeze opţiuni și setaţi SelectedValue pentru a alege pe cel activ.
• Programaţi împotriva IStructuredDocumentTag în loc să accesaţi direct StructuredDocumentTag dacă codul dvs. trebuie să gestioneze în aceeaşi manieră atât controalele obișnuite, cât şi pe cele multi-secţiune (cu interval).
• XmlMapping.SetMapping() se leagă de o parte XML personalizată care trebuie să existe deja în depozitul de date XML personalizat al documentului — adăugaţi sau încărcaţi datele XML înainte de a mapa un control la acestea.

Probleme comune

FAQ

Ce tipuri de control al conținutului pot insera direct cu DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture și Date. Alte valori SdtType nu sunt suportate de InsertStructuredDocumentTag().

Cum pot găsi toate controalele de conținut cu o etichetă specifică?

Folosiți Range.StructuredDocumentTags.GetByTag(), sau GetByTitle() / GetById() dacă faceți potrivirea pe acestea în schimb.

Cum pot elimina un control al conținutului păstrând totuși conținutul?

Apelați StructuredDocumentTag.RemoveSelfOnly() în loc de Remove().

Cum pot asocia un control al conținutului cu date XML personalizate?

Apelă XmlMapping.SetMapping() pe control, îndreptându-l către o parte XML personalizată existentă și o expresie XPath în interiorul acesteia.

Care este diferența dintre un StructuredDocumentTag simplu și unul cu interval?

Un control al conținutului care acoperă mai multe secțiuni ale documentului este reprezentat ca o pereche StructuredDocumentTagRangeStart/StructuredDocumentTagRangeEnd în loc de un nod singular; ambele forme implementează IStructuredDocumentTag.

Rezumat API Reference

Vezi și:

• Aspose.Words for .NET — Enterprise Documentation