Lucrul cu câmpurile

Lucrul cu câmpuri

Un câmp Word – DATE, IF, DATABASE, REF, și zeci de altele – este reprezentat în Aspose.Words FOSS pentru .NET de către Field clasa și subclasele sale, toate în Aspose.Words.Fields spațiu de nume. Această pagină acoperă motorul de bază al câmpurilor: Field modelul de obiecte în sine, modul în care câmpurile sunt colectate și actualizate, și interfețele de apel invers care îți permit să integrezi date și comportamente personalizate în timpul actualizării unui câmp. Familiile specifice de câmpuri – hyperlinkuri și referințe încrucișate, câmpuri de dată/oră, câmpuri de îmbinare a corespondenței, câmpuri de index și de cuprins – fiecare are propria pagină dedicată ghidului pentru dezvoltatori.


Modelul de obiecte al câmpului

Fiecare câmp dintr-un document este o instanță Field formată din trei noduri de marcaj – FieldStart, Separator și FieldEnd – expuse ca proprietățile Field.Start, Field.Separator și Field.End. Field.Type identifică care FieldType reprezintă câmpul, Field.Result și Field.DisplayResult expun valoarea calculată ultima dată, iar Field.Format conține orice comutatoare (cum ar fi șiruri de format numeric sau de dată-oră) atașate codului câmpului. Field.IsLocked și Field.IsDirty raportează starea blocată și expirată a câmpului. Apelează Field.GetFieldCode() pentru a citi textul brut al codului câmpului, Field.Update() pentru a recalcula rezultatul, Field.Unlink() pentru a înlocui câmpul cu text static și Field.Remove() pentru a-l șterge complet.


Accesarea și actualizarea câmpurilor într-un document

Document.Range.Fields returnează un FieldCollection – câmpurile conținute în acel interval, cu Count, Remove(), RemoveAt() și Clear() pentru eliminare în bloc. Range.UpdateFields() recalculează fiecare câmp din interval, Range.UnlinkFields() convertește fiecare câmp din interval în text static și Range.NormalizeFieldTypes() reconciliază codul de tip stocat al unui câmp cu codul său real după editări manuale. DocumentBuilder.InsertField() inserează un câmp nou la cursor, cu suprasarcini care fie actualizează imediat rezultatul noului câmp, fie îl lasă pentru o trecere ulterioară de Range.UpdateFields().


Opțiuni de actualizare a câmpului și cultură

Document.FieldOptions este o instanță FieldOptions care guvernează modul în care câmpurile întregului document se comportă la actualizare: CurrentUser furnizează UserInformation utilizat de câmpurile de identitate, DefaultDocumentAuthor generează rezultate legate de autor, LegacyNumberFormat și UseInvariantCultureNumberFormat controlează formatarea numerelor, și PreProcessCulture și FieldUpdateCultureSource (împreună cu apelul invers IFieldUpdateCultureProvider) determină ce cultură guvernează formatarea datei și a numerelor în timpul unei actualizări. TemplateName, FileName și BuiltInTemplatesPaths furnizează valori pe care câmpurile conștiente de șablon și de numele fișierului le citesc înapoi.


Urmărirea și personalizarea actualizărilor de câmpuri

Implementați IFieldUpdatingCallback (FieldUpdating și FieldUpdated) pe FieldOptions pentru a rula cod imediat înainte și după fiecare recalculare a unui câmp — util pentru auditarea câmpurilor modificate într-un job de lot. Implementați IFieldUpdatingProgressCallback (Notify) pentru a urmări progresul general într-un document mare; primește un FieldUpdatingProgressArgs cu TotalFieldsCount, UpdatedFieldsCount și UpdateCompleted. Pentru a modifica modul în care rezultatul numeric sau general al unui câmp este redat ca text, implementați IFieldResultFormatter (Format(value, format) și FormatNumeric(value, format)) și atribuiți-l lui FieldOptions.ResultFormatter.


Furnizarea de date externe către câmpuri

Câmpul DATABASE își citește rândurile prin IFieldDatabaseProvider.GetQueryResult(), care returnează un FieldDatabaseDataTable (ColumnNames, Rows) construit din instanțe FieldDatabaseDataRow (Values) — atribuiți implementarea dumneavoastră lui FieldOptions.FieldDatabaseProvider. Câmpurile de comparare, cum ar fi IF, evaluează condiția prin IComparisonExpressionEvaluator.Evaluate(), care primește un ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) și returnează un ComparisonEvaluationResult (Result, ErrorMessage); atribuiți un evaluator personalizat lui FieldOptions.ComparisonExpressionEvaluator pentru a suprascrie logica de comparare implicită. Câmpurile care în mod normal solicită utilizatorului intrare în timpul unei actualizări — cum ar fi ASK și FILLIN — apelează IFieldUserPromptRespondent.Respond() când unul este atribuit lui FieldOptions.UserPromptRespondent, astfel încât o actualizare nesupravegheată să nu blocheze așteptând intrare interactivă.


Identitatea utilizatorului și a documentului pentru câmpuri

UserInformation (Name, Initials, Address și UserInformation.DefaultUser static) furnizează identitatea din care citează câmpurile legate de autor și de numele utilizatorului. Atribuiți o instanță lui Document.FieldOptions.CurrentUser înainte de a actualiza câmpurile care depind de autorul documentului sau de identitatea utilizatorului.


Sfaturi și bune practici

  • Aspose.Words FOSS nu recalculează câmpurile automat la încărcare sau salvare așa cum face Word — apelează Range.UpdateFields() (sau Field.Update() pentru un singur câmp) explicit după orice editare programatică care ar trebui să se reflecte în rezultatele câmpurilor.
  • FieldStart, Separator și FieldEnd sunt noduri reale în arborele documentului; elimină un câmp prin Field.Remove() sau Field.Unlink() în loc să ștergi direct nodurile marker, altfel structura câmpului poate deveni inconsistentă.
  • Câmpurile al căror rezultat depinde de dispunerea paginii — PAGE, NUMPAGES și intrările de număr de pagină din TOC — evaluează la un placeholder 0, deoarece această ediție nu include motorul de aranjare/redare a paginii.
  • Înregistrează IFieldUpdatingCallback înainte de a rula Range.UpdateFields() pe un document mare sau necunoscut dacă trebuie să înregistrezi sau să verifici exact ce câmpuri s-au modificat.
  • Setează FieldOptions.UserPromptRespondent (sau furnizează valori DefaultResponse pentru clasele de câmpuri individuale bazate pe prompt) înainte de a actualiza un document într-un pipeline neasistat, astfel încât câmpurile ASK/FILLIN să nu rămână blocate așteptând input interactiv.

Probleme comune

ProblemaCauzăRemediere
Rezultatul câmpului este învechit după editarea documentuluiAspose.Words FOSS nu actualizează automat câmpurile la încărcare sau salvareApelă Range.UpdateFields() sau Field.Update() explicit
PAGE, NUMPAGES, sau numerele de pagină din Cuprins afișează 0Aspectul/redarea paginii nu fac parte din această edițieComportament așteptat – utilizaţi versiunea comercială Aspose.Words pentru .NET dacă aveţi nevoie de numere de pagină calculate
Câmpul DATABASE nu produce rânduriNiciun IFieldDatabaseProvider nu este atribuit lui FieldOptions.FieldDatabaseProviderImplementaţi IFieldDatabaseProvider și alocaţi-l înainte de a apela Range.UpdateFields()
Actualizarea în lot a câmpului pare să se blochezeUn câmp condus de prompt (ASK, FILLIN) nu are IFieldUserPromptRespondent atribuitAtribuiţi FieldOptions.UserPromptRespondent, sau setaţi DefaultResponse pe instanţa câmpului

FAQ

Evaluează Aspose.Words FOSS fiecare tip de câmp Word?

Modelul obiect Field reprezintă fiecare valoare FieldType și actualizează majoritatea acestora, dar câmpurile a căror rezultat depinde de aspectul paginii — cum ar fi PAGE și NUMPAGES — evaluează la un 0 placeholder deoarece această ediție nu include motorul de aspect/redare.

Cum pot reevalua câmpurile după ce editez un document programatic?

Apelați Range.UpdateFields() pe intervalul care acoperă conținutul editat sau Document.Range.UpdateFields() pentru a actualiza fiecare câmp din document.

Pot converti un câmp în text simplu, static?

Da – Field.Unlink() înlocuiește câmpul cu rezultatul său calculat ultima dată ca text obișnuit, eliminând codul de bază al câmpului.

Cum pot elimina complet un câmp, inclusiv rezultatul său?

Apelați Field.Remove(). Aceasta șterge nodurile FieldStart, Separator și FieldEnd împreună cu codul și conținutul rezultat al câmpului.

Cum pot furniza date personalizate câmpului DATABASE?

Implementați IFieldDatabaseProvider și atribuiți-l lui Document.FieldOptions.FieldDatabaseProvider. Implementarea GetQueryResult() dvs. returnează un FieldDatabaseDataTable construit din FieldDatabaseDataRow instanțe.


Rezumat API Reference

Clasă / InterfațăDescriere:
FieldClasă de bază pentru un câmp Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionCâmpurile dintr-un interval, prin Range.Fields; Count, Remove(), Clear()
FieldTypeEnum care identifică ce câmp Word reprezintă o instanță Field
FieldOptionsConfigurarea actualizării câmpurilor la nivel de document, prin Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hooks în jurul fiecărei actualizări de câmp
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsRaportarea progresului pentru o actualizare în bloc a câmpurilor
IFieldResultFormatterFormatare personalizată a rezultatului calculat al unui câmp
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowSursă externă de date pentru câmpul DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultEvaluare personalizată a expresiilor de tip comparație pentru câmpuri
IFieldUserPromptRespondentFurnizează răspunsuri pentru câmpurile ghidate de prompt în actualizări neasistate
IFieldUpdateCultureProvider / FieldUpdateCultureSourceSelectarea culturii în timpul actualizărilor de câmp
UserInformationIdentitatea autorului/utilizatorului (Name, Initials, Address) citită de câmpurile de identitate

Vezi și:

 Română