Arbeta med fält

Översikt

Ett Word-fält – DATE, IF, DATABASE, REF, och dussintals andra – representeras i Aspose.Words FOSS för .NET av Field klassen och dess underklasser, alla i Aspose.Words.Fields namnutrymmet. Den här sidan täcker kärnfältmotorn: den Field objektmodellen själv, hur fält samlas in och uppdateras, och de återuppringningsgränssnitt som låter dig ansluta anpassad data och beteende under en fältuppdatering. Specifika fältfamiljer – hyperlänkar och korsreferenser, datum/tidsfält, mail-merge-fält, index- och innehållsförteckningsfält – har var sin dedikerade utvecklarguide-sida.


Fältobjektmodellen

Varje fält i ett dokument är en Field-instans bestående av tre markörnoder – FieldStart, Separator och FieldEnd – som exponeras som egenskaperna Field.Start, Field.Separator och Field.End. Field.Type identifierar vilken FieldType fältet representerar, Field.Result och Field.DisplayResult visar det senast beräknade värdet, och Field.Format innehåller eventuella växlar (såsom numeriska eller datum-/tid-formatsträngar) som är kopplade till fältkoden. Field.IsLocked och Field.IsDirty rapporterar fältets låsta och föråldrade tillstånd. Anropa Field.GetFieldCode() för att läsa den råa fältkodstexten, Field.Update() för att beräkna resultatet på nytt, Field.Unlink() för att ersätta fältet med statisk text, och Field.Remove() för att ta bort det helt.


Att komma åt och uppdatera fält i ett dokument

Document.Range.Fields returnerar en FieldCollection – fälten som finns i det intervallet, med Count, Remove(), RemoveAt() och Clear() för massborttagning. Range.UpdateFields() beräknar om varje fält i intervallet, Range.UnlinkFields() konverterar varje fält i intervallet till statisk text, och Range.NormalizeFieldTypes() jämför ett fälts lagrade typkod mot dess faktiska fältkod efter manuella redigeringar. DocumentBuilder.InsertField() infogar ett nytt fält vid markören, med överlagringar som antingen uppdaterar det nya fältets resultat omedelbart eller lämnar det för ett senare Range.UpdateFields()-pass.


Alternativ för fältuppdatering och kultur

Document.FieldOptions är en FieldOptions instans som styr hur hela dokumentets fält beter sig när de uppdateras: CurrentUser tillhandahåller UserInformation som används av identitetsfält, DefaultDocumentAuthor sår resultat relaterade till författare, LegacyNumberFormat och UseInvariantCultureNumberFormat styr nummerformatering, och PreProcessCulture och FieldUpdateCultureSource (i par med IFieldUpdateCultureProvider callback) bestämmer vilken kultur som styr datum- och nummerformatering under en uppdatering. TemplateName, FileName och BuiltInTemplatesPaths levererar värden som mall- och filnamnsmedvetna fält läser tillbaka.


Spårning och anpassning av fältuppdateringar

Implementera IFieldUpdatingCallback (FieldUpdating och FieldUpdated) på FieldOptions för att köra kod omedelbart före och efter varje fält beräknas om – användbart för att auditera vilka fält som ändrades i ett batchjobb. Implementera IFieldUpdatingProgressCallback (Notify) för att spåra övergripande framsteg i ett stort dokument; den tar emot en FieldUpdatingProgressArgs med TotalFieldsCount, UpdatedFieldsCount och UpdateCompleted. För att ändra hur ett fälts numeriska eller allmänna resultat renderas som text, implementera IFieldResultFormatter (Format(value, format) och FormatNumeric(value, format)) och tilldela den till FieldOptions.ResultFormatter.


Tillhandahålla extern data till fält

Fältet DATABASE läser sina rader via IFieldDatabaseProvider.GetQueryResult(), som returnerar en FieldDatabaseDataTable (ColumnNames, Rows) byggd från FieldDatabaseDataRow (Values)-instanser – tilldela din implementation till FieldOptions.FieldDatabaseProvider. Jämförelsfält såsom IF utvärderar sitt villkor via IComparisonExpressionEvaluator.Evaluate(), som tar emot en ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) och returnerar en ComparisonEvaluationResult (Result, ErrorMessage); tilldela en anpassad evaluator till FieldOptions.ComparisonExpressionEvaluator för att åsidosätta standardjämförelselogiken. Fält som normalt ber användaren om input under en uppdatering – såsom ASK och FILLIN – anropar IFieldUserPromptRespondent.Respond() när ett är tilldelat till FieldOptions.UserPromptRespondent, så att en oövervakad uppdatering inte blockerar och väntar på interaktiv input.


Användar- och dokumentidentitet för fält

UserInformation (Name, Initials, Address och den statiska UserInformation.DefaultUser) tillhandahåller den identitet som författar- och användarnamnrelaterade fält läser från. Tilldela en instans till Document.FieldOptions.CurrentUser innan du uppdaterar fält som beror på dokumentförfattare eller användaridentitet.


Tips och bästa praxis

  • Aspose.Words FOSS beräknar inte om fält automatiskt vid laddning eller sparande på det sätt som Word gör – anropa Range.UpdateFields() (eller Field.Update() för ett enskilt fält) explicit efter varje programmatisk redigering som ska återspeglas i fältresultaten.
  • FieldStart, Separator och FieldEnd är riktiga noder i dokumentträdet; ta bort ett fält via Field.Remove() eller Field.Unlink() istället för att radera markeringsnoderna direkt, annars kan fältstrukturen bli inkonsekvent.
  • Fält vars resultat beror på sidlayout – PAGE, NUMPAGES och TOC-sidnummerposter – utvärderas till en platshållare 0, eftersom denna utgåva inte inkluderar sidlayout/renderingsmotorn.
  • Registrera IFieldUpdatingCallback innan du kör Range.UpdateFields() på ett stort eller obekant dokument om du behöver logga eller granska exakt vilka fält som har ändrats.
  • Ställ in FieldOptions.UserPromptRespondent (eller ange DefaultResponse-värden på de enskilda prompt-styrda fältklasserna) innan du uppdaterar ett dokument i en obevakad pipeline, så att ASK/FILLIN-fälten inte fastnar och väntar på interaktiv inmatning.

Vanliga problem

ProblemOrsakÅtgärd
Fältresultatet är föråldrat efter att ha redigerat dokumentetAspose.Words FOSS uppdaterar inte automatiskt fält vid inläsning eller sparningAnropa Range.UpdateFields() eller Field.Update() explicit
PAGE, NUMPAGES, eller TOC-sidnummer visar 0Sidlayout/återgivning är inte en del av denna utgåvaFörväntat beteende – använd den kommersiella Aspose.Words för .NET om du behöver beräknade sidnummer
DATABASE fältet producerar inga raderIngen IFieldDatabaseProvider är tilldelad FieldOptions.FieldDatabaseProviderImplementera IFieldDatabaseProvider och tilldela den innan du anropar Range.UpdateFields()
Batch-fältuppdatering verkar hängaEtt promptdrivet fält (ASK, FILLIN) har ingen IFieldUserPromptRespondent tilldeladTilldela FieldOptions.UserPromptRespondent, eller ange DefaultResponse på fältinstansen

FAQ

Utvärderar Aspose.Words FOSS varje Word-fälttyp?

Objektmodellen Field representerar varje FieldType-värde och uppdaterar de flesta av dem, men fält vars resultat beror på sidlayout – såsom PAGE och NUMPAGES – utvärderas till en platshållare 0 eftersom den här utgåvan inte innehåller layout/renderingsmotorn.

Hur kan jag omvärdera fält efter att ha redigerat ett dokument programmässigt?

Anropa Range.UpdateFields() på det område som omfattar det redigerade innehållet, eller Document.Range.UpdateFields() för att uppdatera alla fält i dokumentet.

Kan jag konvertera ett fält till vanlig, statisk text?

Ja – Field.Unlink() ersätter fältet med dess senast beräknade resultat som vanlig text och tar bort den underliggande fältkoden.

Hur tar jag bort ett fält helt, inklusive dess resultat?

Anropa Field.Remove(). Det tar bort noderna FieldStart, Separator och FieldEnd tillsammans med fältets kod och resultatinnehåll.

Hur levererar jag anpassade data till DATABASE-fältet?

Implementera IFieldDatabaseProvider och tilldela den till Document.FieldOptions.FieldDatabaseProvider. Din GetQueryResult() implementation returnerar en FieldDatabaseDataTable byggd av FieldDatabaseDataRow instanser.


API Reference Sammanfattning

Klass / GränssnittBeskrivning
FieldBas-klass för ett Word-fält; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionFälten i ett intervall, via Range.Fields; Count, Remove(), Clear()
FieldTypeEnum som identifierar vilket Word-fält en Field-instans representerar
FieldOptionsDokumentomfattande fältuppdateringskonfiguration, via Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hookar runt varje fältuppdatering
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsProgressrapportering för en bulk fältuppdatering
IFieldResultFormatterAnpassad formatering av ett fälts beräknade resultat
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowExtern datakälla för fältet DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultAnpassad utvärdering av jämförelsestil fältuttryck
IFieldUserPromptRespondentTillhandahåller svar för promptstyrda fält i oövervakade uppdateringar
IFieldUpdateCultureProvider / FieldUpdateCultureSourceKulturval vid fältuppdateringar
UserInformationFörfattar-/användaridentitet (Name, Initials, Address) läses av identitetsfält

Se även

 Svenska