PullRefresh プルリフレッシュ - Vant 4

🔄 PullRefresh プルリフレッシュ

🎯 紹介

PullRefresh コンポーネントはプルリフレッシュインタラクションを提供し、リフレッシュコールバック、成功通知などの機能をサポートします。主にリストのシナリオでの差分データ取得に使用されます。簡単な下方向のスワイプ操作で、ユーザーはページコンテンツを簡単に更新し、最新のデータを取得して、ユーザー体験を向上させることができます。

📦 導入

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

import { createApp } from 'vue';
import { PullRefresh } from 'vant';

const app = createApp();
app.use(PullRefresh);

🎯 コードデモ

🔧 基本的な使い方

プルリフレッシュを行うと、refresh イベントがトリガーされます。イベントのコールバック関数内で同期または非同期操作を行い、操作が完了したら v-model を false に設定すると、ロード完了を示します。これは最も一般的な使用シナリオで、リストデータの更新に適しています。

html

<template>
  <van-pull-refresh v-model="loading" @refresh="onRefresh">
    <div class="content">
      <p>更新回数: {{ count }}</p>
      <p>下に引っ張ってみてください 👆</p>
    </div>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const count = ref(0);
const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    showToast('更新成功');
    loading.value = false;
    count.value++;
  }, 1000);
};
</script>

<style>
.content {
  padding: 20px;
  text-align: center;
  background: #f7f8fa;
  min-height: 200px;
}
</style>

✅ 成功通知

success-text で更新成功後の上部通知テキストを設定できます。この機能により、ユーザーに明確なフィードバックを提供し、リフレッシュ操作が正常に完了したことを知らせることができます。

html

<template>
  <van-pull-refresh 
    v-model="loading" 
    success-text="更新成功 ✨"
    @refresh="onRefresh"
  >
    <div class="content">
      <p>成功通知付きのプルリフレッシュ</p>
      <p>更新後に成功通知が表示されます</p>
    </div>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 1000);
};
</script>

🎨 カスタム通知

スロットを使用して、プルリフレッシュ中の通知コンテンツをカスタマイズできます。この機能により、リフレッシュ中の視覚効果を完全にカスタマイゼし、独特なユーザー体験を実現できます。

html

<template>
  <van-pull-refresh v-model="loading" @refresh="onRefresh">
    <template #pulling="{ distance }">
      <div class="custom-pulling">
        <van-icon name="arrow-down" />
        <span>プル距離: {{ distance }}px</span>
      </div>
    </template>
    
    <template #loosing>
      <div class="custom-loosing">
        <van-icon name="success" color="#07c160" />
        <span>離すと更新します</span>
      </div>
    </template>
    
    <template #loading>
      <div class="custom-loading">
        <van-loading size="16" />
        <span>データを更新中...</span>
      </div>
    </template>
    
    <div class="content">
      <p>カスタム通知コンテンツ</p>
      <p>各状態に異なる通知があります</p>
    </div>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 2000);
};
</script>

<style>
.custom-pulling,
.custom-loosing,
.custom-loading {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 50px;
  font-size: 14px;
  color: #969799;
}

.custom-pulling span,
.custom-loosing span,
.custom-loading span {
  margin-left: 8px;
}
</style>

🎛️ カスタム設定

さまざまな属性を使用して、プルリフレッシュの動作と外観をカスタマイズできます。トリガー距離、アニメーションの期間、ヘッドの高さなどです。

html

<template>
  <van-pull-refresh 
    v-model="loading"
    pulling-text="力を込めて引っ張ってください 💪"
    loosing-text="もうすぐ離してください 🚀"
    loading-text="全力で読み込み中 ⚡"
    success-text="完了！ 🎉"
    :success-duration="2000"
    :animation-duration="500"
    :head-height="80"
    :pull-distance="100"
    @refresh="onRefresh"
  >
    <div class="content">
      <p>カスタム設定のプルリフレッシュ</p>
      <p>より高いヘッド、より長いトリガー距離</p>
      <p>個性化された通知テキスト</p>
    </div>
  </van-pull-refresh>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

const onRefresh = () => {
  setTimeout(() => {
    loading.value = false;
  }, 1500);
};
</script>

📋 API

🎛️ Props

パラメータ	説明	型	デフォルト値
v-model	読み込み中かどうか、リフレッシュアニメーションの表示を制御 🔄	boolean	-
pulling-text	プル中の通知テキスト、ユーザーに更に引っ張るよう誘導 👇	string	`下に引っ張って更新...`
loosing-text	離す過程の通知テキスト、ユーザーに離すと更新するよう通知 🚀	string	`離すと更新...`
loading-text	読み込み中の通知テキスト、データ読み込み状態を表示 ⏳	string	`読み込み中...`
success-text	更新成功の通知テキスト、ユーザーに成功をフィードバック ✅	string	-
success-duration	更新成功通知の表示時間(ms)、成功通知の表示時間を制御 ⏰	number \| string	`500`
animation-duration	アニメーションの期間、プルリフレッシュアニメーションのスムーズさを制御 🎬	number \| string	`300`
head-height	上部コンテンツの高さ、リフレッシュエリアの高さを設定 📏	number \| string	`50`
pull-distance	プルリフレッシュをトリガーする距離、リフレッシュの感度を制御 📐	number \| string	`head-height` と同じ
disabled	プルリフレッシュを無効にするかどうか、特定のシナリオでリフレッシュを禁止可能 🚫	boolean	`false`

🎪 Events

イベント名	説明	コールバック引数
refresh	プルリフレッシュ時にトリガーされ、データのリフレッシュロジックを実行 🔄	-
change	ドラッグ中または状態が変わるときにトリガーされ、リフレッシュ状態の変化を監視 📊	{ status: string, distance: number }

🎭 Slots

名前	説明	パラメータ
default	カスタムコンテンツ、更新が必要な主要コンテンツを配置 📄	-
normal	非プル状態の上部コンテンツ、デフォルト状態の通知エリア 😌	-
pulling	プル中の上部コンテンツ、ユーザーがプルしたときの動的通知 👇	{ distance: number }
loosing	離す過程の上部コンテンツ、リフレッシュがトリガーされそうなときの通知 🚀	{ distance: number }
loading	読み込み中の上部コンテンツ、データ読み込み中の状態表示 ⏳	{ distance: number }
success	更新成功の通知コンテンツ、リフレッシュが正常に完了した後のフィードバック ✨	-

📝 型定義

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

import type { PullRefreshProps } from 'vant';

🎨 テーマカスタマイズ

🎭 スタイル変数

コンポーネントは次のCSS変数を提供しています。スタイルをカスタマイズするには、ConfigProviderコンポーネントを参照してください。

名前	デフォルト値	説明
--van-pull-refresh-head-height	50px	リフレッシュヘッドの高さ、プルエリアの視覚的な空間を制御 📏
--van-pull-refresh-head-font-size	var(--van-font-size-md)	ヘッドのフォントサイズ、通知テキストの可読性に影響 📝
--van-pull-refresh-head-text-color	var(--van-text-color-2)	ヘッドのテキスト色、通知テキストの表示色を設定 🎨
--van-pull-refresh-loading-icon-size	16px	読み込みアイコンのサイズ、読み込みアニメーションの視覚的なサイズを制御 ⚙️

❓ よくある質問

PullRefreshの内容が画面いっぱいになっていない場合、一部分のエリアだけがプル可能になっていますか？

デフォルトでは、プルエリアの高さはコンテンツの高さと一致しています。プルエリアを常にフルスクリーンにするには、PullRefreshにスクリーンサイズと等しい最小高さを設定します：

html

<van-pull-refresh style="min-height: 100vh;">
  <!-- コンテンツ -->
</van-pull-refresh>

PullRefreshのトリガー条件は何ですか？

PullRefreshのトリガー条件は「親スクロール要素のスクロールバーが上端にある」です。

最も近いスクロール可能な親要素が window の場合、window.pageYOffset === 0 である必要があります。
最も近いスクロール可能な親要素が Element の場合、Element.scrollTop === 0 である必要があります。

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

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

📚 関連ドキュメント

🔗 関連コンポーネント

List リスト - リストコンポーネント、プルリフレッシュと組み合わせてデータを表示するのによく使用されます 📋
Search 検索 - 検索コンポーネント、検索結果ページの更新 🔍
Toast トースト - 軽量な通知、リフレッシュ成功のユーザーフィードバックに使用 🍞
Loading ローディング - ローディング状態インジケータ、データ読み込み中の状態表示 ⏳
Swipe スワイプ - スワイプコンポーネント、ジェスチャー操作によるコンテンツの表示 📱
Grid グリッド - グリッドレイアウト、グリッドコンテンツの一括更新 🔲

🔄 PullRefresh プルリフレッシュ ​

🎯 紹介 ​

📦 導入 ​

🎯 コードデモ ​

🔧 基本的な使い方 ​

✅ 成功通知 ​

🎨 カスタム通知 ​

🎛️ カスタム設定 ​

📋 API ​

🎛️ Props ​

🎪 Events ​

🎭 Slots ​

📝 型定義 ​

🎨 テーマカスタマイズ ​

🎭 スタイル変数 ​

❓ よくある質問 ​

PullRefreshの内容が画面いっぱいになっていない場合、一部分のエリアだけがプル可能になっていますか？ ​

PullRefreshのトリガー条件は何ですか？ ​

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

📚 関連ドキュメント ​

🔗 関連コンポーネント ​

🔄 PullRefresh プルリフレッシュ

🎯 紹介

📦 導入

🎯 コードデモ

🔧 基本的な使い方

✅ 成功通知

🎨 カスタム通知

🎛️ カスタム設定

📋 API

🎛️ Props

🎪 Events

🎭 Slots

📝 型定義

🎨 テーマカスタマイズ

🎭 スタイル変数

❓ よくある質問

PullRefreshの内容が画面いっぱいになっていない場合、一部分のエリアだけがプル可能になっていますか？

PullRefreshのトリガー条件は何ですか？

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

📚 関連ドキュメント

🔗 関連コンポーネント