Przeglądarka

Główna klasa przeglądarki dokumentów

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z Razor pages, kontrolerów MVC, komponentów Blazor lub minimalnych API. Jest sealed, zarejestrowany jako usługa transient przez AddDoconut() i rozwiązywany przez 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 pojęcia → Jak działa przeglądarka).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego używa widżet kliencki 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 ono o wykryciu 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ł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 — 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 — wygasanie ze ślizgiem wykonuje tę samą operację czyszczenia — ale jest zalecane przy dużych dokumentach.

GetPageCount

text
int GetPageCount(string token)

Całkowita 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ększenia — przestrzeń współrzędnych dla adnotacji tworzonych w kodzie. page jest akceptowane dla zgodności; wynik to domyślne ustawienie 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.

Wymienione są tylko renderowane arkusze: ukryte i puste arkusze są pomijane, a gdy ExcelConfig.SheetNames ogranicza renderowanie, pojawiają się wyłącznie te arkusze. Jeden 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ć licencjonowany Ribbon tylko wtedy, gdy serwer faktycznie go udostępni — zobacz Szybki start.

DocOptions

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. Ciąg formatowania: "^Text~Color~FontSize~FontName~Opacity~Angle", np. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Przesuwany czas wygaśnięcia sesji w minutach.
boolIsSecuredtrueObecnie nie egzekwowane — zarezerwowane. Powiązanie tokenu jest kontrolowane globalnie przez DoconutOptions.UnsafeMode (zobacz Core Concepts → Sessions & Security).

Klasa udostępnia również specjalistyczne właściwości, które są celowo poza normalnym przepływem wyświetlania 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 wiodący ^ żą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
Wiodący ^^Opcjonalny układ we wszystkich rogach. Bez niego używany jest normalny układ znaku wodnego.
TekstConfidentialTekst renderowany na każdej stronie. Nie może być pusty.
KolorRedNazwany kolor rozumiany przez warstwę rysowania.
RozmiarCzcionki24Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje użycie domyślnego rozmiaru renderera.
NazwaCzcionkiVerdanaŻądana rodzina czcionek. Upewnij się, że jest zainstalowana w środowisku wdrożeniowym.
Krycie80Wartość bajtowa od 0 do 255. Musi się poprawnie parsować.
Kąt-45Kąt obrotu w stopniach; nieprawidłowa wartość numeryczna powoduje użycie domyślnego.

Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja jest zastępowana widoczną wartością zastępczą SDK 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
Aktywna tymczasowa/pokazowa przeglądarka bazowaNieCzysta strona przeglądarki bazowej
Aktywna tymczasowa/pokazowa przeglądarka bazowaTakNiestandardowy znak wodny, gdy stosowana jest czysta ścieżka przeglądarki bazowej
Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domenyDowolnaZnak wodny wymuszania/ewaluacji; wartość niestandardowa go nie nadpisuje
Renderowanie wtyczki według zasad ewaluacjiDowolnaZnak 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 Przewodnikach → Adnotacje; interfejs to:

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 zbudowane 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)Eksportuj 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)

Zwraca metadane tagów DICOM dla sesji otwartych 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 ograniczonych licencją, takich jak wyszukiwanie i adnotacje, są emitowane tylko gdy licencja je włącza, utrzymując interfejs użytkownika spójny z zachowaniem serwera.

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

Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ograniczone wyszukiwaniem), IncludeAnnotationCss (ograniczone adnotacjami).

Flagi ScriptConfig: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (ograniczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (ograniczone adnotacjami), EmitFeatureFlags (domyślnie true: także zapisuje wbudowany skrypt window.Doconut.features = { search, annotation, editor }; ustaw na false przy polityce Content‑Security‑Policy blokującej 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?