一文詳解如何封裝一個(gè)生產(chǎn)級(jí)的React Native分頁列表Hook

更新時(shí)間：2026年05月14日 15:18:17 作者：皮蛋小精靈

分享了在React Native中使用FlatList實(shí)現(xiàn)分頁列表時(shí)遇到的幾個(gè)經(jīng)典問題及其解決方案,包括并發(fā)鎖、閉包陷阱、雙重觸發(fā)等內(nèi)容,感興趣的小伙伴可以了解下

先看最終接口

const {
  data,
  total,
  loading,      // 初始加載
  refreshing,   // 下拉刷新中
  loadingMore,  // 上拉加載更多中
  hasMore,
  refresh,
  loadMore,
} = usePaginatedList({
  fetcher: ({ pageNumber, pageSize, type }) =>
    api.getList({ pageNumber, pageSize }),
  pageSize: 20,
  autoLoad: true,
});

fetcher 是唯一必填項(xiàng)，其他都有默認(rèn)值。Hook 內(nèi)部管理所有狀態(tài)，調(diào)用方只需要關(guān)心"拿到的數(shù)據(jù)"和"觸發(fā)動(dòng)作"。

三種加載狀態(tài)，分開管理

很多實(shí)現(xiàn)只有一個(gè) loading，用來表示所有加載場(chǎng)景。這會(huì)帶來一個(gè)問題：下拉刷新時(shí)，列表底部的"加載更多"指示器也會(huì)一起亮起；反過來上拉加載時(shí)，頂部的下拉刷新轉(zhuǎn)圈也可能錯(cuò)誤地顯示。

分開管理語義更清晰，也和 FlatList 的 props 直接對(duì)應(yīng)：

const [loading, setLoading] = useState(false);       // 首次進(jìn)入頁面
const [refreshing, setRefreshing] = useState(false);  // FlatList.refreshing
const [loadingMore, setLoadingMore] = useState(false);// 底部 Loading 組件

在 fetchData 里根據(jù) type 參數(shù)決定置哪個(gè) flag：

if (type === 'refresh') {
  setRefreshing(true);
} else if (type === 'loadMore') {
  setLoadingMore(true);
} else {
  setLoading(true);
}

三個(gè)狀態(tài)在 finally 里統(tǒng)一重置，不管請(qǐng)求成功還是失敗都能正確恢復(fù)：

finally {
  setLoading(false);
  setRefreshing(false);
  setLoadingMore(false);
  isFetchingRef.current = false;
  lastFetchTimeRef.current = Date.now();
}

并發(fā)鎖：用 Ref 而不是 State

這是最容易寫錯(cuò)的地方。很多人會(huì)用 useState 來做"正在請(qǐng)求"的 flag：

// ? 錯(cuò)誤寫法
const [isFetching, setIsFetching] = useState(false);

const fetchData = async () => {
  if (isFetching) return; // 這里讀到的是閉包里的舊值！
  setIsFetching(true);
  // ...
};

問題在于 useState 的更新是異步的，當(dāng)你在 fetchData 里讀 isFetching 時(shí)，讀到的是本次渲染時(shí)的快照值。如果兩個(gè)請(qǐng)求幾乎同時(shí)觸發(fā)，兩個(gè)閉包里的 isFetching 都是 false，鎖就失效了。

正確做法是用 useRef：

// ? 正確寫法
const isFetchingRef = useRef(false);

const fetchData = async () => {
  if (isFetchingRef.current) return; // Ref 是可變對(duì)象，永遠(yuǎn)讀最新值
  isFetchingRef.current = true;
  // ...
  finally {
    isFetchingRef.current = false;
  }
};

useRef 返回的是同一個(gè)對(duì)象引用，.current 的修改立刻生效，不受閉包影響。這才是真正的同步鎖。

閉包陷阱：頁碼也要用 Ref 追蹤

loadMore 的實(shí)現(xiàn)里有一個(gè)類似的坑——頁碼。

直覺上你可能會(huì)這樣寫：

// ? 容易出 bug 的寫法
const loadMore = useCallback(() => {
  if (hasMore && !isFetchingRef.current) {
    fetchData(pageNum + 1, 'loadMore');
  }
}, [hasMore, fetchData, pageNum]);

這里的 pageNum 是 useState 的值，loadMore 會(huì)在每次 pageNum 變化時(shí)重新生成。但問題是：loadMore 同時(shí)還被 FlatList 的 onEndReached 引用著，在某些 layout 變化場(chǎng)景下，新的 loadMore 還沒有傳遞給 FlatList，舊的那個(gè)就被調(diào)用了，于是 pageNum 還是上一次的值。

同樣，用 Ref 來解決：

const pageNumRef = useRef(1);

// 每次請(qǐng)求成功后同步更新
pageNumRef.current = page;
setPageNum(page); // State 用于驅(qū)動(dòng) UI 重渲染，Ref 用于在閉包中讀最新值

// ? loadMore 里用 Ref 讀頁碼
const loadMore = useCallback(() => {
  if (hasMore && !isFetchingRef.current) {
    fetchData(pageNumRef.current + 1, 'loadMore');
  }
}, [hasMore, fetchData]);

pageNumRef 不出現(xiàn)在依賴數(shù)組里——因?yàn)?Ref 的變化不觸發(fā)重渲染，也不需要觸發(fā) loadMore 的重新生成。這樣 loadMore 的引用保持穩(wěn)定，同時(shí)始終能讀到最新頁碼。

hasMore的判斷邏輯

hasMore 決定了是否還要繼續(xù)加載，判斷方式值得想一想。

最簡(jiǎn)單的判斷是 data.length < total，但這要求每次都能拿到準(zhǔn)確的 total，而部分接口設(shè)計(jì)不返回 total，或者 total 可能因?yàn)閿?shù)據(jù)變化而不準(zhǔn)確。

這里采用了一個(gè)更魯棒的策略：用返回條數(shù)是否達(dá)到 pageSize 來判斷。

setHasMore(items.length >= pageSize);

邏輯是：如果這次請(qǐng)求返回了滿頁（比如 pageSize=20，返回了 20 條），說明后面大概率還有數(shù)據(jù)；如果返回了不足一頁（比如只有 7 條），說明已經(jīng)到底了。

這個(gè)判斷在絕大多數(shù)場(chǎng)景下都準(zhǔn)確，邊界情況（恰好是 pageSize 的整數(shù)倍）會(huì)多發(fā)一次請(qǐng)求，但返回空數(shù)組后 hasMore 會(huì)變?yōu)?false，不影響正確性。

為什么要記錄lastFetchTimeRef

lastFetchTimeRef.current = Date.now();

這個(gè) Ref 記錄了上次請(qǐng)求完成的時(shí)間戳。它本身沒有在 Hook 內(nèi)部使用，而是暴露給調(diào)用方用于防抖。

FlatList 有一個(gè)特性：當(dāng)列表高度發(fā)生變化（比如第一頁數(shù)據(jù)渲染完成），它會(huì)重新計(jì)算 onEndReachedThreshold，有時(shí)會(huì)再次觸發(fā) onEndReached。雖然 isFetchingRef 能擋住并發(fā)請(qǐng)求，但在請(qǐng)求剛結(jié)束、數(shù)據(jù)剛渲染完的那一瞬間，鎖已經(jīng)釋放，layout 變化又來了一次觸發(fā)，就會(huì)發(fā)出第二個(gè)請(qǐng)求。

調(diào)用方可以這樣使用：

const { loadMore, lastFetchTimeRef } = usePaginatedList({ ... });

const handleEndReached = useCallback(() => {
  // 上次請(qǐng)求結(jié)束后 500ms 內(nèi)不響應(yīng)
  if (Date.now() - lastFetchTimeRef.current < 500) return;
  loadMore();
}, [loadMore, lastFetchTimeRef]);

這是一個(gè)協(xié)作式冷卻的設(shè)計(jì)：Hook 提供時(shí)間戳，調(diào)用方?jīng)Q定冷卻策略，關(guān)注點(diǎn)分離。

FetchType的設(shè)計(jì)意圖

export type FetchType = 'init' | 'refresh' | 'loadMore';

type 被透?jìng)鹘o fetcher，這讓調(diào)用方可以根據(jù)加載類型做差異化處理：

fetcher: ({ pageNumber, pageSize, type }) => {
  // 比如刷新時(shí)清除本地緩存，初始化時(shí)走緩存優(yōu)先
  if (type === 'refresh') {
    cache.clear();
  }
  return api.getList({ pageNumber, pageSize });
}

Hook 不需要知道這些業(yè)務(wù)邏輯，只是誠(chéng)實(shí)地把信息傳出去。

數(shù)據(jù)合并策略

setData(prev => (type === 'loadMore' ? [...prev, ...items] : items));

只有 loadMore 時(shí)追加數(shù)據(jù)，init 和 refresh 都是替換。用函數(shù)式更新 prev => ... 而不是直接引用 data，同樣是為了避免閉包里讀到過期的 data。

完整代碼

import {useCallback, useEffect, useState, useRef} from 'react';

export type FetchType = 'init' | 'refresh' | 'loadMore';

interface PaginatedResult<T> {
  data: T[];
  total: number;
}

interface UsePaginatedListOptions<T> {
  fetcher: (params: {
    pageNumber: number;
    pageSize: number;
    type: FetchType;
  }) => Promise<{
    code: number | string;
    data?: PaginatedResult<T>;
  }>;
  pageSize?: number;
  autoLoad?: boolean;
}

export function usePaginatedList<T>({
  fetcher,
  pageSize = 10,
  autoLoad = true,
}: UsePaginatedListOptions<T>) {
  const [data, setData] = useState<T[]>([]);
  const [pageNum, setPageNum] = useState(1);
  const pageNumRef = useRef(1);
  const [hasMore, setHasMore] = useState(true);
  const [loading, setLoading] = useState(false);
  const [refreshing, setRefreshing] = useState(false);
  const [loadingMore, setLoadingMore] = useState(false);
  const [total, setTotal] = useState(0);

  const isFetchingRef = useRef(false);
  const lastFetchTimeRef = useRef(0);

  const fetchData = useCallback(
    async (page: number, type: FetchType) => {
      if (isFetchingRef.current) return;
      isFetchingRef.current = true;

      if (type === 'refresh') {
        setRefreshing(true);
      } else if (type === 'loadMore') {
        setLoadingMore(true);
      } else {
        setLoading(true);
      }

      try {
        const res = await fetcher({pageNumber: page, pageSize, type});
        if (res.code === 200 && res.data) {
          const items = res.data.data ?? [];
          setData(prev => (type === 'loadMore' ? [...prev, ...items] : items));
          setTotal(res.data.total ?? 0);
          setHasMore(items.length >= pageSize);
          pageNumRef.current = page;
          setPageNum(page);
        }
      } catch {
      } finally {
        setLoading(false);
        setRefreshing(false);
        setLoadingMore(false);
        isFetchingRef.current = false;
        lastFetchTimeRef.current = Date.now();
      }
    },
    [fetcher, pageSize],
  );

  const refresh = useCallback(async () => {
    await fetchData(1, 'refresh');
  }, [fetchData]);

  const loadMore = useCallback(() => {
    if (hasMore && !isFetchingRef.current) {
      fetchData(pageNumRef.current + 1, 'loadMore');
    }
  }, [hasMore, fetchData]);

  useEffect(() => {
    if (autoLoad) {
      fetchData(1, 'init');
    }
  }, [autoLoad, fetchData]);

  return {
    data,
    total,
    loading,
    refreshing,
    loadingMore,
    hasMore,
    refresh,
    loadMore,
    lastFetchTimeRef,
  };
}

小結(jié)

這個(gè) Hook 沒有引入任何第三方庫，核心是對(duì) React 幾個(gè)基礎(chǔ)機(jī)制的正確使用：

問題	解決方案
并發(fā)請(qǐng)求重復(fù)	`useRef` 同步鎖（而不是 `useState`）
閉包讀到過期頁碼	`pageNumRef` 追蹤最新頁碼
`FlatList` layout 變化觸發(fā)雙請(qǐng)求	`lastFetchTimeRef` 暴露時(shí)間戳給調(diào)用方防抖
數(shù)據(jù)合并讀到過期 `data`	函數(shù)式 `setData(prev => ...)`
三種加載狀態(tài)混用	`loading` / `refreshing` / `loadingMore` 分開管理