モバイルWebでPull-to-Refresh実装時の注意点と解決策

公開日:

2025-06-28

Pull-to-Refresh（下に引っ張って更新）は、モバイルアプリでお馴染みのUIパターンです。しかし、Webアプリケーションでこの機能を実装する際には、ネイティブアプリとは異なる多くの課題があります。本記事では、実際に遭遇した問題とその解決方法について詳しく解説します。

Pull-to-Refresh実装時の主な問題

1. 無限ループ問題

最も厄介な問題の一つが、「離して更新」の表示が消えず、ローディング状態が続いてしまう無限ループです。

問題のあるコード：

const handleTouchEnd = async () => {
  if (pullDistance > PULL_THRESHOLD) {
    setIsRefreshing(true);
    await onRefresh();
    setIsRefreshing(false); // これが実行されない場合がある
  }
};

解決方法：

const handleTouchEnd = async () => {
  if (pullDistance > PULL_THRESHOLD && !isRefreshing) {
    setIsRefreshing(true);
    setPullDistance(0); // 即座にリセット
    setIsPulling(false);
    
    try {
      await onRefresh();
    } catch (error) {
      console.error('Refresh failed:', error);
    } finally {
      // 確実にリセットされるようにタイムアウトも設定
      setTimeout(() => {
        setIsRefreshing(false);
      }, 100);
    }
  }
};

2. スクロール干渉問題

通常のスクロール操作がPull-to-Refreshとして誤認識される問題も頻繁に発生します。

解決方法：

const handleTouchMove = (e) => {
  // より厳密な条件チェック
  if (window.scrollY > 0 || document.body.scrollTop > 0) return;
  if (isRefreshing) return;
  
  const deltaY = e.touches[0].clientY - startY.current;
  
  // 最初の動きが下向きの場合のみ処理
  if (deltaY > 0 && startY.current > 0) {
    // iOS Safari のオーバースクロールを無効化
    document.body.style.overscrollBehavior = 'none';
    e.preventDefault();
    
    setPullDistance(Math.min(deltaY, PULL_THRESHOLD + 20));
    setIsPulling(deltaY > PULL_THRESHOLD);
  }
};

React実装の完全な例

import { useState, useRef, useEffect } from 'react';
import { RefreshCw } from 'lucide-react';

export function PullToRefresh({ onRefresh, children }) {
  const [isPulling, setIsPulling] = useState(false);
  const [pullDistance, setPullDistance] = useState(0);
  const [isRefreshing, setIsRefreshing] = useState(false);
  const startY = useRef(0);
  const containerRef = useRef(null);
  
  const PULL_THRESHOLD = 80;

  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;

    const handleTouchStart = (e) => {
      if (window.scrollY === 0) {
        startY.current = e.touches[0].clientY;
      }
    };

    const handleTouchMove = (e) => {
      if (window.scrollY > 0 || isRefreshing) return;

      const currentY = e.touches[0].clientY;
      const deltaY = currentY - startY.current;

      if (deltaY > 0) {
        e.preventDefault();
        const distance = Math.min(deltaY, PULL_THRESHOLD + 20);
        setPullDistance(distance);
        setIsPulling(distance > PULL_THRESHOLD);
      }
    };

    const handleTouchEnd = async () => {
      if (pullDistance > PULL_THRESHOLD && !isRefreshing) {
        setIsRefreshing(true);
        setPullDistance(0);
        setIsPulling(false);
        
        try {
          await onRefresh();
        } catch (error) {
          console.error('Refresh failed:', error);
        } finally {
          setTimeout(() => {
            setIsRefreshing(false);
          }, 100);
        }
      } else {
        setPullDistance(0);
        setIsPulling(false);
      }
      
      startY.current = 0;
    };

    container.addEventListener('touchstart', handleTouchStart);
    container.addEventListener('touchmove', handleTouchMove, { passive: false });
    container.addEventListener('touchend', handleTouchEnd);

    return () => {
      container.removeEventListener('touchstart', handleTouchStart);
      container.removeEventListener('touchmove', handleTouchMove);
      container.removeEventListener('touchend', handleTouchEnd);
    };
  }, [onRefresh, pullDistance, isRefreshing]);

  return (
    <div ref={containerRef} className="relative overflow-hidden">
      <div 
        className={`absolute top-0 left-0 right-0 z-50 flex items-center justify-center
          bg-blue-50 transition-all duration-300 ease-out
          ${pullDistance > 0 ? 'opacity-100' : 'opacity-0'}`}
        style={{ 
          height: `${Math.min(pullDistance, PULL_THRESHOLD)}px`,
          transform: `translateY(-${Math.max(0, PULL_THRESHOLD - pullDistance)}px)`
        }}
      >
        <div className="flex items-center gap-2 text-blue-600">
          <RefreshCw className={`w-5 h-5 ${isRefreshing ? 'animate-spin' : ''}`} />
          <span className="text-sm font-medium">
            {isRefreshing ? '更新中...' : isPulling ? '離して更新' : '下に引いて更新'}
          </span>
        </div>
      </div>
      
      <div 
        className="transition-transform duration-300 ease-out"
        style={{ transform: `translateY(${Math.min(pullDistance * 0.5, PULL_THRESHOLD * 0.5)}px)` }}
      >
        {children}
      </div>
    </div>
  );
}

ブラウザ別の考慮事項

iOS Safari対応

// iOS Safari 特有の対応
const isiOS = /iPad|iPhone|iPod/.test(navigator.userAgent);

if (isiOS) {
  // bounce スクロールの制御
  document.addEventListener('touchmove', (e) => {
    if (isPulling) {
      e.preventDefault();
    }
  }, { passive: false });
}

Android Chrome対応

/* overscroll-behavior でネイティブの挙動を制御 */
.pull-to-refresh-enabled {
  overscroll-behavior-y: contain;
}

パフォーマンス最適化

requestAnimationFrameの活用

const rafRef = useRef();

const handleTouchMove = (e) => {
  if (rafRef.current) {
    cancelAnimationFrame(rafRef.current);
  }
  
  rafRef.current = requestAnimationFrame(() => {
    const deltaY = e.touches[0].clientY - startY.current;
    
    if (deltaY > 0 && window.scrollY === 0) {
      e.preventDefault();
      setPullDistance(Math.min(deltaY, PULL_THRESHOLD + 20));
      setIsPulling(deltaY > PULL_THRESHOLD);
    }
  });
};

静的サイトでの考慮事項

静的サイトジェネレーター（SSG）で生成されたサイトでは、Pull-to-Refreshの実装に特別な注意が必要です。

問題点：

データの更新ができない（静的コンテンツのため）
Service Workerのキャッシュとの競合
ユーザーの期待と実際の動作のギャップ

推奨される対処法：

// 1. 機能を無効化または削除
const shouldEnablePullToRefresh = () => {
  // 動的なデータ取得が可能な場合のみ有効化
  return window.location.pathname.includes('/api/') || 
         hasRealtimeDataSource();
};

// 2. 明確なフィードバック
const handleRefresh = async () => {
  try {
    const hasNewContent = await checkForUpdates();
    
    if (!hasNewContent) {
      showToast('すでに最新の内容です');
      return;
    }
    
    window.location.reload();
  } catch (error) {
    showToast('更新に失敗しました');
  }
};

デバッグのヒント

状態の可視化

// 開発環境でのデバッグ表示
{process.env.NODE_ENV === 'development' && (
  <div className="fixed top-0 left-0 bg-black text-white p-2 text-xs">
    <div>Pull Distance: {pullDistance}px</div>
    <div>Is Pulling: {isPulling ? 'Yes' : 'No'}</div>
    <div>Is Refreshing: {isRefreshing ? 'Yes' : 'No'}</div>
  </div>
)}

コンソールログの活用

useEffect(() => {
  console.log('Pull-to-Refresh State:', {
    pullDistance,
    isPulling,
    isRefreshing,
    scrollY: window.scrollY
  });
}, [pullDistance, isPulling, isRefreshing]);