Alanlarla Çalışma
Genel Bakış
Bir Word alanı – DATE, IF, DATABASE, REF, ve onlarca başka – temsil edilir Aspose.Words FOSS için .NET tarafından Field sınıf ve alt sınıfları, hepsi Aspose.Words.Fields ad alanında. Bu sayfa temel alan motorunu kapsar: Field nesne modeli kendisi, alanların nasıl toplandığı ve güncellendiği, ve bir alan güncellemesi sırasında özelleştirilmiş veri ve davranış eklemenizi sağlayan geri çağırma arayüzleri. Belirli alan aileleri – hiper bağlantılar ve çapraz başvurular, tarih/saat alanları, birleştirme alanları, indeks ve içindekiler tablosu alanları – her biri kendi özel geliştirici-rehber sayfasına sahiptir.
Alan Nesne Modeli
Bir belgedeki her alan, üç işaretçi düğümünden oluşan bir Field örneğidir – FieldStart, Separator ve FieldEnd – ve bunlar Field.Start, Field.Separator ve Field.End özellikleri olarak sunulur. Field.Type, alanın temsil ettiği FieldType‘i tanımlar, Field.Result ve Field.DisplayResult son hesaplanmış değeri ortaya çıkarır, ve Field.Format alan koduna eklenmiş herhangi bir anahtarı (örneğin sayısal veya tarih-saat biçim dizgileri) tutar. Field.IsLocked ve Field.IsDirty alanın kilitli ve eski durumunu rapor eder. Çağırın Field.GetFieldCode() ham alan kodu metnini okumak için, Field.Update() sonucu yeniden hesaplamak için, Field.Unlink() alanı sabit metinle değiştirmek için ve Field.Remove() tamamen silmek için.
Belgedeki Alanlara Erişim ve Güncelleme
Document.Range.Fields bir FieldCollection döndürür – o aralıkta bulunan alanlar, toplu kaldırma için Count, Remove(), RemoveAt() ve Clear() ile. Range.UpdateFields() aralıktaki tüm alanları yeniden hesaplar, Range.UnlinkFields() aralıktaki tüm alanları sabit metne dönüştürür ve Range.NormalizeFieldTypes() manuel düzenlemelerden sonra bir alanın saklanan tür kodunu gerçek alan koduyla uzlaştırır. DocumentBuilder.InsertField() imleç konumunda yeni bir alan ekler; aşırı yüklemeleri, yeni alanın sonucunu hemen günceller ya da daha sonraki bir Range.UpdateFields() geçişi için bırakır.
Alan Güncelleme Seçenekleri ve Kültür
Document.FieldOptions, güncellendiğinde tüm belgenin alanlarının nasıl davranacağını yöneten bir FieldOptions örneğidir: CurrentUser, kimlik alanları tarafından kullanılan UserInformation‘ı sağlar, DefaultDocumentAuthor yazarla ilgili sonuçları başlatır, LegacyNumberFormat ve UseInvariantCultureNumberFormat sayı biçimlendirmesini kontrol eder, ve PreProcessCulture ve FieldUpdateCultureSource (IFieldUpdateCultureProvider geri çağrımı ile eşleştirilmiş) bir güncelleme sırasında tarih ve sayı biçimlendirmesini yöneten kültürü belirler. TemplateName, FileName ve BuiltInTemplatesPaths, şablon ve dosya adı farkında olan alanların okuduğu değerleri sağlar.
Alan Güncellemelerini İzleme ve Özelleştirme
IFieldUpdatingCallback (FieldUpdating ve FieldUpdated) FieldOptions üzerinde, her alan yeniden hesaplandığında kodu hemen öncesinde ve sonrasında çalıştırmak için uygulayın — toplu işte hangi alanların değiştiğini denetlemek için faydalıdır. IFieldUpdatingProgressCallback (Notify)‘i, büyük bir belgede genel ilerlemeyi izlemek için uygulayın; FieldUpdatingProgressArgs‘ı TotalFieldsCount, UpdatedFieldsCount ve UpdateCompleted ile alır. Bir alanın sayısal veya genel sonucunun metin olarak nasıl görüntüleneceğini değiştirmek için IFieldResultFormatter (Format(value, format) ve FormatNumeric(value, format))‘yi uygulayın ve FieldOptions.ResultFormatter‘e atayın.
Alanlara Dış Veri Sağlama
DATABASE alanı, satırlarını IFieldDatabaseProvider.GetQueryResult() aracılığıyla okur; IFieldDatabaseProvider.GetQueryResult(), FieldDatabaseDataRow (Values) örneklerinden oluşturulan bir FieldDatabaseDataTable (ColumnNames, Rows) döndürür — uygulamanızı FieldOptions.FieldDatabaseProvider‘e atayın. IF gibi karşılaştırma alanları, koşullarını IComparisonExpressionEvaluator.Evaluate() üzerinden değerlendirir; IComparisonExpressionEvaluator.Evaluate(), bir ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) alır ve bir ComparisonEvaluationResult (Result, ErrorMessage) döndürür; varsayılan karşılaştırma mantığını geçersiz kılmak için FieldOptions.ComparisonExpressionEvaluator‘ye özel bir değerlendirici atayın. Güncelleme sırasında normalde kullanıcıdan girdi isteyen alanlar — örneğin ASK ve FILLIN — FieldOptions.UserPromptRespondent‘e atandığında IFieldUserPromptRespondent.Respond()‘i çağırır, böylece denetimsiz bir güncelleme etkileşimli girdi bekleyerek bloklanmaz.
Alanlar için Kullanıcı ve Belge Kimliği
UserInformation (Name, Initials, Address ve statik UserInformation.DefaultUser), yazar ve kullanıcı adıyla ilgili alanların okuduğu kimliği sağlar. Belge yazarına veya kullanıcı kimliğine bağlı alanları güncellemeden önce bir örneği Document.FieldOptions.CurrentUser‘e atayın.
İpuçları ve En İyi Uygulamalar
- Aspose.Words FOSS, Word gibi yükleme veya kaydetme sırasında alanları otomatik olarak yeniden hesaplamaz – alan sonuçlarında yansıtılması gereken herhangi bir programatik düzenlemeden sonra
Range.UpdateFields()‘ı (veya tek bir alan içinField.Update()‘ı) açıkça çağırın. FieldStart,SeparatorveFieldEndbelge ağacındaki gerçek düğümlerdir; işaretçi düğümlerini doğrudan silmek yerineField.Remove()veyaField.Unlink()aracılığıyla bir alanı kaldırın, aksi takdirde alan yapısı tutarsız hale gelebilir.- Sonucu sayfa düzenine bağlı olan alanlar –
PAGE,NUMPAGESve TOC sayfa numarası girişleri – bir yer tutucu0olarak değerlendirilir, çünkü bu sürüm sayfa düzeni/işleme motorunu içermemektedir. - Hangi alanların değiştiğini tam olarak kaydetmek veya denetlemek istiyorsanız, büyük veya tanıdık olmayan bir belge üzerinde
Range.UpdateFields()‘i çalıştırmadan önceIFieldUpdatingCallback‘ı kaydedin. - Belgeyi denetimsiz bir işlem hattında güncellemeden önce
FieldOptions.UserPromptRespondent‘ı ayarlayın (veya bireysel istem-tabanlı alan sınıflarındaDefaultResponsedeğerlerini sağlayın), böyleceASK/FILLINalanları etkileşimli giriş bekleyerek takılmaz.
Yaygın Sorunlar
| Sorun | Neden | Düzeltme |
|---|---|---|
| Belgeyi düzenledikten sonra alan sonucu güncel değil | Aspose.Words FOSS, yükleme veya kaydetme sırasında alanları otomatik güncellemez | Range.UpdateFields() veya Field.Update()‘i açıkça çağırın |
PAGE, NUMPAGES veya TOC sayfa numaraları 0 gösteriyor | Sayfa düzeni/işleme bu sürümün bir parçası değildir | Beklenen davranış – ticari sürümü kullanın Aspose.Words için .NET hesaplanmış sayfa numaralarına ihtiyacınız varsa |
DATABASE alanı satır üretmiyor | Hiç IFieldDatabaseProvider FieldOptions.FieldDatabaseProvider‘ye atanmadı | IFieldDatabaseProvider‘ı uygulayın ve Range.UpdateFields()‘i çağırmadan önce atayın |
| Toplu alan güncellemesi takılmış gibi görünüyor | İstem temelli bir alan (ASK, FILLIN) için IFieldUserPromptRespondent atanmadı | FieldOptions.UserPromptRespondent‘ı atayın, ya da alan örneğinde DefaultResponse‘ı ayarlayın |
FAQ
Aspose.Words FOSS her Word alan türünü değerlendiriyor mu?
Field nesne modeli, her FieldType değerini temsil eder ve çoğunu günceller, ancak sonucu sayfa düzenine bağlı olan alanlar — örneğin PAGE ve NUMPAGES — bir 0 yer tutucusuna değerlendirilir çünkü bu sürüm düzenleme/renderleme motorunu içermez.
Bir belgeyi programlı olarak düzenledikten sonra alanları nasıl yeniden değerlendirebilirim?
Düzenlenen içeriği kapsayan aralıkta Range.UpdateFields() çağırın veya belgedeki tüm alanları güncellemek için Document.Range.UpdateFields() kullanın.
Bir alanı düz, sabit metne dönüştürebilir miyim?
Evet — Field.Unlink(), alanı son hesaplanmış sonucuyla sıradan metin olarak değiştirir ve temel alan kodunu kaldırır.
Bir alanı sonucuyla birlikte tamamen nasıl kaldırabilirim?
Field.Remove() çağırın. Bu, alanın kodu ve sonuç içeriğiyle birlikte FieldStart, Separator ve FieldEnd düğümlerini siler.
DATABASE alanına özel veri nasıl sağlayabilirim?
Uygulayın IFieldDatabaseProvider ve onu Document.FieldOptions.FieldDatabaseProvider‘e atayın. Sizin GetQueryResult() uygulamanız, FieldDatabaseDataRow örneklerinden oluşturulmuş bir FieldDatabaseDataTable döndürür.
API Reference Özeti
| Sınıf / Arayüz | Açıklama |
|---|---|
Field | Word alanı için temel sınıf; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Bir aralıktaki alanlar, Range.Fields aracılığıyla; Count, Remove(), Clear() |
FieldType | Bir Field örneğinin temsil ettiği Word alanını belirten Enum |
FieldOptions | Belge çapında alan güncelleme yapılandırması, Document.FieldOptions üzerinden |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated kancaları her alan güncellemesinin etrafında |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Toplu alan güncellemesi sırasında ilerleme raporlaması |
IFieldResultFormatter | Bir alanın hesaplanan sonucunun özel biçimlendirilmesi |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | DATABASE alanı için harici veri kaynağı |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Karşılaştırma tarzı alan ifadelerinin özel değerlendirilmesi |
IFieldUserPromptRespondent | Denetimsiz güncellemelerde istem-türetilen alanlar için yanıtları sağlar |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Alan güncellemeleri sırasında kültür seçimi |
UserInformation | Yazar/kullanıcı kimliği (Name, Initials, Address) kimlik alanları tarafından okunur |