Hoe te werken met velden in .NET
Deze gids laat zien hoe u met Word-velden werkt — DATE, IF, REF, DATABASE en tientallen anderen — in Aspose.Words FOSS voor .NET: een veld invoegen en het resultaat lezen, velden bijwerken na een programmatische wijziging, update-gedrag configureren, updates volgen met een callback, en een veld converteren of verwijderen. Aspose.Words FOSS voor .NET is beschikbaar via NuGet of door te bouwen vanaf de bron.
Stapsgewijze gids
Stap 1: Verkrijg de bibliotheek
Kloon de repository en bouw Aspose.Words.sln in Release-configuratie, voeg vervolgens een projectreferentie toe aan Aspose.Words.csproj vanuit je eigen .NET project, zoals beschreven in de Installatiehandleiding. Voeg using Aspose.Words; and using Aspose.Words.Fields; bovenaan elk bestand dat met velden werkt.
Stap 2: Een veld invoegen en het resultaat lezen
DocumentBuilder.InsertField() voegt een nieuw veld in op de cursor, met overloads die het resultaat van het veld meteen bijwerken of het achterhouden voor een latere update-ronde. Elk veld is een Field-instantie bestaande uit drie markerknopen — FieldStart, Separator en FieldEnd, blootgesteld als Field.Start / Field.Separator / Field.End. Field.Type identificeert welke FieldType het vertegenwoordigt, Field.Result en Field.DisplayResult bevatten de laatst berekende waarde, Field.Format bevat eventuele formaat-schakelaars die aan de code zijn gekoppeld, en Field.GetFieldCode() retourneert de ruwe veldcode-tekst.
Stap 3: Velden bijwerken na een programmatische bewerking
Aspose.Words FOSS berekent velden niet opnieuw wanneer het document wordt geladen of opgeslagen. Na een bewerking die het resultaat van een veld zou moeten wijzigen, roep Range.UpdateFields() aan om elk veld in dat bereik opnieuw te berekenen — gebruik Document.Range.UpdateFields() voor het hele document — of Field.Update() voor een enkel veld. Range.UnlinkFields() converteert elk veld in het bereik naar statische tekst in één oproep, en Range.NormalizeFieldTypes() verzoent de opgeslagen typecode van een veld met de feitelijke veldcode na een handmatige bewerking.
Stap 4: Het gedrag van veldupdates configureren met FieldOptions
Document.FieldOptions (een FieldOptions instantie) bepaalt hoe de velden van het hele document zich gedragen tijdens een update: CurrentUser (een UserInformation instantie — Name, Initials, Address) levert de identiteit waaruit auteur- en gebruikersnaambestemde velden lezen, DefaultDocumentAuthor voedt auteurgerelateerde resultaten, en LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource regelen de opmaak van nummers en datums. Voor onbeheerde pipelines, wijs FieldOptions.UserPromptRespondent (een IFieldUserPromptRespondent) toe zodat prompt-gedreven velden zoals ASK en FILLIN niet blokkeren door te wachten op interactieve invoer, en wijs een aangepaste IFieldDatabaseProvider toe aan FieldOptions.FieldDatabaseProvider om de rijen van het DATABASE veld uit uw eigen gegevensbron te leveren in plaats van via een echte databaseverbinding.
Stap 5: Veldupdates bijhouden met een callback
Implementeer IFieldUpdatingCallback (FieldUpdating en FieldUpdated) en wijs deze toe aan FieldOptions om code direct vóór en na elke veldherberekening uit te voeren — nuttig voor het auditen van precies welke velden zijn veranderd in een batchtaak. Voor voortgangsrapportage over een groot document, implementeer IFieldUpdatingProgressCallback (Notify), die een FieldUpdatingProgressArgs ontvangt die TotalFieldsCount, UpdatedFieldsCount en UpdateCompleted blootlegt.
Stap 6: Een veld converteren of verwijderen
Field.Unlink() vervangt het veld door zijn laatst berekende resultaat als gewone statische tekst, waarbij de onderliggende veldcode wordt weggegooid — gebruik het wanneer u de waarde permanent in het document wilt opnemen. Field.Remove() verwijdert de FieldStart, Separator en FieldEnd knooppunten samen met de veldcode en het resultaat, waardoor het veld volledig wordt verwijderd. Geef de voorkeur aan deze twee methoden boven het direct verwijderen van de markerknooppunten, omdat het handmatig verwijderen van slechts een deel van de veldstructuur de documentboom inconsistent kan maken.
Veelvoorkomende problemen en oplossingen
Het weergegeven resultaat van een veld is verouderd na het bewerken van het document. Aspose.Words FOSS werkt velden niet automatisch bij laden of opslaan. Roep Range.UpdateFields() or Field.Update() expliciet na de bewerking.
PAGE, NUMPAGES, of een inhoudsopgave-paginanummer wordt altijd weergegeven 0. Pagina-indeling/rendering maakt geen deel uit van deze editie, dus velden waarvan het resultaat afhankelijk is van paginering evalueren tot een placeholder 0. Dit is verwacht gedrag in deze editie.
Een batch-veldupdate lijkt te hangen. Een prompt-gedreven veld (ASK, FILLIN) heeft geen IFieldUserPromptRespondent toegewezen. Wijs toe FieldOptions.UserPromptRespondent, of stel DefaultResponse op de individuele veldinstantie.
De DATABASE veld levert geen rijen op. Geen IFieldDatabaseProvider is toegewezen aan FieldOptions.FieldDatabaseProvider. Implementeer de interface en wijs deze toe voordat je aanroept Range.UpdateFields().
Veelgestelde vragen
Evalueert Aspose.Words FOSS elk type Word-veld?
Het Field objectmodel vertegenwoordigt elke FieldType waarde en werkt de meeste bij, maar velden waarvan het resultaat afhankelijk is van de paginalay-out — zoals PAGE en NUMPAGES — evalueren tot een placeholder 0 omdat deze editie de lay-out/rendering engine niet bevat.
Hoe evalueer ik velden opnieuw na een programmatische bewerking?
Roep Range.UpdateFields() aan op het bereik dat de bewerkte inhoud omvat, of Document.Range.UpdateFields() voor het hele document.
Kan ik een veld omzetten naar platte, statische tekst?
Ja — Field.Unlink() vervangt het veld door zijn laatst berekende resultaat als gewone tekst.
Hoe verwijder ik een veld volledig, inclusief het resultaat?
Roep Field.Remove() aan. Het verwijdert de FieldStart, Separator en FieldEnd knooppunten samen met de code en resultaatinhoud van het veld.
Hoe lever ik aangepaste gegevens aan het DATABASE veld?
Implementeer IFieldDatabaseProvider en wijs het toe aan Document.FieldOptions.FieldDatabaseProvider. De GetQueryResult() implementatie retourneert een FieldDatabaseDataTable die is opgebouwd uit FieldDatabaseDataRow instanties.
