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()(lubField.Update()dla pojedynczego pola) jawnie po każdej programowej edycji, która powinna być odzwierciedlona w wynikach pól. FieldStart,SeparatoriFieldEndsą rzeczywistymi węzłami w drzewie dokumentu; usuń pole przy użyciuField.Remove()lubField.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,NUMPAGESoraz wpisy numerów stron w spisie treści – oceniają się jako placeholder0, ponieważ ta edycja nie zawiera silnika układu/renderingu strony. - Zarejestruj
IFieldUpdatingCallbackprzed uruchomieniemRange.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ściDefaultResponsew poszczególnych klasach pól wywoływanych z promptu) przed aktualizacją dokumentu w nieobsługiwanym potoku, aby polaASK/FILLINnie zatrzymywały się, czekając na interaktywny input.
Typowe problemy
| Problem | Przyczyna | Naprawa |
|---|---|---|
| Wynik pola jest nieaktualny po edycji dokumentu | Aspose.Words FOSS nie aktualizuje automatycznie pól przy ładowaniu lub zapisywaniu | Wywołaj Range.UpdateFields() lub Field.Update() jawnie |
PAGE, NUMPAGES lub numery stron spisu treści pokazują 0 | Układ/renderowanie stron nie jest częścią tej edycji | Oczekiwane zachowanie — użyj wersji komercyjnej Aspose.Words dla .NET jeśli potrzebujesz obliczonych numerów stron |
pole DATABASE nie zwraca żadnych wierszy | Nie przypisano IFieldDatabaseProvider do FieldOptions.FieldDatabaseProvider | Zaimplementuj IFieldDatabaseProvider i przypisz go przed wywołaniem Range.UpdateFields() |
| Aktualizacja pól wsadowych wydaje się zawieszać | Pole sterowane monitorem (ASK, FILLIN) nie ma przypisanego IFieldUserPromptRespondent | Przypisz 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 / Interface | Opis |
|---|---|
Field | Base class dla pola Word; GetFieldCode(), Update(), Unlink(), Remove() |
FieldCollection | Pola w zakresie, za pomocą Range.Fields; Count, Remove(), Clear() |
FieldType | Enum określający, które pole Word reprezentuje instancja Field |
FieldOptions | Konfiguracja aktualizacji pól w całym dokumencie, za pomocą Document.FieldOptions |
IFieldUpdatingCallback | FieldUpdating / FieldUpdated hooki wokół każdej aktualizacji pola |
IFieldUpdatingProgressCallback / FieldUpdatingProgressArgs | Raportowanie postępu podczas masowej aktualizacji pola |
IFieldResultFormatter | Niestandardowe formatowanie wyliczonego wyniku pola |
IFieldDatabaseProvider / FieldDatabaseDataTable / FieldDatabaseDataRow | Zewnętrzne źródło danych dla pola DATABASE |
IComparisonExpressionEvaluator / ComparisonExpression / ComparisonEvaluationResult | Niestandardowa ocena wyrażeń pola w stylu porównawczym |
IFieldUserPromptRespondent | Dostarcza odpowiedzi dla pól sterowanych podpowiedzią w aktualizacjach bez nadzoru |
IFieldUpdateCultureProvider / FieldUpdateCultureSource | Wybór kultury podczas aktualizacji pól |
UserInformation | Tożsamość autora/użytkownika (Name, Initials, Address) odczytywana przez pola tożsamości |