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

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