Modal

現在のページの上で、集中した操作を行うためのダイアログコンポーネントです。フォーカストラップ、スクロールロック、背景の無効化を備えています。

こんなときに：ページの上に重ねて集中した操作をさせるダイアログが必要で、フォーカストラップ・スクロールロック・背景の無効化もほしいとき。<r-modal> は open 属性、または命令的な Modal.confirm / Modal.info ヘルパーで動かします。

クイックスタート

基本的な使い方

モーダルの表示は open 属性（または open プロパティ）で制御します。初期状態は閉じていて、開くまで何も描画しません。開閉するトリガーを用意してください。

<r-button onclick="modal.open = true">モーダルを開く</r-button>

<r-modal id="modal" heading="基本のモーダル">
  <p>これがモーダルの内容です。</p>
  <div slot="footer">
    <r-button type="primary" onclick="modal.open = false">OK</r-button>
  </div>
</r-modal>

API リファレンス

プロパティ

closing は要素が自分自身に反映する読み取り専用の属性です（設定できるプロパティではありません）。close() が走った瞬間から、マスクとダイアログのフェード＋縮小のトランジションが実際に終わるまで（およそ 0.3 秒後、afterclose イベントと同じタイミング）付いています。その見た目の余韻のあいだも、モーダルが「まだそこにある」ものとして扱う必要のあるホストページで役に立ちます。下のベストプラクティスを参照してください。

タイトル title

<r-modal open heading="項目を削除">
  <p>この項目を削除してよろしいですか？</p>
</r-modal>

閉じるボタン closable

ヘッダーの閉じるボタンを隠し、あなた自身のコントロールからしか閉じられないようにします。

<r-modal open heading="利用規約" closable="false">
  <p>続けるには規約に同意する必要があります。</p>
  <div slot="footer">
    <r-button type="primary">同意する</r-button>
  </div>
</r-modal>

マスククリックで閉じる maskClosable

既定では背景のクリックでモーダルが閉じます。false にすると、はっきりした操作を必要にできます。

<r-modal open heading="未保存の変更" maskClosable="false">
  <p>外側をクリックしてもこのダイアログは閉じません。</p>
</r-modal>

Escape で閉じる closeOnEsc

<r-modal open heading="レポート" closeOnEsc="false">
  <p>このダイアログでは Escape キーが無効です。</p>
</r-modal>

スクロールのロック lockScroll

<r-modal open heading="プレビュー" lockScroll="false">
  <p>モーダルの背後のページは、まだスクロールできます。</p>
</r-modal>

自動フォーカス autoFocus

<r-modal open heading="検索" autoFocus="false">
  <input type="text" placeholder="入力して検索" />
</r-modal>

ヘッダーなしモード hideHeader

タイトルバーとその境界線を丸ごと省き、closable のときだけ右上に浮いた閉じるボタンを残します。画像や図のライトボックスのように、タイトルバーが内容を削るだけの「中身しかない」ダイアログ向けです。見えている <h3> のタイトルがなくなっても、ダイアログは aria-label（title から作られます）でアクセシブルな名前を保ちます。ヘッダーなしモードでも、スクリーンリーダー用のラベルとして title は設定してください。

<r-modal open hide-header>
  <img src="/diagram.png" alt="アーキテクチャ図" style="display: block; max-width: 100%;" />
</r-modal>

スロット

<r-modal open heading="確認">
  <p>本文はデフォルトスロットに入ります。</p>
  <div slot="footer">
    <r-button onclick="modal.open = false">キャンセル</r-button>
    <r-button type="primary">確定</r-button>
  </div>
</r-modal>

イベント

閉じるに関わるイベントはすべて、何が原因で閉じたかを表す trigger を event.detail に載せます。値は 'mask'、'button'、'escape'、'program' のいずれかです。

<r-modal id="modal" heading="例"></r-modal>

<script>
  const modal = document.getElementById('modal');

  modal.addEventListener('beforeclose', (e) => {
    if (!confirm('変更を破棄しますか？')) e.preventDefault();
  });

  modal.addEventListener('close', (e) => {
    console.log('閉じた原因:', e.detail.trigger); // 'mask' | 'button' | 'escape' | 'program'
  });
</script>

プログラムから使う API

Modal クラスには、マークアップなしでモーダルを作り、マウントし、結果を返す静的ヘルパーがあります。いずれも Promise<{ action, trigger }> を返し、action は 'confirm'、'cancel'、'dismiss' のいずれかです。

オプション（すべて任意）：title、content、okText、cancelText、showCancel、maskClosable、closeOnEsc、lockScroll、autoFocus、closable、onConfirm、onCancel。onConfirm / onCancel が false（または false に解決する Promise）を返すと、モーダルは開いたままになります。

import { Modal } from 'ranui/modal';

const result = await Modal.confirm({
  title: 'プロジェクトを削除',
  content: 'この操作は取り消せません。',
  okText: '削除',
  cancelText: '残す',
  onConfirm: async () => {
    await deleteProject();
  },
});

if (result.action === 'confirm') {
  // 削除された
}

CSS parts

::part() で内部の各部にスタイルを当てられます。

r-modal::part(dialog) {
  border-radius: 8px;
}
r-modal::part(mask) {
  background: rgba(0, 0, 0, 0.6);
}

スタイル

<r-modal> は自前の CSS カスタムプロパティを 23 個と、テーマから読み取るセマンティックトークンを公開しています。継承が届く場所ならどこでも指定できます（:root、ラッパー、要素そのものなど）。

r-modal {
  --ran-modal-mask-background: var(--ran-color-bg-subtle);
}

Parts：body · close · dialog · footer · header · mask · root · title

全一覧はスタイルトークンにあります。どのトークンを使うかはデザインシステムを参照してください。

ベストプラクティス

• トリガーと開閉：modal.open = true で開き、modal.open = false（または close()）で閉じます。
• 破壊的な閉じ方を守る：beforeclose を受けて preventDefault() すれば、保存していない作業を捨てる前に確認を挟めます。
• フッターのアクション：主要／副次のボタンは slot="footer" に置きます。フッターバーはこのスロットに中身があるときだけ現れます。
• 閉じられないフロー：closable="false" と maskClosable="false" を設定すると、はっきり選択させることを強制できます。
• その場限りのダイアログ：手早い問い合わせなら、マークアップを書かずに Modal.confirm / Modal.info を使ってください。
• モーダルが開いている間だけホストページを前面に上げる：[open] だけでなく :has(r-modal[open]), :has(r-modal[closing]) にマッチさせてください。open は close() が走った瞬間に外れますが、マスクとダイアログのトランジションはそこからさらに 0.3 秒ほど描画を続けます。フェードの途中で z-index の引き上げをやめると、まだ見えているマスクが、それまで上に乗っていた相手の下で描き直されてしまいます。