Práce s poli

Práce s poli

Pole Word – DATE, IF, DATABASE, REF, a desítky dalších – je reprezentováno v Aspose.Words FOSS pro .NET pomocí Field třídy a jejích podtříd, všechny v Aspose.Words.Fields jmenném prostoru. Tato stránka pokrývá hlavní motor polí: Field samotný objektový model, jak jsou pole shromažďována a aktualizována, a rozhraní zpětných volání, která vám umožní vložit vlastní data a chování během aktualizace pole. Specifické rodiny polí – hypertextové odkazy a křížové odkazy, pole data/času, pole hromadné korespondence, pole rejstříku a obsahu – mají každá svou samostatnou stránku v průvodci pro vývojáře.

Objektový model pole

Každé pole v dokumentu je instance Field složená ze tří značkovacích uzlů – FieldStart, Separator a FieldEnd – které jsou vystaveny jako vlastnosti Field.Start, Field.Separator a Field.End. Field.Type určuje, který FieldType pole představuje, Field.Result a Field.DisplayResult vystavují naposledy vypočtenou hodnotu a Field.Format obsahuje jakékoli přepínače (například číselné nebo formátovací řetězce data/času) připojené k kódu pole. Field.IsLocked a Field.IsDirty hlásí zamčený a zastaralý stav pole. Zavolejte Field.GetFieldCode() pro načtení surového textu kódu pole, Field.Update() pro přepočítání výsledku, Field.Unlink() pro nahrazení pole statickým textem a Field.Remove() pro jeho úplné smazání.

Přístup k polím a jejich aktualizace v dokumentu

Document.Range.Fields vrací FieldCollection – pole obsažená v tomto rozsahu, s Count, Remove(), RemoveAt() a Clear() pro hromadné odebrání. Range.UpdateFields() přepočítá každé pole v rozsahu, Range.UnlinkFields() převede každé pole v rozsahu na statický text a Range.NormalizeFieldTypes() sladí uložený typový kód pole s jeho skutečným kódem po ručních úpravách. DocumentBuilder.InsertField() vloží nové pole na pozici kurzoru, s přetíženími, která buď okamžitě aktualizují výsledek nového pole, nebo jej nechají pro pozdější průchod Range.UpdateFields().

Možnosti aktualizace pole a kultura

Document.FieldOptions je FieldOptions instance, která řídí chování všech polí dokumentu při aktualizaci: CurrentUser poskytuje UserInformation používané identifikačními poli, DefaultDocumentAuthor zasévá výsledky související s autorem, LegacyNumberFormat a UseInvariantCultureNumberFormat kontrolují formátování čísel a PreProcessCulture a FieldUpdateCultureSource (spojené s callbackem IFieldUpdateCultureProvider) určují, která kultura řídí formátování data a čísel během aktualizace. TemplateName, FileName a BuiltInTemplatesPaths poskytují hodnoty, které pole citlivá na šablonu a název souboru načítají zpět.

Sledování a přizpůsobení aktualizací polí

Implementujte IFieldUpdatingCallback (FieldUpdating a FieldUpdated) na FieldOptions, aby se kód spustil okamžitě před a po každém přepočtu pole – užitečné pro audit, které pole se změnila v dávkovém úkolu. Implementujte IFieldUpdatingProgressCallback (Notify), abyste sledovali celkový postup v rozsáhlém dokumentu; přijímá FieldUpdatingProgressArgs s TotalFieldsCount, UpdatedFieldsCount a UpdateCompleted. Pro změnu způsobu, jakým je číselný nebo obecný výsledek pole vykreslen jako text, implementujte IFieldResultFormatter (Format(value, format) a FormatNumeric(value, format)) a přiřaďte jej k FieldOptions.ResultFormatter.

Poskytování externích dat polí

Pole DATABASE načítá své řádky přes IFieldDatabaseProvider.GetQueryResult(), který vrací FieldDatabaseDataTable (ColumnNames, Rows) vytvořený z instancí FieldDatabaseDataRow (Values) – přiřaďte svou implementaci k FieldOptions.FieldDatabaseProvider. Porovnávací pole, jako je IF, vyhodnocují svou podmínku pomocí IComparisonExpressionEvaluator.Evaluate(), který přijímá ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) a vrací ComparisonEvaluationResult (Result, ErrorMessage); přiřaďte vlastní evaluátor k FieldOptions.ComparisonExpressionEvaluator, abyste přepsali výchozí logiku porovnání. Pole, která obvykle vyzývají uživatele k zadání během aktualizace – například ASK a FILLIN – volají IFieldUserPromptRespondent.Respond(), když je jedno přiřazeno k FieldOptions.UserPromptRespondent, takže neinteraktivní aktualizace neblokuje čekáním na vstup.

Identita uživatele a dokumentu pro pole

UserInformation (Name, Initials, Address a statický UserInformation.DefaultUser) poskytuje identitu, ze které čtou pole související s autorem a uživatelským jménem. Přiřaďte instanci k Document.FieldOptions.CurrentUser před aktualizací polí, která závisí na autorovi dokumentu nebo identitě uživatele.

Tipy a osvědčené postupy

• Aspose.Words FOSS nepřepočítává pole automaticky při načtení nebo uložení, jak to dělá Word – zavolejte Range.UpdateFields() (nebo Field.Update() pro jediné pole) explicitně po jakékoli programové úpravě, která by měla být odrazena ve výsledcích pole.
• FieldStart, Separator a FieldEnd jsou skutečné uzly ve stromu dokumentu; odstraňte pole pomocí Field.Remove() nebo Field.Unlink() místo přímého mazání uzlů značek, jinak může být struktura pole nekonzistentní.
• Pole, jejichž výsledek závisí na rozložení stránky – PAGE, NUMPAGES a položky číslování stránek obsahu – se vyhodnocují jako zástupný znak 0, protože tato verze neobsahuje engine pro rozložení/renderování stránky.
• Zaregistrujte IFieldUpdatingCallback před spuštěním Range.UpdateFields() na velkém nebo neznámém dokumentu, pokud potřebujete zaznamenat nebo auditovat přesně, která pole se změnila.
• Nastavte FieldOptions.UserPromptRespondent (nebo poskytněte hodnoty DefaultResponse u jednotlivých tříd polí řízených výzvou) před aktualizací dokumentu v nepřítomném pipeline, aby pole ASK/FILLIN nečekala na interaktivní vstup.

Časté problémy

FAQ

Vyhodnocuje Aspose.Words FOSS každý typ pole Wordu?

Objektový model Field představuje každou hodnotu FieldType a aktualizuje většinu z nich, ale pole, jejichž výsledek závisí na rozložení stránky – například PAGE a NUMPAGES – vyhodnocují se jako zástupný 0, protože tato edice neobsahuje engine pro rozložení/vykreslování.

Jak mohu po programové úpravě dokumentu znovu vyhodnotit pole?

Zavolejte Range.UpdateFields() na rozsah, který zahrnuje upravený obsah, nebo Document.Range.UpdateFields() pro aktualizaci všech polí v dokumentu.

Mohu převést pole na prostý, statický text?

Ano – Field.Unlink() nahradí pole jeho naposledy vypočteným výsledkem jako běžný text a odstraní podkladový kód pole.

Jak mohu pole úplně odstranit, včetně jeho výsledku?

Zavolejte Field.Remove(). Smaže uzly FieldStart, Separator a FieldEnd spolu s kódem pole a obsahem výsledku.

Jak dodat vlastní data do pole DATABASE?

Implementujte IFieldDatabaseProvider a přiřaďte jej k Document.FieldOptions.FieldDatabaseProvider. Vaše GetQueryResult() implementace vrací FieldDatabaseDataTable postavený z FieldDatabaseDataRow instancí.

Souhrn API Reference

Viz také:

• Aspose.Words for .NET — Enterprise Documentation