Przeglądarka

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‑request i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie w pamięci podręcznej sesji, więc zwolnienie usługi nigdy nie zamknie otwartego dokumentu (zobacz Podstawowe koncepcje → Jak działa przeglądarka).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widget kliencki używa we wszystkich kolejnych żądaniach.

// 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łania
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 — znaleziona licencja jest odrzucona (wiadomość zawiera przyczynę odrzucenia) lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie kalendarza bez wiadomości o odrzuceniu skutkuje renderowaniem z znakami wodnymi zamiast wyrzucenia wyjątku.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia.

CloseDocument

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 — wygasanie przesuwne wykonuje tę samą czynność czyszczenia — ale jest zalecane dla dużych dokumentów.

GetPageCount

int GetPageCount(string token)

Łączna liczba stron otwartej sesji. Rzuca wyjątek, jeśli token jest nieznany lub wygasł.

DocOptions

Opcje niezależne od formatu, obowiązujące przy otwieraniu (namespace Doconut):

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

Niestandardowy znak wodny

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

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

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

Decyzja licencyjna

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ą aplikacji objętą licencją, 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:

Metadane DICOM

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

Zwraca metadane tagów DICOM dla sesji otwieranych przez wtyczkę DICOM; null dla dokumentów nie‑DICOM.

Pomocnicy zasobów — ReferenceCss / ReferenceScripts

Emituj 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ą emitowane tylko gdy licencja je umożliwia, utrzymując spójność UI klienta z zachowaniem serwera.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + przeglądarka + wyszukiwanie + adnotacja
string ReferenceScripts(ScriptConfig? config = null)

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

ScriptConfig flagi: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (zabezpieczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (zabezpieczone adnotacją).

@inject Doconut.Viewer Viewer

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

GetWorksheetNames

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.

Dodano w wersji 26.9.0.