クイックスタート

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

このウォークスルーは、空の 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(); // session state にはキャッシュが必要です (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 つのページ構成として扱います。 検索と 注釈は埋め込みリボンをオプションのマウントに注入しますが、これらのモジュールは決して 単独では使用されません:常に同じページの 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 がない検索または注釈リボンの例 インスタンス。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 ツールバー、検索/注釈マウント、そして Viewer マウントを一緒にレンダリングします。
  3. Viewer とライセンスモジュール用のスクリプトを出力します。
  4. ホストアプリケーション独自のツールバーヘルパースクリプトをロードします。
  5. docViewer を初期化し、結果として得られる objViewer を保持します。
  6. 各ライセンスされた検索または注釈リボンを初期化します。
  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 を生成します。検索は Find、Options、Results グループを含みます。注釈は作成ツール、スタイルコントロール、保存アクション、そしてオプションのエクスポート/画像アクションを含みます。これらのバーは open()、close()、reset()、isOpen() を公開します;作成後は必ず attach(objViewer) を一度呼び出してください。

上記の例では、起動を最小限に抑えるためにオプションのホストコールバックと注釈のエクスポート/画像エンドポイントを省略しています。完全な機能別設定については 検索 と 注釈 を参照してください。また、ホスト所有の 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 がライセンスを取得する方法と取得後の変化については、ライセンス設定をご覧ください。

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