ViewerConfig
クライアントビューアウィジェットのオプション
ViewerConfig (namespace Doconut) は、ブラウザビューアの外観と動作を説明します。ドキュメントのレンダリング品質には影響しません;そのためにはフォーマット設定を使用してください。C# クラスと長年使用されている JavaScript ウィジェットはデフォルトが異なるため、値を明示的にマッピングしてください。
このリリースのクライアント側の2つの変更は黙って失敗します。 ハンドラ関数はオプションとして渡され — ウィジェットはもはやコンテナ ID からイベントコールバックを取得しません — そして
ResPathはアプリケーションルートではなくリソースプレフィックスを指す必要があります。どちらも サーバーは正常に動作し続け、ブラウザコンソールには何も報告されません。以前のライブラリからページを引き継いでいる場合は、 コールバック と パスチェックリスト をまず読んでください。
C# プロパティ
| 型 | プロパティ | デフォルト | 説明 |
|---|---|---|---|
bool | ShowThumbs | true | サムネイルパネルを表示します。 |
bool | AutoLoad | false | 初期化後に自動的にロードします。通常のトークンフローは View(token) を明示的に呼び出します。 |
bool | AutoFocus | true | 初期化時にブラウザのフォーカス/スクロールをビューアに移動します。 |
bool | AutoPageFocus | true | ページが変わっても現在のサムネイルを表示し続けます。 |
int | PageZoom | 100 | 初期ズーム率。 |
int | ZoomStep | 10 | ズームコマンドで加算または減算されるパーセンテージ。 |
int | MaxZoom | 300 | 最大ズーム率。 |
bool | ShowToolTip | true | スクロール中にページ位置ツールチップを表示します。 |
string | ToolTipPageText | "Page " | ページツールチップで使用されるプレフィックス。 |
bool | CacheEnabled | false | ブラウザメモリにページ画像の移動ウィンドウを保持します。localStorage は使用しません。 |
bool | LargeDoc | false | 大きなドキュメント用に、ページ要素を時間制御されたバッチで追加します。 |
bool | ShowHyperlinks | false | サーバー設定が抽出したハイパーリンクオーバーレイをレンダリングします。 |
bool | FixedZoom | true | レスポンシブな再計算ではなく、固定ズーム率を使用します。 |
int | FixedZoomPercent | 100 | 固定デスクトップズーム。 |
int | FixedZoomPercentMobile | 75 | 固定モバイルズーム。 |
string | BasePath | "/" | ビューアがページリクエストを送信する場所。"/" はサイトルートで DocImage.axd です;それ以外の場合はホストが UseDoconut() をマップするブランチで、先頭に / を付けずに("doconut" は /doconut/DocImage.axd を意味します)。 |
string | ResPath | "doconut-res/images" (26.9.0; "doconut-res" before) | ウィジェットが自身の画像を読み込むフォルダ:ResourcesPath の下にある images フォルダで、先頭に / を付けずに。 |
string | FitType | "width" | "width"、"height"、または空は自動フィットなしを意味します。"page" は現在のウィジェットでは受け付けられません。 |
bool | RetryOn409 | false | 非同期/分散ページ生成が 202 Accepted に応答する際にポーリングを有効にします;409 は古いサーバーとの互換性のためにも受け入れられます。通常の同期ビューアでは必要ありません。 |
var config = new ViewerConfig
{
ShowThumbs = true,
AutoLoad = false,
PageZoom = 100,
MaxZoom = 300,
FitType = "width",
BasePath = "doconut", // 先頭に '/' がない: ビューアが追加します ("/doconut" は //doconut になり、別のホストになります)
ResPath = "doconut-res/images",
ShowHyperlinks = true
};C# から JavaScript へのマッピング
直接シリアライズされた ViewerConfig を docViewer(...) に渡さないでください。ほとんどのウィジェットキーは camelCase ですが、3 つの確立されたパス/フィットキーは PascalCase です。
| C# | JavaScript |
|---|---|
ShowThumbs | showThumbs |
AutoLoad | autoLoad |
AutoFocus | autoFocus |
AutoPageFocus | autoPageFocus |
PageZoom | pageZoom |
ZoomStep | zoomStep |
MaxZoom | maxZoom |
ShowToolTip | showToolTip |
ToolTipPageText | toolTipPageText |
CacheEnabled | cacheEnabled |
LargeDoc | largeDoc |
ShowHyperlinks | showHyperlinks |
FixedZoom | fixedZoom |
FixedZoomPercent | fixedZoomPercent |
FixedZoomPercentMobile | fixedZoomPercentMobile |
BasePath | BasePath |
ResPath | ResPath |
FitType | FitType |
RetryOn409 | retryOn409 |
JavaScript のデフォルト
このウィジェットには、C# クラスとは異なる古いデフォルトがあります。以下の値は現在の docViewer.js 実装から取得したものです。
| オプション | デフォルト | 備考 |
|---|---|---|
leftMinWidth / leftMaxWidth | 220 / 800 | サムネイルペイン幅の境界。 |
showThumbs | true | 初期サムネイルの表示状態。 |
autoFocus / autoPageFocus | true / false | autoPageFocus は C# のデフォルトと異なります。 |
thumbWidth / thumbHeight / thumbPadding | 150 / 200 / 10 | ピクセル単位のサムネイルジオメトリ。 |
pageZoom / zoomStep / maxZoom | 100 / 10 / 200 | JavaScript maxZoom は C# (300) と異なります。 |
showToolTip / toolTipPageText | true / "Page " | ページ位置ツールチップ。 |
format / doc / AccessToken | "" / 0 / "" | 内部初期化値。通常は View(token) によって設定されます。 |
debugMode | false | 追加のクライアント診断情報。 |
FitType | "" | 提供されない限り自動フィットは行われません。 |
BasePath | "DocImage.axd" | 互換性のために保持された過去のクライアントデフォルト。現在の ASP.NET Core ホストは、マッピングされたミドルウェアブランチに明示的に設定する必要があります。 |
ResPath | "" | 埋め込み画像パスに明示的に設定してください。 |
cacheEnabled / cacheCount / cacheDelay | false / 3 / 3 | メモリ内ページ事前読み込みウィンドウと遅延。 |
autoLoad | false | 明示的なトークンフローが推奨されます。 |
largeDoc | true | C# のデフォルトと異なります。 |
fixedZoom | false | C# のデフォルトと異なります。 |
fixedZoomPercent / fixedZoomPercentMobile | 100 / 50 | モバイル値は C# (75) と異なります。 |
showHyperlinks | true | オーバーレイを生成するにはサーバー側での抽出が必要です。 |
いずれかのデフォルトに依存せず、動作上重要なすべての値を設定してください:
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>
<script>
const objViewer = $('#div_ctlDoc').docViewer({
showThumbs: true,
autoLoad: false,
autoFocus: true,
autoPageFocus: true,
pageZoom: 100,
zoomStep: 10,
maxZoom: 300,
FitType: 'width',
cacheEnabled: false,
largeDoc: false,
showHyperlinks: true,
fixedZoom: true,
fixedZoomPercent: 100,
fixedZoomPercentMobile: 75,
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onViewerReady: function () {},
onError: function (message) { console.error('DocViewer:', message); }
});
</script>コールバック
| コールバック | 引数 | 目的 |
|---|---|---|
onPageLoading | pageNum | ページリクエストが開始されます。 |
onPageLoaded | pageNum | ページ画像の読み込みが完了しました。 |
onThumbnailClicked | pageNum | ユーザーがサムネイルを選択しました。 |
onPageClicked | pageNum | ユーザーがページを選択しました。 |
onDoubleClick | none | ビューアがダブルクリックを受信しました。 |
onViewerBusy | none | ビューアがビジー状態になりました。 |
onViewerReady | none | 初期化が完了しました。 |
onViewerError | none | ビューアがエラー状態になりました。 |
onError | message | 操作がエラーメッセージを返しました。 |
onCopy | data | テキストコピー用データが利用可能です。 |
onAutoLoadStatus | pageNum | 自動読み込みがページに進みました。 |
onThumbsShown | none | サムネイルパネルが表示されました。 |
onAnnLoaded | none | 注釈データがロードされました。 |
onAnnSaved | none | 注釈データが保存されました。 |
onAnnSaveError | none | 注釈の保存に失敗しました。 |
onAnnClosed | none | 注釈 UI が閉じられました。 |
コールバックは高速に保ち、テレメトリは非同期で送信し、ページのレンダリングをブロックしないでください。
これらすべては init オブジェクトのオプションです。 前のビューアは、コンテナ ID から導出した名前のグローバル関数を検索していました — <div id="div_ctlDoc"> を使用したページは function ctlDoc_OnViewerReady() を宣言するだけで済みました。その検索は廃止されました。関数を明示的に渡してください:
function ctlDoc_OnViewerBusy() { /* ビジーインジケータを表示する */ }
function ctlDoc_OnViewerReady() { /* 非表示にする */ }
function ctlDoc_Copy(text) { /* コピーしたテキストを使用する */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* 進捗を報告する */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... 既存のオプション ...
onViewerBusy: ctlDoc_OnViewerBusy, // 名前で見つかりました
onViewerReady: ctlDoc_OnViewerReady, // 名前で見つかりました
onCopy: ctlDoc_Copy, // は ctlDoc_Copy(text)
onAutoLoadStatus: ctlDoc_AutoLoadStatus // は ctlDoc_AutoLoadStatus(page)
});古い検索は空の catch でラップされていたため、何も報告されませんでした。このリリースでは、関数は単に実行されません。一般的な症状は、非表示にするハンドラが onViewerReady だったために停止しないビジースピナーです。その背後のドキュメントは正しくレンダリングされています。
2 つのアノテーション保存フックは依然として名前で検索されます:SaveAnnotations() は、存在する場合に <elementId>_BeforeAnnSave() と <elementId>_DeletedAnnotationIds() を呼び出し、要素の完全な ID(上記サンプルでは div_ctlDoc_BeforeAnnSave)を使用します。
リンククリックのコールバックはありません — ハイパーリンク処理は組み込まれており、showHyperlinks によって制御されます。
パブリックメソッドグループ
| グループ | 共通メソッド |
|---|---|
| ライフサイクル | View(token, accessToken?), Close(server?), Token(), Init(), IsLoaded() |
| ナビゲーション | GotoPage(page), ShowPage(page, focus?), Next(next), CurrentPage(), TotalPages() |
| ズームとフィット | Zoom(zoomIn), CurrentZoom(), FitType(value), Refit() |
| 向き | Rotate(page, angle), Flip(page, flipType) |
| サムネイル | HideThumbs(hide), ThumbSize(size), ReloadThumbs(width), ScrollToThumb(thumb) |
| 検索 | CanSearch(), Search(...), SearchMatchCount(), SearchSummary(...), GotoSearchMatch(...) |
| 注釈 | SaveAnnotations(), GetAnnotations(), PushAnnotations(...), CloseAnnotations(...), ShowAnnotations(...) |
| コピー | Copy(...), CopyPage(pageNumber), CopyMode(enabled) |
この JavaScript ファイルには内部ヘルパーも含まれています。リファレンス UI が使用し、ここや機能ガイドで文書化されているメソッドのみを安定した統合ポイントとして扱ってください。
分散ページがまだレンダリング中の間のリトライ
retryOn409 はその歴史的な名前を保持しています。非同期ページ生成のためのもので、現在の 202 Accepted 準備完了レスポンスと古い 409 Conflict シグナルの両方をリトライします。有効にすると、ウィジェットはこれらの JavaScript デフォルトでポーリングします:
| オプション | デフォルト |
|---|---|
retryInitialDelayMs | 250 |
retryBackoffFactor | 1.6 |
retryMaxDelayMs | 2500 |
retryMaxAttempts | 150 |
retryMaxTotalMs | 300000 |
通常のシングルノードビューアでは無効のままにしてください。有効化しても、サポートされていない同期レンダリングを非同期にすることはできません。
FirstPagePriority を使用した共有ストレージからページが提供される場合に有効にしてください。その場合、後続のページは書き込まれるまで正当に 202 Accepted に応答します。リトライしないクライアントは、まだレンダリング中のページで破損したタイルを表示します — 分散デプロイメント を参照してください。
パスチェックリスト
DoconutOptions.MiddlewarePathは実際にマップするブランチを記述する必要があります。BasePathはそのブランチを対象とし、先頭の/を付けずに記述する必要があります('doconut'、'/doconut'ではなく:ビューアがスラッシュを追加し、//doconut/...は別ホストへのリクエストです)。一般的な設定では、MapWhenブランチ上で歴史的なDocImage.axdリクエスト形状を保持し、そのためBasePath: '/'を設定します。DoconutOptions.ResourcesPathは埋め込みリソースのルートです。ResPathは通常、そのimagesサブフォルダを対象とし、先頭の/は付けません — デフォルトプレフィックスでは'doconut-res/images'です。空のResPathは以前のライブラリでは正しかったですが、リソースがアプリケーションルートから提供されていたためです。ここでは正しくなく、エラーなしで失敗します。ExtractHyperlinksはサーバーフォーマット設定で有効にしなければ、showHyperlinksが何も表示できません。
このページは役に立ちましたか?