Picker 選択器 - Vant 4

🎯 Picker 選択器

🎯 紹介

Picker コンポーネントは複数のオプション集合からユーザーに選択を提供し、単列選択、複数列選択、カスケード選択をサポートします。通常はポップアップコンポーネントと組み合わせて使用します。選択操作をより簡便にします！

📦 導入

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

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

🎯 コード例

🔧 基本用法

Picker は万能の選択魔法使いのようです！🎩 columns 属性でオプションデータを設定することで、文字列でもオブジェクト配列でも簡単に扱うことができます。上部バーは親切な操作パネルのようで、タイトル、確認、キャンセルボタンがあり、ユーザーのすべての選択が明確になります。

html

<template>
  <van-picker
    title="都市を選択"
    :columns="columns"
    @confirm="onConfirm"
    @cancel="onCancel"
    @change="onChange"
  />
</template>

import { showToast } from 'vant';

export default {
  setup() {
    const columns = [
      { text: '杭州', value: 'Hangzhou' },
      { text: '寧波', value: 'Ningbo' },
      { text: '温州', value: 'Wenzhou' },
      { text: '紹興', value: 'Shaoxing' },
      { text: '湖州', value: 'Huzhou' },
    ];
    
    const onConfirm = ({ selectedValues }) => {
      showToast(`選択しました: ${selectedValues.join(',')}`);
    };
    
    const onChange = ({ selectedValues }) => {
      console.log(`現在の選択: ${selectedValues.join(',')}`);
    };
    
    const onCancel = () => showToast('選択をキャンセル');
    
    return {
      columns,
      onChange,
      onCancel,
      onConfirm,
    };
  },
};

🎭 ポップアップと組み合わせる

実際のアプリケーションシナリオでは、Picker は優雅なダンサーのようで、Popup や Field コンポーネントと一緒に踊ることがよくあります！💃 この組み合わせにより、フォームの記入がよりスムーズで自然になり、ユーザーエクスペリエンスが向上します。

html

<template>
  <van-field
    v-model="fieldValue"
    is-link
    readonly
    label="都市を選択"
    placeholder="都市を選択するにはクリック"
    @click="showPicker = true"
  />
  <van-popup v-model:show="showPicker" position="bottom">
    <van-picker
      title="都市を選択"
      :columns="columns"
      @confirm="onConfirm"
      @cancel="showPicker = false"
    />
  </van-popup>
</template>

import { ref } from 'vue';

export default {
  setup() {
    const columns = [
      { text: '杭州', value: 'Hangzhou' },
      { text: '寧波', value: 'Ningbo' },
      { text: '温州', value: 'Wenzhou' },
      { text: '紹興', value: 'Shaoxing' },
      { text: '湖州', value: 'Huzhou' },
    ];
    
    const fieldValue = ref('');
    const showPicker = ref(false);
    
    const onConfirm = ({ selectedValues, selectedOptions }) => {
      showPicker.value = false;
      fieldValue.value = selectedOptions[0].text;
    };
    
    return {
      columns,
      onConfirm,
      fieldValue,
      showPicker,
    };
  },
};

🔄 双方向バインディング

データの双方向同期を実現したいですか？v-model はあなたの最高の相棒です！🤝 データとビューを繋ぐ橋のようで、選択状態とデータを完全に同期させます。

html

<template>
  <van-picker
    v-model="selectedValues"
    title="都市選択"
    :columns="columns"
  />
</template>

import { ref } from 'vue';

export default {
  setup() {
    const columns = [
      { text: '杭州', value: 'Hangzhou' },
      { text: '寧波', value: 'Ningbo' },
      { text: '温州', value: 'Wenzhou' },
      { text: '紹興', value: 'Shaoxing' },
      { text: '湖州', value: 'Huzhou' },
    ];
    
    const selectedValues = ref(['Wenzhou']);
    
    return {
      columns,
      selectedValues,
    };
  },
};

📊 複数列選択

複数の次元のデータを同時に選択する必要がありますか？複数列選択は多機能ツールボックスのようです！🧰 二次元配列で設定することで、曜日と時間帯などの複雑な組み合わせ選択を簡単に実現できます。

html

<template>
  <van-picker
    title="時間を選択"
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

import { showToast } from 'vant';

export default {
  setup() {
    const columns = [
      // 第一列：曜日
      [
        { text: '月曜日', value: 'Monday' },
        { text: '火曜日', value: 'Tuesday' },
        { text: '水曜日', value: 'Wednesday' },
        { text: '木曜日', value: 'Thursday' },
        { text: '金曜日', value: 'Friday' },
      ],
      // 第二列：時間帯
      [
        { text: '午前', value: 'Morning' },
        { text: '午後', value: 'Afternoon' },
        { text: '夜', value: 'Evening' },
      ],
    ];
    
    const onConfirm = ({ selectedValues }) => {
      showToast(`選択しました：${selectedValues.join(' ')}`);
    };
    
    return { columns, onConfirm };
  },
};

🌊 カスケード選択

カスケード選択はスマートなナビゲーションシステムのようです！🗺️ 上位の選択に応じて自動的に下位のオプションを表示し、複雑な階層選択を秩序立てて行います。省市区選択は最も典型的なアプリケーションシナリオです。

html

<template>
  <van-picker
    title="地域を選択"
    :columns="columns"
    @confirm="onConfirm"
  />
</template>

import { showToast } from 'vant';

export default {
  setup() {
    const columns = [
      {
        text: '浙江省',
        value: 'Zhejiang',
        children: [
          {
            text: '杭州',
            value: 'Hangzhou',
            children: [
              { text: '西湖区', value: 'Xihu' },
              { text: '余杭区', value: 'Yuhang' },
            ],
          },
          {
            text: '温州',
            value: 'Wenzhou',
            children: [
              { text: '鹿城区', value: 'Lucheng' },
              { text: '甌海区', value: 'Ouhai' },
            ],
          },
        ],
      },
      {
        text: '福建省',
        value: 'Fujian',
        children: [
          {
            text: '福州',
            value: 'Fuzhou',
            children: [
              { text: '鼓楼区', value: 'Gulou' },
              { text: '台江区', value: 'Taijiang' },
            ],
          },
          {
            text: '厦門',
            value: 'Xiamen',
            children: [
              { text: '思明区', value: 'Siming' },
              { text: '海滄区', value: 'Haicang' },
            ],
          },
        ],
      },
    ];
    
    const onConfirm = ({ selectedValues }) => {
      showToast(`選択した地域：${selectedValues.join(' - ')}`);
    };
    
    return { columns, onConfirm };
  },
};

💡 ヒント：カスケード選択のデータのネスト深さは一貫している必要があります。一部のオプションに子オプションがない場合は、空の文字列で埋めることができます。

🚫 オプションを無効にする

一部のオプションは一時的に利用できないですか？disabled 属性を設定すると、オプションに「サービス一時停止」のラベルを貼るようなものです！🏷️ ユーザーは見ることはできますが選択することはできず、より使いやすくなります。

html

<template>
  <van-picker
    title="都市を選択"
    :columns="columns"
  />
</template>

export default {
  setup() {
    const columns = [
      { text: '杭州', value: 'Hangzhou', disabled: true },
      { text: '寧波', value: 'Ningbo' },
      { text: '温州', value: 'Wenzhou' },
    ];
    
    return { columns };
  },
};

⏳ ロード状態

データはまだ途中ですか？ロード状態は親切な待機ヒントのようです！⌛ 選択器のデータが非同期的に取得される必要がある場合、loading 属性によって優雅なロードアニメーションが表示され、ユーザーに良いものが準備中であることを知らせます。

html

<template>
  <van-picker
    title="都市を選択"
    :columns="columns"
    :loading="loading"
  />
</template>

import { ref } from 'vue';

export default {
  setup() {
    const columns = ref([]);
    const loading = ref(true);
    
    // 非同期データロードのシミュレーション
    setTimeout(() => {
      columns.value = [
        { text: '杭州', value: 'Hangzhou' },
        { text: '寧波', value: 'Ningbo' },
        { text: '温州', value: 'Wenzhou' },
      ];
      loading.value = false;
    }, 2000);
    
    return { columns, loading };
  },
};

📭 空の状態

データがない場合はどうしますか？空の状態のスロットは親切な表示板のようです！📋 データが空の場合、表示内容をカスタマイズすることで、ユーザーに現在の状況を理解してもらうことができます。

html

<template>
  <van-picker title="都市を選択" :columns="[]">
    <template #empty>
      <div class="empty-content">
        <img src="empty-icon.png" alt="データなし" />
        <p>選択可能な都市はありません</p>
      </div>
    </template>
  </van-picker>
</template>

🔧 Columns の構造をカスタマイズ

データ構造が標準でないですか？問題ありません！columns-field-names 属性によって、データに適切な服を着せるようなものです！👔 どんな構造のデータでも完璧に適合させることができます。

html

<template>
  <van-picker
    title="地域を選択"
    :columns="columns"
    :columns-field-names="customFieldName"
  />
</template>

export default {
  setup() {
    const columns = [
      {
        cityName: '浙江省',
        cities: [
          {
            cityName: '杭州',
            cities: [
              { cityName: '西湖区' },
              { cityName: '余杭区' }
            ],
          },
          {
            cityName: '温州',
            cities: [
              { cityName: '鹿城区' },
              { cityName: '甌海区' }
            ],
          },
        ],
      },
      {
        cityName: '福建省',
        cities: [
          {
            cityName: '福州',
            cities: [
              { cityName: '鼓楼区' },
              { cityName: '台江区' }
            ],
          },
          {
            cityName: '厦門',
            cities: [
              { cityName: '思明区' },
              { cityName: '海滄区' }
            ],
          },
        ],
      },
    ];
    
    const customFieldName = {
      text: 'cityName',
      value: 'cityName',
      children: 'cities',
    };
    
    return {
      columns,
      customFieldName,
    };
  },
};

API

プロパティ

パラメータ	説明	型	デフォルト値
v-model	現在の選択項目に対応する値、選択器の選択状態を制御 🎯	number[] \| string[]	-
columns	オブジェクト配列、各列に表示するデータを設定、選択器のデータソースのよう 📊	PickerOption[] \| PickerOption[][]	`[]`
columns-field-names	`columns` 構造内のフィールドをカスタマイズ、データ構造をより柔軟にする 🔧	object	`{ text: 'text', value: 'value', children: 'children' }`
title	上部バーのタイトル、選択器に明確な識別子を追加 📝	string	-
confirm-button-text	確認ボタンのテキスト、空の文字列を設定するとボタンを非表示にできる ✅	string	`确认`
cancel-button-text	キャンセルボタンのテキスト、空の文字列を設定するとボタンを非表示にできる ❌	string	`取消`
toolbar-position	上部バーの位置、`bottom` を指定可能、ツールバーの表示位置を制御 📍	string	`top`
loading	ロード状態を表示するかどうか、データロード時の親切なヒント ⏳	boolean	`false`
readonly	読み取り専用モードかどうか、読み取り専用モードではオプションを切り替えられない 🔒	boolean	`false`
show-toolbar	上部バーを表示するかどうか、ツールバーの表示と非表示を制御 🎛️	boolean	`true`
allow-html	オプションの内容に HTML をレンダリングするかどうか、リッチテキスト表示をサポート 🎨	boolean	`false`
option-height	オプションの高さ、px``vw``vh``rem 単位をサポート、デフォルトは `px` 📏	number \| string	`44`
visible-option-num	表示可能なオプションの数、選択器のウィンドウサイズを制御 👀	number \| string	`6`
swipe-duration	素早くスワイプしたときの慣性スクロールの時間、単位 `ms`、スワイプ体験に影響する ⚡	number \| string	`1000`

イベント

イベント名	説明	コールバック引数
confirm	完了ボタンをクリックしたときにトリガー、選択操作を確定 ✨	{ selectedValues, selectedOptions, selectedIndexes }
cancel	キャンセルボタンをクリックしたときにトリガー、選択操作をキャンセル 🚫	{ selectedValues, selectedOptions, selectedIndexes }
change	選択したオプションが変更されたときにトリガー、リアルタイムで選択の変化に応答 🔄	{ selectedValues, selectedOptions, selectedIndexes, columnIndex }
click-option	オプションをクリックしたときにトリガー、ユーザーのクリック行動をキャプチャ 👆	{ currentOption, selectedValues, selectedOptions, selectedIndexes, columnIndex }
scroll-into `v4.2.1`	ユーザーがクリックまたはドラッグしてオプションを中央の選択エリアにスクロールしたときにトリガー 🎯	{ currentOption, columnIndex }

スロット

名前	説明	パラメータ
toolbar	上部バー全体の内容をカスタマイズ、ツールバーのスタイルを完全に制御 🎛️	-
title	タイトルの内容をカスタマイズ、個性化されたタイトル表示 📝	-
confirm	確認ボタンの内容をカスタマイズ、独自の確認ボタンを作成 ✅	-
cancel	キャンセルボタンの内容をカスタマイズ、個性化されたキャンセルボタン ❌	-
option	オプションの内容をカスタマイズ、オプションの表示スタイルを完全に制御 🎨	option: PickerOption, index: number
columns-top	オプションの上部の内容をカスタマイズ、選択エリアの上にコンテンツを追加 ⬆️	-
columns-bottom	オプションの下部の内容をカスタマイズ、選択エリアの下にコンテンツを追加 ⬇️	-
empty `v4.9.10`	空の状態の内容をカスタマイズ、データが空の場合の親切なヒント 📭	-

PickerOption データ構造

キー名	説明	型
text	オプションのテキスト内容、ユーザーに表示されるテキスト 📝	string \| number
value	オプションに対応する値、データバインディングに使用される実際の値 🎯	string \| number
disabled	オプションを無効にするかどうか、無効にすると選択できない 🚫	boolean
children	カスケードオプション、多段階選択構造を構築するために使用 🌊	PickerOption[]
className	オプションの追加クラス名、カスタムスタイルに使用 🎨	string \| Array \| object

メソッド

ref を使用すると、Picker インスタンスを取得してインスタンスメソッドを呼び出すことができます。詳細についてはコンポーネントインスタンスメソッドを参照してください。

メソッド名	説明	パラメータ	戻り値
confirm	慣性スクロールを停止し、`confirm` イベントをトリガー、手動で選択を確定 ✅	-	-
getSelectedOptions	現在選択されているオプションを取得、完全なオプションオブジェクトを返す 📋	-	(PickerOption \| undefined)[]

型定義

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

import type {
  PickerProps,
  PickerColumn,
  PickerOption,
  PickerInstance,
  PickerFieldNames,
  PickerToolbarPosition,
  PickerCancelEventParams,
  PickerChangeEventParams,
  PickerConfirmEventParams,
} from 'vant';

PickerInstance はコンポーネントインスタンスの型で、以下のように使用します：

import { ref } from 'vue';
import type { PickerInstance } from 'vant';

const pickerRef = ref<PickerInstance>();
pickerRef.value?.confirm();

🎨 テーマカスタマイズ

スタイル変数

ユニークな選択器を作りたいですか？これらの CSS 変数はあなたのカラーパレットです！🎨 これらの変数をカスタマイズすることで、簡単に個性化された視覚効果を実現できます。

名前	デフォルト値	説明
--van-picker-background	var(--van-background-2)	選択器の背景色、全体の雰囲気を作り出す 🎭
--van-picker-toolbar-height	44px	ツールバーの高さ、上部操作エリアのサイズを制御 📏
--van-picker-title-font-size	var(--van-font-size-lg)	タイトルのフォントサイズ、タイトルの重要性を強調 📝
--van-picker-title-line-height	var(--van-line-height-md)	タイトルの行間、テキストの表示効果を最適化 📐
--van-picker-action-padding	0 var(--van-padding-md)	操作ボタンの内側余白、ボタンのタッチ領域を調整 👆
--van-picker-action-font-size	var(--van-font-size-md)	操作ボタンのフォントサイズ、ボタンの読みやすさを確保 🔤
--van-picker-confirm-action-color	var(--van-primary-color)	確認ボタンの色、主要な操作を強調 ✅
--van-picker-cancel-action-color	var(--van-text-color-2)	キャンセルボタンの色、二次的な操作と区別 ❌
--van-picker-option-padding	0 var(--van-padding-base)	オプションの内側余白、オプションの表示効果を最適化 📦
--van-picker-option-font-size	var(--van-font-size-lg)	オプションのフォントサイズ、オプションの明確な読みやすさを確保 🔍
--van-picker-option-text-color	var(--van-text-color)	オプションのテキスト色、良好なコントラストを維持 🎨
--van-picker-option-disabled-opacity	0.3	無効なオプションの透明度、視覚的に使用可能な状態を区別 👻
--van-picker-mask-color	linear-gradient	マスクのグラデーション色、フォーカス効果を作り出す 🌈
--van-picker-loading-icon-color	var(--van-primary-color)	ロードアイコンの色、ブランドの一貫性を維持 ⏳
--van-picker-loading-mask-color	rgba(255, 255, 255, 0.9)	ロードマスクの色、ロード状態のフィードバックを提供 🎭

❓ よくある質問

デスクトップ環境でコンポーネントを操作できませんか？

デスクトップ対応を参照してください。

📚 関連文書

Popup ポップアップ - 強力なポップアップコンポーネント、Picker とよく組み合わせて使用 📱
Field 入力フィールド - フォーム入力コンポーネント、Picker と完璧に組み合わせて選択入力を実現 ✏️
DatePicker 日付選択 - 専門の日付選択器、Picker を基に構築 📅
TimePicker 時間選択 - 専門の時間選択器、時間選択の最適な選択 ⏰
Cascader カスケード選択 - 多段階カスケード選択コンポーネント、複雑な階層データを処理 🌊
ActionSheet アクションシート - 下部アクション選択パネル、別の選択インタラクション方式 📋
PickerGroup 選択器グループ - 複数の選択器の組み合わせ管理 🎯
ConfigProvider グローバル設定 - グローバル設定コンポーネント、テーマスタイルを一元管理 ⚙️

🎯 Picker 選択器 ​

🎯 紹介 ​

📦 導入 ​

🎯 コード例 ​

🔧 基本用法 ​

🎭 ポップアップと組み合わせる ​

🔄 双方向バインディング ​

📊 複数列選択 ​

🌊 カスケード選択 ​

🚫 オプションを無効にする ​

⏳ ロード状態 ​

📭 空の状態 ​

🔧 Columns の構造をカスタマイズ ​

API ​

プロパティ ​

イベント ​

スロット ​

PickerOption データ構造 ​

メソッド ​

型定義 ​

🎨 テーマカスタマイズ ​

スタイル変数 ​

❓ よくある質問 ​

デスクトップ環境でコンポーネントを操作できませんか？ ​

📚 関連文書 ​

🎯 Picker 選択器

🎯 紹介

📦 導入

🎯 コード例

🔧 基本用法

🎭 ポップアップと組み合わせる

🔄 双方向バインディング

📊 複数列選択

🌊 カスケード選択

🚫 オプションを無効にする

⏳ ロード状態

📭 空の状態

🔧 Columns の構造をカスタマイズ

API

プロパティ

イベント

スロット

PickerOption データ構造

メソッド

型定義

🎨 テーマカスタマイズ

スタイル変数

❓ よくある質問

デスクトップ環境でコンポーネントを操作できませんか？

📚 関連文書