Cum să lucrați cu etichetele de document structurat în .NET
Acest ghid arată cum să inserați, să configurați, să găsiți, să eliminați și să legați date la etichetele de document structurate (controale de conținut) în Aspose.Words FOSS pentru .NET, utilizând StructuredDocumentTag clasa în Aspose.Words.Markup spațiu de nume. Acoperă care tipuri de controale de conținut DocumentBuilder pot insera, setând conținut specific tipului, cum ar fi starea casetei de bifare sau opțiunile dintr-un meniu derulant, localizarea controalelor după etichetă sau titlu, eliminarea unui control cu sau fără conținutul său și maparea unui control la date personalizate XML.
Ghid pas cu pas
Pasul 1: Instalați pachetul
Aspose.Words FOSS pentru .NET nu publică încă un pachet NuGet – construiți biblioteca din sursă în schimb. Clonați https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, apoi construiți Aspose.Words.sln în configurația Release cu SDK-ul .NET și referiți asamblarea Aspose.Words rezultat din proiectul dumneavoastră. Biblioteca vizează .NET Standard 2.0, astfel că rulează pe .NET Framework 4.6.2+ și .NET 6/8/10.
Pasul 2: Importați clasele necesare
Adăugați o directivă using Aspose.Words; pentru Document și DocumentBuilder, și o directivă using Aspose.Words.Markup; pentru StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, și celelalte clase de control de conținut acoperite de acest ghid.
Pasul 3: Verificați ce tipuri de Control de Conținut puteți insera
Înainte de inserare, verificați dacă ținta SdtType este unul dintre cele șapte tipuri acceptate de DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture și Date. RepeatingSection și RepeatingSectionItem nu pot fi inserate la un cursor de text cu această metodă — ele încadrează întregi paragrafe sau rânduri de tabel în schimb. Valorile SdtType rămase care pot apărea într-un fișier Word, dar nu sunt prezente în interfața Word ca tipuri inserabile — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group și EntityPicker — nu sunt acceptate deloc de această metodă de inserare.
Pasul 4: Inserarea unui Control de Conținut la cursor
Apelați DocumentBuilder.InsertStructuredDocumentTag(SdtType) cu unul dintre cele șapte tipuri acceptate pentru a insera un nou control la poziția curentă a cursorului builderului; apelul returnează noul StructuredDocumentTag. Setați Tag și Title pe controlul returnat pentru a-i oferi șirurile de identificare pe care autorii le văd în Word și setați PlaceholderName (susținut de un Placeholder BuildingBlock) pentru textul sugestiv pe care Word îl afișează când controlul este gol — IsShowingPlaceholderText raportează dacă acel mesaj este afișat în prezent.
Pasul 5: Configurarea conținutului specific tipului
Pentru un control de tip casetă de bifare, citiți sau setați StructuredDocumentTag.Checked și apelați SetCheckedSymbol() / SetUncheckedSymbol() pentru a personaliza glifele afișate pentru fiecare stare. Pentru un control de tip dată, setați FullDate, cu DateDisplayFormat și DateDisplayLocale care controlează modul în care este redat, DateStorageFormat (SdtDateStorageFormat) care controlează modul în care este stocat când este legat de datele XML, și CalendarType (SdtCalendarType) care selectează sistemul de calendar. Pentru o listă derulantă sau o casetă combinată, populați ListItems — un SdtListItemCollection de SdtListItem (DisplayText, Value) — înainte de a seta SelectedValue pentru a alege opțiunea activă. Pentru un control de text simplu, Multiline este o proprietate bool pe StructuredDocumentTag care poate fi setată pentru a configura controlul.
Pasul 6: Aspectul și blocarea controlului
Setați Appearance (SdtAppearance) pentru a controla cum este delimitat vizual controlul în Word și Color pentru a stabili culoarea de evidențiere. ContentsFont și EndCharacterFont controlează fontul aplicat conținutului controlului și caracterul său final. LockContentControl și LockContents sunt comutatoare independente — setați LockContentControl pentru a bloca ștergerea controlului în sine și LockContents pentru a bloca editarea conținutului său, fără a afecta celălalt.
Pasul 7: Găsiți și eliminați controalele de conținut
Citiți Range.StructuredDocumentTags – un StructuredDocumentTagCollection limitat la acel interval – și apelați GetById(), GetByTag() sau GetByTitle() pentru a localiza un control specific, sau Remove() / RemoveAt() pe colecție pentru a elimina unul prin referință sau index. Pentru un control individual, apelați Remove() pentru a șterge controlul împreună cu conținutul său, RemoveSelfOnly() pentru a șterge doar învelișul păstrând conținutul în document, sau Clear() pentru a goli conținutul în timp ce controlul rămâne la loc.
Pasul 8: Asociați un control cu datele personalizate XML
Citiți StructuredDocumentTag.XmlMapping – o XmlMapping instanță – și apelați SetMapping(customXmlPart, xPath, prefixMapping) pentru a asocia controlul cu o parte XML personalizată existentă, deja prezentă în depozitul de date personalizate XML al documentului, utilizând o expresie XPath pentru a selecta elementul asociat. XmlMapping.IsMapped raportează dacă o asociere este în prezent activă, CustomXmlPart și StoreItemId identifică partea de date asociată, iar Delete() elimină maparea.
Pasul 9: Gestionați controalele de conținut care se extind pe mai multe secțiuni
Un control de conținut care se întinde pe mai mult de o secțiune a documentului – raportat de IsMultiSection – este reprezentat nu printr-un singur nod StructuredDocumentTag, ci printr-o pereche StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, conectată prin StructuredDocumentTagRangeStart.RangeEnd. Programați împotriva interfeței comune IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) când codul trebuie să gestioneze uniform atât formele cu nod unic, cât și cele cu interval, în loc să facă ramificare pe tipul concret.
Probleme comune și soluții
InsertStructuredDocumentTag aruncă NotImplementedException Cea solicitată SdtType – de exemplu Citation, Equation, sau BuildingBlockGallery – nu este unul dintre cele șapte tipuri inserabile. Folosiți PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, sau Date în schimb.
InsertStructuredDocumentTag aruncă InvalidOperationException RepeatingSection or RepeatingSectionItem a fost solicitat la un cursor de text. Aceste două tipuri înfășoară paragrafe întregi sau rânduri de tabel, în loc să fie inserate la poziția cursorului.
Eliminarea unui control de conținut șterge, de asemenea, textul din interiorul său Remove() șterge controlul și conținutul său împreună. Apelă RemoveSelfOnly() în schimb pentru a păstra conținutul în document și a elimina doar învelișul.
Caseta de bifare nu afișează simbolul așteptat Glifele personalizate bifate și nebifate nu au fost niciodată setate. Apelă SetCheckedSymbol() and SetUncheckedSymbol() pe control.
O listă derulantă sau o casetă combo nu afișează nicio opțiune ListItems nu a fost niciodată populată. Adaugă SdtListItem intrări la control. ListItems colecție înainte de a aștepta ca opțiunile să apară, apoi setează SelectedValue pentru a selecta pe cel activ.
Întrebări frecvente
Ce tipuri de control de conținut 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ă?
Citește Range.StructuredDocumentTags și apelează GetByTag(), sau GetByTitle() / GetById() dacă faci potrivirea pe acele identificatoare în schimb.
Cum pot elimina un control de conținut, dar să păstrez conținutul său în document?
Apelează StructuredDocumentTag.RemoveSelfOnly() în loc de Remove().
Cum pot asocia un control de conținut cu datele personalizate XML?
Apelează XmlMapping.SetMapping() pe XmlMapping controlului, îndreptându-l spre o parte XML personalizată existentă și o expresie XPath din interiorul ei.
Cum diferă un control de conținut care se întinde pe mai multe secțiuni de unul obișnuit?
Este reprezentat ca o pereche StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd în loc de un singur nod StructuredDocumentTag; ambele forme implementează IStructuredDocumentTag, astfel IsMultiSection îți spune cu ce formă lucrezi.
