Przeglądarka
Główna klasa przeglądarki dokumentów
Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z kontrolerów MVC, stron Web Forms i obsługujących handlerów. Jest to usługa przejściowa skomponowana przez DoconutHost.Initialize; rozwiąż ją tam, gdzie jej używasz:
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();new Viewer() działa również po uruchomieniu DoconutHost.Initialize — rozwiązuje te same usługi — co pozwala na kompilację kodu przeniesionego z klasycznego pakietu. Przed Initialize, zgłasza InvalidOperationException.
Viewer nie przechowuje stanu dokumentu per żądanie i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie od niego, więc zwolnienie Viewer nigdy nie zamknie otwartego dokumentu (zobacz How the Viewer Works).
OpenDocumentAsync
Otwiera dokument i zwraca token sesji, którego widżet używa przy każdym późniejszym żądaniu. Gdy UnsafeMode jest false (domyślnie), token jest przydzielany do sesji ASP.NET bieżącego żądania — wywołaj go z żądania, które ma stan sesji (zobacz Sessions & Security).
| 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 (przesyłanie, baza danych, blob). fileInfo musi mieć odpowiednie rozszerzenie — wybiera format |
// 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 przesłania (HttpPostedFileBase w MVC; HttpPostedFile w Web Forms)
using (var ms = new MemoryStream())
{
await file.InputStream.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}Wyjątki do obsłużenia:
LicenseException— licencja została znaleziona, ale odrzucona (wiadomość zawiera przyczynę), lub format wymaga możliwości wtyczki, której licencja nie przyznaje.FormatNotSupportedException— żaden podgląd nie obsługuje rozszerzenia pliku.InvalidDataException— zawartość jest uszkodzona lub nie pasuje do jej rozszerzenia.
OpenDocument (synchronous)
Dla kodu zaplecza Web Forms i innego kodu, który nie używa stron asynchronicznych:
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)Każdy zwraca token i dodatkowo przechowuje go w viewer.Token. fileName musi mieć odpowiednie rozszerzenie. Te opakowania są bezpieczne do wywołania z strony Web Forms: ścieżka otwarcia nigdy nie wznawia się w kontekście żądania ASP.NET, więc oczekiwanie na nią nie może spowodować zakleszczenia. To samo nie dotyczy każdego asynchronicznego API Doconut — zobacz sekcję Web Forms w Converter Plugin.
Zamknij dokument
void CloseDocument(string token)Usuwa sesję (natychmiast zwalniając silnik dokumentu), usuwa przyznanie tokenu z sesji ASP.NET bieżącego żądania i unieważnia token. Opcjonalnie — wygasanie przesuwne wykonuje tę samą operację czyszczenia — ale zalecane jest dla dużych dokumentów.
Zapytania sesji
| Członek | Zwraca |
|---|---|
int GetPageCount(string token) | Łączna liczba stron otwartego dokumentu |
(int Width, int Height) GetPageDimensions(string token, int page = 1) | Domyślny rozmiar renderowanej strony przy 100 % powiększeniu — przestrzeń współrzędnych dla adnotacji tworzonych w kodzie |
IReadOnlyList<string> GetWorksheetNames(string token) | Renderowane arkusze kalkulacyjne, w kolejności skoroszytu; puste dla innych dokumentów |
Każde zgłasza InvalidOperationException (Document session not found. Please re-open document.), jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.
Opcje dokumentu
Opcje niezależne od formatu, obowiązujące przy otwarciu (przestrzeń nazw Doconut):
| Typ | Właściwość | Domyślne | Opis |
|---|---|---|---|
string | Password | "" | Hasło do chronionych dokumentów (automatycznie kopiowane do konfiguracji formatu). |
string | Watermark | "" | Niestandardowy tekst znaku wodnego rysowany na renderowanych stronach — patrz poniżej. |
int | TimeOut | 60 | Przesuwne wygasanie sesji, w minutach. |
string | BrowserId | "" | Farmy sieciowe: przeglądarka, do której przypisany jest podpisany bilet. Ustaw ją za pomocą DoconutFarmBinding.EnsureBrowserId (zobacz Sesje i bezpieczeństwo). |
string | UserId | "" | Farmy sieciowe: zalogowany użytkownik, do którego przypisany jest bilet, pochodzący z DoconutFarmBinding.ResolveUserId. |
int | ImageResolution | 0 | Przestarzałe. Ustaw ImageResolution w konfiguracji formatu zamiast tego. |
bool | IsSecured | true | Zarezerwowane; nie wymuszane. Kontrola dostępu to DoconutOptions.UnsafeMode. |
bool | IsWebFarm / string WebFarmPath | false / "" | Zachowane dla kodu migrowanego z klasycznego pakietu. Nie włączają trybu farmy — AddDoconutDistributed robi. |
bool | EditMode | false | Zarezerwowane dla oddzielnie dystrybuowanego edytora; pozostaw false. |
Niestandardowy znak wodny
DocOptions.Watermark przyjmuje sześć 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 |
|---|---|---|
Leading ^ | ^ | Opcjonalny układ we wszystkich rogach. Bez niego używane jest normalne rozmieszczenie. |
| Text | Confidential | Tekst rysowany na każdej stronie. Nie może być pusty. |
| Color | Red | Nazwany kolor. |
| FontSize | 24 | Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje powrót do domyślnego. |
| FontName | Verdana | Rodzina czcionek. Musi być zainstalowana na serwerze — Windows Server ma mniej czcionek niż komputer stacjonarny. |
| Opacity | 80 | 0 do 255. Musi dawać się sparsować. |
| Angle | -45 | Obrót w stopniach; nieprawidłowa wartość numeryczna powoduje powrót do domyślnego. |
Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja jest zastępowana widocznym tekstem 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/licencja demonstracyjna | Nie | Czysta strona |
| Aktywna tymczasowa/licencja demonstracyjna | Tak | Niestandardowy znak wodny |
| Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domeny | Obie | Znak wodny ewaluacyjny; wartość niestandardowa go nie zastępuje |
Ta sama decyzja ma zastosowanie do serwowanych stron oraz eksportów adnotacji. Niestandardowy znak wodny jest funkcją licencjonowanej aplikacji, a nie sposobem na zastąpienie znaku wodnego ewaluacyjnego.
API adnotacji
Ładowanie i eksport adnotacji po stronie serwera. Przewodnik znajduje się w Adnotacje.
| 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 stworzone w C# do sesji |
void LoadAnnotationData(string token, string annotationData) | Wczytaj zakodowaną kopertę zwróconą 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)W tym pakiecie zawsze zwraca null, a żądanie metadanych widżetu odpowiada 501 Not Implemented: odczyt tagów DICOM nie jest dostępny w .NET Framework. Renderowanie DICOM — strony, klatki i animacje — działa. Zobacz Wtyczka DICOM.
Pomocnicy zasobów — ReferenceCss / ReferenceScripts
Emituj tagi <link> i <script> dla zasobów, które moduł zasobów udostępnia pod DoconutOptions.ResourcesPath, w kolejności zależności. Pliki funkcji zabezpieczonych licencją (Search, Annotation) są emitowane tylko gdy licencja je przyznaje.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + przeglądarka + wyszukiwanie + adnotacja
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; } // stan licencji, w celu ochrony kodu inicjalizacji wstążki
bool IsAnnotationEnabled { get; }Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).
Flagi ScriptConfig: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts i IncludeSearchBar (search-gated), IncludeAnnotationScripts i IncludeAnnotationBar (annotation-gated), EmitFeatureFlags (default true: also writes an inline window.Doconut.features = { search, annotation, editor } script; set it to false under a Content-Security-Policy that blocks inline script).
Oba zwracają HTML: zapisz je przy użyciu @Html.Raw(...) w MVC 5 (generuj je w kontrolerze — widoki nie mają @inject) lub <%= %> w Web Forms. Szybki start pokazuje oba.
RenderViewer
string RenderViewer(string elementId, string token, ViewerConfig? config = null)Zwraca blok <script>, który inicjalizuje widżet na elemencie o identyfikatorze elementId i wyświetla dokument: docViewer({...}) zbudowany z ViewerConfig (domyślnie: BasePath: '/', ResPath: 'doconut-res/images'), a następnie .View(token). Umieść go po skryptach podglądu. Wygenerowany skrypt nie przechowuje odniesienia do obiektu podglądu, więc strona z własnym paskiem narzędzi powinna ręcznie zainicjować widżet. Zobacz KonfiguracjaPodglądu.
Farma sieciowa
string? AccessToken przechowuje podpisany bilet wydany przy ostatnim otwarciu, gdy tryb rozproszony jest aktywny i UnsafeMode jest false; jest null na pojedynczym serwerze. Wyślij go do widżetu wraz z tokenem: objViewer.View(token, accessToken).
Czy ta strona była pomocna?