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()(vagyField.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ésFieldEndvalós csomópontok a dokumentumfában; távolítsa el a mezőt aField.Remove()vagy aField.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 – egy0helykitöltőre értékelődnek, mivel ez a kiadás nem tartalmazza az oldalelrendezés/renderelés motorját. - Regisztrálja a
IFieldUpdatingCallbackelemet, mielőtt aRange.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 aDefaultResponseértékeket az egyes prompt-alapú mezőosztályokon) a dokumentum frissítése előtt egy felügyelet nélküli folyamatban, hogy aASK/FILLINmezők ne akadjanak meg interaktív bemenet várásával.
Gyakori problémák
| Kérdés | Ok | Javítás |
|---|---|---|
| A mező eredménye elavult a dokumentum szerkesztése után | Aspose.Words FOSS nem frissíti automatikusan a mezőket betöltéskor vagy mentéskor | Hívja meg explicit módon a Range.UpdateFields() vagy Field.Update() elemet |
PAGE, NUMPAGES, vagy a TOC oldalszámai 0 mutatnak | Az oldalelrendezés/megjelenítés nem része ennek a kiadásnak | Vá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 sorokat | Nincs IFieldDatabaseProvider hozzárendelve a(z) FieldOptions.FieldDatabaseProvider számára | Implementá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ész | Leírás |
|---|---|
Field | Alaposztály egy Word mezőhöz; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | A tartomány mezői, a Range.Fields használatával; Count, Remove(), Clear() |
FieldType | Felsorolás (enum), amely meghatározza, hogy a Field példány mely Word mezőt képviseli |
FieldOptions | Dokumentum-szintű mezőfrissítési konfiguráció, a Document.FieldOptions használatával |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hookok minden mezőfrissítés körül |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Folyamatjelentés a tömeges mezőfrissítés során |
IFieldResultFormatter | Egy mező számított eredményének egyedi formázása |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Külső adatforrás a DATABASE mezőhöz |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Egyedi kiértékelés összehasonlítási stílusú mezőkifejezésekhez |
IFieldUserPromptRespondent | Válaszokat szolgáltat a prompt-vezérelt mezők számára felügyelet nélküli frissítések során |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Kultúraválasztás a mezőfrissítések során |
UserInformation | Szerző/felhasználói azonosító (Name, Initials, Address) azonosító mezők által olvasott |