Jak pracować z polami w .NET
Ten przewodnik pokazuje, jak pracować z polami Word — DATE, IF, REF, DATABASE i wieloma innymi — w Aspose.Words FOSS dla .NET: wstawianie pola i odczytywanie jego wyniku, aktualizowanie pól po programowej edycji, konfigurowanie zachowania aktualizacji, śledzenie aktualizacji przy użyciu wywołania zwrotnego oraz konwertowanie lub usuwanie pola. Aspose.Words FOSS dla .NET jest dostępny poprzez NuGet lub poprzez budowanie ze źródeł.
Przewodnik krok po kroku
Krok 1: Pobierz bibliotekę
Sklonuj repozytorium i zbuduj Aspose.Words.sln w konfiguracji Release, a następnie dodaj odwołanie do projektu Aspose.Words.csproj z własnego projektu .NET, jak opisano w przewodniku instalacji. Dodaj using Aspose.Words; and using Aspose.Words.Fields; na początku każdego pliku, który pracuje z polami.
Krok 2: Wstaw pole i odczytaj jego wynik
DocumentBuilder.InsertField() wstawia nowe pole w miejscu kursora, z przeciążeniami, które albo aktualizują wynik pola od razu, albo pozostawiają go do późniejszego przebiegu aktualizacji. Każde pole jest instancją Field składającą się z trzech węzłów znaczników — FieldStart, Separator i FieldEnd, udostępnionych jako Field.Start / Field.Separator / Field.End. Field.Type identyfikuje, które FieldType reprezentuje, Field.Result i Field.DisplayResult przechowują ostatnio obliczoną wartość, Field.Format zawiera wszelkie przełączniki formatowania dołączone do kodu, a Field.GetFieldCode() zwraca surowy tekst kodu pola.
Krok 3: Aktualizuj pola po programowej edycji
Aspose.Words FOSS nie przelicza pól podczas ładowania lub zapisywania dokumentu. Po edycji, która powinna zmienić wynik pola, wywołaj Range.UpdateFields(), aby przeliczyć każde pole w tym zakresie — użyj Document.Range.UpdateFields() dla całego dokumentu — lub Field.Update() dla pojedynczego pola. Range.UnlinkFields() zamienia każde pole w zakresie na statyczny tekst w jednym wywołaniu, a Range.NormalizeFieldTypes() porównuje przechowywany kod typu pola z jego rzeczywistym kodem pola po ręcznej edycji.
Krok 4: Skonfiguruj zachowanie aktualizacji pól za pomocą FieldOptions
Document.FieldOptions (instancja FieldOptions) określa, jak pola całego dokumentu zachowują się podczas aktualizacji: CurrentUser (instancja UserInformation — Name, Initials, Address) dostarcza tożsamość, z której odczytują pola związane z autorem i nazwą użytkownika, DefaultDocumentAuthor inicjuje wyniki związane z autorem, a LegacyNumberFormat / UseInvariantCultureNumberFormat / PreProcessCulture / FieldUpdateCultureSource kontrolują formatowanie liczb i dat. Dla potoków bez nadzoru przydziel FieldOptions.UserPromptRespondent (IFieldUserPromptRespondent), aby pola wywoływane z monitu, takie jak ASK i FILLIN, nie blokowały oczekując na interaktywne wejście, oraz przypisz własny IFieldDatabaseProvider do FieldOptions.FieldDatabaseProvider, aby dostarczyć wiersze pola DATABASE z własnego źródła danych zamiast rzeczywistego połączenia z bazą danych.
Krok 5: Śledź aktualizacje pól za pomocą wywołania zwrotnego
Zaimplementuj IFieldUpdatingCallback (FieldUpdating i FieldUpdated) i przypisz go do FieldOptions, aby uruchomić kod bezpośrednio przed i po każdym przeliczeniu pola — przydatne do audytu, które dokładnie pola zmieniły się w zadaniu wsadowym. Do raportowania postępu w dużym dokumencie, zaimplementuj IFieldUpdatingProgressCallback (Notify), który otrzymuje FieldUpdatingProgressArgs udostępniający TotalFieldsCount, UpdatedFieldsCount i UpdateCompleted.
Krok 6: Konwertuj lub usuń pole
Field.Unlink() zastępuje pole jego ostatnio obliczonym wynikiem jako zwykły statyczny tekst, odrzucając podstawowy kod pola — użyj go, gdy chcesz, aby wartość była trwale wbudowana w dokument. Field.Remove() usuwa węzły FieldStart, Separator i FieldEnd razem z kodem i wynikiem pola, całkowicie usuwając pole. Preferuj te dwie metody zamiast bezpośredniego usuwania węzłów znacznika, ponieważ ręczne usunięcie tylko części struktury pola może spowodować niespójność drzewa dokumentu.
Typowe problemy i rozwiązania
Wyświetlany wynik pola jest nieaktualny po edycji dokumentu. Aspose.Words FOSS nie aktualizuje automatycznie pól podczas ładowania lub zapisywania. Wywołaj Range.UpdateFields() or Field.Update() jawnie po edycji.
PAGE, NUMPAGES, lub numer strony spisu treści zawsze się wyświetla 0. Page-layout/rendering nie jest częścią tej edycji, więc pola, których wynik zależy od paginacji, ocenia się jako placeholder 0. To jest oczekiwane zachowanie w tej edycji.
Aktualizacja pól wsadowych wydaje się zawieszać. Pole sterowane podpowiedzią (ASK, FILLIN) nie ma IFieldUserPromptRespondent przypisanego. Przypisz FieldOptions.UserPromptRespondent, lub ustaw DefaultResponse na pojedynczej instancji pola.
Ten DATABASE pole nie zwraca żadnych wierszy. Brak IFieldDatabaseProvider jest przypisane do FieldOptions.FieldDatabaseProvider. Zaimplementuj interfejs i przypisz go przed wywołaniem Range.UpdateFields().
Najczęściej zadawane pytania
Czy Aspose.Words FOSS ocenia każdy typ pola Word?
Model obiektowy 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 mogę ponownie ocenić pola po programowej edycji?
Wywołaj Range.UpdateFields() na zakresie obejmującym edytowaną treść lub Document.Range.UpdateFields() dla całego dokumentu.
Czy mogę zamienić pole na zwykły, statyczny tekst?
Tak — Field.Unlink() zastępuje pole jego ostatnio obliczonym wynikiem jako zwykły tekst.
Jak usunąć pole całkowicie, łącznie z jego wynikiem?
Wywołaj Field.Remove(). Usuwa węzły FieldStart, Separator i FieldEnd razem z kodem pola oraz treścią wyniku.
Jak dostarczyć własne dane do pola DATABASE?
Zaimplementuj IFieldDatabaseProvider i przypisz go do Document.FieldOptions.FieldDatabaseProvider. Jego GetQueryResult() implementacja zwraca FieldDatabaseDataTable zbudowany z FieldDatabaseDataRow instancji.
