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()(ellerField.Update()för ett enskilt fält) explicit efter varje programmatisk redigering som ska återspeglas i fältresultaten. FieldStart,SeparatorochFieldEndär riktiga noder i dokumentträdet; ta bort ett fält viaField.Remove()ellerField.Unlink()istället för att radera markeringsnoderna direkt, annars kan fältstrukturen bli inkonsekvent.- Fält vars resultat beror på sidlayout –
PAGE,NUMPAGESoch TOC-sidnummerposter – utvärderas till en platshållare0, eftersom denna utgåva inte inkluderar sidlayout/renderingsmotorn. - Registrera
IFieldUpdatingCallbackinnan du körRange.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 angeDefaultResponse-värden på de enskilda prompt-styrda fältklasserna) innan du uppdaterar ett dokument i en obevakad pipeline, så attASK/FILLIN-fälten inte fastnar och väntar på interaktiv inmatning.
Vanliga problem
| Problem | Orsak | Åtgärd |
|---|---|---|
| Fältresultatet är föråldrat efter att ha redigerat dokumentet | Aspose.Words FOSS uppdaterar inte automatiskt fält vid inläsning eller sparning | Anropa Range.UpdateFields() eller Field.Update() explicit |
PAGE, NUMPAGES, eller TOC-sidnummer visar 0 | Sidlayout/återgivning är inte en del av denna utgåva | Förväntat beteende – använd den kommersiella Aspose.Words för .NET om du behöver beräknade sidnummer |
DATABASE fältet producerar inga rader | Ingen IFieldDatabaseProvider är tilldelad FieldOptions.FieldDatabaseProvider | Implementera IFieldDatabaseProvider och tilldela den innan du anropar Range.UpdateFields() |
| Batch-fältuppdatering verkar hänga | Ett promptdrivet fält (ASK, FILLIN) har ingen IFieldUserPromptRespondent tilldelad | Tilldela 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änssnitt | Beskrivning |
|---|---|
Field | Bas-klass för ett Word-fält; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Fälten i ett intervall, via Range.Fields; Count, Remove(), Clear() |
FieldType | Enum som identifierar vilket Word-fält en Field-instans representerar |
FieldOptions | Dokumentomfattande fältuppdateringskonfiguration, via Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hookar runt varje fältuppdatering |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Progressrapportering för en bulk fältuppdatering |
IFieldResultFormatter | Anpassad formatering av ett fälts beräknade resultat |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Extern datakälla för fältet DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Anpassad utvärdering av jämförelsestil fältuttryck |
IFieldUserPromptRespondent | Tillhandahåller svar för promptstyrda fält i oövervakade uppdateringar |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Kulturval vid fältuppdateringar |
UserInformation | Författar-/användaridentitet (Name, Initials, Address) läses av identitetsfält |