画像の本来の幅がレンダリング幅（デバイスピクセル比を考慮）より大きい場合、隅に小さな拡大ボタンが表示され、操作可能であることを示すうっすらとした枠線が画像に付きます。隅のボタンだけでなく画像のどこをクリックしてもフルスクリーンダイアログで開きます。

## 横幅の広い画像 — ボタンが表示される

以下の画像は 2400 px 幅で、一般的なコンテンツカラムより大きいサイズです。ブラウザがレンダリングサイズを計測すると、拡大ボタンが表示されます。

![横幅の広いプレースホルダー画像](/img/image-enlarge/image-wide.webp)

## 小さな画像 — ボタンは表示されない

この画像は 300 px 幅で、コンテンツカラムに収まります。画像がコンテナより大きくないため、拡大ボタンは非表示のままです。

![小さなプレースホルダー画像](/img/image-enlarge/image-small.webp)

## 拡大を無効化する（オプトアウト）

幅が大きい画像でも、特定の画像だけ拡大ボタンを無効にしたい場合は、Markdown のタイトル属性に `"no-enlarge"` を指定します。title 属性はレンダリング後の `<img>` からも削除されるため、ブラウザのツールチップには表示されません。

```md
![alt text](./image.png "no-enlarge")
```

![オプトアウトを適用した横幅の広い画像](/img/image-enlarge/image-opt-out.webp "no-enlarge")

## アセットページへのキャプションリンク

アセットビューアーが有効な場合、アセットマニフェストに含まれる単独画像のキャプションに **Open asset page** リンクが加わります。リンク先は画像専用の幅広い閲覧ページで、寸法、元ファイルに対する操作、背景の切り替え、この画像を参照しているドキュメントへのリンクを確認できます。拡大ボタンが現れない小さな画像や `"no-enlarge"` を指定した画像にも、このリンクは表示されます。

実際の表示例は [アセットビューアー](https://zudo-doc.takazudomodular.com/ja/docs/guides/asset-viewer)を参照してください。埋め込み画像でもアセットページへのリンクに加えて拡大ダイアログを使いたい場合は、`imageEnlarge: true` を設定します。

## 動作の仕組み

この機能は 2 つの部分で構成されています。

- **サーバーレンダリング（SSR）** — zudo-doc のパッケージ MDX コンポーネント（`packages/zudo-doc/src/mdx-components/`）にある MDX 段落（`p`）コンポーネントオーバーライドが、画像 1 枚だけを含む段落を `<figure class="zd-enlargeable">` でラップし、非表示の `<button class="zd-enlarge-btn">` を注入します。インラインテキストと混在する画像はラップされません。
- **実行時** — クライアントアイランド（`ImageEnlarge`）が `ResizeObserver` を使用して `naturalWidth` と `clientWidth × devicePixelRatio` を比較し、ボタンの `hidden` 属性を切り替えます。`hidden` が外れている間は画像全体がクリック対象となり、ホバー時のフィードバックも表示されるため、画像のどこをクリックしても `<dialog>` で開きます。**ESC** キー、ビューポート右上の閉じるボタン、または画像の外側をクリックすると閉じられます。

:::note

高 DPI ディスプレイ（例：2× Retina）では、デバイスピクセル比を考慮して拡大ボタンの表示判定が行われます。2000 px の画像が 2× 画面で 1000 CSS px にレンダリングされる場合、`2000 ≤ 1000 × 2` となるため、ボタンは表示されません。

:::

## 設定

画像拡大表示は `zfb.config.ts` の `imageEnlarge` フィールドで有効にします。

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    imageEnlarge: true,
  }),
);
```

`imageEnlarge: false` に設定すると、機能全体を無効にできます。

## オーバーレイ色のカスタマイズ

拡大ボタンとダイアログの閉じるボタンは、外観を制御するトークンペアを共有しています。

- `image-overlay-bg` — アイコンの背後に 80% の不透明度で描画される背景レイヤーの色。
- `image-overlay-fg` — 背景の上に 100% の不透明度で描画されるアイコンの色。

適切なオーバーレイ色はコンテンツ画像に依存し、サイトによって異なります。デフォルト値はほとんどのケースで機能しますが、3 層カラー戦略（[Color](https://zudo-doc.takazudomodular.com/ja/docs/reference/color) を参照）に従い、任意のカラースキームで上書きできます。

```ts
// your colorSchemes override module, passed via the `colorSchemes` field in zfb.config.ts
semantic: {
  imageOverlayBg: { base: 4 },   // ramp stop — deep surface
  imageOverlayFg: { base: 0 },  // ramp stop — light text
  // or a literal OKLCH string: imageOverlayBg: "oklch(.185 .005 65)"
},
```

Design Token Panel の Color タブ（有効時）を使えば、コードを編集せずにこれらのトークンをライブで調整できます。

## 関連ページ

- [Image Enlarge（Markdown 機能）](https://zudo-doc.takazudomodular.com/ja/docs/markdown-features/image-enlarge) — `imageEnlarge` の設定フィールドと段落ラップのパイプライン