Przeglądarka

Główna klasa przeglądarki dokumentów

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z stron Razor, kontrolerów MVC, komponentów Blazor lub minimalnych API. Jest sealed, zarejestrowany jako usługa transient przez AddDoconut() i rozwiązywany poprzez wstrzykiwanie przez konstruktor — nigdy nie twórz go bezpośrednio.

Viewer nie przechowuje stanu per żądanie i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie w pamięci podręcznej sesji, więc zwolnienie usługi nigdy nie spowoduje zamknięcia otwartego dokumentu (zobacz Podstawowe koncepcje → Jak działa przeglądarka).

OpenDocumentAsync

Otwarcie dokumentu i zwraca token sesji, którego widget klienta używa we wszystkich kolejnych żądaniach.

PrzeciążenieKiedy używać
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Otwieranie z dysku z automatycznym wykrywaniem formatu i domyślną konfiguracją formatu
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Potrzebujesz opcji renderowania per format (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokument nie jest plikiem na dysku (upload, baza danych, blob). fileInfo musi zawierać prawidłowe rozszerzenie — decyduje o wykrywaniu formatu
csharp
// Proste otwarcie
string token = await viewer.OpenDocumentAsync(path);

// Z konfiguracją i opcjami dla każdego formatu
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Z przesyłki
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Wyjątki do obsłużenia:

  • LicenseException — znalezione licencje są odrzucane (wiadomość zawiera przyczynę odrzucenia) lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie kalendarza bez komunikatu o odrzuceniu skutkuje renderowaniem z znakiem wodnym zamiast wyrzucenia wyjątku.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia.

CloseDocument

text
void CloseDocument(string token)

Usuwa sesję z pamięci podręcznej (natychmiast zwalnia silnik dokumentu), usuwa znacznik bezpieczeństwa i cofa przyznany dostęp. Opcjonalnie — wygaszenie przesuwne wykonuje tę samą czynność czyszczenia — ale jest zalecane dla dużych dokumentów.

GetPageCount

text
int GetPageCount(string token)

Łączna liczba stron otwartej sesji. Rzuca InvalidOperationException (Document session not found. Please re-open document.) jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Domyślny rozmiar renderowanej strony dokumentu przy 100% powiększeniu — przestrzeń współrzędnych dla adnotacji tworzonych w kodzie. page jest akceptowane dla kompatybilności; wynik to domyślna wartość dokumentu. Rzuca InvalidOperationException (Document session not found. Please re-open document.) jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Zwraca nazwy arkuszy otwartego arkusza kalkulacyjnego, w kolejności skoroszytu, lub pustą listę, gdy otwarty dokument nie jest arkuszem kalkulacyjnym.

Wymieniane są tylko renderowane arkusze: ukryte i puste arkusze są pomijane, a gdy ExcelConfig.SheetNames ogranicza renderowanie, pojawiają się tylko te arkusze. Arkusz nie zawsze odpowiada jednej stronie — bardzo duży arkusz jest renderowany na kilku stronach. Rzuca InvalidOperationException (Document session not found. Please re-open document.) jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

Dodano w wersji 26.9.0.

Flagi możliwości

CzłonekZnaczenie
bool IsSearchEnabledObecna licencja przyznaje Search
bool IsAnnotationEnabledObecna licencja przyznaje Annotation

Użyj ich w widoku Razor, aby renderować licencjonowaną wstążkę tylko wtedy, gdy serwer faktycznie ją udostępni — zobacz Szybki start.

Opcje dokumentu

Opcje niezależne od formatu, obowiązujące przy każdym otwarciu (przestrzeń nazw Doconut):

TypWłaściwośćDomyślneOpis
stringPassword""Hasło do chronionych dokumentów (automatycznie kopiowane do konfiguracji formatu).
intImageResolution0Przestarzałe. Zachowane wyłącznie dla kompatybilności — zamiast tego ustaw ImageResolution w konfiguracji formatu.
stringWatermark""Niestandardowy tekst znaku wodnego rysowany na renderowanych stronach. Łańcuch formatowy: "^Text~Color~FontSize~FontName~Opacity~Angle", np. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Przesuwające się wygaśnięcie sesji w minutach.
boolIsSecuredtrueObecnie nie egzekwowane — zarezerwowane. Powiązanie tokena jest kontrolowane globalnie przez DoconutOptions.UnsafeMode (zobacz Podstawowe pojęcia → Sesje i bezpieczeństwo).

Klasa udostępnia również specjalistyczne właściwości, które są celowo poza normalnym przepływem przeglądania jednego hosta:

TypWłaściwośćDomyślneOpis
boolIsWebFarmfalsePrzestarzałe — nie ma efektu. Opublikuj dokument z DistributedDocumentPublisher.PublishAsync (lub IDistributedPublishQueue.EnqueueAsync) i zamiast tego ustaw FileShareConfig.RootPath.
stringWebFarmPath""Przestarzałe — nie ma efektu. Użyj FileShareConfig.RootPath zamiast tego.
boolEditModefalseZarezerwowane dla oddzielnie dystrybuowanego przepływu pracy Edytora; pozostaw false dla standardowego przeglądarki.

Niestandardowy znak wodny

DocOptions.Watermark używa sześciu pól oddzielonych tyldą. Opcjonalny początkowy ^ żąda układu we wszystkich rogach:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
PolePrzykładZnaczenie
Leading ^^Opcjonalny układ we wszystkich rogach. Bez niego używany jest normalny układ znaku wodnego.
TextConfidentialTekst renderowany na każdej stronie. Nie może być pusty.
ColorRedNazwany kolor rozumiany przez warstwę rysowania.
FontSize24Rozmiar czcionki; nieprawidłowy numeryczny input powoduje użycie domyślnego rozmiaru renderera.
FontNameVerdanaŻądana rodzina czcionek. Upewnij się, że jest zainstalowana w środowisku wdrożeniowym.
Opacity80Wartość bajtowa od 0 do 255. Musi zostać poprawnie sparsowana.
Angle-45Kąt obrotu w stopniach; nieprawidłowy numeryczny input powoduje użycie wartości domyślnej.

Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja jest zastępowana widoczną w SDK alternatywą Invalid Watermark zamiast cichego zniknięcia.

Decyzja licencyjna

Stan licencjiDostarczona wartość niestandardowaWynik renderowania
Ważna płatna licencja przeglądarkiNieCzysta strona
Ważna płatna licencja przeglądarkiTakNiestandardowy znak wodny
Aktywny tymczasowy/demonstracyjny podgląd bazowyNieCzysta strona bazowego podglądu
Aktywny tymczasowy/demonstracyjny podgląd bazowyTakNiestandardowy znak wodny, gdy stosowana jest czysta ścieżka bazowego podglądu
Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja z nieprawidłową domenąObieZnak wodny wymuszający/ewaluacyjny; wartość niestandardowa nie nadpisuje go
Renderowanie wtyczki zgodnie z zasadami ewaluacjiObieZnak wodny ewaluacji

Ta sama decyzja jest stosowana do serwowanych obrazów stron i eksportów adnotacji. Wyjście w formacie animowanego GIF jest znakowane klatka po klatce. Niestandardowy znak wodny jest więc funkcją licencjonowanej aplikacji, a nie sposobem na zastąpienie lub ukrycie znaku wodnego ewaluacji.

API adnotacji

Ładowanie i eksport adnotacji po stronie serwera. Pełny przewodnik znajduje się w Przewodniki → Adnotacje; interfejs wygląda następująco:

CzłonekCel
AnnotationManager GetAnnotationManager(string token)Menedżer powiązany z wymiarami strony otwartej sesji
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Menedżer z wyraźnie określonymi wymiarami strony
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Menedżer niezależny od sesji
void LoadAnnotationData(string token, AnnotationManager manager)Wczytaj adnotacje stworzone w C# do sesji
void LoadAnnotationData(string token, string annotationData)Wczytaj adnotacje z zakodowanej strony/envelopy Base64 zwróconej przez AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Wczytaj adnotacje z XML
XmlDocument GetAnnotationXML(string token)Wyeksportuj adnotacje sesji jako XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF z wtopionymi adnotacjami
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Jeden PNG na stronę, adnotacje wtopione, zapisane do directoryPath (utworzone, jeśli brak); zwraca liczbę zapisanych obrazów
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP z PNG‑ami per strona z wtopionymi adnotacjami

Metadane DICOM

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

Metoda jest dostępna w celu dopasowania API, ale przeglądarka DICOM .NET 6 nie może dostarczyć technicznych tagów. Zwraca null dla sesji DICOM i nie‑DICOM; w sesji DICOM dodatkowo wypisuje jednorazowe ostrzeżenie wyjaśniające ograniczenie platformy. Renderowanie stron, klatek i animacji pozostaje wspierane.

Pomocnicze zasoby — ReferenceCss / ReferenceScripts

Wygeneruj tagi <link>/<script> dla osadzonych zasobów serwowanych przez UseDoconutResources(), w prawidłowej kolejności zależności. Pakiety dla funkcji zabezpieczonych licencją, takich jak wyszukiwanie i adnotacje, są generowane tylko gdy licencja je włącza, utrzymując interfejs klienta spójny z zachowaniem serwera.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flagi: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (zabezpieczone wyszukiwaniem), IncludeAnnotationCss (zabezpieczone adnotacjami).

ScriptConfig flagi: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (zabezpieczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (zabezpieczone adnotacjami), EmitFeatureFlags (domyślnie true: również zapisuje wbudowany skrypt window.Doconut.features = { search, annotation, editor }; ustaw na false w ramach Content-Security-Policy, które blokuje wbudowane skrypty).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Czy ta strona była pomocna?