Swipe スワイプ - Vant 4
Swipe スワイプ
紹介
画像やコンテンツのグループを循環表示します。
導入
以下の方法でコンポーネントをグローバル登録します。詳細はコンポーネント登録を参照してください。
import { createApp } from'vue'; import { Swipe, SwipeItem } from'vant'; const app = createApp(); app.use(Swipe); app.use(SwipeItem);コード例
基本用法
各 SwipeItem は 1 枚のスライドを表します。autoplay 属性で自動再生の間隔を設定できます。
遅延レンダリング
画像を含む場合は lazy-render 属性で遅延レンダリングを有効化できます。遅延レンダリングでは、現在のページと次のページのみがレンダリングされます。
exportdefault { setup() { const images = [ 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg', 'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg', ]; return { images }; }, };change イベントの監視
各ページのスワイプが終了すると change イベントが発火します。
import { showToast } from'vant'; exportdefault { setup() { constonChange = (index) => showToast('現在の Swipe のインデックス：' + index); return { onChange }; }, };縦方向スクロール
vertical 属性を設定するとスライドが縦方向に並びます。この場合、スライドコンテナの高さを指定してください。
スライドサイズのカスタマイズ
スライドのデフォルト幅は 100% です。width 属性で単一スライドの幅を、縦スクロールモードでは height 属性で高さを設定できます。
現時点ではループモードでスライドサイズのカスタマイズはできません。
loopをfalseに設定してください。
インジケータのカスタマイズ
indicator スロットでインジケータのスタイルをカスタマイズできます。
API
Swipe Props
| 属性名 | 説明 | 型 | デフォルト |
|---|---|---|---|
| autoplay | 自動再生の間隔（ms） | *number | string* |
| duration | アニメーション時間（ms） | *number | string* |
| initial-swipe | 初期位置のインデックス | *number | string* |
| width | スライドの幅（px） | *number | string* |
| height | スライドの高さ（px） | *number | string* |
| loop | ループ再生を有効にするか | boolean | true |
| show-indicators | インジケータを表示するか | boolean | true |
| vertical | 縦方向スクロールにするか | boolean | false |
| touchable | ジェスチャーでスワイプ可能か | boolean | true |
| stop-propagation | スワイプイベントのバブリングを防止するか | boolean | true |
| lazy-render | 未表示のスライドを遅延レンダリングするか | boolean | false |
| indicator-color | インジケータの色 | string | #1989fa |
Swipe Events
| イベント名 | 説明 | コールバック引数 |
|---|---|---|
| change | 各ページのスワイプ終了後に発火 | index: number |
drag-start v4.0.9 | ユーザーがドラッグを開始したときに発火 | { index: number } |
drag-end v4.0.9 | ユーザーがドラッグを終了したときに発火 | { index: number } |
SwipeItem Events
| イベント名 | 説明 | コールバック引数 |
|---|---|---|
| click | クリック時に発火 | event: MouseEvent |
Swipe メソッド
ref で Swipe のインスタンスを取得してメソッドを呼び出せます。詳細はコンポーネントインスタンスのメソッドを参照してください。
| メソッド名 | 説明 | 引数 | 戻り値 |
|---|---|---|---|
| prev | 前のスライドに切り替え | - | - |
| next | 次のスライドに切り替え | - | - |
| swipeTo | 指定位置へ切り替え | index: number, options: SwipeToOptions | - |
| resize | 外側要素のサイズや表示状態が変化したときに再描画をトリガー | - | - |
型定義
コンポーネントは以下の型をエクスポートします：
importtype { SwipeProps, SwipeInstance, SwipeToOptions } from'vant';SwipeInstance はコンポーネントインスタンスの型です。使用例：
import { ref } from'vue'; importtype { SwipeInstance } from'vant'; const swipeRef = ref<SwipeInstance>(); swipeRef.value?.next();SwipeToOptions 形式
| 名前 | 説明 | 型 |
|---|---|---|
| immediate | アニメーションをスキップするか | boolean |
Swipe Slots
| 名前 | 説明 | パラメータ |
|---|---|---|
| default | スワイプコンテンツ | - |
| indicator | カスタムインジケータ | { active: number, total: number } |
テーマカスタマイズ
スタイル変数
コンポーネントは以下の CSS 変数を提供します。使用方法は ConfigProvider コンポーネント を参照してください。
| 変数名 | デフォルト値 | 説明 |
|---|---|---|
| --van-swipe-indicator-size | 6px | - |
| --van-swipe-indicator-margin | var(--van-padding-sm) | - |
| --van-swipe-indicator-active-opacity | 1 | - |
| --van-swipe-indicator-inactive-opacity | 0.3 | - |
| --van-swipe-indicator-active-background | var(--van-primary-color) | - |
| --van-swipe-indicator-inactive-background | var(--van-border-color) | - |
よくある質問
スワイプ時に click が発火するのはなぜ？
この現象はプロジェクトに fastclick を導入している場合に発生しがちです。fastclick は Touch イベントから click を擬似的に生成しますが、Swipe は内部で touchmove のバブリングをデフォルトで抑止するため、その判定が干渉されて問題が起きます。
Swipe コンポーネントの stop-propagation を false に設定すると回避できます。
デスクトップでは操作できない？
詳しくはデスクトップ対応を参照してください。
Swipe コンポーネントの機能が少なく、複雑な効果を実現できない？
Vant の Swipe は軽量な設計のため機能は基本的なものに絞られています。より複雑なスライダー効果が必要な場合は、vue-awesome-swiper などのコミュニティライブラリの利用をおすすめします。
コンポーネントが非表示から表示に切り替わると正しく描画されない？
Swipe はマウント時に自身の幅を取得してスライド位置を計算します。最初にコンポーネントが非表示の場合、取得される幅が常に 0 となり、正しく位置計算ができません。
解決方法
方法1：v-show で表示制御している場合は v-if に置き換えると解決します。
方法2：コンポーネントの resize メソッドを呼び出して再描画を強制します。
this.$refs.swipe.resize();