萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

原生 JavaScript 實現下拉刷新(Pull-to-Refresh)完整教學

效果預覽

在移動端網頁中,用戶向下拖動列表超過閾值後釋放,觸發資料重新載入動畫,並將新資料插入列表頂部。

核心原理

  1. 監聽 touchstart 記錄手指初始 Y 軸座標。
  2. touchmove 計算位移差值,動態調整列表 transform: translateY() 或 top 實現跟手拖動。
  3. touchend 判斷位移是否超過閾值(如 70px),超過則觸發刷新回調,否則平滑回彈。
  4. 刷新完成後,重置列表位置。

完整實作代碼

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
  <title>Pull to Refresh Demo</title>
  <style>
    * { box-sizing: border-box; margin: 0; padding: 0; }
    .outer-scroller {
      position: relative; /* 改為 relative 以便內部 absolute 定位 */
      width: 100%; height: 100vh;
      overflow: hidden;
      touch-action: pan-y; /* 允許垂直滾動 */
    }
    .scroll-list {
      position: absolute;
      top: 0; left: 0; right: 0;
      list-style: none;
      transition: transform 0.3s cubic-bezier(0.25, 0.46, 0.45, 0.94);
      will-change: transform;
    }
    .scroll-list li {
      height: 50px; line-height: 50px;
      padding: 0 15px; border-bottom: 1px solid #eee;
      background: #fff;
    }
    .pull-tip {
      height: 60px; line-height: 60px;
      text-align: center; color: #999; font-size: 14px;
    }
  </style>
</head>
<body>
  <div class="outer-scroller">
    <ul class="scroll-list" id="list">
      <li class="pull-tip">下拉刷新</li>
      <li>項目 1</li>
      <li>項目 2</li>
      <li>項目 3</li>
      <li>項目 4</li>
      <li>項目 5</li>
    </ul>
  </div>

  <script>
  (function () {
    const list = document.getElementById('list');
    const scroller = document.querySelector('.outer-scroller');
    const THRESHOLD = 70; // 觸發刷新的位移閾值
    const MAX_PULL = 120; // 最大允許下拉距離
    let startY = 0;
    let currentY = 0;
    let isPulling = false;
    let isRefreshing = false;

    // 使用 transform 而非 top,效能更好(GPU 加速)
    function setTranslateY(y) {
      list.style.transform = `translate3d(0, ${y}px, 0)`;
    }

    scroller.addEventListener('touchstart', (e) => {
      if (isRefreshing) return;
      startY = e.touches[0].pageY;
      // 只有在列表已滾到頂部才允許下拉
      if (list.getBoundingClientRect().top >= 0) {
        isPulling = true;
        list.style.transition = 'none'; // 取消動畫,跟手移動
      }
    }, { passive: true });

    scroller.addEventListener('touchmove', (e) => {
      if (!isPulling || isRefreshing) return;
      currentY = e.touches[0].pageY;
      const delta = currentY - startY;
      if (delta > 0) {
        e.preventDefault(); // 防止頁面整體滾動
        const pullDistance = Math.min(delta * 0.5, MAX_PULL); // 阻尼係數 0.5
        setTranslateY(pullDistance);
        // 更新提示文字
        const tip = list.querySelector('.pull-tip');
        if (tip) tip.textContent = pullDistance > THRESHOLD ? '釋放刷新' : '下拉刷新';
      }
    }, { passive: false });

    scroller.addEventListener('touchend', () => {
      if (!isPulling || isRefreshing) return;
      isPulling = false;
      const pullDistance = parseFloat(list.style.transform.match(/translate3d\(0,\s*([\d.]+)px/)?.[1] || 0);

      if (pullDistance > THRESHOLD) {
        triggerRefresh(pullDistance);
      } else {
        // 彈回
        list.style.transition = 'transform 0.3s ease-out';
        setTranslateY(0);
      }
    });

    async function triggerRefresh(pullDistance) {
      isRefreshing = true;
      list.style.transition = 'transform 0.3s ease-out';
      setTranslateY(60); // 保留一點高度顯示 loading

      const tip = list.querySelector('.pull-tip');
      if (tip) tip.textContent = '載入中...';

      try {
        // 模擬 API 請求
        await new Promise(r => setTimeout(r, 1500));
        // 插入新資料
        for (let i = 3; i >= 1; i--) {
          const li = document.createElement('li');
          li.textContent = `新項目 ${i}`;
          list.insertBefore(li, list.children[1]); // 插在提示條後面
        }
        if (tip) tip.textContent = '刷新成功';
      } catch (err) {
        if (tip) tip.textContent = '刷新失敗';
      } finally {
        setTimeout(() => {
          isRefreshing = false;
          list.style.transition = 'transform 0.3s ease-out';
          setTranslateY(0);
          if (tip) tip.textContent = '下拉刷新';
        }, 800);
      }
    }
  })();
  </script>
</body>
</html>

關鍵優化點

  • 使用 transform 而非 top:translate3d 啟用 GPU 加速,避免佈局重排。
  • 阻尼係數:下拉距離隨手指移動遞減(delta * 0.5),手感更自然。
  • passive 事件監聽器:touchstart 設 passive: true 提升滾動流暢度;touchmove 需 passive: false 以便 preventDefault()。
  • 邊界檢查:只有列表頂部已到達視窗頂部(getBoundingClientRect().top >= 0)才允許下拉,避免與原生滾動衝突。

擴展方向

  • 加入 Loading 動畫(CSS Spinner / Lottie)。
  • 支援上拉加載更多(Infinite Scroll)。
  • 封裝為可複用的 ES Module / Web Component。
  • TypeScript 重寫,提供完整型別定義。
copyright © 萬盛學電腦網 all rights reserved