DropdownMenu ドロップダウンメニュー - Vant 4
📋 DropdownMenu ドロップダウンメニュー
🎯 紹介
ショッピングサイトを見ているとき、商品を素早く絞り込むための便利なツールが欲しくなりませんか？DropdownMenu ドロップダウンメニューコンポーネントはまさにそのような素晴らしい存在です！✨
魔法の箱のように、軽くタップするだけで様々なオプションが展開され、ユーザーは多くの選択肢の中から簡単に目的の内容を見つけることができます。商品のカテゴリ、並び替え方法、その他の絞り込み条件など、DropdownMenu は複雑な選択をシンプルで楽しいものに変えてくれます！🎪
📦 導入
以下の方法でグローバルにコンポーネントを登録します。詳細な登録方法については、コンポーネントの登録を参照してください。
import { createApp } from 'vue';
import { DropdownMenu, DropdownItem } from 'vant';
const app = createApp();
app.use(DropdownMenu);
app.use(DropdownItem);🎯 コードのデモ
🔧 基本的な使い方
最もシンプルなドロップダウンメニューはブロックを積むように簡単です！オプションのデータを準備するだけで、DropdownMenu は美しく実用的なドロップダウンセレクターを表示してくれます。以下の例を見てください。とても簡単に使えますね！🎮
<template>
<van-dropdown-menu>
<van-dropdown-item v-model="value1" :options="option1" />
<van-dropdown-item v-model="value2" :options="option2" />
</van-dropdown-menu>
</template>
<script setup>
import { ref } from 'vue';
const value1 = ref(0);
const value2 = ref('a');
const option1 = [
{ text: '全ての商品', value: 0 },
{ text: '新商品', value: 1 },
{ text: 'イベント商品', value: 2 },
];
const option2 = [
{ text: 'デフォルトの並び替え', value: 'a' },
{ text: '評判順', value: 'b' },
{ text: '販売数順', value: 'c' },
];
</script>🎨 メニューのカスタマイズ
標準的なオプションリストではクリエイティブなニーズを満たせない場合もありますが、心配しないでください！DropdownMenu は変幻自在なマジシャンのようで、スロット機能を使用して、ドロップダウンメニューにスイッチボタン、スライダー、さらには小さなゲームまで、あらゆるものを配置することができます！🎭
カスタムコンテンツを使用する場合は、テレビのリモコンのように、メニューの開閉を手動で制御することを忘れないでください。
<template>
<van-dropdown-menu ref="menuRef">
<van-dropdown-item ref="itemRef" title="カスタムコンテンツ">
<!-- カスタムコンテンツ -->
<div class="custom-content">
<div class="custom-content__switch">
<span>表示オプション1</span>
<van-switch v-model="switch1" />
</div>
<div class="custom-content__switch">
<span>表示オプション2</span>
<van-switch v-model="switch2" />
</div>
<div class="custom-content__buttons">
<van-button type="default" block @click="onConfirm">確認</van-button>
</div>
</div>
</van-dropdown-item>
</van-dropdown-menu>
</template>
<script setup>
import { ref } from 'vue';
const menuRef = ref(null);
const itemRef = ref(null);
const switch1 = ref(false);
const switch2 = ref(false);
const onConfirm = () => {
itemRef.value.toggle();
// または
// menuRef.value.close();
};
</script>
<style>
.custom-content {
padding: 16px;
}
.custom-content__switch {
display: flex;
align-items: center;
justify-content: space-between;
padding: 12px 0;
}
.custom-content__buttons {
margin-top: 8px;
}
</style>🌈 選択状態の色をカスタマイズ
ドロップダウンメニューにもっと個性を与えたいですか？それはメニューに違う色の新しい服を着せるようなものです！active-color 属性を使用すると、選択されたオプションに好みの色をつけることができ、インターフェース全体をブランドの雰囲気に合わせることができます。🎨
<template>
<van-dropdown-menu active-color="#ee0a24">
<van-dropdown-item v-model="value" :options="options" />
</van-dropdown-menu>
</template>
<script setup>
import { ref } from 'vue';
const value = ref(0);
const options = [
{ text: '全ての商品', value: 0 },
{ text: '新商品', value: 1 },
{ text: 'イベント商品', value: 2 },
];
</script>🏃♂️ 横スクロール
オプションが多すぎてメニューバーに収まらない場合はどうしますか？心配しないでください！DropdownMenu は横スクロール機能をサポートしています。厚いアルバムをめくるように、左右にスワイプするだけでより多くのオプションを見ることができます。swipe-threshold 属性を使用すると、このスクロール機能をいつ有効にするかをカスタマイズすることもできます！📱
<template>
<van-dropdown-menu swipe-threshold="4">
<van-dropdown-item v-model="value1" :options="option1" />
<van-dropdown-item v-model="value2" :options="option2" />
<van-dropdown-item v-model="value3" :options="option3" />
<van-dropdown-item v-model="value4" :options="option4" />
<van-dropdown-item v-model="value5" :options="option5" />
</van-dropdown-menu>
</template>
<script setup>
import { ref } from 'vue';
const value1 = ref(0);
const value2 = ref('a');
const value3 = ref('x');
const value4 = ref(100);
const value5 = ref(true);
const createOptions = (prefix, count) => {
return Array.from({ length: count }, (_, i) => ({
text: `${prefix} ${i + 1}`,
value: i,
}));
};
const option1 = createOptions('オプションA', 3);
const option2 = createOptions('オプションB', 3);
const option3 = createOptions('オプションC', 3);
const option4 = createOptions('オプションD', 3);
const option5 = createOptions('オプションE', 3);
</script>⬆️ 上方向に展開
ボタンが画面の下部にある場合など、メニューを上方向に展開する必要があることもあります。direction を up に設定するだけで、メニューは風船のように上方向に展開されます！🎈
<template>
<div style="padding: 200px 0;">
<van-dropdown-menu direction="up">
<van-dropdown-item v-model="value" :options="options" />
</van-dropdown-menu>
</div>
</template>
<script setup>
import { ref } from 'vue';
const value = ref(0);
const options = [
{ text: '全ての商品', value: 0 },
{ text: '新商品', value: 1 },
{ text: 'イベント商品', value: 2 },
];
</script>🚫 メニューを無効にする
一時的に特定のメニューアイテムが使用できない場合があります。これはお店の「一時的に在庫切れ」のラベルのようなものです。無効化機能を使用すると、ユーザーにこのオプションが現在選択できないことを伝え、混乱を避けることができます。
<template>
<van-dropdown-menu>
<van-dropdown-item v-model="value1" :options="option1" />
<van-dropdown-item v-model="value2" :options="option2" disabled />
</van-dropdown-menu>
</template>
<script setup>
import { ref } from 'vue';
const value1 = ref(0);
const value2 = ref('a');
const option1 = [
{ text: '全ての商品', value: 0 },
{ text: '新商品', value: 1 },
];
const option2 = [
{ text: 'デフォルトの並び替え', value: 'a' },
{ text: '評判順', value: 'b' },
];
</script>API
DropdownMenu Props
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| active-color | メニューのタイトルとオプションの選択状態の色 | string | #1989fa |
| direction | メニューの展開方向、up が使用可能 | string | down |
| z-index | メニューバーの z-index 階層 | number | string | 10 |
| duration | アニメーションの期間（秒単位）、0 に設定するとアニメーションを無効にできます | number | string | 0.2 |
| overlay | マスクレイヤーを表示するかどうか | boolean | true |
| close-on-click-overlay | マスクレイヤーをクリックした後にメニューを閉じるかどうか | boolean | true |
| close-on-click-outside | 外部要素をクリックした後にメニューを閉じるかどうか | boolean | true |
| swipe-threshold | スクロールのしきい値。オプションの数がしきい値を超え、合計幅がメニューバーの幅を超えると、横スクロールが可能になります | number | string | - |
| auto-locate | 祖先要素に transform が設定されている場合、ドロップダウンメニューの位置を自動的に調整します | boolean | false |
DropdownItem Props
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| v-model | 現在の選択アイテムに対応する value | number | string | - |
| title | メニューアイテムのタイトル | string | 現在の選択アイテムのテキスト |
| options | オプションの配列 | Option[] | [] |
| disabled | メニューを無効にするかどうか | boolean | false |
| lazy-render | 初めて展開するときにのみメニューの内容をレンダリングするかどうか | boolean | true |
| title-class | タイトルの追加クラス名 | string | Array | object | - |
| teleport | マウントするノードを指定します。Teleport コンポーネントの to 属性 と同等です | string | Element | - |
DropdownItem Events
| イベント名 | 説明 | コールバック引数 |
|---|---|---|
| change | オプションをクリックして value が変更されたときにトリガーされます | value |
| open | メニューバーを開くときにトリガーされます | - |
| close | メニューバーを閉じるときにトリガーされます | - |
| opened | メニューバーを開いてアニメーションが終了した後にトリガーされます | - |
| closed | メニューバーを閉じてアニメーションが終了した後にトリガーされます | - |
DropdownItem Slots
| 名前 | 説明 |
|---|---|
| default | メニューの内容 |
| title | メニューアイテムのタイトルをカスタマイズ |
DropdownMenu メソッド
ref を使用して DropdownMenu インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細については、コンポーネントインスタンスメソッドを参照してください。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| close | すべてのメニューの表示状態を閉じます | - | - |
DropdownItem メソッド
ref を使用して DropdownItem インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細については、コンポーネントインスタンスメソッドを参照してください。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| toggle | メニューの表示状態を切り替えます。true を渡すと表示、false を渡すと非表示、パラメータを渡さないと反転します | show?: boolean | - |
型定義
コンポーネントは以下の型定義をエクスポートします：
import type {
DropdownMenuProps,
DropdownItemProps,
DropdownItemOption,
DropdownItemInstance,
DropdownMenuInstance,
DropdownMenuDirection,
} from 'vant';DropdownMenuInstance と DropdownItemInstance はコンポーネントインスタンスの型で、次のように使用します：
import { ref } from 'vue';
import type { DropdownMenuInstance, DropdownItemInstance } from 'vant';
const dropdownMenuRef = ref<DropdownMenuInstance>();
const dropdownItemRef = ref<DropdownItemInstance>();
dropdownMenuRef.value?.close();
dropdownItemRef.value?.toggle();Option データ構造
| キー名 | 説明 | 型 |
|---|---|---|
| text | テキスト | string |
| value | 識別子 | number | string | boolean |
| disabled | オプションを無効にするかどうか | boolean |
| icon | 左側のアイコン名または画像リンク。Icon コンポーネントの name 属性 と同等です | string |
テーマカスタマイズ
スタイル変数
コンポーネントは次の CSS 変数を提供しており、ConfigProvider コンポーネントを参照して、カスタマイズすることができます。
| 名称 | デフォルト値 | 説明 |
|---|---|---|
| --van-dropdown-menu-height | 48px | - |
| --van-dropdown-menu-background | var(--van-background-2) | - |
| --van-dropdown-menu-shadow | 0 2px 12px fade(var(--van-gray-7), 12) | - |
| --van-dropdown-menu-title-font-size | 15px | - |
| --van-dropdown-menu-title-text-color | var(--van-text-color) | - |
| --van-dropdown-menu-title-active-text-color | var(--van-primary-color) | - |
| --van-dropdown-menu-title-disabled-text-color | var(--van-text-color-2) | - |
| --van-dropdown-menu-title-padding | 0 var(--van-padding-xs) | - |
| --van-dropdown-menu-title-line-height | var(--van-line-height-lg) | - |
| --van-dropdown-menu-option-active-color | var(--van-primary-color) | - |
| --van-dropdown-menu-option-disabled-color | var(--van-text-color-3) | - |
| --van-dropdown-menu-content-max-height | 80% | - |
| --van-dropdown-item-z-index | 10 | - |
🤔 よくある質問
親要素に transform を設定すると、ドロップダウンメニューの位置が間違ってしまいますか？
ドロップダウンメニューが迷子の子供のように、不思議な位置に表示されることがあります。これは通常、DropdownMenu を Tabs など transform が設定されたコンポーネントの内部に配置した場合に発生します。
これは移動する電車の車両内に物を置くようなもので、座標系が変化します！CSS の fixed 位置は、ページ全体ではなく、transform が設定された親要素に対して位置を計算します。
心配しないでください！解決策は簡単です！迷子の子供に家への道を示すように、DropdownItem の teleport 属性を body に設定して、メニューをページのルートに直接「テレポート」します：
<van-dropdown-item teleport="body" />または、DropdownMenu の auto-locate 属性を true に設定して、コンポーネントに自動的に正しい位置を見つけさせることもできます：
<van-dropdown-menu auto-locate="true" />🔗 関連ドキュメント
DropdownMenu を使用する際には、次のような関連コンポーネントも役立つことがあります。これらは仲良しの友人のように、プロジェクトでよく一緒に登場します：
- Popup ポップアップ - ドロップダウンメニューの基盤となる実装。これを理解すると、メニューの動作原理をより深く理解することができます
- ActionSheet アクションシート - もう一つの選択方法。特にモバイル端末の下部からのポップアップ選択に適しています
- Picker ピッカー - オプションが多く、階層関係がある場合に最適な選択肢です
- Tab タブ - DropdownMenu とよく組み合わせて使用され、ページの分類と絞り込み機能を実現します
- NavBar ナビゲーションバー - ドロップダウンメニューは多くの場合、ナビゲーションバーに配置され、クイックフィルタリング機能を提供します
- Search 検索 - ドロップダウンメニューと組み合わせることで、より強力なコンテンツの絞り込み機能を提供します
- Button ボタン - ドロップダウンメニューをトリガーするための一般的なコンポーネント
- Icon アイコン - メニューオプションにアイコンを追加し、インターフェースをより直感的で美しくします