🔍Miradorのページ送りでズームが引き継がれる — preserveViewportの既定と、@latestの落とし穴

本記事は生成AIと共同で執筆しています。事実関係は可能な範囲で公式ドキュメント等と照合していますが、誤りが含まれている可能性があります。重要な判断を行う前にご自身でも一次情報をご確認ください。

Mirador で画像を拡大した状態のまま次のページに送ると、前ページの拡大率・表示位置がそのまま引き継がれます。「ページを変えたら全体表示に戻ってほしい」と感じる場面もあり、これがデフォルトなのか・変えられるのかを調べたので、確認した事実と対処をまとめます。

osdConfig.preserveViewport という設定

ページ送り時にビューポート（拡大率・表示位置）を引き継ぐかどうかは、preserveViewport で決まります。

• true: canvas を切り替えても 拡大率・表示位置を維持（前ページでズームしていれば、次ページも同じ拡大状態のまま）
• false: canvas 切り替えのたびに 新しい canvas 全体にフィット（いわゆるホーム表示にリセット）

ここで間違えやすいのが置き場所です。preserveViewport は Mirador の window 設定ではなく、OpenSeadragon 用の osdConfig ブロックに置きます。Mirador のデフォルト設定でも osdConfig 配下に定義されています（window 配下に書いても認識されません）。

const config = {
  id: 'viewer',
  windows: [{ manifestId: 'https://example.org/manifest.json' }],
  osdConfig: {
    // ...
    preserveViewport: false, // ページ送りで拡大率・表示位置をリセット
  },
};
Mirador.viewer(config);

挙動の中身を Mirador v4.0.0 のソースで追うと、ページ送りのアクション setCanvas が getConfig(state).osdConfig.preserveViewport を読み、false のときに viewport の状態をリセットしています。

// src/state/actions/canvas.js（抜粋）
const { preserveViewport } = getConfig(state).osdConfig;
// → SET_CANVAS アクションに preserveViewport を載せて dispatch

// src/state/reducers/viewers.js（抜粋）
case ActionTypes.SET_CANVAS:
  if (!action.preserveViewport) {
    return set([action.windowId], null, state); // 保存していた拡大/位置を破棄→次ページは全体表示
  }
  return state;                                  // 維持

つまり「osdConfig に渡すが、効くのは OpenSeadragon の sequenceMode 経由ではなく、Mirador 自身がページ送り時にこのフラグを見てビューポート状態を保持/破棄している」という作りです（Mirador は sequenceMode を使っていません）。画像表示自体は OpenSeadragon ベースです。

既定値：3.3.0〜4.0.0 は true、main は false

「引き継ぐのが既定なのか」を確かめるため、リリースごとの src/config/settings.js の既定値を確認しました。

バージョン	preserveViewport 既定
3.3.0	true
3.4.0	true
3.4.3	true
4.0.0	true
main（未リリース）	false

つまり 引き継ぐ（true）のが長らくの既定で、v3→v4 で変わったわけではありません（筆者は当初 v3 は false だと思い込んでいましたが、確認したら誤りでした）。一方、未リリースの main では false に変わっているので、将来のリリースで既定が反転する可能性があります。

確認は GitHub の raw とパッケージCDNで手元から行えます。

# mirador@latest が今どの版に解決されるか（unpkg のリダイレクト先）
curl -sI "https://unpkg.com/mirador@latest/dist/mirador.min.js" | grep -i '^location'
# → location: /mirador@4.0.0/dist/mirador.min.js

# 各タグの既定値
curl -s "https://raw.githubusercontent.com/ProjectMirador/mirador/v4.0.0/src/config/settings.js" \
  | grep -n preserveViewport
# → 548:    preserveViewport: true,

どちらを選ぶか

• 同じくらいの大きさのページが連続する資料（書籍の見開きなど）では、true（引き継ぎ）だと拡大したまま読み進められて快適なことがあります。
• ページごとに canvas のサイズがばらつく場合は、false（リセット）の方が自然です。たとえば大判のスキャン画像の中に、サイズの異なる固定寸法の画像（差し替え用のプレースホルダや、解像度の違う別資料）が混ざるケース。true のままだと、大きい画像でズームした状態のまま小さい画像へ移り、その一部だけが拡大表示されることになります。

筆者のケースは後者で、大判画像の中に固定サイズ（1000×1414）の画像が混ざる構成だったため、preserveViewport: false を明示してページごとに全体表示へフィットさせました。

落とし穴：mirador@latest は既定挙動ごと動く

このビューアは CDN から mirador@latest を読み込んでいました。前述のとおり @latest は現在 4.0.0 に解決されますが、可変バージョン指定はメジャー更新を黙って取り込みます。さらに既定値そのものも（main を見るに）変わりうる値です。

対策はシンプルです。

1. バージョンを固定する（例 mirador@4.0.0。CSS も同じ版に揃える）
2. 依存している挙動は既定値に頼らず明示する（ここでは preserveViewport を明示的に true / false で書く）

こうしておけば、CDN 側の更新や将来の既定変更があっても、ビューアの挙動は固定されます。

まとめ

• Mirador のページ送りでズームが引き継がれるのは preserveViewport の既定（true）の挙動。false にすると各ページで全体表示にフィット（リセット）。設定は window ではなく osdConfig 配下に置く。
• 既定は 3.3.0〜4.0.0 まで一貫して true。false は未リリースの main のみで、将来反転しうる。
• ページごとに canvas サイズが異なる構成では false が自然。
• mirador@latest は既定挙動ごと動くので、バージョン固定＋設定の明示で安定させる。