Arbeiten mit Feldern

Übersicht

Ein Word-Feld – DATE, IF, DATABASE, REF, und dutzende andere – wird dargestellt in Aspose.Words FOSS für .NET von dem Field Klasse und ihren Unterklassen, alle im Aspose.Words.Fields Namensraum. Diese Seite behandelt die Kern-Feld-Engine: die Field Objektmodell selbst, wie Felder gesammelt und aktualisiert werden, und die Callback-Schnittstellen, die es Ihnen ermöglichen, benutzerdefinierte Daten und Verhalten während einer Feldaktualisierung einzuklinken. Spezifische Feldfamilien – Hyperlinks und Querverweise, Datums-/Uhrzeit-Felder, Seriendruck-Felder, Index- und Inhaltsverzeichnis-Felder – haben jeweils ihre eigene dedizierte Developer-Guide-Seite.


Das Feld-Objektmodell

Jedes Feld in einem Dokument ist eine Field-Instanz, die aus drei Markierungs-Knoten besteht – FieldStart, Separator und FieldEnd – die als die Eigenschaften Field.Start, Field.Separator und Field.End bereitgestellt werden. Field.Type identifiziert, welchen FieldType das Feld darstellt, Field.Result und Field.DisplayResult geben den zuletzt berechneten Wert zurück, und Field.Format enthält alle Schalter (wie numerische oder Datums-/Uhrzeit-Formatzeichenfolgen), die dem Feldcode zugeordnet sind. Field.IsLocked und Field.IsDirty melden den gesperrten bzw. veralteten Zustand des Feldes. Rufen Sie Field.GetFieldCode() auf, um den rohen Feldcode-Text zu lesen, Field.Update(), um das Ergebnis neu zu berechnen, Field.Unlink(), um das Feld durch statischen Text zu ersetzen, und Field.Remove(), um es vollständig zu löschen.


Zugriff auf und Aktualisieren von Feldern in einem Dokument

Document.Range.Fields gibt ein FieldCollection zurück – die Felder, die in diesem Bereich enthalten sind, mit Count, Remove(), RemoveAt() und Clear() für die Massenentfernung. Range.UpdateFields() berechnet jedes Feld im Bereich neu, Range.UnlinkFields() wandelt jedes Feld im Bereich in statischen Text um, und Range.NormalizeFieldTypes() gleicht den gespeicherten Typcode eines Feldes mit seinem tatsächlichen Feldcode nach manuellen Änderungen ab. DocumentBuilder.InsertField() fügt ein neues Feld an der Cursorposition ein, mit Überladungen, die entweder das Ergebnis des neuen Feldes sofort aktualisieren oder es für einen späteren Range.UpdateFields()-Durchlauf belassen.


Optionen für Feldaktualisierungen und Kultur

Document.FieldOptions ist eine FieldOptions-Instanz, die bestimmt, wie sich die Felder des gesamten Dokuments beim Aktualisieren verhalten: CurrentUser liefert das UserInformation, das von Identitätsfeldern verwendet wird, DefaultDocumentAuthor erzeugt autorbezogene Ergebnisse, LegacyNumberFormat und UseInvariantCultureNumberFormat steuern die Zahlenformatierung, und PreProcessCulture und FieldUpdateCultureSource (in Kombination mit dem IFieldUpdateCultureProvider-Callback) bestimmen, welche Kultur die Datums- und Zahlenformatierung während eines Updates regelt. TemplateName, FileName und BuiltInTemplatesPaths stellen Werte bereit, die von vorlagen- und dateinamenbewussten Feldern zurückgelesen werden.


Verfolgung und Anpassung von Feldaktualisierungen

Implementieren Sie IFieldUpdatingCallback (FieldUpdating und FieldUpdated) auf FieldOptions, um Code sofort vor und nach jeder Neuberechnung eines Feldes auszuführen – nützlich, um zu prüfen, welche Felder in einem Batch-Job geändert wurden. Implementieren Sie IFieldUpdatingProgressCallback (Notify), um den Gesamtfortschritt über ein großes Dokument hinweg zu verfolgen; es erhält ein FieldUpdatingProgressArgs mit TotalFieldsCount, UpdatedFieldsCount und UpdateCompleted. Um zu ändern, wie das numerische oder allgemeine Ergebnis eines Feldes als Text dargestellt wird, implementieren Sie IFieldResultFormatter (Format(value, format) und FormatNumeric(value, format)) und weisen es FieldOptions.ResultFormatter zu.


Bereitstellung externer Daten für Felder

Das DATABASE-Feld liest seine Zeilen über IFieldDatabaseProvider.GetQueryResult(), das ein FieldDatabaseDataTable (ColumnNames, Rows) zurückgibt, das aus FieldDatabaseDataRow (Values)-Instanzen aufgebaut ist – weisen Sie Ihre Implementierung FieldOptions.FieldDatabaseProvider zu. Vergleichsfelder wie IF bewerten ihre Bedingung über IComparisonExpressionEvaluator.Evaluate(), das ein ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) erhält und ein ComparisonEvaluationResult (Result, ErrorMessage) zurückgibt; weisen Sie einen benutzerdefinierten Evaluator FieldOptions.ComparisonExpressionEvaluator zu, um die Standardvergleichslogik zu überschreiben. Felder, die normalerweise den Benutzer während eines Updates zur Eingabe auffordern – wie ASK und FILLIN – rufen IFieldUserPromptRespondent.Respond() auf, wenn eines FieldOptions.UserPromptRespondent zugewiesen ist, sodass ein unbeaufsichtigtes Update nicht auf interaktive Eingaben wartet.


Benutzer- und Dokumentidentität für Felder

UserInformation (Name, Initials, Address und das statische UserInformation.DefaultUser) liefert die Identität, aus der autor- und benutzernamenbezogene Felder lesen. Weisen Sie vor dem Aktualisieren von Feldern, die vom Dokumentautor oder der Benutzeridentität abhängen, eine Instanz Document.FieldOptions.CurrentUser zu.


Tipps und bewährte Verfahren

  • Aspose.Words FOSS berechnet Felder nicht automatisch beim Laden oder Speichern, wie Word es tut – rufen Sie Range.UpdateFields() (oder Field.Update() für ein einzelnes Feld) explizit nach jeder programmgesteuerten Änderung auf, die in den Feldresultaten sichtbar sein soll.
  • FieldStart, Separator und FieldEnd sind echte Knoten im Dokumentbaum; entfernen Sie ein Feld über Field.Remove() oder Field.Unlink() anstatt die Markerknoten direkt zu löschen, da sonst die Feldstruktur inkonsistent werden kann.
  • Felder, deren Ergebnis vom Seitenlayout abhängt – PAGE, NUMPAGES und TOC-Seitenzahlen-Einträge – werden zu einem Platzhalter 0 ausgewertet, weil diese Ausgabe keine Seitenlayout-/Rendering-Engine enthält.
  • Registrieren Sie IFieldUpdatingCallback, bevor Sie Range.UpdateFields() über ein großes oder unbekanntes Dokument ausführen, falls Sie genau protokollieren oder prüfen müssen, welche Felder geändert wurden.
  • Setzen Sie FieldOptions.UserPromptRespondent (oder geben Sie DefaultResponse-Werte für die einzelnen promptgesteuerten Feldklassen an), bevor Sie ein Dokument in einer unbeaufsichtigten Pipeline aktualisieren, damit ASK/FILLIN-Felder nicht auf interaktive Eingaben warten.

Häufige Probleme

ProblemUrsacheBehebung
Das Feldergebnis ist nach dem Bearbeiten des Dokuments veraltetAspose.Words FOSS aktualisiert Felder beim Laden oder Speichern nicht automatischRufen Sie Range.UpdateFields() oder Field.Update() explizit auf
PAGE, NUMPAGES oder Inhaltsverzeichnis-Seitenzahlen zeigen 0Seitenlayout/-rendering ist nicht Teil dieser AusgabeErwartetes Verhalten – verwenden Sie die kommerzielle Aspose.Words für .NET wenn Sie berechnete Seitenzahlen benötigen
DATABASE Feld liefert keine ZeilenKein IFieldDatabaseProvider ist FieldOptions.FieldDatabaseProvider zugewiesenImplementieren Sie IFieldDatabaseProvider und weisen Sie es zu, bevor Sie Range.UpdateFields() aufrufen
Batch-Feldaktualisierung scheint zu hängenEin promptgesteuertes Feld (ASK, FILLIN) hat keinen IFieldUserPromptRespondent zugewiesenWeisen Sie FieldOptions.UserPromptRespondent zu oder setzen Sie DefaultResponse auf die Feldinstanz

FAQ

Bewertet Aspose.Words FOSS jeden Word-Feldtyp?

Das Field Objektmodell repräsentiert jeden FieldType Wert und aktualisiert die meisten davon, aber Felder, deren Ergebnis vom Seitenlayout abhängt – wie PAGE und NUMPAGES – werden zu einem Platzhalter 0 ausgewertet, weil diese Ausgabe nicht die Layout-/Rendering-Engine enthält.

Wie kann ich Felder nach dem programmgesteuerten Bearbeiten eines Dokuments neu auswerten?

Rufen Sie Range.UpdateFields() für den Bereich auf, der den bearbeiteten Inhalt umfasst, oder Document.Range.UpdateFields(), um jedes Feld im Dokument zu aktualisieren.

Kann ich ein Feld in einfachen, statischen Text umwandeln?

Ja – Field.Unlink() ersetzt das Feld durch sein zuletzt berechnetes Ergebnis als normalen Text und entfernt den zugrunde liegenden Feldcode.

Wie entferne ich ein Feld vollständig, einschließlich seines Ergebnisses?

Rufen Sie Field.Remove() auf. Es löscht die FieldStart, Separator und FieldEnd Knoten zusammen mit dem Feldcode und dem Ergebnisinhalt.

Wie kann ich dem DATABASE-Feld benutzerdefinierte Daten bereitstellen?

Implementieren Sie IFieldDatabaseProvider und weisen Sie es Document.FieldOptions.FieldDatabaseProvider zu. Ihre GetQueryResult()-Implementierung gibt ein FieldDatabaseDataTable zurück, das aus FieldDatabaseDataRow-Instanzen gebaut ist.


API Reference Zusammenfassung

Klasse / SchnittstelleBeschreibung
FieldBasisklasse für ein Word-Feld; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionDie Felder in einem Bereich, über Range.Fields; Count, Remove(), Clear()
FieldTypeEnum, das identifiziert, welches Word-Feld eine Field-Instanz darstellt
FieldOptionsDokumentweite Feldaktualisierungskonfiguration, über Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated Hooks um jede Feldaktualisierung
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsFortschrittsberichterstattung bei einer Massenfeldaktualisierung
IFieldResultFormatterBenutzerdefinierte Formatierung des berechneten Ergebnisses eines Feldes
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowExterne Datenquelle für das Feld DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultBenutzerdefinierte Auswertung von vergleichsartigen Feldausdrücken
IFieldUserPromptRespondentStellt Antworten für promptgesteuerte Felder bei unbeaufsichtigten Updates bereit
IFieldUpdateCultureProvider / FieldUpdateCultureSourceKulturauswahl während Feldaktualisierungen
UserInformationAutor/Benutzer-Identität (Name, Initials, Address) wird von Identitätsfeldern gelesen

Siehe auch

 Deutsch