Jak utworzyć podgląd w .NET przy użyciu GroupDocs.Annotation

Generowanie doświadczenia tworzenia podglądu jest kluczowym elementem nowoczesnych aplikacji skoncentrowanych na dokumentach. Dzięki GroupDocs.Annotation dla .NET możesz renderować miniatury PDF, tworzyć bezpieczne strumienie podglądu dokumentów i utrzymywać interfejs użytkownika responsywny nawet na urządzeniach mobilnych. W tym przewodniku dowiesz się, dlaczego generowanie podglądu ma znaczenie, poznasz typowe scenariusze implementacji oraz otrzymasz plan dodania wysokiej jakości podglądów do własnych rozwiązań.

Szybkie odpowiedzi

Klasa AnnotationApi jest podstawowym komponentem GroupDocs.Annotation, który ładuje dokumenty i tworzy obrazy podglądu. Metoda GetPages zwraca renderowane obrazy stron jako tablice bajtów. Flaga HideAnnotations usuwa wszystkie warstwy adnotacji z renderowanego obrazu.

  • Jaki jest najszybszy sposób renderowania miniatury PDF? Ładuj PDF za pomocą AnnotationApi, ustaw DPI = 150 i wywołaj GetPages – pierwsza strona jest zwracana jako PNG w czasie krótszym niż 200 ms dla pliku o wielkości 2 MB.
  • Czy mogę ukryć wszystkie adnotacje w podglądzie? Tak – użyj flagi HideAnnotations przed renderowaniem, aby uzyskać czysty widok.
  • Czy generowanie podglądu jest wątkowo‑bezpieczne? API jest bezstanowe; możesz bezpiecznie uruchamiać wiele zadań podglądu równolegle.
  • Czy potrzebuję licencji do użytku produkcyjnego? Wymagana jest ważna licencja GroupDocs.Annotation do nieograniczonego generowania podglądów.
  • Jakie wersje .NET są obsługiwane? .NET Framework 4.6+, .NET Core 3.1+, .NET 5/6/7.

Czym jest podgląd dokumentu?

Podgląd dokumentu to lekka wizualna reprezentacja pliku — zazwyczaj obrazu lub serii obrazów — która pozwala użytkownikom spojrzeć na zawartość bez pobierania pełnego dokumentu. Poprawia UX, zmniejsza zużycie pasma i dodaje warstwę bezpieczeństwa, udostępniając tylko to, co zdecydujesz się wyrenderować.

Dlaczego używać bezpiecznego podglądu dokumentu?

Bezpieczny podgląd dokumentu zapewnia, że wrażliwe metadane, ukryte warstwy lub ograniczone adnotacje nigdy nie opuszczają serwera. GroupDocs.Annotation szyfruje strumień podglądu i usuwa wszelkie znaczniki, które nie są wyraźnie dozwolone, dając pełną kontrolę nad tym, co widzą użytkownicy końcowi. Kwantyfikowane stwierdzenie: biblioteka obsługuje ponad 30 formatów plików i może generować podglądy PDF‑ów o 500 stronach w czasie krótszym niż 2 sekundy na standardowym serwerze 8‑rdzeniowym przy użyciu domyślnego DPI 150.

Jak renderować miniaturę PDF?

Załaduj PDF za pomocą AnnotationApi, określ DPI w zakresie 150‑300 dla wyraźnego tekstu i żądaj pierwszej strony jako PNG. To dwustopniowe podejście zwraca tablicę bajtów, którą możesz strumieniować bezpośrednio do przeglądarki lub buforować na dysku. Użycie wyższego DPI (np. 300) poprawia czytelność dokumentów z dużą ilością tekstu, natomiast niższe DPI (np. 72) zmniejsza rozmiar pliku dla siatek miniatur.

Wymagania wstępne

  • .NET Framework 4.6+ lub .NET Core 3.1+ zainstalowane.
  • Ważna licencja GroupDocs.Annotation (tymczasowa licencja działa w trybie ewaluacji).
  • Dostęp do plików PDF, Word, Excel lub innych obsługiwanych, które zamierzasz podglądać.

Jak utworzyć podgląd krok po kroku

Aby utworzyć podgląd, musisz zainstalować pakiet GroupDocs.Annotation, zainicjować API z licencją, skonfigurować opcje podglądu, wygenerować obraz i opcjonalnie buforować wynik. Poniższe sekcje przeprowadzają przez każdy krok z przykładami kodu, pokazując jak ukrywać adnotacje, ustawiać DPI i efektywnie obsługiwać duże pliki.

Krok 1: zainstaluj pakiet NuGet

Open your project’s Package Manager Console and run:

Install-Package GroupDocs.Annotation

Krok 2: zainicjuj API

Create an AnnotationApi instance, passing your license file path and optional configuration (e.g., cache folder, memory limit).

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

Krok 3: wygeneruj podgląd bez adnotacji

Set the HideAnnotations flag to true, choose the desired DPI, and request the page(s) you need.

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

Wywołanie GetPreview zwraca tablicę bajtów, którą możesz wysłać bezpośrednio w odpowiedzi HTTP, przechowywać w CDN lub osadzić w komponencie UI.

Krok 4: buforuj i ponownie używaj podglądów

Aby uniknąć wielokrotnego generowania tego samego podglądu, przechowuj obraz używając hasha pliku źródłowego i ustawień podglądu jako klucza pamięci podręcznej. Gdy dokument źródłowy się zmieni, unieważnij pamięć podręczną porównując znaczniki czasu.

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

Krok 5: efektywnie obsługuj duże dokumenty

Dla plików większych niż 100 MB użyj bloku using, aby zapewnić szybkie zwolnienie wewnętrznych strumieni przez AnnotationApi. Przetwarzaj strony w partiach, jeśli potrzebujesz podglądów wielostronicowych, zwalniając każdą partię przed przejściem do kolejnej.

Typowe scenariusze implementacji

  • Systemy zarządzania dokumentami – wyświetlaj siatkę miniatur obrazów dla szybkiej nawigacji wizualnej.
  • Platformy współpracy – renderuj widoki tylko z podglądem dla recenzentów, a następnie umożliwiaj włączanie warstw adnotacji na żądanie.
  • Portale internetowe – pokaż podgląd po najechaniu na linki do plików, zmniejszając potrzebę pełnych pobrań.
  • Aplikacje mobilne – generuj PNG o niskiej rozdzielczości (72 DPI), aby utrzymać zużycie pasma poniżej 50 KB na stronę.

Rozwiązywanie problemów z generowaniem podglądu

  • Wzrost zużycia pamięci przy dużych PDF‑ach – upewnij się, że wywołujesz Dispose() na AnnotationApi po każdej partii podglądu i ogranicz liczbę równoczesnych zadań podglądu.
  • Rozmyty tekst w miniaturach – zwiększ DPI do 300 lub zmień format wyjściowy na PNG; kompresja JPEG może rozmywać cienkie znaki.
  • Brak obrazów w podglądach Excel – upewnij się, że obiekty wykresów w skoroszycie są w pełni załadowane, ustawiając LoadCharts = true w opcjach podglądu.
  • Wolne czasy odpowiedzi – przenieś generowanie podglądu do wątku w tle (np. Task.Run) i wyświetlaj obraz zastępczy, dopóki prawdziwy podgląd nie będzie gotowy.

Najczęściej zadawane pytania

P: Czy mogę generować podglądy dla dokumentów chronionych hasłem?
O: Tak. Podaj hasło w LoadOptions przy tworzeniu instancji AnnotationApi; podgląd zostanie wygenerowany po pomyślnym odszyfrowaniu.

P: Czy biblioteka obsługuje renderowanie podglądów dla formatów innych niż PDF, takich jak DOCX lub XLSX?
O: Zdecydowanie tak. GroupDocs.Annotation może renderować podglądy dla ponad 30 różnych formatów, w tym DOCX, XLSX, PPTX oraz wielu typów obrazów.

P: Jak zapewnić, że podgląd nie ujawnia ukrytych metadanych?
O: Użyj opcji HideMetadata w PreviewOptions; API usuwa wszystkie właściwości dokumentu przed renderowaniem obrazu.

P: Czy bezpieczne jest publiczne udostępnianie punktu końcowego podglądu?
O: Strumień podglądu jest generowany po stronie serwera i może być dostarczany przez HTTPS. Połącz to z uwierzytelnianiem opartym na tokenach, aby ograniczyć dostęp tylko do autoryzowanych użytkowników.

P: Jaka jest zalecana polityka wygaśnięcia pamięci podręcznej?
O: Przechowuj podglądy w pamięci podręcznej przez cały okres życia wersji dokumentu źródłowego. Gdy znacznik czasu ostatniej modyfikacji dokumentu się zmieni, unieważnij buforowany obraz i wygeneruj go ponownie.

Dodatkowe zasoby

Ostatnia aktualizacja: 2026-08-09
Testowano z: GroupDocs.Annotation 23.10 dla .NET
Autor: GroupDocs

Powiązane samouczki