Visare
Den huvudsakliga dokumentvisarklassen
Viewer (namespace Doconut) är den offentliga ingångspunkten för att öppna dokument från Razor‑sidor, MVC‑kontroller, Blazor‑komponenter eller minimal‑API:er. Den är sealed, registrerad som en transient‑tjänst av AddDoconut(), och löses upp via konstruktor‑injektion — skapa den aldrig direkt.
Viewer har ingen per‑begäran‑stat och implementerar avsiktligt inte IDisposable: dokumentsessioner lever oberoende i sessionscachen, så att avyttra tjänsten aldrig kan stänga ett öppet dokument (se Core Concepts → Hur Visaren fungerar).
OpenDocumentAsync – Öppna dokument asynkront
Öppnar ett dokument och returnerar sessionstoken som klientwidgeten använder för alla efterföljande begäran.
| Överlagring | Använd när |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | Öppning från disk med automatisk formatdetektering och formatets standardkonfiguration |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | Du behöver per‑format renderingsalternativ (PdfConfig, WordConfig, …) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | Dokumentet är inte en fil på disk (uppladdning, databas, blob). fileInfo måste ha rätt filändelse — den styr formatdetektering |
// Enkel öppning
string token = await viewer.OpenDocumentAsync(path);
// Med per-format konfiguration och alternativ
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// Från en uppladdning
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));Undantag att hantera:
LicenseException— en hittad licens avvisas (meddelandet innehåller avvisningsorsaken), eller så kräver formatet en plugin‑funktion som inte längre beviljas. Kalenderutgång utan avvisningsmeddelande degraderas till vattenstämpelrendering istället för att kasta ett undantag.FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— filinnehållet är korrupt eller matchar inte dess filändelse.
CloseDocument – Stäng dokument
void CloseDocument(string token)Tar bort sessionen från cachen (avyttrar dokumentmotorn omedelbart), raderar säkerhetsmarkören och återkallar åtkomstbehörigheten. Valfritt — glidande utgång utför samma städning — men rekommenderas för stora dokument.
GetPageCount – Hämta sidantal
int GetPageCount(string token)Totalt antal sidor i den öppna sessionen. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.
GetPageDimensions – Hämta siddimensioner
(int Width, int Height) GetPageDimensions(string token, int page = 1)Dokumentets standardrenderade sidstorlek vid 100 % zoom — koordinatrymden för annotationer byggda i kod. page accepteras för kompatibilitet; resultatet är dokumentets standard. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.
GetWorksheetNames – Hämta bladnamn
IReadOnlyList<string> GetWorksheetNames(string token)Returnerar bladnamnen i ett öppet kalkylblad, i arbetsboksordning, eller en tom lista när det öppna dokumentet inte är ett kalkylblad.
Endast renderade blad listas: dolda och tomma blad exkluderas, och när ExcelConfig.SheetNames begränsar rendering visas endast de bladen. Ett blad är inte alltid en sida — ett mycket stort blad renderas över flera sidor. Kastar InvalidOperationException (Document session not found. Please re-open document.) om token är okänd eller har gått ut, och ArgumentException för en tom token.
Tillagt i 26.9.0.
Funktionsflaggor
| Medlem | Betydelse |
|---|---|
bool IsSearchEnabled | Den aktuella licensen beviljar Search |
bool IsAnnotationEnabled | Den aktuella licensen beviljar Annotation |
Använd dessa i en Razor‑vy för att rendera ett licensierat Ribbon endast när servern faktiskt kommer att leverera det — se Snabbstart.
DocOptions
Per öppning, formatoberoende alternativ (namnrymd Doconut):
| Typ | Egenskap | Standard | Beskrivning |
|---|---|---|---|
string | Password | "" | Lösenord för skyddade dokument (kopieras automatiskt till formatkonfigurationen). |
int | ImageResolution | 0 | Föråldrad. Behålls endast för kompatibilitet — ställ in ImageResolution i formatkonfigurationen istället. |
string | Watermark | "" | Anpassad vattenstämpeltext som ritas på renderade sidor. Formatsträng: "^Text~Color~FontSize~FontName~Opacity~Angle", t.ex. "^Sample Copy~Red~24~Verdana~80~-45". |
int | TimeOut | 60 | Sessionens glidande utgång i minuter. |
bool | IsSecured | true | Ej för närvarande verkställd — reserverad. Tokenbindning styrs globalt av DoconutOptions.UnsafeMode (se Kärnkoncept → Sessioner & Säkerhet). |
Klassen exponerar också specialiserade egenskaper som avsiktligt ligger utanför det normala enkla värdflödet:
| Typ | Egenskap | Standard | Beskrivning |
|---|---|---|---|
bool | IsWebFarm | false | Föråldrad — har ingen effekt. Publicera dokumentet med DistributedDocumentPublisher.PublishAsync (eller IDistributedPublishQueue.EnqueueAsync) och ställ in FileShareConfig.RootPath istället. |
string | WebFarmPath | "" | Föråldrad — har ingen effekt. Använd FileShareConfig.RootPath istället. |
bool | EditMode | false | Reserverad för det separat distribuerade Editor‑arbetsflödet; lämna false för standardvisaren. |
Anpassad vattenstämpel
DocOptions.Watermark använder sex tilde‑separerade fält. En valfri inledande ^ begär layout med alla hörn:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Fält | Exempel | Betydelse |
|---|---|---|
Inledande ^ | ^ | Valfri layout med alla hörn. Utan den används normal placering av vattenstämpeln. |
| Text | Confidential | Text som renderas på varje sida. Den får inte vara tom. |
| Färg | Red | Namngiven färg som förstås av ritlagret. |
| FontSize | 24 | Teckenstorlek; ogiltig numerisk inmatning faller tillbaka på renderarens standard. |
| FontName | Verdana | Begärd typsnittsfamilj. Säkerställ att den är installerad i driftsmiljön. |
| Opacity | 80 | Byte‑värde från 0 till 255. Det måste kunna parsas korrekt. |
| Angle | -45 | Rotationsvinkel i grader; ogiltig numerisk inmatning faller tillbaka på standardvärdet. |
Parsern förväntar sig exakt sex fält efter den valfria ^. En ogiltig definition ersätts av SDK:ns synliga Invalid Watermark‑fallback istället för att tyst försvinna.
Licensbeslut
| Licensstatus | Anpassat värde tillhandahållet | Renderat resultat |
|---|---|---|
| Giltig betald visningslicens | Nej | Ren sida |
| Giltig betald visningslicens | Ja | Anpassad vattenstämpel |
| Aktiv tillfällig/demo-basvisare | Nej | Ren bas‑visarsida |
| Aktiv tillfällig/demo-basvisare | Ja | Anpassad vattenstämpel när den rena bas‑visarvägen gäller |
| Saknad, avvisad, utgången, fel version eller ogiltig domänlicens | Båda | Genomdrifts-/utvärderingsvattenstämpel; det anpassade värdet åsidosätter den inte |
| Plugin‑rendering under utvärderingsregler | Båda | Utvärderingsvattenstämpel |
Samma beslut tillämpas på levererade sidbilder och export av annotationer. Animerad GIF‑utdata märks bildruta för bildruta. En anpassad vattenstämpel är därför en licensierad applikationsfunktion, inte ett sätt att ersätta eller undertrycka utvärderingsvattenstämpeln.
Annotations-API
Server‑sidig inläsning och export av annotationer. Den fullständiga genomgången finns i Guider → Annotations; gränssnittet är:
| Medlem | Syfte |
|---|---|
AnnotationManager GetAnnotationManager(string token) | Manager bunden till den öppna sessionens siddimensioner |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | Manager med explicita siddimensioner |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | Sessionsoberoende manager |
void LoadAnnotationData(string token, AnnotationManager manager) | Läs in annotationer byggda i C# i sessionen |
void LoadAnnotationData(string token, string annotationData) | Läs in annotationer från den kodade sida/Base64‑omslaget som returneras av AnnotationManager.GetAnnotationData() |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | Läs in annotationer från XML |
XmlDocument GetAnnotationXML(string token) | Exportera sessionens annotationer som XML |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | PDF med inbrända annotationer |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | En PNG per sida, annotationer inbrända, skrivs till directoryPath (skapas om den saknas); returnerar antalet skrivna bilder |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | ZIP med PNG‑filer per sida med inbrända annotationer |
DICOM-metadata
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)Returnerar DICOM‑taggmetadata för sessioner som öppnats via DICOM‑pluginet; null för icke‑DICOM‑dokument.
Resurs‑hjälpare — ReferenceCss / ReferenceScripts
Generera <link>/<script>‑taggarna för de inbäddade resurserna som levereras av UseDoconutResources(), i korrekt beroendeordning. Paket för licensstyrda funktioner såsom sökning och annotation genereras endast när licensen aktiverar dem, så att klient‑UI:n förblir i linje med serverbeteendet.
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + visare + sök + annotering
string ReferenceScripts(ScriptConfig? config = null)CssConfig‑flaggor: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (sökning‑styrd), IncludeAnnotationCss (annotation‑styrd).
ScriptConfig‑flaggor: IncludeJQuery (krävs av alla andra), IncludeBootstrap, IncludeViewerScripts (kärna: docViewer.js + splitter + länkar), IncludeSearchScripts och IncludeSearchBar (sökning‑styrd), IncludeAnnotationScripts och IncludeAnnotationBar (annotation‑styrd), EmitFeatureFlags (standard true: skriver också ett inbäddat window.Doconut.features = { search, annotation, editor }‑skript; sätt den till false under en Content‑Security‑Policy som blockerar inbäddade skript).
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))Var den här sidan hjälpsam?