.NET में संरचित दस्तावेज़ टैग के साथ कैसे काम करें
यह गाइड दिखाता है कि कैसे सम्मिलित करें, कॉन्फ़िगर करें, खोजें, हटाएँ, और संरचित दस्तावेज़ टैग (content controls) में डेटा को बाइंड करें Aspose.Words FOSS के लिए .NET, का उपयोग करके StructuredDocumentTag क्लास में Aspose.Words.Markup नेमस्पेस। यह बताता है कि कौन से content-control प्रकार DocumentBuilder डाल सकते हैं, type-specific content जैसे checkbox state या drop-down choices सेट करना, टैग या शीर्षक से controls को locate करना, control को उसकी सामग्री के साथ या बिना हटाना, और control को कस्टम XML डेटा से map करना।
स्टेप-बाय-स्टेप गाइड
चरण 1: पैकेज स्थापित करें
Aspose.Words FOSS for .NET अभी तक एक NuGet पैकेज प्रकाशित नहीं करता है – इसके बजाय लाइब्रेरी को स्रोत से बनाएँ। https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git को क्लोन करें, फिर Aspose.Words.sln को Release कॉन्फ़िगरेशन में .NET SDK के साथ बनाएँ और अपने प्रोजेक्ट से उत्पन्न Aspose.Words असेंबली को रेफ़रेंस करें। लाइब्रेरी .NET Standard 2.0 को टार्गेट करती है, इसलिए यह .NET Framework 4.6.2+ और .NET 6/8/10 पर चलती है।
चरण 2: आवश्यक क्लासेस आयात करें
Document और DocumentBuilder के लिए एक using Aspose.Words; निर्देश जोड़ें, और StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping तथा इस गाइड में कवर किए गए अन्य कंटेंट-कंट्रोल क्लासेस के लिए एक using Aspose.Words.Markup; निर्देश जोड़ें।
चरण 3: जाँचें कि आप कौन से कंटेंट-कंट्रोल प्रकार सम्मिलित कर सकते हैं
सम्मिलित करने से पहले, जांचें कि लक्ष्य SdtType DocumentBuilder.InsertStructuredDocumentTag(SdtType) द्वारा स्वीकृत सात प्रकारों में से एक है या नहीं: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, और Date. RepeatingSection और RepeatingSectionItem इस विधि से टेक्स्ट कर्सर पर सम्मिलित नहीं किए जा सकते — वे पूरी पैराग्राफ या टेबल पंक्तियों को घेरते हैं। शेष SdtType मान जो Word फ़ाइल में प्रकट हो सकते हैं लेकिन Word UI में सम्मिलित करने योग्य प्रकार के रूप में नहीं दिखते — 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 of SdtListItem (DisplayText, Value) — फिर सक्रिय विकल्प चुनने के लिए SelectedValue सेट करें। एक प्लेन-टेक्स्ट कंट्रोल के लिए, Multiline StructuredDocumentTag पर एक bool प्रॉपर्टी है जिसे कंट्रोल को कॉन्फ़िगर करने के लिए सेट किया जा सकता है।
चरण 6: नियंत्रण की उपस्थिति और लॉकिंग
Appearance (SdtAppearance) सेट करें ताकि Word में कंट्रोल की दृश्य सीमा निर्धारित की जा सके, और Color सेट करके उसका हाइलाइट रंग निर्धारित करें। ContentsFont और EndCharacterFont कंट्रोल की सामग्री और उसके अंत के कैरेक्टर पर लागू फ़ॉन्ट को नियंत्रित करते हैं। LockContentControl और LockContents स्वतंत्र स्विच हैं — LockContentControl सेट करके कंट्रोल को स्वयं हटाने से रोका जा सकता है, और LockContents सेट करके उसके अंदर की सामग्री के संपादन को रोका जा सकता है, बिना दूसरे को प्रभावित किए।
चरण 7: कंटेंट कंट्रोल्स को खोजें और हटाएँ
Read Range.StructuredDocumentTags – उस रेंज के लिए एक StructuredDocumentTagCollection – और GetById(), GetByTag(), या GetByTitle() को कॉल करें ताकि एक विशिष्ट कंट्रोल लोकेट किया जा सके, या संग्रह पर Remove() / RemoveAt() को कॉल करके रेफ़रेंस या इंडेक्स द्वारा एक को हटाया जा सके। एक व्यक्तिगत कंट्रोल पर, Remove() को कॉल करके कंट्रोल को उसकी सामग्री सहित डिलीट करें, RemoveSelfOnly() को कॉल करके केवल रैपर को हटाएँ जबकि उसकी सामग्री दस्तावेज़ में बनी रहे, या Clear() को कॉल करके उसकी सामग्री को खाली करें जबकि कंट्रोल स्वयं जगह पर बना रहे।
चरण 8: कस्टम XML डेटा से कंट्रोल को बाइंड करें
Read 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() द्वारा समर्थित नहीं हैं।
मैं विशिष्ट टैग वाले सभी content controls को कैसे खोजूँ?
Range.StructuredDocumentTags पढ़ें और GetByTag() को कॉल करें, या यदि उन पहचानकर्ताओं पर मिलान किया जाए तो GetByTitle() / GetById()।
मैं content control को कैसे हटाऊँ लेकिन उसके कंटेंट को दस्तावेज़ में रखूँ?
Remove() के बजाय StructuredDocumentTag.RemoveSelfOnly() को कॉल करें।
मैं content control को कस्टम XML डेटा से कैसे बाँधूँ?
कंट्रोल के XmlMapping पर XmlMapping.SetMapping() को कॉल करें, इसे मौजूदा कस्टम XML भाग और उसके भीतर एक XPath अभिव्यक्ति की ओर संकेत करते हुए।
एक content control जो कई सेक्शन में फैला हो, सामान्य कंट्रोल से कैसे अलग होता है?
यह एकल StructuredDocumentTag नोड के बजाय StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd जोड़ी के रूप में दर्शाया जाता है; दोनों रूप IStructuredDocumentTag को लागू करते हैं, इसलिए IsMultiSection आपको बताता है कि आप किस रूप के साथ काम कर रहे हैं।
