ビューア
メイン ドキュメント ビューア クラス
Viewer (namespace Doconut) は、Razor ページ、MVC コントローラー、Blazor コンポーネント、または最小限の API からドキュメントを開くための公開エントリーポイントです。sealed で、AddDoconut() によって transient サービスとして登録され、コンストラクタ インジェクションで解決されます — 直接インスタンス化しないでください。
Viewer はリクエストごとの状態を保持せず、意図的に not IDisposable を実装しません: ドキュメント セッションはセッション キャッシュ内で独立して存在するため、サービスを破棄しても開かれたドキュメントが削除されることはありません(Core Concepts → How the Viewer Works を参照)。
OpenDocumentAsync
ドキュメントを開き、クライアント ウィジェットが以降のすべてのリクエストで使用するセッショントークンを返します。
| オーバーロード | 使用シーン |
|---|---|
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default) | 自動フォーマット検出とフォーマットのデフォルト設定でディスクから開く |
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default) | フォーマットごとのレンダリングオプションが必要な場合(PdfConfig、WordConfig、…) |
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default) | ドキュメントがディスク上のファイルではありません(アップロード、データベース、ブロブ)。fileInfo は正しい拡張子を持っている必要があります — それがフォーマット検出を行います |
// 簡単に開く
string token = await viewer.OpenDocumentAsync(path);
// フォーマット別の設定とオプション
token = await viewer.OpenDocumentAsync(
path,
new PdfConfig { AllowSearch = true, AllowCopy = true },
new DocOptions { TimeOut = 30 });
// アップロードから
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));対処すべき例外:
LicenseException— 見つかったライセンスが拒否された場合(メッセージに拒否理由が含まれます)、またはフォーマットがもはや付与されていないプラグイン機能を必要とする場合。拒否メッセージなしのカレンダー期限切れは、例外をスローする代わりに透かし付きレンダリングにフォールバックします。FormatNotSupportedException—Document format '<extension>' is not supported.InvalidDataException— ファイル内容が破損しているか、拡張子と一致しません。
CloseDocument
void CloseDocument(string token)キャッシュからセッションを削除し(ドキュメント エンジンを即座に破棄)、セキュリティ マーカーを削除し、アクセス権を取り消します。オプションとして、スライディング有効期限も同様のクリーンアップを行います — ただし大きなドキュメントには推奨されます。
GetPageCount
int GetPageCount(string token)開かれたセッションの総ページ数です。トークンが不明または期限切れの場合は InvalidOperationException(Document session not found. Please re-open document.)がスローされ、空のトークンの場合は ArgumentException がスローされます。
GetPageDimensions
(int Width, int Height) GetPageDimensions(string token, int page = 1)ドキュメントのデフォルトのレンダリングページサイズ(100% ズーム)です — コード内で構築されたアノテーション用の座標空間。互換性のために page が受け入れられます;結果はドキュメントのデフォルトです。トークンが不明または期限切れの場合は InvalidOperationException(Document session not found. Please re-open document.)がスローされ、空のトークンの場合は ArgumentException がスローされます。
GetWorksheetNames
IReadOnlyList<string> GetWorksheetNames(string token)開かれたスプレッドシートのワークシート名をブック順で返します。開かれたドキュメントがスプレッドシートでない場合は空のリストを返します。
レンダリングされたワークシートのみが一覧表示されます。非表示および空のワークシートは除外され、ExcelConfig.SheetNames がレンダリングを制限している場合は、そのワークシートだけが表示されます。ワークシートは必ずしも 1 ページとは限らず、非常に大きいものは複数ページにまたがってレンダリングされます。トークンが不明または期限切れの場合は InvalidOperationException(Document session not found. Please re-open document.)がスローされ、空のトークンの場合は ArgumentException がスローされます。
26.9.0 で追加
機能フラグ
| メンバー | 意味 |
|---|---|
bool IsSearchEnabled | 現在のライセンスは Search を付与します |
bool IsAnnotationEnabled | 現在のライセンスは Annotation を付与します |
これらを Razor ビューで使用して、サーバーが実際に提供する場合にのみ、ライセンスされたリボンをレンダリングします — クイックスタート を参照してください。
DocOptions
オープンごとに使用できる、フォーマットに依存しないオプション(名前空間 Doconut):
| 型 | プロパティ | デフォルト | 説明 |
|---|---|---|---|
string | Password | "" | 保護されたドキュメントのパスワード(自動的にフォーマット設定にコピーされます)。 |
int | ImageResolution | 0 | 廃止予定。 互換性のためだけに保持されています — 代わりにフォーマット設定で ImageResolution を設定してください。 |
string | Watermark | "" | レンダリングされたページに描画されるカスタム透かしテキスト。書式文字列: "^Text~Color~FontSize~FontName~Opacity~Angle"、例: "^Sample Copy~Red~24~Verdana~80~-45"。 |
int | TimeOut | 60 | セッションのスライディング有効期限(分単位)。 |
bool | IsSecured | true | 現在は適用されていません — 予約されています。トークンバインディングは DoconutOptions.UnsafeMode によってグローバルに制御されます(Core Concepts → Sessions & Security を参照)。 |
このクラスは、意図的に通常のシングルホスト閲覧フローの外にある、特化したプロパティも公開しています:
| 型 | プロパティ | デフォルト | 説明 |
|---|---|---|---|
bool | IsWebFarm | false | 廃止予定 — 効果なし。 ドキュメントを DistributedDocumentPublisher.PublishAsync(または IDistributedPublishQueue.EnqueueAsync)で公開し、代わりに FileShareConfig.RootPath を設定してください。 |
string | WebFarmPath | "" | 廃止予定 — 効果なし。 代わりに FileShareConfig.RootPath を使用してください。 |
bool | EditMode | false | 別途配布されるエディタワークフロー用に予約されています;標準ビューア用に false を残してください。 |
カスタム透かし
DocOptions.Watermark は6つのチルダ区切りフィールドを使用します。オプションの先頭 ^ は全角レイアウトを要求します:
^Text~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| フィールド | 例 | 意味 |
|---|---|---|
Leading ^ | ^ | オプションの全角レイアウト。これがない場合、通常の透かし配置が使用されます。 |
| Text | Confidential | 各ページに描画されるテキスト。空であってはなりません。 |
| Color | Red | 描画レイヤーが理解できる名前付きカラー。 |
| FontSize | 24 | フォントサイズ。数値が無効な場合はレンダラのデフォルトにフォールバックします。 |
| FontName | Verdana | 要求されたフォントファミリー。デプロイ環境にインストールされていることを確認してください。 |
| Opacity | 80 | 0から255までのバイト値。正しく解析できる必要があります。 |
| Angle | -45 | 度単位の回転角度。数値が無効な場合はデフォルトにフォールバックします。 |
パーサーはオプションの ^ の後に正確に6つのフィールドがあることを期待します。無効な定義は、黙って消える代わりに SDK の可視 Invalid Watermark フォールバックに置き換えられます。
ライセンスの判断
| ライセンス状態 | カスタム値が提供されたか | レンダリング結果 |
|---|---|---|
| 有効な有料ビューアライセンス | なし | クリーンページ |
| 有効な有料ビューアライセンス | あり | カスタム透かし |
| アクティブな一時/デモベースビューア | なし | クリーンベースビューアページ |
| アクティブな一時/デモベースビューア | あり | クリーンベースビューアパスが適用されるときのカスタム透かし |
| 欠損、拒否、期限切れ、バージョン不一致、または無効ドメインのライセンス | どちらでも | 強制/評価透かし;カスタム値は上書きできません |
| 評価ルール下のプラグインレンダリング | どちらでも | 評価透かし |
アノテーション API
サーバー側のアノテーションのロードとエクスポートです。完全な手順は Guides → Annotations にあります。インターフェースは次のとおりです:
| メンバー | 目的 |
|---|---|
AnnotationManager GetAnnotationManager(string token) | 開いているセッションのページ寸法にバインドされたマネージャー |
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight) | 明示的なページ寸法を持つマネージャー |
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight) | セッションに依存しないマネージャー |
void LoadAnnotationData(string token, AnnotationManager manager) | C# で作成されたアノテーションをセッションにロードする |
void LoadAnnotationData(string token, string annotationData) | AnnotationManager.GetAnnotationData() が返すエンコードされたページ/Base64 エンベロープからアノテーションをロードする |
void LoadAnnotationXML(string token, XmlDocument annotationXml) | XML からアノテーションをロードする |
XmlDocument GetAnnotationXML(string token) | セッションのアノテーションを XML としてエクスポートする |
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default) | アノテーションが埋め込まれた PDF |
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default) | ページごとに 1 つの PNG、アノテーションが埋め込まれ、directoryPath に書き込まれます(存在しない場合は作成)。書き込まれた画像数を返します |
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default) | アノテーションが埋め込まれたページごとの PNG の ZIP |
DICOM メタデータ
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)このメソッドは API の整合性のために存在しますが、.NET 6 DICOM ビューアは技術タグを提供できません。DICOM セッションと非 DICOM セッションの両方で null を返します。DICOM セッションの場合、プラットフォームの制限を説明する一度だけの警告も出力します。ページ、フレーム、アニメーションのレンダリングは引き続きサポートされています。
リソースヘルパー — ReferenceCss / ReferenceScripts
UseDoconutResources() が提供する埋め込みリソース用に <link>/<script> タグを正しい依存順序で出力します。検索やアノテーションなど、ライセンスで制御される機能のバンドルは、ライセンスが有効な場合にのみ 出力され、クライアント UI をサーバーの動作と一致させます。
string ReferenceCss(CssConfig? config = null) // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)CssConfig フラグ: IncludeBootstrapCss、IncludeViewerCss、IncludeSearchCss(検索制御)、IncludeAnnotationCss(アノテーション制御)。
ScriptConfig フラグ: IncludeJQuery(すべての他に必須)、IncludeBootstrap、IncludeViewerScripts(コア: docViewer.js + スプリッタ + リンク)、IncludeSearchScripts と IncludeSearchBar(検索制御)、IncludeAnnotationScripts と IncludeAnnotationBar(アノテーション制御)、EmitFeatureFlags(デフォルト true:インライン window.Doconut.features = { search, annotation, editor } スクリプトも書き込みます。インラインスクリプトをブロックする Content-Security-Policy の下では false に設定してください)。
@inject Doconut.Viewer Viewer
@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))このページは役に立ちましたか?