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ążenie | Kiedy 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 |
// 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
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
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
(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
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łonek | Znaczenie |
|---|---|
bool IsSearchEnabled | Obecna licencja przyznaje Search |
bool IsAnnotationEnabled | Obecna 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):
| Typ | Właściwość | Domyślne | Opis |
|---|---|---|---|
string | Password | "" | Hasło do chronionych dokumentów (automatycznie kopiowane do konfiguracji formatu). |
int | ImageResolution | 0 | Przestarzałe. Zachowane wyłącznie dla kompatybilności — zamiast tego ustaw ImageResolution w konfiguracji formatu. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Przesuwany czas wygaśnięcia sesji w minutach. |
bool | IsSecured | true | Obecnie 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:
| Typ | Właściwość | Domyślne | Opis |
|---|---|---|---|
bool | IsWebFarm | false | Przestarzałe — nie ma efektu. Opublikuj dokument z DistributedDocumentPublisher.PublishAsync (lub IDistributedPublishQueue.EnqueueAsync) i zamiast tego ustaw FileShareConfig.RootPath. |
string | WebFarmPath | "" | Przestarzałe — nie ma efektu. Użyj FileShareConfig.RootPath zamiast tego. |
bool | EditMode | false | Zarezerwowane 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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Pole | Przykład | Znaczenie |
|---|---|---|
Wiodący ^ | ^ | Opcjonalny układ we wszystkich rogach. Bez niego używany jest normalny układ znaku wodnego. |
| Tekst | Confidential | Tekst renderowany na każdej stronie. Nie może być pusty. |
| Kolor | Red | Nazwany kolor rozumiany przez warstwę rysowania. |
| RozmiarCzcionki | 24 | Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje użycie domyślnego rozmiaru renderera. |
| NazwaCzcionki | Verdana | Żądana rodzina czcionek. Upewnij się, że jest zainstalowana w środowisku wdrożeniowym. |
| Krycie | 80 | Wartość bajtowa od 0 do 255. Musi się poprawnie parsować. |
| Kąt | -45 | Ką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 licencji | Dostarczona wartość niestandardowa | Wynik renderowania |
|---|---|---|
| Ważna płatna licencja przeglądarki | Nie | Czysta strona |
| Ważna płatna licencja przeglądarki | Tak | Niestandardowy znak wodny |
| Aktywna tymczasowa/pokazowa przeglądarka bazowa | Nie | Czysta strona przeglądarki bazowej |
| Aktywna tymczasowa/pokazowa przeglądarka bazowa | Tak | Niestandardowy znak wodny, gdy stosowana jest czysta ścieżka przeglądarki bazowej |
| Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domeny | Dowolna | Znak wodny wymuszania/ewaluacji; wartość niestandardowa go nie nadpisuje |
| Renderowanie wtyczki według zasad ewaluacji | Dowolna | Znak 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łonek | Cel |
|---|---|
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
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.
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).
@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?