クイックスタート

数分で最初のドキュメントをレンダリング

このウォークスルーは、空の Program.cs からブラウザでレンダリングされたドキュメントへと ASP.NET Core アプリを導きます:サーバー登録、完全な Viewer パッケージ(Viewer ツールバー、Viewer マウント、オプションの検索/注釈リボン)、アセット参照、クライアント初期化、ドキュメントのオープン、そして実行。

サーバー設定

AddDoconut() はサービスを登録します; UseDoconutResources() と UseDoconut() はミドルウェアを接続します。リソース呼び出しは最初に行う必要があります。UseDoconut() は到達したすべてのリクエストに応答するので、app.Map を使用して独自のブランチにマウントしてください。セッション呼び出しも必要です — Doconut のデフォルトドキュメントセキュリティは、すべてのページリクエストを ASP.NET セッション状態と照合して検証します。セッション状態にはキャッシュが必要です:AddDistributedMemoryCache() がそれを提供します。MVC または Razor Pages アプリはすでに登録されていますが、最小 API アプリは登録されておらず、Unable to resolve service for type 'IDistributedCache' が発生して起動時に停止します。すでに インストール 中に Doconut を登録しましたか?次のセクションへ進んでください。

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // セッション状態にはキャッシュが必要です(MVC/Razor Pages はすでに追加されています)
builder.Services.AddSession(); // Doconut ドキュメント セキュリティは ASP.NET セッション状態に依存しています

app.UseSession();          // UseDoconut() の前に UseSession() を呼び出してください
app.UseDoconutResources(); // UseDoconut() の前に登録する必要があります
app.Map("/doconut", branch => branch.UseDoconut());

本番環境スタイルのパスレイアウトの場合、ドキュメントミドルウェアを明示的なブランチにマッピングし、4 つのパス設定を揃えておきます:

csharp
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false;
});
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

app.UseRouting();
app.UseSession();
app.UseDoconutResources();
app.Map("/doconut", branch => branch.UseDoconut());

MiddlewarePath は調整値です;それ自体では ASP.NET Core のブランチをマッピングしません。この例ではホストが /doconut をマッピングするので、クライアントは BasePath: 'doconut' を使用します。ResourcesPath は埋め込みバンドルを /doconut-res で提供し、ウィジェットの画像リソースパスはそのため ResPath: 'doconut-res/images' になります。先頭のスラッシュなしで両方を書いてください:ビューアは自動的にスラッシュを付加するため、'/doconut' は //doconut/DocImage.axd になり、ブラウザはそれを doconut というホストへのリクエストとして解釈し、ビューアは「The viewer handler could not be reached」というエラーで失敗します。

ページにビューアを追加

Viewer はページに必須のコアです。そのレンダリングサーフェスは 2 つの入れ子になった div を使用します:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

ツールバー、モジュールマウント、Viewer サーフェスを 1 つのページ構成として扱います。Search と
Annotation は埋め込みリボンをオプションのマウントに注入しますが、これらのモジュールは決して
単独では使用されません:常に同じページ上の Viewer に接続されます。この順序で使用してください:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer のナビゲーション、ズーム、検索、アノテーション ボタン -->
</nav>

<div id="searchBarMount"></div>
<div id="annBarMount"></div>

<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

ビューアアセットの参照

Razor ビューでは、注入された Viewer サービスが依存順序でビューアの <link> と <script> タグを出力します — ウィジェットは jQuery プラグインなので、viewer スクリプトの前に jQuery をロードする必要があります:

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss = true,
    IncludeViewerCss    = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery        = true,
    IncludeBootstrap     = true,
    IncludeViewerScripts = true
}))

完全な Viewer パッケージを取得するには、Viewer とモジュールリソースを一緒にリクエストします:

html
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
    IncludeBootstrapCss  = true,
    IncludeViewerCss     = true,
    IncludeSearchCss     = true,
    IncludeAnnotationCss = true
}))

@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
    IncludeJQuery             = true,
    IncludeBootstrap         = true,
    IncludeViewerScripts     = true,
    IncludeSearchScripts     = true,
    IncludeSearchBar         = true,
    IncludeAnnotationScripts = true,
    IncludeAnnotationBar     = true
}))

IncludeViewerCss と IncludeViewerScripts は必須のコアフラグです。これら、Viewer マウント、そして docViewer
インスタンスがない状態で Search または Annotation Ribbon の例を公開しないでください。ReferenceCss と ReferenceScripts は、現在のライセンスがその機能を許可していない場合にオプションモジュールのリソースを省略します;コア Viewer はそれでも起動します。

ビューアの初期化

クライアント側ウィジェットは jQuery プラグインです。これは実際の初期化オプションの最小セットです(疑似コードではありません):

javascript
let searchBar = null;
let annBar = null;

const objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   'doconut',             // 先頭に '/' がありません
    ResPath:    'doconut-res/images',  // 先頭に '/' がありません
    onViewerReady: function () {
        // ページが表示されています; ここでロードスピナーを非表示にしても安全です
    },
    // 埋め込みリボンが存在する場合、アノテーションのライフサイクルイベントを転送します
    onAnnLoaded:    () => annBar?.handleAnnLoaded(),
    onAnnSaved:     () => annBar?.handleAnnSaved(),
    onAnnSaveError: () => annBar?.handleAnnSaveError(),
    onAnnClosed:    () => annBar?.handleAnnClosed(),
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

オプションのケースは実際に混在しています — showThumbs、autoLoad、pageZoom は camelCase ですが、FitType、BasePath、ResPath は PascalCase です。一貫したルールはなく、ケースが間違っているとオプションは黙って無視されます(ウィジェットは例外を投げる代わりにデフォルトにフォールバックします)。

さらに4つの詳細はエラーメッセージなしで失敗します:

  • BasePath に先頭スラッシュがありません。 'doconut' は /doconut/DocImage.axd をリクエストし、'/doconut' は //doconut/DocImage.axd を生成します。ブラウザはこれを別ホストへのリクエストとして読み取ります。
  • ResPath: 'doconut-res/images' — アイコンはリソースルートの1つ下のフォルダーにあります。'doconut-res' を使用すると、すべてのアイコンが 404 を返し、ツールバーのグリフもロードスピナーも表示されませんが、ドキュメント自体はまだレンダリングされます。先頭スラッシュは BasePath と同様に壊します。
  • コールバックはオプションです。 onViewerReady、onError およびその他は docViewer(...) に渡されるオブジェクトに入れます。ビューア名のグローバル関数(例:ctlDoc_ViewerReady)は決して呼び出されません。
  • ビューアを保持し、View を別途呼び出します。 docViewer(...) は Zoom、Next、FitType を含むオブジェクトを返します。View(...) は別のものを返します。var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) はドキュメントをレンダリングしますが、最初のツールバークリックで objViewer.Zoom is not a function に失敗します。

完全な Viewer パッケージの組み立て

完全なビューアページは以下の部品をまとめてインストールします:

パッケージの部品要件接続方法
Viewer リソース、マウント、および objViewer必須コアドキュメントレンダラ
Viewer ツールバー完全なページに必須ホストマークアップ;ボタンは同じ objViewer を呼び出す
検索リボンオプション、ライセンスモジュールdoconutSearchBar(...).attach(objViewer)
注釈リボンオプション、ライセンスモジュールdoconutAnnotationBar(...).attach(objViewer)

メインの Viewer ツールバーはホストマークアップですが、Viewer と共にインストールされ、
単独のコントロールとして文書化してはなりません。これにより、レイアウト、ラベル、アイコン、
認可ルールはアプリケーション側で管理され、
すべてのボタンが同じ Viewer インスタンスを操作します:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.GotoPage(objViewer.TotalPages())">Last</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
    <button type="button" onclick="objViewer.FitType('height')">Fit height</button>
    <button type="button" id="openSearch">Search</button>
    <button type="button" id="openAnnotations">Annotations</button>
</nav>

回転、サムネイル、印刷、全画面、レイアウト、ボタン状態ヘルパーは、あなたの
独自ツールバースクリプトに属します。このスクリプトは同じ objViewer を呼び出します。ロードは
Viewer.ReferenceScripts(...) の後に、そしてその <nav id="toolbar"> マークアップと一緒に保持してください。

この初期化順序を保持してください:

  1. Viewer とライセンスモジュール用の CSS を出力する。
  2. Viewer ツールバー、Search/Annotation のマウント、そして Viewer のマウントを一緒にレンダリングする。
  3. Viewer とライセンスモジュール用のスクリプトを出力する。
  4. ホストアプリケーションの独自ツールバーヘルパースクリプトをロードする。
  5. docViewer を初期化し、結果として得られる objViewer を保持する。
  6. 各ライセンス付き Search または Annotation リボンを初期化する。
  7. すべてのリボンで attach(objViewer) を呼び出す。
  8. ドキュメントを開き、Viewer とモジュールリクエスト用にそのトークンを保持する。

分散展開では、追加の access リクエスト値と非同期レンダリング
リトライ設定はトランスポートに属し、Viewer、ツールバー、または
リボンの組み立て方法を変更しません。

サーバー側のガードは重要です:オプション機能が利用できない場合、
そのスクリプトは出力されず、jQuery プラグイン関数も存在しません。

html
<script>
    let token = '';

    const refitViewer = () =>
        requestAnimationFrame(() => objViewer.Refit());

    @if (Viewer.IsSearchEnabled)
    {
        <text>
    searchBar = $('#searchBarMount').doconutSearchBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    searchBar.attach(objViewer);
        </text>
    }

    @if (Viewer.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: () => ({ token }),
        onLayout: refitViewer
    });
    annBar.attach(objViewer);
        </text>
    }

    document.getElementById('openSearch').addEventListener('click', () => {
        if (!searchBar) return;
        searchBar.isOpen() ? searchBar.close() : searchBar.open();
    });

    document.getElementById('openAnnotations').addEventListener('click', () => {
        if (!annBar) return;
        annBar.isOpen() ? annBar.close() : annBar.open();
    });
</script>

両方の埋め込みコンポーネントはそれぞれ独自のリボン DOM を生成します。Search には Find、Options、
Results グループが含まれます。Annotation には作成ツール、スタイルコントロール、保存アクション、
そしてオプションのエクスポート/画像アクションが含まれます。バーは open()、close()、reset()、および
isOpen() を公開します;作成後に必ず attach(objViewer) を一度呼び出してください。

上記の例では、オプションのホストコールバックと Annotation のエクスポート/画像エンドポイントを省略し、
起動時の負荷を最小限に抑えています。完全な機能別設定については 検索 と
注釈 を参照してください。または
カスタムテーマ でホスト所有の Viewer
ツールバーのスタイル変更や置き換えができます。

ドキュメントを開く

サーバー側は単一のエンドポイントです:注入された Viewer サービスがドキュメントを開き、セッショントークンを返します。

csharp
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // トークンは不透明です — ウィジェットに渡し、決してログに記録したり永続化したりしないでください。
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

クライアントはそのトークンを取得し、objViewer.View(token) を使用してウィジェットに渡します:

javascript
fetch('/api/open', { method: 'POST' })
    .then(resp => resp.json())
    .then(data => {
        token = data.token;
        objViewer.View(token);
    });

ドキュメントを閉じる

ユーザーがビューアを離れるか代替ドキュメントを開くときは objViewer.Close(true) を呼び出します:ウィジェットをクリアし、サーバーにクローズリクエストを送信します。引数なしで objViewer.Close() を呼び出すとウィジェットだけがクリアされます。サーバー主導のワークフローでは、viewer.CloseDocument(token) はキャッシュされたセッションを即座に削除し、レンダリングエンジンを破棄し、セキュリティマーカーを削除し、トークンを無効化します。スライディング有効期限でも最終的に同様のクリーンアップが行われますが、大きなドキュメントの場合は明示的なクローズが推奨されます。

完了したリクエストフローは次のとおりです:

text
AddDoconut + middleware
    -> render CSS/scripts and mount div
    -> initialize docViewer
    -> OpenDocumentAsync
    -> return opaque token
    -> objViewer.View(token)
    -> page/search/annotation requests
    -> Close / CloseDocument

トークンはベアラークレデンシャルとして扱ってください:決してログに記録せず、永続化せず、ウィジェットにのみ渡します。トークンはサーバー上のライブドキュメントセッションを識別し、そのセッションが期限切れになると機能しなくなります — 新しいトークンを取得するにはドキュメントを再度開いてください。

実行する

wwwroot/files/Sample.pdf に PDF を配置し、dotnet run を実行し、ウィジェットをホストするページを開きます。最初のページがビューアに表示され、左側にサムネイルパネルが表示されます。表示されない場合は、トラブルシューティングをご覧ください。

ライセンスなしで得られるもの

ライセンスがない場合でも例外は発生しません。ビューアは通常通りレンダリングしますが、すべてのページに評価用の透かしが付加されます。Doconut がライセンスを取得する方法と取得後の変化については、ライセンス設定をご覧ください。

このページは役に立ちましたか?