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()(sauField.Update()pentru un singur câmp) explicit după orice editare programatică care ar trebui să se reflecte în rezultatele câmpurilor. FieldStart,SeparatorșiFieldEndsunt noduri reale în arborele documentului; elimină un câmp prinField.Remove()sauField.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 placeholder0, deoarece această ediție nu include motorul de aranjare/redare a paginii. - Înregistrează
IFieldUpdatingCallbackînainte de a rulaRange.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ă valoriDefaultResponsepentru clasele de câmpuri individuale bazate pe prompt) înainte de a actualiza un document într-un pipeline neasistat, astfel încât câmpurileASK/FILLINsă nu rămână blocate așteptând input interactiv.
Probleme comune
| Problema | Cauză | Remediere |
|---|---|---|
| Rezultatul câmpului este învechit după editarea documentului | Aspose.Words FOSS nu actualizează automat câmpurile la încărcare sau salvare | Apelă Range.UpdateFields() sau Field.Update() explicit |
PAGE, NUMPAGES, sau numerele de pagină din Cuprins afișează 0 | Aspectul/redarea paginii nu fac parte din această ediție | Comportament 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ânduri | Niciun IFieldDatabaseProvider nu este atribuit lui FieldOptions.FieldDatabaseProvider | Implementaţi IFieldDatabaseProvider și alocaţi-l înainte de a apela Range.UpdateFields() |
| Actualizarea în lot a câmpului pare să se blocheze | Un câmp condus de prompt (ASK, FILLIN) nu are IFieldUserPromptRespondent atribuit | Atribuiţ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: |
|---|---|
Field | Clasă de bază pentru un câmp Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Câmpurile dintr-un interval, prin Range.Fields; Count, Remove(), Clear() |
FieldType | Enum care identifică ce câmp Word reprezintă o instanță Field |
FieldOptions | Configurarea actualizării câmpurilor la nivel de document, prin Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hooks în jurul fiecărei actualizări de câmp |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Raportarea progresului pentru o actualizare în bloc a câmpurilor |
IFieldResultFormatter | Formatare personalizată a rezultatului calculat al unui câmp |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Sursă externă de date pentru câmpul DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Evaluare personalizată a expresiilor de tip comparație pentru câmpuri |
IFieldUserPromptRespondent | Furnizează răspunsuri pentru câmpurile ghidate de prompt în actualizări neasistate |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Selectarea culturii în timpul actualizărilor de câmp |
UserInformation | Identitatea autorului/utilizatorului (Name, Initials, Address) citită de câmpurile de identitate |