List リスト - Vant 4
📋 List リスト
🎯 紹介
List コンポーネントは、「スマートな滝」🌊 のようなものです！ユーザーのスクロール行動を自動的に感知し、ユーザーがリストの底部に近づくと、魔法使いのように自動的により多くのコンテンツを「出現」させます。商品リスト、ニュース情報、SNSの動的コンテンツなど、どんな場面でもスムーズな無限スクロール体験を提供し、ユーザーをコンテンツの海に没頭させます！
📦 導入
以下の方法でコンポーネントをグローバルに登録します。詳細な登録方法についてはコンポーネントの登録を参照してください。
import { createApp } from'vue'; import { List } from'vant'; const app = createApp(); app.use(List);🚀 コードサンプル
🔧 基本的な使い方
List コンポーネントは loading と finished の2つの変数でロード状態を制御します。まるでリストに「スマートブレイン」🧠 を搭載したかのようです！コンポーネントが底部までスクロールすると、load イベントがトリガーされ、loading が true に設定されます。この時点で非同期操作を開始してデータを更新し、データの更新が完了したら、loading を false に設定するだけです。データがすべてロード済みの場合は、単純に finished を true に設定するだけです。
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); constonLoad = () => { // 非同期でデータを更新// setTimeout は例示用であり、実際のシナリオでは通常 ajax リクエストを使用しますsetTimeout(() => { for (let i = 0; i < 10; i++) { list.value.push(list.value.length + 1); } // ロード状態を終了する loading.value = false; // データがすべてロード完了if (list.value.length >= 40) { finished.value = true; } }, 1000); }; return { list, onLoad, loading, finished, }; }, };❌ エラーメッセージ
リストデータのロードに失敗した場合、error を true に設定するだけでエラーメッセージを表示できます。まるでユーザーに親切な「再試行ボタン」🔄 を提供するかのようです！ユーザーがエラーメッセージをクリックすると、load イベントが再トリガーされ、失敗を再開の機会に変えます。
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const error = ref(false); const loading = ref(false); constonLoad = () => { fetchSomeThing().catch(() => { loading.value = false; error.value = true; }); }; return { list, error, onLoad, loading, }; }, };🔄 プルリフレッシュ
List コンポーネントは PullRefresh コンポーネントと組み合わせて使用することができ、プルリフレッシュの効果を実現します。まるでリストに「タイムマシン」を搭載したかのようで、ユーザーは簡単に最新のコンテンツを取得できます！
import { ref } from'vue'; exportdefault { setup() { const list = ref([]); const loading = ref(false); const finished = ref(false); const refreshing = ref(false); constonLoad = () => { setTimeout(() => { if (refreshing.value) { list.value = []; refreshing.value = false; } for (let i = 0; i < 10; i++) { list.value.push(list.value.length + 1); } loading.value = false; if (list.value.length >= 40) { finished.value = true; } }, 1000); }; constonRefresh = () => { // リストデータを空にする finished.value = false; // データを再ロード// loading を true に設定して、ロード中の状態を示す loading.value = true; onLoad(); }; return { list, onLoad, loading, finished, onRefresh, refreshing, }; }, };API
Props
| パラメータ | 説明 | 型 | デフォルト値 |
|---|---|---|---|
| v-model:loading | ロード中の状態かどうか。ロード中は load イベントはトリガーされません | boolean | false |
| v-model:error | ロードに失敗したかどうか。ロードに失敗すると、エラーメッセージをクリックすると load イベントが再トリガーされます | boolean | false |
| finished | すべてのデータがロード済みかどうか。ロード完了後は load イベントはトリガーされません | boolean | false |
| offset | スクロールバーが底部から offset よりも小さい距離にあるときに load イベントをトリガー | number | string | 300 |
| loading-text | ロード中のメッセージ | string | 読み込み中... |
| finished-text | ロード完了後のメッセージ | string | - |
| error-text | ロード失敗後のメッセージ | string | - |
| immediate-check | 初期化時にスクロール位置を即座にチェックするかどうか | boolean | true |
| disabled | スクロールロードを無効にするかどうか | boolean | false |
| direction | スクロールによるロードのトリガー方向。オプションは up | string | down |
scroller v4.6.4 | スクロールイベントを監視するノードを指定します。デフォルトは直近の親スクロールノードです | Element | - |
Events
| イベント名 | 説明 | コールバックパラメータ |
|---|---|---|
| load | スクロールバーが底部から offset よりも小さい距離にあるときにトリガー | - |
メソッド
ref を使用して List インスタンスを取得し、インスタンスメソッドを呼び出すことができます。詳細はコンポーネントインスタンスメソッドを参照してください。
| メソッド名 | 説明 | パラメータ | 戻り値 |
|---|---|---|---|
| check | 現在のスクロール位置をチェックします。底部までスクロールされている場合は、load イベントがトリガーされます | - | - |
型定義
コンポーネントは以下の型定義をエクスポートしています：
importtype { ListProps, ListInstance, ListDirection } from'vant';ListInstance はコンポーネントインスタンスの型で、以下のように使用します：
import { ref } from'vue'; importtype { ListInstance } from'vant'; const listRef = ref<ListInstance>(); listRef.value?.check();Slots
| 名前 | 説明 |
|---|---|
| default | リストのコンテンツ |
| loading | カスタム底部ローディングメッセージ |
| finished | カスタムロード完了後のメッセージ |
| error | カスタムロード失敗後のメッセージ |
テーマカスタマイズ
スタイル変数
コンポーネントは以下の CSS 変数を提供しており、カスタムスタイルに使用できます。使用方法については ConfigProvider コンポーネント を参照してください。
| 名前 | デフォルト値 | 説明 |
|---|---|---|
| --van-list-text-color | var(--van-text-color-2) | - |
| --van-list-text-font-size | var(--van-font-size-md) | - |
| --van-list-text-line-height | 50px | - |
| --van-list-loading-icon-size | 16px | - |
よくある質問
List の動作メカニズムは何ですか？
List はブラウザのスクロールイベントを監視し、リストの位置を計算します。リストの底部と表示領域の距離が offset より小さくなると、List は load イベントを1回トリガーします。
なぜ List の初期化後にすぐに load イベントがトリガーされるのですか？
List の初期化後、最初の画面のデータをロードするために load イベントが1回トリガーされます。この機能は immediate-check 属性で無効にすることができます。
なぜ load イベントが連続してトリガーされるのですか？
1回のリクエストでロードされるデータの数が少なく、リストのコンテンツが現在の画面を埋めることができない場合、List はコンテンツが画面を埋めるかデータがすべてロードされるまで、引き続き load イベントをトリガーします。
したがって、取得するデータの数を調整する必要があります。理想的には、1回のリクエストで取得するデータの数は、画面の高さを埋めるのに十分なものである必要があります。
loading と finished はそれぞれどういう意味ですか？
List には以下の3つの状態があります。これらの状態を理解すると、List コンポーネントを正しく使用するのに役立ちます：
- 非ロード中、
loadingがfalse：このとき、リストのスクロール位置に基づいてloadイベントをトリガーするかどうかが判断されます（リストコンテンツが1画面未満の場合、直接トリガーされます）。 - ロード中、
loadingがtrue：非同期リクエストを送信中であることを示します。このとき、loadイベントはトリガーされません。 - ロード完了、
finishedがtrue：このとき、loadイベントはトリガーされません。
各リクエストが完了したら、loading を false に手動で設定して、ロードが終了したことを示す必要があります。
float レイアウトを使用すると、ロードが継続的にトリガーされるのはなぜですか？
List のコンテンツが float レイアウトを使用している場合、容器に van-clearfix クラス名を追加してフロートをクリアすることで、List が要素の位置を正しく判断できるようになります。
html、body に overflow を設定すると、ロードが継続的にトリガーされるのはなぜですか？
html タグと body タグに overflow-x: hidden スタイルを設定すると、List がロードを継続的にトリガーする可能性があります。
html, body { overflow-x: hidden; }この問題の原因は、要素に overflow-x: hidden スタイルを設定すると、その要素の overflow-y がブラウザによってデフォルトの visible ではなく auto に設定され、List がスクロールコンテナを正しく判断できなくなるためです。解決策は、このスタイルを削除するか、html タグと body タグに height: 100% スタイルを追加することです。
direction 属性を up に設定すると、ロードが継続的にトリガーされるのはなぜですか？
direction 属性を up に設定すると、スクロールバーがページの上部にあるときに、List コンポーネントのロードがトリガーされます。
したがって、この属性を使用する場合は、データのロードが完了するたびに、スクロールバーをページの下部または上部以外の位置にスクロールすることをお勧めします。
📚 関連ドキュメント
🔄 インタラクションコンポーネント
- PullRefresh プルリフレッシュ - プルリフレッシュコンポーネント。リストとの完璧な組み合わせ
- SwipeCell スワイプセル - スワイプセルコンポーネント。リストアイテムのインタラクションを強化
📋 リスト関連
- Cell セル - セルコンポーネント。リストアイテムを構築する基本コンポーネント
- IndexBar インデックスバー - インデックスバーコンポーネント。長いリストの高速位置特定ツール
🚀 パフォーマンス最適化
- Lazyload レイジーロード - レイジーロードコンポーネント。リストのパフォーマンスを向上させる神器
- Loading ローディング - ローディングコンポーネント。待ち時間の体験を向上
- Skeleton スケルトンスクリーン - スケルトンスクリーンコンポーネント。ローディング状態の優雅な表示
🎨 デザインコンポーネント
- Empty 空の状態 - 空の状態コンポーネント。データがない場合の友好的なヒント
- ConfigProvider グローバル設定 - グローバル設定コンポーネント。テーマスタイルを統一的に管理
- Divider 分割線 - 分割線コンポーネント。リストコンテンツのグループ化ツール