Vant

日本語

繁體中文
简体中文
English

日本語

繁體中文
简体中文
English

Appearance

Popover ポップオーバー - Vant 4

💬 Popover ポップオーバー ​

🎯 紹介 ​

Popover はポップアップ式のバブルメニューです。トリガー要素に基づく正確な位置決め、ライト/ダークテーマ、矢印表示に対応し、操作項目を直感的かつ軽量に提示します。

📦 導入 ​

以下の方法でコンポーネントをグローバル登録します。詳細はコンポーネント登録を参照してください。

js
import { createApp } from'vue'; import { Popover } from'vant'; const app = createApp(); app.use(Popover);

🎯 コード例 ​

🔧 基本用法 ​

Popover は reference スロットの内容を基準に位置決めされます。最適な位置に表示されます 🎯

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  @select="onSelect"
  placement="bottom-start"
>
  <template #reference>
    <van-button type="primary">ライトテーマ</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    const showPopover = ref(false);
    
    // actions プロパティでメニュー項目を定義。各項目は小さな機能です ⚡
    const actions = [
      { text: 'オプション1' },
      { text: 'オプション2' },
      { text: 'オプション3' },
    ];

    const onSelect = (action) => showToast(action.text);

    return {
      actions,
      onSelect,
      showPopover,
    };
  },
};

🌙 ダークテーマ ​

ライト/ダークの 2 スタイルに対応。theme="dark" でダークスタイルに切り替えられます 🌃

html
<van-popover
  v-model:show="showPopover"
  theme="dark"
  :actions="actions"
  placement="bottom-start"
>
  <template #reference>
    <van-button type="primary">ダークテーマ</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    
    // ダークテーマの選択肢 🌙
    const actions = [
      { text: 'オプション1' },
      { text: 'オプション2' },
      { text: 'オプション3' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

📐 水平配置 ​

actions-direction="horizontal" で選択肢を横並び配置にできます 🎖️

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  actions-direction="horizontal"
  placement="bottom-start"
>
  <template #reference>
    <van-button type="primary">水平配置</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    
    // 水平配置の選択肢 ➡️
    const actions = [
      { text: 'オプション1' },
      { text: 'オプション2' },
      { text: 'オプション3' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

🧭 表示位置 ​

placement 属性で表示位置を制御します。コンパスのように精密に位置決めします 🧭

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  placement="top"
>
  <template #reference>
    <van-button type="primary">上から表示</van-button>
  </template>
</van-popover>

placement は以下の値をサポートします：

bash
top           # 上・中央 ⬆️
top-start     # 上・左 ↖️
top-end       # 上・右 ↗️
left          # 左・中央 ⬅️
left-start    # 左・上 ↖️
left-end      # 左・下 ↙️
right         # 右・中央 ➡️
right-start   # 右・上 ↗️
right-end     # 右・下 ↘️
bottom        # 下・中央 ⬇️
bottom-start  # 下・左 ↙️
bottom-end    # 下・右 ↘️

🎨 アイコン表示 ​

actions 配列の icon でアイコンを指定できます。アイコン名や画像リンクに対応し、選択肢を分かりやすくします 🎨

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  placement="bottom-start"
>
  <template #reference>
    <van-button type="primary">アイコン表示</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    
    // アイコン付きの選択肢 ✨
    const actions = [
      { text: 'オプション1', icon: 'add-o' },
      { text: 'オプション2', icon: 'music-o' },
      { text: 'オプション3', icon: 'more-o' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

🚫 無効な選択肢 ​

actions の disabled で選択肢を無効化できます。グレー表示で操作不可を示します 🚫

html
<van-popover
  v-model:show="showPopover"
  :actions="actions"
  placement="bottom-start"
>
  <template #reference>
    <van-button type="primary">無効な選択肢</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    
    // 一部選択肢を無効化 ⛔
    const actions = [
      { text: 'オプション1', disabled: true },
      { text: 'オプション2', disabled: true },
      { text: 'オプション3' },
    ];

    return {
      actions,
      showPopover,
    };
  },
};

🎭 カスタム内容 ​

default スロットで任意の内容を配置できます。自由に表現しましょう 🎭

html
<van-popover v-model:show="showPopover" placement="top">
  <van-grid
    square
    clickable
    :border="false"
    column-num="3"
    style="width: 240px;"
  >
    <van-grid-item
      v-for="i in 6"
      :key="i"
      text="選択肢"
      icon="photo-o"
    />
  </van-grid>
  <template #reference>
    <van-button type="primary">カスタム内容</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';

export default {
  setup() {
    const showPopover = ref(false);
    
    return { showPopover };
  },
};

🎮 非制御モード ​

Popover は制御/非制御の両モードで利用できます 🎮

  • v-model:show をバインドすると制御モード（表示は値に依存） 🎛️
  • バインドしない場合は非制御モード（show 初期値を渡す） 🤖
html
<van-popover
  :actions="actions"
  placement="bottom-start"
  @select="onSelect"
>
  <template #reference>
    <van-button type="primary">非制御モード</van-button>
  </template>
</van-popover>
js
import { ref } from 'vue';
import { showToast } from 'vant';

export default {
  setup() {
    // 非受控模式下的选项配置 🎯
    const actions = [
      { text: '选项一' },
      { text: '选项二' },
      { text: '选项三' },
    ];

    const onSelect = (action) => showToast(action.text);

    return {
      actions,
      onSelect,
    };
  },
};

📋 API ​

🎛️ Props ​

属性名説明型デフォルト
v-model:showポップオーバーの表示制御 👁️booleanfalse
actions選択肢一覧 📋PopoverAction[][]
actions-direction v4.4.1選択肢の配置方向（horizontal で水平） 📐PopoverActionsDirectionvertical
placement表示位置 🧭PopoverPlacementbottom
themeテーマ（dark 対応） 🎨PopoverThemelight
triggerトリガー方式（manual 対応） 🎯PopoverTriggerclick
durationアニメーション時間（秒）。0 で無効化 ⏱️*numberstring*
offset位置のオフセット 📏[number, number][0, 8]
overlayオーバーレイ表示（フォーカス管理） 🎭booleanfalse
overlay-classオーバーレイのカスタムクラス 🎨*stringArray
overlay-styleオーバーレイのカスタムスタイル ✨object-
show-arrow矢印を表示するか ➡️booleantrue
close-on-click-action選択後に閉じるか 🔄booleantrue
close-on-click-outside外部クリックで閉じるか 👆booleantrue
close-on-click-overlayオーバーレイクリックで閉じるか 🎭booleantrue
teleportマウント先ノード（Teleport の to と同等） 🚀*stringElement*
icon-prefixアイコンクラスの接頭辞（Icon の class-prefix と同等） 🎨stringvan-icon

PopoverAction データ構造 ​

actions はオブジェクト配列で、各オブジェクトが一つの選択肢を表します：

キー名説明型
text選択肢テキスト 📝string
iconテキスト左のアイコン（Icon の name と同等） 🎨string
colorテキスト色 🌈string
disabled無効化（クリック不可） 🚫boolean
classNameカスタムクラス ✨*string

🎯 Events ​

イベント名説明コールバック引数
select選択肢クリックで発火 🎯action: PopoverAction, index: number
openメニューを開いたとき 📂-
closeメニューを閉じたとき 📁-
openedアニメーション終了後（完全表示） ✨-
closedアニメーション終了後（完全非表示） 🎭-
click-overlayオーバーレイクリックで発火 👆event: MouseEvent

🎨 Slots ​

名称説明パラメータ
defaultメニュー内容のカスタマイズ 🎨-
reference表示をトリガーする要素内容 🎯-
action選択肢のカスタマイズ ✨{ action: PopoverAction, index: number }

📝 型定義 ​

コンポーネントは以下の型定義をエクスポートします：

ts
importtype { PopoverProps, PopoverTheme, PopoverAction, PopoverActionsDirection, PopoverTrigger, PopoverPlacement, } from'vant';

🎨 テーマカスタマイズ ​

🎛️ スタイル変数 ​

コンポーネントは以下の CSS 変数を提供しており、カスタムスタイルに使用できます。使用方法については ConfigProvider コンポーネント を参照してください。

名称デフォルト値説明
--van-popover-arrow-size6px矢印サイズ
--van-popover-radiusvar(--van-radius-lg)角丸半径
--van-popover-action-width128pxアクション項目の幅
--van-popover-action-height44pxアクション項目の高さ
--van-popover-action-font-sizevar(--van-font-size-md)アクション項目の文字サイズ
--van-popover-action-line-heightvar(--van-line-height-md)アクション項目の行高
--van-popover-action-icon-size20pxアクション項目のアイコンサイズ
--van-popover-horizontal-action-height34px横並び時の項目高さ
--van-popover-horizontal-action-icon-size16px横並び時のアイコンサイズ
--van-popover-light-text-colorvar(--van-text-color)ライトテーマの文字色
--van-popover-light-backgroundvar(--van-background-2)ライトテーマの背景色
--van-popover-light-action-disabled-text-colorvar(--van-text-color-3)ライトテーマの無効文字色
--van-popover-dark-text-colorvar(--van-white)ダークテーマの文字色
--van-popover-dark-background#4a4a4aダークテーマの背景色
--van-popover-dark-action-disabled-text-colorvar(--van-text-color-2)ダークテーマの無効文字色

よくある質問 ​

Popover のクリックイベントが正しく発火しない？ ​

プロジェクトに fastclick を導入している場合に発生することがあります。fastclick を削除するか、ignore 設定 を適用してください。

📚 関連ドキュメント ​

関連コンポーネントで完全なインタラクションを構築しましょう：

Vant に基づく企業向けモバイルソリューション

Copyright © 2025 siex.cn ｜ sitemap