Mezőkkel való munka

Áttekintés

A Word mező – DATE, IF, DATABASE, REF, és tucatnyi egyéb – a következőben van ábrázolva Aspose.Words FOSS a .NET számára által Field osztály és annak alosztályai, mind a Aspose.Words.Fields névtérben. Ez az oldal lefedi a magmező motorját: a Field objektummodell maga, hogyan gyűjtik és frissítik a mezőket, és a visszahívási interfészek, amelyek lehetővé teszik, hogy egyedi adatokat és viselkedést illessz be egy mezőfrissítés során. Specifikus mezőcsaládok – hiperhivatkozások és keresztutalások, dátum/idő mezők, levél-összevonás mezők, index és tartalomjegyzék mezők – mind saját dedikált fejlesztői útmutató oldallal rendelkeznek.


A Mező Objektummodell

Minden dokumentumban lévő mező egy Field példány, amely három jelölő csomópontból áll – FieldStart, Separator és FieldEnd – és a Field.Start, Field.Separator és Field.End tulajdonságokként van kitéve. Field.Type meghatározza, melyik FieldType mezőt képviseli, Field.Result és Field.DisplayResult a legutóbb kiszámított értéket mutatják, míg Field.Format minden kapcsolót (például numerikus vagy dátum-idő formátum stringeket) tárol, amelyek a mezőkódhoz vannak csatolva. Field.IsLocked és Field.IsDirty jelentik a mező zárolt és elavult állapotát. Hívja a Field.GetFieldCode() függvényt a nyers mezőkód szövegének beolvasásához, a Field.Update()-t az eredmény újraszámításához, a Field.Unlink()-t a mező statikus szöveggé cseréléséhez, és a Field.Remove()-t a teljes törléshez.


Mezők elérése és frissítése egy dokumentumban

Document.Range.Fields egy FieldCollection értékkel tér vissza – az adott tartományban lévő mezőkkel, valamint Count, Remove(), RemoveAt() és Clear() lehetőséggel tömeges eltávolításhoz. Range.UpdateFields() újraszámítja a tartományban lévő összes mezőt, Range.UnlinkFields() a tartomány minden mezőjét statikus szöveggé alakítja, és Range.NormalizeFieldTypes() egyezteti a mező tárolt típuskódját a manuális szerkesztés után keletkezett tényleges mezőkóddal. DocumentBuilder.InsertField() új mezőt szúr be a kurzornál, olyan túlterhelésekkel, amelyek vagy azonnal frissítik az új mező eredményét, vagy későbbi Range.UpdateFields() lépésre hagyják.


Mezőfrissítési beállítások és kultúra

Document.FieldOptions egy FieldOptions példány, amely meghatározza, hogyan viselkednek a dokumentum összes mezői frissítéskor: CurrentUser biztosítja a UserInformation-t, amelyet az azonosító mezők használnak, DefaultDocumentAuthor adja az íróval kapcsolatos eredményeket, LegacyNumberFormat és UseInvariantCultureNumberFormat szabályozzák a számformázást, és PreProcessCulture és FieldUpdateCultureSource (a IFieldUpdateCultureProvider visszahívással párosítva) határozzák meg, hogy melyik kultúra irányítja a dátum- és számformázást a frissítés során. TemplateName, FileName és BuiltInTemplatesPaths olyan értékeket szolgáltatnak, amelyeket a sablon- és fájlnév-érzékeny mezők visszaolvasnak.


Mezőfrissítések nyomon követése és testreszabása

Implementálja a IFieldUpdatingCallback (FieldUpdating és FieldUpdated) a FieldOptions-n, hogy a kódot minden mező újraszámolása előtt és után azonnal lefuttassa – hasznos a mezők változásainak auditálásához kötegelt feladatokban. Implementálja a IFieldUpdatingProgressCallback (Notify) a nagy dokumentumok átfogó előrehaladásának nyomon követéséhez; ez egy FieldUpdatingProgressArgs-t kap, amely TotalFieldsCount, UpdatedFieldsCount és UpdateCompleted tartalmaz. Ahhoz, hogy megváltoztassa, hogyan jelenik meg egy mező numerikus vagy általános eredménye szövegként, implementálja a IFieldResultFormatter (Format(value, format) és FormatNumeric(value, format)) és rendelje hozzá a FieldOptions.ResultFormatter-hez.


Külső adatok biztosítása a mezőknek

A DATABASE mező a sorait a IFieldDatabaseProvider.GetQueryResult() segítségével olvassa, amely egy FieldDatabaseDataTable (ColumnNames, Rows) ad vissza, a FieldDatabaseDataRow (Values) példányokból felépítve – rendelje saját megvalósítását a FieldOptions.FieldDatabaseProvider-hez. Összehasonlítási mezők, például a IF, a feltételüket a IComparisonExpressionEvaluator.Evaluate() segítségével értékelik, amely egy ComparisonExpression-t kap (LeftExpression, ComparisonOperator, RightExpression) és egy ComparisonEvaluationResult-t ad vissza (Result, ErrorMessage); egy egyedi értékelőt a FieldOptions.ComparisonExpressionEvaluator-hez rendelve felülbírálhatja az alapértelmezett összehasonlítási logikát. Azok a mezők, amelyek általában a felhasználótól kérnek bevitelt frissítéskor – például a ASK és a FILLIN – a IFieldUserPromptRespondent.Respond()-t hívják, amikor egyet a FieldOptions.UserPromptRespondent-hez rendelik, így egy felügyelet nélküli frissítés nem blokkolódik interaktív bemenetre várva.


Felhasználó és dokumentumazonosító a mezők számára

A UserInformation (Name, Initials, Address, valamint a statikus UserInformation.DefaultUser) biztosítja az azonosságot, amelyet a szerző- és felhasználónevet érintő mezők olvasnak. Rendeljen egy példányt a Document.FieldOptions.CurrentUser-hez, mielőtt olyan mezőket frissítene, amelyek a dokumentum szerzőjét vagy felhasználói azonosítótól függnek.


Tippek és bevált gyakorlatok

  • Aspose.Words FOSS nem számolja újra a mezőket automatikusan betöltéskor vagy mentéskor, ahogyan a Word teszi – hívja meg explicit módon a Range.UpdateFields() (vagy Field.Update() egyetlen mező esetén) minden programozott módosítás után, amelynek tükröződnie kell a mezőeredményekben.
  • FieldStart, Separator és FieldEnd valós csomópontok a dokumentumfában; távolítsa el a mezőt a Field.Remove() vagy a Field.Unlink() segítségével, a marker csomópontok közvetlen törlése helyett, különben a mezőszerkezet inkonzisztenssé válhat.
  • Azok a mezők, amelyek eredménye az oldalelrendezéstől függ – PAGE, NUMPAGES és a TOV oldal-szám bejegyzései – egy 0 helykitöltőre értékelődnek, mivel ez a kiadás nem tartalmazza az oldalelrendezés/renderelés motorját.
  • Regisztrálja a IFieldUpdatingCallback elemet, mielőtt a Range.UpdateFields() futtatásával nagy vagy ismeretlen dokumentumot dolgozna fel, ha pontosan nyomon szeretné követni vagy auditálni, mely mezők változtak.
  • Állítsa be a FieldOptions.UserPromptRespondent értéket (vagy adja meg a DefaultResponse értékeket az egyes prompt-alapú mezőosztályokon) a dokumentum frissítése előtt egy felügyelet nélküli folyamatban, hogy a ASK/FILLIN mezők ne akadjanak meg interaktív bemenet várásával.

Gyakori problémák

KérdésOkJavítás
A mező eredménye elavult a dokumentum szerkesztése utánAspose.Words FOSS nem frissíti automatikusan a mezőket betöltéskor vagy mentéskorHívja meg explicit módon a Range.UpdateFields() vagy Field.Update() elemet
PAGE, NUMPAGES, vagy a TOC oldalszámai 0 mutatnakAz oldalelrendezés/megjelenítés nem része ennek a kiadásnakVárható viselkedés – használja a kereskedelmi változatot Aspose.Words a(z) .NET számára ha számított oldalszámokra van szükséged
DATABASE mező nem ad sorokatNincs IFieldDatabaseProvider hozzárendelve a(z) FieldOptions.FieldDatabaseProvider számáraImplementáld a(z) IFieldDatabaseProvider elemet, és rendeld hozzá, mielőtt meghívnád a(z) Range.UpdateFields().
A kötegelt mezőfrissítés akadozni látszik.A prompt-alapú mező (ASK, FILLIN) nincs IFieldUserPromptRespondent hozzárendelve.Rendeld hozzá a(z) FieldOptions.UserPromptRespondent elemet, vagy állítsd be a(z) DefaultResponse a mezőpéldányon.

FAQ

A Aspose.Words FOSS minden Word mezőtípust kiértékel?

A Field objektummodell minden FieldType értéket képvisel, és a legtöbbet frissíti, de azok a mezők, amelyek eredménye az oldalelrendezéstől függ – például a PAGE és a NUMPAGES – helyőrző 0 értékkel értékelődnek, mivel ez a kiadás nem tartalmazza az elrendezés/megjelenítő motorját.

Hogyan tudom újraértékelni a mezőket a dokumentum programozott szerkesztése után?

Hívja a Range.UpdateFields() a szerkesztett tartalmat lefedő tartományra, vagy használja a Document.Range.UpdateFields() a dokumentum összes mezőjének frissítéséhez.

Átalakíthatom a mezőt egyszerű, statikus szöveggé?

Igen – a Field.Unlink() a mezőt az utolsó számított eredményével helyettesíti egyszerű szövegként, és eltávolítja a mező alapkódját.

Hogyan távolíthatok el egy mezőt teljesen, beleértve az eredményét is?

Hívja a Field.Remove(). Ez törli a FieldStart, Separator és FieldEnd csomópontokat a mező kódjával és eredmény tartalmával együtt.

Hogyan adhatok egyedi adatot a DATABASE mezőnek?

Implementáld a IFieldDatabaseProvider elemet, és rendeld hozzá a Document.FieldOptions.FieldDatabaseProvider változóhoz. A GetQueryResult() megvalósításod egy FieldDatabaseDataTable-t ad vissza, amely FieldDatabaseDataRow példányokból épül fel.


API Reference összegzés

Osztály / InterfészLeírás
FieldAlaposztály egy Word mezőhöz; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionA tartomány mezői, a Range.Fields használatával; Count, Remove(), Clear()
FieldTypeFelsorolás (enum), amely meghatározza, hogy a Field példány mely Word mezőt képviseli
FieldOptionsDokumentum-szintű mezőfrissítési konfiguráció, a Document.FieldOptions használatával
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hookok minden mezőfrissítés körül
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsFolyamatjelentés a tömeges mezőfrissítés során
IFieldResultFormatterEgy mező számított eredményének egyedi formázása
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowKülső adatforrás a DATABASE mezőhöz
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultEgyedi kiértékelés összehasonlítási stílusú mezőkifejezésekhez
IFieldUserPromptRespondentVálaszokat szolgáltat a prompt-vezérelt mezők számára felügyelet nélküli frissítések során
IFieldUpdateCultureProvider / FieldUpdateCultureSourceKultúraválasztás a mezőfrissítések során
UserInformationSzerző/felhasználói azonosító (Name, Initials, Address) azonosító mezők által olvasott

Lásd még:

 Magyar