TypeScript中如何定义支持无限滚动列表的分页数据类型

无限滚动列表本质上是一个不断向后追加数据的过程，但它的分页协议和传统页码翻页有显著区别。传统分页通常会返回总页数、当前页码和每页数量，而无限滚动更关心从哪个位置继续拉取，以及本次返回的数据是否已经到达末尾。如果直接用any或者写死一个宽泛的对象类型，TypeScript给出的类型保障就会大打折扣。我们需要根据游标、偏移量或者时间戳等不同的分页策略，定义出足够精确同时又具备复用能力的类型结构。

先厘清偏移分页与游标分页的类型差异

偏移分页是最容易理解的一种方式，接口通常会接收page和pageSize，返回total、items以及可能的hasMore字段。这种模型在数据量稳定、顺序变化不频繁的场景下足够使用，但无限滚动有一个明显问题：如果列表在滚动过程中有新数据插入，基于页码的偏移就会产生重复或遗漏。类型层面我们依然可以把它定义得很清晰，例如下面这个基础接口。

比较推荐的做法是把请求参数和响应包裹拆成两个泛型接口。请求参数包含页码和每页条数，响应包裹则包含数据数组、总数以及是否还有更多数据。这样不同的业务列表只需要传入具体的元素类型即可。需要注意的是，很多后端在hasMore为false时仍然会返回空数组，所以前端逻辑不能只依赖数组长度判断，类型中把hasMore设为必填可以迫使调用方正确处理。

// 偏移分页的请求参数
interface OffsetPageRequest {
  page: number;
  pageSize: number;
}

// 偏移分页的响应包裹，T为列表元素类型
interface OffsetPageResult<T> {
  items: T[];
  total: number;
  hasMore: boolean;
}

游标分页则更适合无限滚动。它不会依赖页码，而是通过上一次返回的游标来获取下一段数据。游标可以是自增ID、时间戳或者服务端生成的加密字符串。类型设计时，请求参数需要携带游标和条数，响应中则应包含下一页的游标以及是否还有更多。这样前端只需要保存最后一个游标，就能持续追加数据。游标分页还有一个额外好处：当列表顶部出现新内容时，已加载的旧数据不会因为页码漂移而错位。

// 游标分页的请求参数
interface CursorPageRequest {
  cursor?: string;
  limit: number;
}

// 游标分页的响应包裹
interface CursorPageResult<T> {
  items: T[];
  nextCursor: string | null;
  hasMore: boolean;
}

可以看到，两种分页模型的字段并不相同，因此在编写通用的无限滚动组件或Hook时，不能只接受一种固定类型。比较灵活的方案是使用联合类型，让调用方根据实际协议选择。如果项目里同时存在偏移分页和游标分页接口，可以定义两个独立的请求/响应对，然后在组件逻辑中通过判别字段进行区分。这种设计能有效避免在代码里写大量as any或as unknown as。

用泛型组合出可复用的分页状态管理类型

在React、Vue等前端框架中管理无限滚动状态，通常需要维护累积列表、游标或页码、加载状态和错误信息。把这些状态封装成一个泛型接口，可以让不同业务组件共享同一套逻辑。下面是一个基于游标分页的状态接口，它把原始数据、下一次请求需要的游标、是否正在加载、是否已经到底以及可选错误信息都放在一起。

累积列表的类型应该是T[]，每次请求成功后把新的一页数据拼接进去。游标类型建议单独抽出来，可以是string | null，如果后端用数字游标，也可以替换成number | null。加载状态和错误状态直接影响界面渲染，所以不应省略。此外，有些场景需要支持下拉刷新后重置整个列表，所以状态接口里最好能体现重置后的初始形态。

// 基于游标分页的无限滚动状态
interface InfiniteScrollState<T> {
  items: T[];
  nextCursor: string | null;
  isLoading: boolean;
  hasMore: boolean;
  error: string | null;
}

// 初始状态工厂函数
function createInitialState<T>(): InfiniteScrollState<T> {
  return {
    items: [],
    nextCursor: null,
    isLoading: false,
    hasMore: true,
    error: null,
  };
}

如果使用偏移分页，状态里的nextCursor可以换成currentPage。不过更好的办法是借助TypeScript的条件类型或者重载，让同一个Hook同时支持两种分页模式。但要注意，条件类型容易把类型推到过于复杂的境地，如果团队里TypeScript经验不多，可以分别写两个Hook，内部共享一些工具函数。类型层面的清晰远比强行统一更重要。

还有一个容易忽略的点：列表元素的类型T可能本身包含联合类型或者带可选字段的对象。例如新闻流里既有图文卡片也有视频卡片，此时T可以定义为ArticleCard | VideoCard，配合判别字段type做类型守卫。这样在渲染不同卡片时就能获得准确的属性提示，而不是所有卡片都共用同一个对象形状。

利用判别联合类型处理分页响应的多种形态

后端接口返回的数据经常不是单一成功形状。有的接口会把错误信息放在code和message字段，有的会直接返回HTTP错误状态码，还有的在数据为空时返回items: null而不是空数组。如果前端把所有情况都塞进一个宽泛类型里，渲染时就需要写很多防御性的判断。判别联合类型在这里非常有用。

我们可以把分页请求的结果定义为一个联合类型：成功、空数据、错误三种情况分别对应不同的子类型，并用status字段作为判别依据。成功时items是数组；空数据时items为空数组但hasMore为false；错误时则携带错误码和错误信息。在请求函数内部，根据后端返回的不同字段构造对应的判别对象，调用方就可以通过switch或if精准地缩小类型范围。

// 使用判别联合类型表示分页请求的三种结果
type PaginationResult<T> =
  | {
      status: 'success';
      items: T[];
      nextCursor: string | null;
      hasMore: boolean;
    }
  | {
      status: 'empty';
      items: [];
      hasMore: false;
    }
  | {
      status: 'error';
      errorCode: number;
      errorMessage: string;
    };

这种写法配合TypeScript的穷尽检查可以强制处理所有分支。当后续新增一种状态时（比如需要登录后继续），编译器会提示所有用到这个联合类型的位置，避免漏改。在实际项目里，后端可能并不会返回统一的status字段，这时可以在前端请求封装层做一次转换，把不同的响应结构统一映射成上面的联合类型。转换逻辑本身不需要复杂类型体操，只要保证字段完整即可。

如果不想在业务代码里手动判断status，也可以进一步提供类型守卫函数。例如isSuccessResult(result)，返回result is Extract<PaginationResult<T>, { status: 'success' }>。这样在if (isSuccessResult(result))块内，TypeScript会自动把result收窄为成功分支，后续访问result.items就不会报错。类型守卫适合在自定义Hook或数据请求层中复用。

在React自定义Hook中集成类型安全的分页逻辑

接下来看一个完整的React Hook示例，它封装了游标分页请求、状态累积和加载更多操作。类型定义都来自前文讨论过的接口，业务组件只需要传入元素类型和请求函数。Hook内部维护InfiniteScrollState<T>，并在加载更多时尝试获取下一段数据。这个示例省略了具体的HTTP请求细节，重点展示类型如何贯穿整个数据流。

请求函数签名可以定义为(cursor: string | null) => Promise<PaginationResult<T>>。Hook内部拿到结果后，根据status字段更新状态。成功分支会追加数据并更新游标；空数据分支把hasMore设为false；错误分支则记录错误信息，同时保持已有数据不变。这种状态更新逻辑与联合类型的判别天然契合，类型错误在编译期就会被暴露出来。

import { useCallback, useState } from 'react';

type FetchPage<T> = (cursor: string | null) => Promise<PaginationResult<T>>;

function useInfiniteScroll<T>(fetchPage: FetchPage<T>) {
  const [state, setState] = useState<InfiniteScrollState<T>>(createInitialState<T>());

  const loadMore = useCallback(async () => {
    if (state.isLoading || !state.hasMore) {
      return;
    }
    setState(prev => ({ ...prev, isLoading: true, error: null }));
    const result = await fetchPage(state.nextCursor);
    setState(prev => {
      switch (result.status) {
        case 'success':
          return {
            ...prev,
            items: [...prev.items, ...result.items],
            nextCursor: result.nextCursor,
            hasMore: result.hasMore,
            isLoading: false,
            error: null,
          };
        case 'empty':
          return {
            ...prev,
            hasMore: false,
            isLoading: false,
          };
        case 'error':
          return {
            ...prev,
            isLoading: false,
            error: result.errorMessage,
          };
        default:
          return { ...prev, isLoading: false };
      }
    });
  }, [fetchPage, state.nextCursor, state.isLoading, state.hasMore]);

  return {
    items: state.items,
    nextCursor: state.nextCursor,
    isLoading: state.isLoading,
    hasMore: state.hasMore,
    error: state.error,
    loadMore,
  };
}

上面这个Hook中的default分支看起来多余，但其实是为了未来扩展联合类型时，让TypeScript在缺失分支的情况下仍能给出穷尽检查提示。如果去掉default，当PaginationResult新增一个成员时，switch就不会编译报错，开发者可能漏改。保留一个返回原状态的default分支可以在编译期获得警告，同时避免运行时出现不可预期的undefined状态。

如果分页协议采用偏移分页而非游标，这个Hook的修改也很直接：把nextCursor替换成page，请求函数接收page参数，成功分支更新页码。更好的做法是让请求函数类型本身携带分页参数信息，然后Hook根据这个信息决定如何传递。不过这样会让泛型约束变得比较绕，除非有很强的复用需求，否则分开写两个Hook反而是更清晰的选择。

类型设计最终要服务于开发效率和运行时稳定性。通过精确的分页数据类型，我们可以在加载更多、下拉刷新、空状态展示等场景中减少运行时错误，同时让新加入的开发者快速理解数据流。定义一次泛型接口和联合类型所花费的时间，会在后续每一个列表页面中成倍地节省回来。

TypeScript无限滚动分页数据类型修改时间：2026-09-22 12:23:31