Praca z polami

Przegląd

Pole Word – DATE, IF, DATABASE, REF, i dziesiątki innych – jest przedstawione w Aspose.Words FOSS for .NET przez Field klasę i jej podklasy, wszystkie w Aspose.Words.Fields przestrzeni nazw. Ta strona opisuje główny silnik pól: Field sam model obiektowy, sposób zbierania i aktualizacji pól oraz interfejsy zwrotne, które pozwalają wstawić własne dane i zachowanie podczas aktualizacji pola. Konkretne rodziny pól – hiperłącza i odnośniki, pola daty/godziny, pola korespondencji seryjnej, pola indeksu i spisu treści – każda ma własną dedykowaną stronę przewodnika dewelopera.


Model obiektowy pola

Każde pole w dokumencie jest instancją Field składającą się z trzech węzłów znaczników — FieldStart, Separator i FieldEnd — udostępnionych jako właściwości Field.Start, Field.Separator i Field.End. Field.Type określa, które FieldType pole reprezentuje, Field.Result i Field.DisplayResult udostępniają ostatnio obliczoną wartość, a Field.Format przechowuje wszelkie przełączniki (takie jak ciągi formatów numerycznych lub daty i czasu) dołączone do kodu pola. Field.IsLocked i Field.IsDirty raportują stan zablokowania i przestarzałości pola. Wywołaj Field.GetFieldCode(), aby odczytać surowy tekst kodu pola, Field.Update(), aby przeliczyć wynik, Field.Unlink(), aby zamienić pole na statyczny tekst oraz Field.Remove(), aby usunąć je całkowicie.


Dostęp i aktualizacja pól w dokumencie

Document.Range.Fields zwraca FieldCollection — pola zawarte w tym zakresie, z Count, Remove(), RemoveAt() i Clear() do masowego usuwania. Range.UpdateFields() przelicza każde pole w zakresie, Range.UnlinkFields() konwertuje każde pole w zakresie na tekst statyczny, a Range.NormalizeFieldTypes() porównuje zapisany kod typu pola z rzeczywistym kodem pola po ręcznych edycjach. DocumentBuilder.InsertField() wstawia nowe pole w miejscu kursora, z przeciążeniami, które albo natychmiast aktualizują wynik nowego pola, albo pozostawiają to do późniejszego etapu Range.UpdateFields().


Opcje aktualizacji pól i kultura

Document.FieldOptions jest instancją FieldOptions, która określa, jak pola całego dokumentu zachowują się po aktualizacji: CurrentUser dostarcza UserInformation używanego przez pola tożsamości, DefaultDocumentAuthor zasiewa wyniki powiązane z autorem, LegacyNumberFormat i UseInvariantCultureNumberFormat kontrolują formatowanie liczb, a PreProcessCulture i FieldUpdateCultureSource (w połączeniu z wywołaniem zwrotnym IFieldUpdateCultureProvider) określają, która kultura reguluje formatowanie dat i liczb podczas aktualizacji. TemplateName, FileName i BuiltInTemplatesPaths dostarczają wartości, które pola świadome szablonu i nazwy pliku odczytują.


Śledzenie i dostosowywanie aktualizacji pól

Zaimplementuj IFieldUpdatingCallback (FieldUpdating i FieldUpdated) na FieldOptions, aby uruchomić kod natychmiast przed i po każdym przeliczeniu pola — przydatne do audytu, które pola zmieniły się w zadaniu wsadowym. Zaimplementuj IFieldUpdatingProgressCallback (Notify), aby śledzić postęp ogólny w dużym dokumencie; otrzymuje ona FieldUpdatingProgressArgs z TotalFieldsCount, UpdatedFieldsCount i UpdateCompleted. Aby zmienić sposób, w jaki numeryczny lub ogólny wynik pola jest renderowany jako tekst, zaimplementuj IFieldResultFormatter (Format(value, format) i FormatNumeric(value, format)) i przypisz go do FieldOptions.ResultFormatter.


Dostarczanie danych zewnętrznych do pól

Pole DATABASE odczytuje swoje wiersze za pośrednictwem IFieldDatabaseProvider.GetQueryResult(), które zwraca FieldDatabaseDataTable (ColumnNames, Rows) zbudowany z instancji FieldDatabaseDataRow (Values) — przypisz swoją implementację do FieldOptions.FieldDatabaseProvider. Pola porównawcze, takie jak IF, oceniają swój warunek za pomocą IComparisonExpressionEvaluator.Evaluate(), które otrzymuje ComparisonExpression (LeftExpression, ComparisonOperator, RightExpression) i zwraca ComparisonEvaluationResult (Result, ErrorMessage); przypisz własny ewaluator do FieldOptions.ComparisonExpressionEvaluator, aby nadpisać domyślną logikę porównywania. Pola, które zazwyczaj proszą użytkownika o wprowadzenie danych podczas aktualizacji — takie jak ASK i FILLIN — wywołują IFieldUserPromptRespondent.Respond(), gdy jedno jest przypisane do FieldOptions.UserPromptRespondent, aby niekontrolowana aktualizacja nie blokowała się, czekając na interaktywny input.


Tożsamość użytkownika i dokumentu dla pól

UserInformation (Name, Initials, Address i statyczny UserInformation.DefaultUser) dostarcza tożsamość, z której odczytują pola związane z autorem i nazwą użytkownika. Przypisz instancję do Document.FieldOptions.CurrentUser przed aktualizacją pól zależnych od autora dokumentu lub tożsamości użytkownika.


Wskazówki i najlepsze praktyki

  • Aspose.Words FOSS nie przelicza pól automatycznie przy ładowaniu lub zapisie tak jak Word – wywołaj Range.UpdateFields() (lub Field.Update() dla pojedynczego pola) jawnie po każdej programowej edycji, która powinna być odzwierciedlona w wynikach pól.
  • FieldStart, Separator i FieldEnd są rzeczywistymi węzłami w drzewie dokumentu; usuń pole przy użyciu Field.Remove() lub Field.Unlink() zamiast usuwać węzły znaczników bezpośrednio, w przeciwnym razie struktura pola może stać się niespójna.
  • Pola, których wynik zależy od układu strony – PAGE, NUMPAGES oraz wpisy numerów stron w spisie treści – oceniają się jako placeholder 0, ponieważ ta edycja nie zawiera silnika układu/renderingu strony.
  • Zarejestruj IFieldUpdatingCallback przed uruchomieniem Range.UpdateFields() na dużym lub nieznanym dokumencie, jeśli potrzebujesz dokładnie logować lub audytować, które pola uległy zmianie.
  • Ustaw FieldOptions.UserPromptRespondent (lub podaj wartości DefaultResponse w poszczególnych klasach pól wywoływanych z promptu) przed aktualizacją dokumentu w nieobsługiwanym potoku, aby pola ASK/FILLIN nie zatrzymywały się, czekając na interaktywny input.

Typowe problemy

ProblemPrzyczynaNaprawa
Wynik pola jest nieaktualny po edycji dokumentuAspose.Words FOSS nie aktualizuje automatycznie pól przy ładowaniu lub zapisywaniuWywołaj Range.UpdateFields() lub Field.Update() jawnie
PAGE, NUMPAGES lub numery stron spisu treści pokazują 0Układ/renderowanie stron nie jest częścią tej edycjiOczekiwane zachowanie — użyj wersji komercyjnej Aspose.Words dla .NET jeśli potrzebujesz obliczonych numerów stron
pole DATABASE nie zwraca żadnych wierszyNie przypisano IFieldDatabaseProvider do FieldOptions.FieldDatabaseProviderZaimplementuj IFieldDatabaseProvider i przypisz go przed wywołaniem Range.UpdateFields()
Aktualizacja pól wsadowych wydaje się zawieszaćPole sterowane monitorem (ASK, FILLIN) nie ma przypisanego IFieldUserPromptRespondentPrzypisz FieldOptions.UserPromptRespondent, lub ustaw DefaultResponse w instancji pola

FAQ

Czy Aspose.Words FOSS ocenia każdy typ pola Word?

Model obiektu Field reprezentuje każdą wartość FieldType i aktualizuje większość z nich, ale pola, których wynik zależy od układu strony — takie jak PAGE i NUMPAGES — oceniają się jako placeholder 0, ponieważ ta edycja nie zawiera silnika układu/renderowania.

Jak ponownie ocenić pola po programowym edytowaniu dokumentu?

Wywołaj Range.UpdateFields() na zakresie obejmującym edytowaną treść, lub Document.Range.UpdateFields(), aby zaktualizować każde pole w dokumencie.

Czy mogę zamienić pole na zwykły, statyczny tekst?

Tak — Field.Unlink() zastępuje pole jego ostatnio obliczonym wynikiem jako zwykły tekst, usuwając leżący pod spodem kod pola.

Jak całkowicie usunąć pole, włącznie z jego wynikiem?

Wywołaj Field.Remove(). Usuwa on węzły FieldStart, Separator i FieldEnd wraz z kodem pola i zawartością wyniku.

Jak dostarczyć własne dane do pola DATABASE?

Zaimplementuj IFieldDatabaseProvider i przypisz go do Document.FieldOptions.FieldDatabaseProvider. Twoja implementacja GetQueryResult() zwraca FieldDatabaseDataTable zbudowany z FieldDatabaseDataRow instancji.


API Reference Podsumowanie

Class / InterfaceOpis
FieldBase class dla pola Word; GetFieldCode(), Update(), Unlink(), Remove()
FieldCollectionPola w zakresie, za pomocą Range.Fields; Count, Remove(), Clear()
FieldTypeEnum określający, które pole Word reprezentuje instancja Field
FieldOptionsKonfiguracja aktualizacji pól w całym dokumencie, za pomocą Document.FieldOptions
IFieldUpdatingCallbackFieldUpdating / FieldUpdated hooki wokół każdej aktualizacji pola
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgsRaportowanie postępu podczas masowej aktualizacji pola
IFieldResultFormatterNiestandardowe formatowanie wyliczonego wyniku pola
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRowZewnętrzne źródło danych dla pola DATABASE
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResultNiestandardowa ocena wyrażeń pola w stylu porównawczym
IFieldUserPromptRespondentDostarcza odpowiedzi dla pól sterowanych podpowiedzią w aktualizacjach bez nadzoru
IFieldUpdateCultureProvider / FieldUpdateCultureSourceWybór kultury podczas aktualizacji pól
UserInformationTożsamość autora/użytkownika (Name, Initials, Address) odczytywana przez pola tożsamości

Zobacz także

 Polski