萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android 下拉刷新 (Pull-to-Refresh) 一分鐘接入指南:自訂 LinearLayout + Touch 事件攔截完整實作

設計理念:組合 View 模式,零侵入、高擴充性

不繼承 `ListView`/`RecyclerView`,而是建立一個 `PullToRefreshLayout` 繼承 `LinearLayout`,內部包含 **Header (下拉頭)** + **目標可滾動 View (ListView/RecyclerView/ScrollView/NestedScrollView)**。透過攔截觸控事件,在目標 View 滾動到頂部且手指繼續下拉時,顯示 Header 並觸發刷新。

下拉刷新原理動圖

Step 1: Header 佈局 (res/layout/pull_to_refresh_header.xml)

<RelativeLayout xmlns:android="https://schemas.android.com/apk/res/android"
    android:id="@+id/pull_to_refresh_head"
    android:layout_width="match_parent"
    android:layout_height="60dp">

    <LinearLayout
        android:layout_width="200dp"
        android:layout_height="60dp"
        android:layout_centerInParent="true"
        android:orientation="horizontal">

        <!-- 左側:箭頭 + 進度條 -->
        <RelativeLayout
            android:layout_width="0dp"
            android:layout_height="match_parent"
            android:layout_weight="3"
            android:gravity="center">

            <ImageView
                android:id="@+id/iv_arrow"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:src="@drawable/ic_arrow_down" />

            <ProgressBar
                android:id="@+id/pb_loading"
                android:layout_width="30dp"
                android:layout_height="30dp"
                android:visibility="gone" />
        </RelativeLayout>

        <!-- 右側:狀態文字 + 更新時間 -->
        <LinearLayout
            android:layout_width="0dp"
            android:layout_height="match_parent"
            android:layout_weight="12"
            android:orientation="vertical"
            android:gravity="center_horizontal">

            <TextView
                android:id="@+id/tv_status"
                android:layout_width="match_parent"
                android:layout_height="0dp"
                android:layout_weight="1"
                android:gravity="center_horizontal|bottom"
                android:text="@string/pull_to_refresh" />

            <TextView
                android:id="@+id/tv_update_time"
                android:layout_width="match_parent"
                android:layout_height="0dp"
                android:layout_weight="1"
                android:gravity="center_horizontal|top"
                android:text="@string/not_updated_yet" />
        </LinearLayout>
    </LinearLayout>
</RelativeLayout>

Step 2: 字串資源 (res/values/strings.xml)

<resources>
    <string name="pull_to_refresh">下拉可以刷新</string>
    <string name="release_to_refresh">釋放立即刷新</string>
    <string name="refreshing">正在刷新…</string>
    <string name="not_updated_yet">暫未更新過</string>
    <string name="updated_at">上次更新於 %1$s 前</string>
</resources>

Step 3: PullToRefreshLayout 核心邏輯

public class PullToRefreshLayout extends LinearLayout {

    // 狀態機
    enum State { PULL_TO_REFRESH, RELEASE_TO_REFRESH, REFRESHING, REFRESH_COMPLETE }

    private View headerView;
    private View targetView; // ListView/RecyclerView/ScrollView
    private ImageView ivArrow;
    private ProgressBar pbLoading;
    private TextView tvStatus, tvUpdateTime;

    private State currentState = State.PULL_TO_REFRESH;
    private int headerHeight;
    private float lastY;
    private boolean isBeingDragged = false;

    private OnRefreshListener listener;

    public interface OnRefreshListener {
        void onRefresh();
    }

    public PullToRefreshLayout(Context context) { this(context, null); }
    public PullToRefreshLayout(Context context, AttributeSet attrs) { this(context, attrs, 0); }
    public PullToRefreshLayout(Context context, AttributeSet attrs, int defStyle) {
        super(context, attrs, defStyle);
        init(context);
    }

    private void init(Context context) {
        setOrientation(VERTICAL);
        setGravity(Gravity.CENTER_HORIZONTAL);

        // 載入 Header
        headerView = LayoutInflater.from(context).inflate(R.layout.pull_to_refresh_header, this, false);
        ivArrow = headerView.findViewById(R.id.iv_arrow);
        pbLoading = headerView.findViewById(R.id.pb_loading);
        tvStatus = headerView.findViewById(R.id.tv_status);
        tvUpdateTime = headerView.findViewById(R.id.tv_update_time);

        // 預設隱藏 Header (向上偏移自身高度)
        addView(headerView);
        headerView.setPadding(0, -getHeaderHeight(), 0, 0); // 稍後 onSizeChanged 修正
    }

    @Override
    protected void onSizeChanged(int w, int h, int oldw, int oldh) {
        super.onSizeChanged(w, h, oldw, oldh);
        headerHeight = headerView.getMeasuredHeight();
        if (headerHeight > 0) {
            headerView.setPadding(0, -headerHeight, 0, 0); // 完全隱藏
        }
    }

    @Override
    protected void onFinishInflate() {
        super.onFinishInflate();
        // 尋找目標可滾動 View (第 2 個子 View)
        if (getChildCount() >= 2) {
            targetView = getChildAt(1);
        }
    }

    // --- Touch 事件攔截核心 ---
    @Override
    public boolean onInterceptTouchEvent(MotionEvent ev) {
        if (targetView == null || currentState == State.REFRESHING) return false;

        switch (ev.getActionMasked()) {
            case MotionEvent.ACTION_DOWN:
                lastY = ev.getRawY();
                isBeingDragged = false;
                break;
            case MotionEvent.ACTION_MOVE:
                float deltaY = ev.getRawY() - lastY;
                // 條件:目標在頂部 (無法再向上滾動) 且 手指向下拖動
                if (deltaY > 0 && isTargetAtTop()) {
                    isBeingDragged = true;
                    return true; // 攔截,由 onTouchEvent 處理
                }
                break;
            case MotionEvent.ACTION_UP:
            case MotionEvent.ACTION_CANCEL:
                isBeingDragged = false;
                break;
        }
        return false;
    }

    @Override
    public boolean onTouchEvent(MotionEvent ev) {
        if (!isBeingDragged || currentState == State.REFRESHING) return super.onTouchEvent(ev);

        switch (ev.getActionMasked()) {
            case MotionEvent.ACTION_MOVE:
                float deltaY = ev.getRawY() - lastY;
                if (deltaY > 0) {
                    // 更新 Header 顯示高度 (阻尼效果)
                    int newTopPadding = (int) (Math.min(deltaY, headerHeight * 2) * 0.5f) - headerHeight;
                    headerView.setPadding(0, newTopPadding, 0, 0);

                    // 狀態切換與箭頭動畫
                    if (newTopPadding >= 0 && currentState != State.RELEASE_TO_REFRESH) {
                        setState(State.RELEASE_TO_REFRESH);
                    } else if (newTopPadding < 0 && currentState != State.PULL_TO_REFRESH) {
                        setState(State.PULL_TO_REFRESH);
                    }
                }
                return true; // 消費事件

            case MotionEvent.ACTION_UP:
            case MotionEvent.ACTION_CANCEL:
                isBeingDragged = false;
                if (currentState == State.RELEASE_TO_REFRESH) {
                    // 觸發刷新
                    setState(State.REFRESHING);
                    smoothScrollHeaderTo(0); // 滑動到 Header 完全顯示位置
                    if (listener != null) listener.onRefresh();
                } else {
                    // 回彈隱藏
                    smoothScrollHeaderTo(-headerHeight);
                }
                return true;
        }
        return super.onTouchEvent(ev);
    }

    private boolean isTargetAtTop() {
        if (targetView instanceof AbsListView) {
            AbsListView list = (AbsListView) targetView;
            return list.getFirstVisiblePosition() == 0 &&
                   (list.getChildAt(0) == null || list.getChildAt(0).getTop() >= 0);
        } else if (targetView instanceof RecyclerView) {
            RecyclerView rv = (RecyclerView) targetView;
            return !rv.canScrollVertically(-1); // -1 向上
        } else if (targetView instanceof ScrollView) {
            ScrollView sv = (ScrollView) targetView;
            return sv.getScrollY() == 0;
        } else if (targetView instanceof NestedScrollView) {
            NestedScrollView nsv = (NestedScrollView) targetView;
            return !nsv.canScrollVertically(-1);
        }
        return false;
    }

    private void setState(State state) {
        currentState = state;
        switch (state) {
            case PULL_TO_REFRESH:
                tvStatus.setText(R.string.pull_to_refresh);
                ivArrow.setVisibility(VISIBLE);
                pbLoading.setVisibility(GONE);
                rotateArrow(0f);
                break;
            case RELEASE_TO_REFRESH:
                tvStatus.setText(R.string.release_to_refresh);
                ivArrow.setVisibility(VISIBLE);
                pbLoading.setVisibility(GONE);
                rotateArrow(180f);
                break;
            case REFRESHING:
                tvStatus.setText(R.string.refreshing);
                ivArrow.setVisibility(GONE);
                pbLoading.setVisibility(VISIBLE);
                break;
            case REFRESH_COMPLETE:
                tvStatus.setText(R.string.pull_to_refresh);
                ivArrow.setVisibility(VISIBLE);
                pbLoading.setVisibility(GONE);
                rotateArrow(0f);
                updateLastUpdateTime();
                break;
        }
    }

    private void rotateArrow(float degrees) {
        ivArrow.animate().rotation(degrees).setDuration(150).start();
    }

    private void smoothScrollHeaderTo(int targetPaddingTop) {
        ValueAnimator animator = ValueAnimator.ofInt(headerView.getPaddingTop(), targetPaddingTop);
        animator.setDuration(300);
        animator.addUpdateListener(animation -> {
            int val = (int) animation.getAnimatedValue();
            headerView.setPadding(0, val, 0, 0);
        });
        animator.start();
    }

    // --- 公開 API ---
    public void setOnRefreshListener(OnRefreshListener listener) { this.listener = listener; }

    public void setRefreshComplete() {
        setState(State.REFRESH_COMPLETE);
        // 延遲隱藏 Header
        postDelayed(() -> smoothScrollHeaderTo(-headerHeight), 500);
    }

    public void setLastUpdateTime(long timestamp) {
        // 格式化並顯示
        String text = (timestamp == 0) ?
            getResources().getString(R.string.not_updated_yet) :
            getResources().getString(R.string.updated_at, formatRelativeTime(timestamp));
        tvUpdateTime.setText(text);
    }

    private String formatRelativeTime(long timestamp) {
        // 簡易相對時間格式化
        long diff = System.currentTimeMillis() - timestamp;
        if (diff < 60000) return "剛剛";
        if (diff < 3600000) return (diff / 60000) + " 分鐘前";
        if (diff < 86400000) return (diff / 3600000) + " 小時前";
        return new SimpleDateFormat("MM-dd HH:mm", Locale.getDefault()).format(new Date(timestamp));
    }
}

Step 4: 在 XML 中使用 (零程式碼侵入)

<com.example.widget.PullToRefreshLayout
    xmlns:android="https://schemas.android.com/apk/res/android"
    android:id="@+id/ptr_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical">

    <!-- Header 由 PullToRefreshLayout 內部自動加載,此處無需寫入 -->

    <!-- 目標可滾動 View (ListView / RecyclerView / ScrollView / NestedScrollView) -->
    <androidx.recyclerview.widget.RecyclerView
        android:id="@+id/recycler_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />
</com.example.widget.PullToRefreshLayout>

Step 5: Activity/Fragment 中啟用

PullToRefreshLayout ptrLayout = findViewById(R.id.ptr_layout);
ptrLayout.setOnRefreshListener(() -> {
    // 執行網路請求、資料庫查詢...
    repository.fetchLatestData(new Callback>() {
        @Override
        public void onSuccess(List data) {
            adapter.submitList(data);
            ptrLayout.setRefreshComplete();
            ptrLayout.setLastUpdateTime(System.currentTimeMillis());
        }
        @Override
        public void onError(Throwable e) {
            ptrLayout.setRefreshComplete(); // 失敗也要收回
            showErrorSnackbar(e);
        }
    });
});

進階擴展點

  • 支援 NestedScrolling:實作 `NestedScrollingParent3`/`NestedScrollingChild3` 介面,完美配合 `CoordinatorLayout`、`ViewPager2`、巢狀 `RecyclerView`。
  • 自訂 Header 動畫:使用 `LottieAnimationView` 替代箭頭/ProgressBar,實現極致視覺體驗。
  • 二樓刷新 (Load More):同樣邏輯反向實作於底部,或整合 `SmartRefreshLayout` 等成熟庫。
  • RTL 支援:使用 `Gravity.START/END` 替代 `LEFT/RIGHT`,箭頭圖示自動鏡像。

現代替代方案

  • SwipeRefreshLayout (AndroidX):官方 Material Design 實作,支援 `RecyclerView`/`ListView`/`ScrollView`,API 簡單但自訂 Header 較麻煩。
  • SmartRefreshLayout (GitHub 30k+ stars):功能最全、擴充性最強、支援所有 View、內建超酷 Header/Footer、Kotlin DSL、瀑布流/虛擬清單支援。**生產環境首選**。
  • Jetpack Compose:`pullRefresh` / `rememberPullRefreshState` 宣告式 API,無需自訂 View。

總結

本文實作的 `PullToRefreshLayout` 採用 **組合模式 + 觸控攔截 + 狀態機**,核心邏輯約 200 行,零依賴、完全可控、易於理解與擴展。掌握其原理 (攔截條件、阻尼計算、狀態流轉、平滑動畫) 後,可快速定製專屬下拉刷新體驗。生產專案建議直接接入 **SmartRefreshLayout** 或 **Compose PullRefresh**,專注業務創新而非輪子重造。

copyright © 萬盛學電腦網 all rights reserved