ビューア
メインのドキュメントビューアクラス
Viewer (namespace Doconut) は、Razor ページ、MVC コントローラー、Blazor コンポーネント、または最小限の API からドキュメントを開くための公開エントリーポイントです。AddDoconut() によって sealed、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) | ドキュメントがディスク上のファイルではありません(アップロード、データベース、Blob)。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
});| フィールド | 例 | 意味 |
|---|---|---|
先頭^ | ^ | オプションの全コーナーレイアウト。これがない場合、通常の透かし配置が使用されます。 |
| テキスト | Confidential | 各ページに描画されるテキスト。空であってはなりません。 |
| 色 | Red | 描画レイヤーが理解できる名前付きカラー。 |
| フォントサイズ | 24 | フォントサイズ;無効な数値入力はレンダラのデフォルトにフォールバックします。 |
| フォント名 | Verdana | 要求されたフォントファミリー。デプロイ環境にインストールされていることを確認してください。 |
| 不透明度 | 80 | 0から255のバイト値。正しく解析できる必要があります。 |
| 角度 | -45 | 度単位の回転角度;無効な数値入力はデフォルトにフォールバックします。 |
パーサーはオプションの^の後に正確に6つのフィールドがあることを期待します。無効な定義は、黙って消える代わりにSDKの可視Invalid Watermarkフォールバックに置き換えられます。
ライセンス判定
| ライセンス状態 | カスタム値が提供されたか | レンダリング結果 |
|---|---|---|
| 有効な有料ビューアライセンス | いいえ | クリーンページ |
| 有効な有料ビューアライセンス | はい | カスタム透かし |
| アクティブな一時/デモベースビューア | いいえ | クリーンベースビューアページ |
| アクティブな一時/デモベースビューア | はい | クリーンベースビューアパスが適用される場合のカスタム透かし |
| 欠落、拒否、期限切れ、バージョン不一致、または無効ドメインのライセンス | いずれか | 強制/評価透かし;カスタム値は上書きできません |
| 評価ルール下のプラグインレンダリング | いずれか | 評価透かし |
同じ判定が配信されるページ画像およびアノテーションのエクスポートにも適用されます。アニメーションGIF出力はフレームごとにスタンプが付けられます。したがって、カスタム透かしは評価透かしを置き換えたり抑制したりする手段ではなく、ライセンスされたアプリケーション機能です。
アノテーション 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)DICOM プラグインを通じて開かれたセッションの DICOM タグメタデータを返します。非 DICOM ドキュメントの場合は null です。
リソースヘルパー — 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 }))このページは役に立ちましたか?