.NET'de Yapılandırılmış Belge Etiketleri ile Nasıl Çalışılır
Bu kılavuz, yapılandırılmış belge etiketlerine (içerik denetimlerine) veri ekleme, yapılandırma, bulma, kaldırma ve bağlama konularını gösterir Aspose.Words FOSS for .NET, kullanarak StructuredDocumentTag sınıfı içinde Aspose.Words.Markup ad alanı. Hangi içerik denetim türlerini kapsadığını açıklar DocumentBuilder ekleyebilir, onay kutusu durumu veya açılır menü seçenekleri gibi tür-özel içerikleri ayarlayabilir, etiket veya başlıkla denetimleri bulabilir, bir denetimi içeriğiyle birlikte ya da içeriği olmadan kaldırabilir ve bir denetimi özel XML verisine eşleyebilir.
Adım Adım Kılavuz
Adım 1: Paketi Yükleyin
Aspose.Words FOSS for .NET henüz bir NuGet paketi yayımlamıyor – bunun yerine kütüphaneyi kaynak koddan derleyin. https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git deposunu klonlayın, ardından Aspose.Words.sln öğesini .NET SDK’sı ile Release yapılandırmasında derleyin ve projenizde oluşan Aspose.Words derlemesini referans alın. Kütüphane .NET Standard 2.0 hedeflediği için .NET Framework 4.6.2+ ve .NET 6/8/10 üzerinde çalışır.
Adım 2: Gerekli Sınıfları İçe Aktarın
Document ve DocumentBuilder için bir using Aspose.Words; yönergesi ekleyin, ayrıca StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping ve bu kılavuzun kapsadığı diğer içerik denetimi sınıfları için bir using Aspose.Words.Markup; yönergesi ekleyin.
Adım 3: Hangi İçerik-Kontrol Türlerini Ekleyebileceğinizi Kontrol Edin
Eklemeden önce, hedef SdtType‘ın DocumentBuilder.InsertStructuredDocumentTag(SdtType) tarafından kabul edilen yedi türden biri olup olmadığını kontrol edin: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ve Date. RepeatingSection ve RepeatingSectionItem bu yöntemle bir metin imlecine eklenemez — bunlar bunun yerine tüm paragrafları veya tablo satırlarını kapsar. Word dosyasında görünebilen ancak Word UI’da eklenebilir türler olarak bulunmayan kalan SdtType değerleri — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group ve EntityPicker — bu ekleme yöntemi tarafından hiç kabul edilmez.
Adım 4: İmleçte Bir İçerik Kontrolü Ekle
DocumentBuilder.InsertStructuredDocumentTag(SdtType)‘ı yedi desteklenen türden biriyle çağırarak, oluşturucunun mevcut imleç konumunda yeni bir kontrol ekleyin; çağrı yeni StructuredDocumentTag‘ı döndürür. Döndürülen kontrol üzerinde Tag ve Title‘ı ayarlayarak yazarların Word’de gördüğü tanımlayıcı metinleri verin ve kontrol boşken Word’ün gösterdiği istem metni için PlaceholderName‘ı (Placeholder BuildingBlock tarafından desteklenen) ayarlayın — IsShowingPlaceholderText bu istemin şu anda görüntülenip görüntülenmediğini rapor eder.
Adım 5: Tür-Özel İçeriği Yapılandır
Bir onay kutusu kontrolü için, StructuredDocumentTag.Checked‘ı okuyun veya ayarlayın ve her durum için gösterilen glifleri özelleştirmek üzere SetCheckedSymbol() / SetUncheckedSymbol()‘yi çağırın. Bir tarih kontrolü için, FullDate‘ü ayarlayın; DateDisplayFormat ve DateDisplayLocale nasıl görüntüleneceğini kontrol eder, DateStorageFormat (SdtDateStorageFormat) XML verisine bağlandığında nasıl depolanacağını kontrol eder ve CalendarType (SdtCalendarType) takvim sistemini seçer. Bir açılır liste veya birleşik kutu için, ListItems‘u doldurun — bu bir SdtListItemCollection SdtListItem (DisplayText, Value)‘dir — ardından aktif seçeneği seçmek için SelectedValue‘i ayarlayın. Düz metin kontrolü için, Multiline, StructuredDocumentTag üzerindeki bool özelliğidir ve kontrolü yapılandırmak için ayarlanabilir.
Adım 6: Kontrolün Görünümü ve Kilitleme
Appearance (SdtAppearance)‘i ayarlayarak kontrolün Word içinde görsel olarak nasıl sınırlandırıldığını, Color‘yi ise vurgulama rengini ayarlamak için kullanın. ContentsFont ve EndCharacterFont, kontrolün içeriğine uygulanan yazı tipini ve son karakterini kontrol eder. LockContentControl ve LockContents bağımsız anahtarlardır — LockContentControl‘i ayarlayarak kontrolün kendisinin silinmesini engelleyin ve LockContents‘i ayarlayarak içindeki içeriğin düzenlenmesini engelleyin, diğerine etki etmeden.
Adım 7: İçerik Denetimlerini Bul ve Kaldır
Read Range.StructuredDocumentTags – bu aralığa kapsamlı bir StructuredDocumentTagCollection – ve belirli bir denetimi bulmak için GetById(), GetByTag() veya GetByTitle() çağırın, ya da koleksiyonda referans veya indeks ile birini kaldırmak için Remove() / RemoveAt() kullanın. Tek bir denetimde, denetimi içeriğiyle birlikte silmek için Remove(), yalnızca sarmalayıcıyı silip içeriği belgede tutmak için RemoveSelfOnly(), ya da içeriği boşaltıp denetimi yerinde tutmak için Clear() çağırın.
Adım 8: Bir Denetimi Özel XML Verisine Bağla
Read StructuredDocumentTag.XmlMapping – bir XmlMapping örneği – ve denetimi, belgenin özel XML veri deposunda zaten mevcut olan mevcut bir özel XML bölümüne bağlamak için SetMapping(customXmlPart, xPath, prefixMapping) çağırın, bağlanan öğeyi seçmek için bir XPath ifadesi kullanın. XmlMapping.IsMapped, bir bağlamanın şu anda etkin olup olmadığını rapor eder, CustomXmlPart ve StoreItemId bağlanan veri bölümünü tanımlar, ve Delete() eşlemeyi kaldırır.
Adım 9: Birden Çok Bölümü Kapsayan İçerik Denetimlerini İşleyin
Birden fazla belge bölümünü kapsayan bir içerik denetimi – IsMultiSection tarafından rapor edilen – tek bir StructuredDocumentTag düğümüyle değil, StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd çiftiyle temsil edilir ve StructuredDocumentTagRangeStart.RangeEnd aracılığıyla bağlanır. Kodun tek düğüm ve aralıklı biçimleri aynı şekilde ele alması gerektiğinde, somut tipe göre dallanmak yerine ortak IStructuredDocumentTag arayüzüne (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) karşı programlayın.
Yaygın Sorunlar ve Çözümler
InsertStructuredDocumentTag NotImplementedException hatasını fırlatır İstenen SdtType – örnek olarak Citation, Equation, veya BuildingBlockGallery – yedi eklenebilir türden biri değildir. Kullan PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, veya Date yerine.
InsertStructuredDocumentTag InvalidOperationException fırlatır RepeatingSection or RepeatingSectionItem metin imlecinde istendi. Bu iki tip, imleç konumunda eklenmek yerine tüm paragrafları veya tablo satırlarını sarar.
Bir içerik denetimini kaldırmak, içindeki metni de siler Remove() kontrolü ve içeriğini birlikte siler. Çağır RemoveSelfOnly() bunun yerine, içeriği belgede tutar ve yalnızca sarmalayıcıyı bırakır.
Onay kutusu beklenen sembolü göstermiyor Özel işaretli ve işaretsiz glifler hiç ayarlanmamıştı. Çağır SetCheckedSymbol() and SetUncheckedSymbol() kontrol üzerinde.
Açılır liste veya birleştirme kutusu hiçbir seçenek göstermiyor ListItems hiç doldurulmamıştı. Ekle SdtListItem girdileri kontrolün ListItems seçeneklerin görünmesini beklemeden önce koleksiyon, ardından ayarla SelectedValue etkin olanı seçmek için.
Sıkça Sorulan Sorular
DocumentBuilder ile doğrudan hangi içerik denetimi türlerini ekleyebilirim?
PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture ve Date. Diğer SdtType değerleri InsertStructuredDocumentTag() tarafından desteklenmez.
Belirli bir etiketle tüm içerik denetimlerini nasıl bulabilirim?
Range.StructuredDocumentTags‘ı okuyun ve GetByTag()‘i çağırın, ya da bunun yerine bu tanımlayıcılara göre eşleşiyorsanız GetByTitle() / GetById()‘ü kullanın.
Bir içerik denetimini nasıl kaldırıp içeriğini belgede tutarım?
StructuredDocumentTag.RemoveSelfOnly()‘ı Remove() yerine çağırın.
Bir içerik denetimini özel XML verisine nasıl bağlarım?
Denetimin XmlMapping üzerinde XmlMapping.SetMapping()‘ı çağırın ve onu mevcut bir özel XML bölümüne ve içinde bir XPath ifadesine yönlendirin.
Birden fazla bölümü kapsayan bir içerik denetimi, sıradan bir denetimden nasıl farklıdır?
Bu, tek bir StructuredDocumentTag düğümü yerine bir StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd çifti olarak temsil edilir; her iki biçim de IStructuredDocumentTag‘yi uygular, bu nedenle IsMultiSection hangi biçimle çalıştığınızı size bildirir.
