Cum să lucrați cu câmpurile în .NET
Acest ghid arată cum să lucraţi cu câmpurile Word — DATE, IF, REF, DATABASE și zeci de altele — în Aspose.Words FOSS pentru .NET: inserarea unui câmp și citirea rezultatului său, actualizarea câmpurilor după o editare programatică, configurarea comportamentului de actualizare, urmărirea actualizărilor cu un callback și convertirea sau eliminarea unui câmp. Aspose.Words FOSS pentru .NET este disponibil prin NuGet sau prin compilare din sursă.
Ghid pas cu pas
Pasul 1: Obțineţi biblioteca
Clonați depozitul și construiți Aspose.Words.sln în configurația Release, apoi adăugați o referință de proiect la Aspose.Words.csproj din propriul dvs. proiect .NET, așa cum este descris în ghidul de instalare. Adăugați using Aspose.Words; and using Aspose.Words.Fields; în partea de sus a oricărui fișier care lucrează cu câmpuri.
Pasul 2: Inserăţi un câmp şi citiţi rezultatul său
DocumentBuilder.InsertField() inserează un nou câmp la cursor, cu suprasarcini care fie actualizează imediat rezultatul câmpului, fie îl lasă pentru o trecere ulterioară de actualizare. Fiecare câmp este o instanță Field formată din trei noduri marcatoare — FieldStart, Separator și FieldEnd, expuse ca Field.Start / Field.Separator / Field.End. Field.Type identifică ce FieldType reprezintă, Field.Result și Field.DisplayResult păstrează valoarea calculată ultima dată, Field.Format conține orice comutatori de format ataşaţi codului, și Field.GetFieldCode() returnează textul brut al codului de câmp.
Pasul 3: Actualizați câmpurile după o editare programatică
Aspose.Words FOSS nu recalculează câmpurile când documentul se încarcă sau se salvează. După o editare care ar trebui să schimbe rezultatul unui câmp, apelați Range.UpdateFields() pentru a recalcula fiecare câmp din acel interval — folosiți Document.Range.UpdateFields() pentru întregul document — sau Field.Update() pentru un singur câmp. Range.UnlinkFields() convertește fiecare câmp din interval în text static într-un singur apel, iar Range.NormalizeFieldTypes() reconciliază codul de tip stocat al unui câmp cu codul său real de câmp după o editare manuală.
Pasul 4: Configurați comportamentul de actualizare a câmpurilor cu FieldOptions
Document.FieldOptions (o instanță FieldOptions) controlează modul în care câmpurile întregului document se comportă în timpul unei actualizări: CurrentUser (o instanță UserInformation — Name, Initials, Address) furnizează identitatea din care citesc câmpurile legate de autor și de numele utilizatorului, DefaultDocumentAuthor generează rezultatele legate de autor, iar LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource controlează formatarea numerelor și a datelor. Pentru fluxuri de lucru nesupravegheate, atribuiți FieldOptions.UserPromptRespondent (un IFieldUserPromptRespondent) astfel încât câmpurile ghidate de prompt, cum ar fi ASK și FILLIN, să nu blocheze așteptând intrare interactivă, și atribuiți un IFieldDatabaseProvider personalizat lui FieldOptions.FieldDatabaseProvider pentru a furniza rândurile câmpului DATABASE din propria sursă de date în loc de o conexiune reală la bază de date.
Pasul 5: Urmăriți actualizările câmpurilor cu un callback
Implementați IFieldUpdatingCallback (FieldUpdating și FieldUpdated) și atribuiți-l lui FieldOptions pentru a rula cod imediat înainte și după fiecare recalculare a unui câmp — util pentru auditarea exactă a câmpurilor care s-au modificat într-un job în lot. Pentru raportarea progresului într-un document mare, implementați IFieldUpdatingProgressCallback (Notify), care primește un FieldUpdatingProgressArgs expunând TotalFieldsCount, UpdatedFieldsCount și UpdateCompleted.
Pasul 6: Convertiți sau eliminați un câmp
Field.Unlink() înlocuiește câmpul cu rezultatul său ultim calculat ca text static obișnuit, eliminând codul de bază al câmpului — folosiți-l când doriți ca valoarea să fie integrată permanent în document. Field.Remove() șterge nodurile FieldStart, Separator și FieldEnd împreună cu codul și rezultatul câmpului, eliminând complet câmpul. Preferă aceste două metode în locul ștergerii directe a nodurilor marcatoare, deoarece eliminarea manuală a doar unei părți din structura unui câmp poate lăsa arborele documentului inconsistent.
Probleme comune și remedii
Rezultatul afișat al unui câmp este învechit după editarea documentului. Aspose.Words FOSS nu actualizează automat câmpurile la încărcare sau salvare. Apelați Range.UpdateFields() or Field.Update() explicit după editare.
PAGE, NUMPAGES, sau un număr de pagină din cuprins se afișează întotdeauna 0. Aspectul/paginarea paginii nu face parte din această ediție, astfel că câmpurile al căror rezultat depinde de paginare evaluează la un marcaj 0. Acest comportament este așteptat în această ediție.
O actualizare în lot a câmpurilor pare să rămână blocată. Un câmp condus de prompt (ASK, FILLIN) nu are IFieldUserPromptRespondent atribuit. Atribuiţi FieldOptions.UserPromptRespondent, sau setaţi DefaultResponse pe instanţa individuală a câmpului.
Câmpul DATABASE nu produce rânduri. Nu IFieldDatabaseProvider este atribuită la FieldOptions.FieldDatabaseProvider. Implementaţi interfaţa şi atribuiţi-o înainte de a apela Range.UpdateFields().
Întrebări frecvente
Evaluă Aspose.Words FOSS fiecare tip de câmp Word?
Modelul de obiecte Field reprezintă fiecare valoare FieldType și actualizează majoritatea acestora, dar câmpurile al 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ă o editare programatică?
Apelați Range.UpdateFields() pe intervalul care acoperă conținutul editat sau Document.Range.UpdateFields() pentru întregul document.
Pot să convertesc 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.
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 sa GetQueryResult() returnează un FieldDatabaseDataTable construit din instanțe FieldDatabaseDataRow.
