Werken met velden

Overzicht

Een Word-veld – DATE, IF, DATABASE, REF, en tientallen anderen – wordt weergegeven in Aspose.Words FOSS voor .NET door de Field klasse en diens subklassen, allemaal in de Aspose.Words.Fields naamruimte. Deze pagina behandelt de kernveldengine: de Field objectmodel zelf, hoe velden worden verzameld en bijgewerkt, en de callback-interfaces die je in staat stellen aangepaste gegevens en gedrag toe te voegen tijdens een veldupdate. Specifieke veldfamilies – hyperlinks en kruisverwijzingen, datum/tijd-velden, mail-merge-velden, index- en inhoudsopgave-velden – hebben elk hun eigen toegewijde developer-guide-pagina.


Het Veldobjectmodel

Elk veld in een document is een Field instantie die bestaat uit drie markerknopen — FieldStart, Separator en FieldEnd — die worden blootgesteld als de Field.Start, Field.Separator en Field.End eigenschappen. Field.Type identificeert welk FieldType het veld vertegenwoordigt, Field.Result en Field.DisplayResult geven de laatst berekende waarde weer, en Field.Format bevat eventuele schakelaars (zoals numerieke of datum-tijd-opmaakstrings) die aan de veldcode zijn gekoppeld. Field.IsLocked en Field.IsDirty rapporteren de vergrendelde en verouderde status van het veld. Roep Field.GetFieldCode() aan om de ruwe veldcode-tekst te lezen, Field.Update() om het resultaat opnieuw te berekenen, Field.Unlink() om het veld te vervangen door statische tekst, en Field.Remove() om het volledig te verwijderen.


Toegang tot en bijwerken van velden in een document

Document.Range.Fields retourneert een FieldCollection — de velden die zich in dat bereik bevinden, met Count, Remove(), RemoveAt() en Clear() voor bulkverwijdering. Range.UpdateFields() berekent elk veld in het bereik opnieuw, Range.UnlinkFields() zet elk veld in het bereik om naar statische tekst, en Range.NormalizeFieldTypes() brengt de opgeslagen typecode van een veld in overeenstemming met de feitelijke veldcode na handmatige bewerkingen. DocumentBuilder.InsertField() voegt een nieuw veld in bij de cursor, met overloads die het resultaat van het nieuwe veld meteen bijwerken of het laten voor een latere Range.UpdateFields() pass.


Veldupdate-opties en Cultuur

Document.FieldOptions is een FieldOptions instantie die bepaalt hoe de velden van het hele document zich gedragen bij een update: CurrentUser levert de UserInformation die door identiteitsvelden wordt gebruikt, DefaultDocumentAuthor zaait auteurgerelateerde resultaten, LegacyNumberFormat en UseInvariantCultureNumberFormat regelen de getalopmaak, en PreProcessCulture en FieldUpdateCultureSource (gepaard met de IFieldUpdateCultureProvider callback) bepalen welke cultuur de datum- en getalopmaak tijdens een update beheerst. TemplateName, FileName en BuiltInTemplatesPaths leveren waarden die door sjabloon- en bestandsnaamsbewuste velden worden gelezen.


Volgen en aanpassen van veldupdates

Implementeer IFieldUpdatingCallback (FieldUpdating en FieldUpdated) op FieldOptions om code direct vóór en na elke herberekening van een veld uit te voeren — nuttig voor het auditen welke velden zijn gewijzigd in een batchtaak. Implementeer IFieldUpdatingProgressCallback (Notify) om de algehele voortgang van een groot document bij te houden; het ontvangt een FieldUpdatingProgressArgs met TotalFieldsCount, UpdatedFieldsCount en UpdateCompleted. Om te wijzigen hoe een numeriek of algemeen resultaat van een veld als tekst wordt weergegeven, implementeer IFieldResultFormatter (Format(value, format) en FormatNumeric(value, format)) en wijs het toe aan FieldOptions.ResultFormatter.


Externe gegevens aan velden leveren

Het DATABASE veld leest zijn rijen via IFieldDatabaseProvider.GetQueryResult(), die een FieldDatabaseDataTable (ColumnNames, Rows) teruggeeft die is opgebouwd uit FieldDatabaseDataRow (Values) instanties — wijs uw implementatie toe aan FieldOptions.FieldDatabaseProvider. Vergelijkingsvelden zoals IF evalueren hun voorwaarde via IComparisonExpressionEvaluator.Evaluate(), die een ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) ontvangt en een ComparisonEvaluationResult (Result, ErrorMessage) teruggeeft; wijs een aangepaste evaluator toe aan FieldOptions.ComparisonExpressionEvaluator om de standaard vergelijkingslogica te overschrijven. Velden die normaal gesproken de gebruiker om invoer vragen tijdens een update — zoals ASK en FILLIN — roepen IFieldUserPromptRespondent.Respond() aan wanneer er één is toegewezen aan FieldOptions.UserPromptRespondent, zodat een onbewaakte update niet blokkeert terwijl er wordt gewacht op interactieve invoer.


Gebruiker- en documentidentiteit voor velden

UserInformation (Name, Initials, Address en de statische UserInformation.DefaultUser) levert de identiteit waar auteur- en gebruikersnaamgerelateerde velden van lezen. Wijs een instantie toe aan Document.FieldOptions.CurrentUser voordat u velden bijwerkt die afhankelijk zijn van de documentauteur of gebruikersidentiteit.


Tips en best practices

  • Aspose.Words FOSS berekent velden niet automatisch opnieuw bij laden of opslaan zoals Word dat doet – roep Range.UpdateFields() (of Field.Update() voor een enkel veld) expliciet aan na elke programmatische wijziging die in veldresultaten moet worden weerspiegeld.
  • FieldStart, Separator en FieldEnd zijn echte knooppunten in de documentboom; verwijder een veld via Field.Remove() of Field.Unlink() in plaats van de marker-knooppunten rechtstreeks te verwijderen, anders kan de veldstructuur inconsistent worden.
  • Velden waarvan het resultaat afhankelijk is van de paginalay-out – PAGE, NUMPAGES en TOC-paginanummervermeldingen – evalueren tot een placeholder 0, omdat deze editie de paginalay-out/rendering-engine niet bevat.
  • Registreer IFieldUpdatingCallback voordat je Range.UpdateFields() uitvoert op een groot of onbekend document als je precies wilt loggen of auditen welke velden zijn gewijzigd.
  • Stel FieldOptions.UserPromptRespondent in (of lever DefaultResponse waarden bij de individuele prompt-gedreven veldklassen) vóór het bijwerken van een document in een onbeheerde pijplijn, zodat ASK/FILLIN velden niet vastlopen terwijl ze wachten op interactieve invoer.

Veelvoorkomende problemen

IssueOorzaakOplossing
Veldresultaat is verouderd na het bewerken van het documentAspose.Words FOSS werkt velden niet automatisch bij laden of opslaanRoep Range.UpdateFields() of Field.Update() expliciet aan
PAGE, NUMPAGES of TOC-paginanummers tonen 0Pagina-indeling/weergave maakt geen deel uit van deze editieVerwacht gedrag – gebruik de commerciële Aspose.Words voor .NET als je berekende paginanummers nodig hebt
DATABASE veld levert geen rijen opGeen IFieldDatabaseProvider is toegewezen aan FieldOptions.FieldDatabaseProviderImplementeer IFieldDatabaseProvider en wijs het toe voordat je Range.UpdateFields() aanroept
Batch-veldupdate lijkt te blijven hangenEen prompt-gestuurd veld (ASK, FILLIN) heeft geen IFieldUserPromptRespondent toegewezenWijs FieldOptions.UserPromptRespondent toe, of stel DefaultResponse in op de veldinstantie

FAQ

Evalueert Aspose.Words FOSS elk Word-veldtype?

Het Field objectmodel vertegenwoordigt elke FieldType waarde en werkt de meeste bij, maar velden waarvan het resultaat afhankelijk is van paginalay-out – zoals PAGE en NUMPAGES – evalueren tot een placeholder 0 omdat deze editie de layout/rendering engine niet bevat.

Hoe evalueer ik velden opnieuw nadat ik een document programmatisch heb bewerkt?

Roep Range.UpdateFields() aan op het bereik dat de bewerkte inhoud omvat, of Document.Range.UpdateFields() om elk veld in het document bij te werken.

Kan ik een veld omzetten naar platte, statische tekst?

Ja – Field.Unlink() vervangt het veld door zijn laatst berekende resultaat als gewone tekst, waarbij de onderliggende veldcode wordt verwijderd.

Hoe verwijder ik een veld volledig, inclusief het resultaat?

Roep Field.Remove() aan. Het verwijdert de FieldStart, Separator en FieldEnd knooppunten samen met de veldcode en de resultaatinhoud.

Hoe lever ik aangepaste gegevens aan het DATABASE veld?

Implementeer IFieldDatabaseProvider en wijs het toe aan Document.FieldOptions.FieldDatabaseProvider. Je GetQueryResult() implementatie retourneert een FieldDatabaseDataTable gebouwd uit FieldDatabaseDataRow instanties.


API Reference Samenvatting

Klasse / InterfaceBeschrijving
FieldBasisclasse voor een Word-veld; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionDe velden in een bereik, via Range.Fields; Count, Remove(), Clear()
FieldTypeEnum die identificeert welk Word-veld een Field-instantie vertegenwoordigt
FieldOptionsDocumentbrede veldupdateconfiguratie, via Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hooks rond elke veldupdate
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsVoortgangsrapportage bij een bulk veldupdate
IFieldResultFormatterAangepaste opmaak van het berekende resultaat van een veld
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowExterne gegevensbron voor het DATABASE veld
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultAangepaste evaluatie van vergelijkingsstijl-veldexpressies
IFieldUserPromptRespondentLevert antwoorden voor prompt-gestuurde velden bij ongecontroleerde updates
IFieldUpdateCultureProvider / FieldUpdateCultureSourceCultuurselectie tijdens veldupdates
UserInformationAuteur-/gebruikeridentiteit (Name, Initials, Address) gelezen door identiteitsvelden

Zie ook

 Nederlands