urql 无限滚动分页实战:纯 UI 层的游标分页实现

原创2026-09-24 17:42:251,462 阅读
文章标签:前端

urql 无限滚动分页实战:纯 UI 层的游标分页实现

在 GraphQL 客户端实践中,无限滚动(Infinite Scroll)是最常见也最容易被过度设计的分页需求。urql 官方仓库中的 examples/with-infinite-pagination 示例演示了一种"纯 UI 代码"实现无限滚动列表的方案:不需要任何额外的状态管理、不需要对列表做数据加工、不需要 useEffect,仅靠组件的递归渲染和 urql 的请求策略(Request Policy)即可完成整页、整页的游标分页加载。本文将以该示例为主体,结合 urql 核心包 中缓存交换器(cacheExchange)的源码实现,深入讲解这套方案的原理与完整代码,并指出它与其他分页方案的差异和适用边界。

读完本文,你将掌握:如何用 useQuery 的 pause、requestPolicy: 'cache-only' 与 executeQuery 动态切换请求策略,实现"先渲染缓存、点击再发网络请求"的逐页加载;如何用组件的递归结构替代"维护一整个分页变量数组"的做法;以及为什么这种方案能同时兼容文档缓存和任何自定义缓存。

示例概览:这是一个什么样的分页方案

先看 examples/with-infinite-pagination/README.md 对示例的定位,它对比了仓库里的另外两个分页示例,给出了非常明确的能力边界:

  • 不需要缓存感知(cache-agnostic):与 with-graphcache-pagination 不同,urql 的缓存不需要了解你的无限列表结构——无论你用的是默认的文档缓存(document cache)还是 graphcache 规范化缓存,本方案都能直接工作;
  • 支持游标与动态变量:与 with-pagination 不同,列表可以使用游标(cursor),每一页都可以更新,下一页的变量是动态计算出来的;
  • 零额外状态:不新增 state、不做列表合并处理、不需要 effects。

换句话说,除非你确实需要一个扁平的数组(例如 React Native 的 FlatList 或某些虚拟列表组件),否则这就是实现无限滚动分页列表的最简方式。而且该示例不仅适用于 React,同样的结构可以平移到 Svelte 或 Vue。

为了直观看清这套方案的定位,下面先对仓库中三种分页示例做一个对比:

维度 with-pagination with-graphcache-pagination with-infinite-pagination(本文)
核心文件 examples/with-pagination/src/PaginatedNpmSearch.jsx examples/with-graphcache-pagination/src/PaginatedNpmSearch.jsx examples/with-infinite-pagination/src/SearchResults.jsx
是否依赖特定缓存 不依赖 依赖 graphcache 规范化缓存 不依赖(文档缓存即可)
分页方式 通过 state 维护"每页变量的数组",逐页渲染 缓存感知的规范化分页 递归渲染组件,每页自管变量
是否需要扁平列表 需要(nodes 数组) 需要 不需要(edges 直接渲染)
额外状态/effects useState 无(由缓存驱动) 无
游标支持 不支持动态游标 支持 支持(endCursor 递归传递)

可以看出,本示例在"最简 UI 代码"与"游标分页能力"之间取得了平衡,下面进入代码细节。

运行示例

示例是一个基于 Vite 的 React 应用。按照 README 的说明,安装依赖并启动 start 脚本即可:

yarn install
yarn run start
# 或使用 npm
npm install
npm run start

入口文件 examples/with-infinite-pagination/src/index.jsx 通过 createRoot 渲染 <App />;examples/with-infinite-pagination/index.html 中挂载了 #root 容器并引入 src/index.jsx。示例依赖 @urql/core、urql(React 绑定)、graphql、react 与 vite,具体版本可查看 examples/with-infinite-pagination/package.json。

客户端搭建与 UI 骨架

examples/with-infinite-pagination/src/App.jsx 完成两件事:创建 urql Client,以及渲染带搜索框的 UI。

import React, { useState } from 'react';
import { Client, Provider, cacheExchange, fetchExchange } from 'urql';

import SearchRoot from './SearchResults';

const client = new Client({
  // 这里的 GraphQL API 使用的是 NPM registry 数据
  // 我们将用它来展示包搜索的结果
  url: 'https://trygql.formidable.dev/graphql/relay-npm',
  exchanges: [cacheExchange, fetchExchange],
});

function PaginatedNpmSearch() {
  const [search, setSearch] = useState('urql');

  const setSearchValue = event => {
    event.preventDefault();
    setSearch(event.currentTarget.value);
  };

  return (
    <>
      <header>
        <h4>Type to search for npm packages</h4>
        {/* 试试改一下搜索词,然后再改回来…… */}
        {/* 如果这样做,所有已缓存的页面都会立即显示! */}
        <input
          type="search"
          value={search}
          onChange={setSearchValue}
          placeholder="npm package name"
        />
      </header>
      <main>
        <SearchRoot searchTerm={search} />
      </main>
    </>
  );
}

function App() {
  return (
    <Provider value={client}>
      <PaginatedNpmSearch />
    </Provider>
  );
}

几个值得注意的点:

  • 交换器只用了 cacheExchange + fetchExchange:这正对应 README 中"与任何缓存(甚至文档缓存)兼容"的承诺——cacheExchange 就是 urql 的默认文档缓存,见 packages/core/src/exchanges/cache.ts 的实现注释;
  • searchTerm 作为 prop 层层下传:搜索词由父组件持有,通过 props 传给 SearchRoot,再由 SearchRoot 传给递归渲染的 SearchPage,变量随之逐层透传;
  • 搜索词切换即触发整棵查询树重跑:useQuery 的 variables 变化时,urql 会生成新的 operation key 并重新执行查询(下文结合源码说明),因此改动搜索词后,所有页面的缓存都会命中并立即显示——这正是 App.jsx 注释"所有已缓存的页面都会立即显示"的含义。

核心实现:递归渲染的 SearchRoot 与 SearchPage

所有分页逻辑都集中在 examples/with-infinite-pagination/src/SearchResults.jsx。文件包含四个角色:

  • packageFragment:定义单个结果项需要的数据(id、name、latest.version);
  • rootQuery:加载第一页结果,并获取 pageInfo(hasNextPage、endCursor);
  • pageQuery:加载后续每一页,多一个 afterCursor 变量;
  • 组件 SearchRoot → SearchPage → Package:递归渲染链。

先看两个查询的定义:

// 定义一个 fragment,用于描述结果列表中每个条目组件所需的数据
const packageFragment = gql`
  fragment SearchPackage on Package {
    id
    name
    latest: version(selector: "latest") {
      version
    }
  }
`;

// 主查询加载第一页结果,并拿到我们的 PageInfo
// PageInfo 会告诉我们是否还有下一页可以查询
const rootQuery = gql`
  query SearchRoot($searchTerm: String!, $resultsPerPage: Int!) {
    search(query: $searchTerm, first: $resultsPerPage) {
      edges {
        cursor
        node {
          ...SearchPackage
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }

  ${packageFragment}
`;

// 我们把后续要加载的每一页拆成单独的查询。在这个示例代码中,
// 两个查询其实可以是同一个,但为了教学目的我们分开写。
// 在真实应用中,你的 "root query" 通常要比搜索页查询取回更多数据。
const pageQuery = gql`
  query SearchPage(
    $searchTerm: String!
    $resultsPerPage: Int!
    $afterCursor: String!
  ) {
    search(query: $searchTerm, first: $resultsPerPage, after: $afterCursor) {
      edges {
        cursor
        node {
          ...SearchPackage
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }

  ${packageFragment}
`;

设计要点:

  1. Relay 风格的连接(connection)查询:API 返回 edges(含 cursor 与 node)和 pageInfo(hasNextPage、endCursor)。游标分页依赖 endCursor 作为下一页的 after 参数;
  2. root 查询与 page 查询刻意分开:尽管二者查询结构相同,示例注释明确指出这是"为了教学目的"——在真实应用中,首屏查询往往需要携带更多业务数据(如筛选条件、排序、聚合信息),而后续页查询只需取列表数据;
  3. fragment 复用:pageQuery 通过 ${packageFragment} 复用 SearchPackage,保证每页取到的字段一致,便于缓存复用与 UI 组件稳定。

SearchRoot:加载第一页并递归渲染后续页

const SearchRoot = ({ searchTerm = 'urql', resultsPerPage = 10 }) => {
  const [rootResult] = useQuery({
    query: rootQuery,
    variables: {
      searchTerm,
      resultsPerPage,
    },
  });

  if (rootResult.fetching) {
    return <em>Loading...</em>;
  }

  // 在这里,我们把结果渲染成 fragment 列表,并且如果 hasNextPage 为真,
  // 就立即为下一页渲染 <SearchPage>。
  const connection = rootResult.data?.search;
  return (
    <>
      {connection?.edges?.length === 0 ? <strong>No Results</strong> : null}

      {connection?.edges.map(edge => (
        <Package key={edge.cursor} node={edge.node} />
      ))}

      {/* <SearchPage> 接收同样的 props,外加它自己 variables 所需的 afterCursor */}
      {connection?.pageInfo.hasNextPage ? (
        <SearchPage
          searchTerm={searchTerm}
          resultsPerPage={resultsPerPage}
          afterCursor={connection.pageInfo.endCursor}
        />
      ) : rootResult.fetching ? (
        <em>Loading...</em>
      ) : null}
    </>
  );
};

这里的关键模式是把"是否还有下一页"直接翻译成"是否渲染下一个子组件":hasNextPage 为真就渲染 <SearchPage>,并把本页的 endCursor 作为下一页的 afterCursor 传下去。列表的展开完全由组件树的结构决定,而不是由某个 state 数组决定——这就是"无额外状态"的来源。

注意 rootResult.fetching 的判空顺序:先检查首屏加载,再渲染结果;三目表达式末尾的 rootResult.fetching ? <em>Loading...</em> : null 在正常流程下不会被走到(因为前面已 return),属于防御性的兜底。

SearchPage:缓存优先、按钮触发网络请求、递归渲染

const SearchPage = ({ searchTerm, resultsPerPage, afterCursor }) => {
  // 每一个 <SearchPage> 都获取自己这一页的结果!
  const [pageResult, executeQuery] = useQuery({
    query: pageQuery,
    // 初始时,我们只想展示结果——当且仅当它们已被缓存
    requestPolicy: 'cache-only',
    // 如果没有游标我们就不想运行这个查询(在这个示例中,这种情况永远不会发生)
    pause: !afterCursor,
    variables: {
      searchTerm,
      resultsPerPage,
      afterCursor,
    },
  });

  // 我们只会在按钮被按下时加载更多结果,方法是允许该查询发起网络请求。
  // 在你的应用中,你可能会希望在用户能看到列表底部时自动触发,
  // 例如通过 IntersectionObserver。
  const onLoadMore = useCallback(() => {
    // 这会告诉上面的查询去执行;不再是禁止网络请求的 cache-only,
    // 而是允许网络请求。
    executeQuery({ requestPolicy: 'cache-first' });
  }, [executeQuery]);

  if (pageResult.fetching) {
    return <em>Loading...</em>;
  }

  const connection = pageResult.data?.search;
  return (
    <>
      {/* 如果我们的查询有节点,就在这里渲染它们。每一页渲染自己的结果 */}
      {connection?.edges.map(edge => (
        <Package key={edge.cursor} node={edge.node} />
      ))}

      {/* 如果我们还有下一页,现在递归渲染它! */}
      {/* 和之前一样,下一个 <SearchPage> 不会立即发起请求,而只会从缓存查询 */}
      {connection?.pageInfo.hasNextPage ? (
        <SearchPage
          searchTerm={searchTerm}
          resultsPerPage={resultsPerPage}
          afterCursor={connection.pageInfo.endCursor}
        />
      ) : pageResult.fetching ? (
        <em>Loading...</em>
      ) : null}

      {!connection && !pageResult.fetching ? (
        <button type="button" onClick={onLoadMore}>
          Load more
        </button>
      ) : null}
    </>
  );
};

SearchPage 是整套方案的心脏,它通过三个配置组合出了"按需加载"的语义:

  1. requestPolicy: 'cache-only':该页挂载时只从缓存取结果,绝不发起网络请求。若缓存中没有该页数据,data 为 undefined,组件渲染出 "Load more" 按钮;
  2. pause: !afterCursor:没有游标时直接暂停查询(示例中 SearchPage 只会被 hasNextPage 为真的分支渲染,因此实际不会遇到,但这是一个健壮性保护);
  3. executeQuery({ requestPolicy: 'cache-first' }):点击按钮时,以 cache-first 重新执行同一查询——先查缓存(此时必然 miss),再发起网络请求拿到这一页数据。请求完成后,urql 的文档缓存会以 operation key 为键写入结果,此后该页组件重渲染时直接从缓存命中,无需再请求。

关键点在于:每次渲染都基于 endCursor 重新计算下一级 SearchPage 的变量。上一页数据到达后,pageInfo.endCursor 成为下一页的 afterCursor,于是"下一页"的组件被创建出来,而它依然处于 cache-only 状态——除非用户再次点击按钮。这就在组件树的层次上天然实现了"逐页展开、逐页加载"。

Package:结果条目

const Package = ({ node }) => (
  <section>
    <strong>{node.name}</strong>
    <em>@{node.latest.version}</em>
  </section>
);

Package 是纯展示组件,注意它渲染的是 node.latest.version——这正是 packageFragment 中 latest: version(selector: "latest") 别名的作用。

原理剖析:requestPolicy 与文档缓存的配合

示例能在"零额外状态"下工作,根本原因是 urql 的请求策略(Request Policy)与文档缓存的精确配合。下面结合核心源码逐一印证。

四种请求策略的语义

packages/core/src/types.ts 定义了四种 RequestPolicy:

export type RequestPolicy =
  | 'cache-first'
  | 'cache-and-network'
  | 'network-only'
  | 'cache-only';

其文档注释(同文件上方)给出的语义为:

  • cache-first(默认)优先返回缓存结果,缓存未命中时才发送 API 请求;
  • cache-and-network 返回缓存结果,但同时在后台总是发送 API 请求;
  • network-only 忽略任何缓存结果,直接发送 API 请求;
  • cache-only 总是返回缓存结果,并阻止 API 请求。

cache-only 与 cache-first 的切换,正是本示例"先展示缓存、点击后再请求"的核心机制。

cacheExchange 如何执行这些策略

默认缓存交换器实现在 packages/core/src/exchanges/cache.ts。它维护两个结构:resultCache(以 operation key 为键的结果缓存)和 operationCache(按 typename 索引的 operation key 集合,用于 mutation 后的自动失效)。

判断一个 operation 是否命中缓存的逻辑如下(cache.ts):

const isOperationCached = (operation: Operation) =>
  operation.kind === 'query' &&
  operation.context.requestPolicy !== 'network-only' &&
  (operation.context.requestPolicy === 'cache-only' ||
    resultCache.has(operation.key));

可以读出两层含义:

  • cache-only 的查询无条件走缓存分支(无论缓存里有没有结果),命中则返回缓存结果,未命中则返回 makeResult(operation, { data: null }) 这样的空结果,并打上 cacheMiss 的调试信息(cache.ts);
  • 非 network-only 的查询,只要 resultCache 中已有该 key,就返回缓存结果。

关键在过滤逻辑(cache.ts):

const forwardedOps$ = pipe(
  merge([...]),
  map(op => addMetadata(op, { cacheOutcome: 'miss' })),
  filter(
    op => op.kind !== 'query' || op.context.requestPolicy !== 'cache-only'
  ),
  forward,
  ...
);

即:cache-only 的查询绝不会被转发到网络。这解释了 SearchPage 挂载时为何不发请求——cache-only 策略在交换器层面就被拦截了。而当 executeQuery({ requestPolicy: 'cache-first' }) 触发后,同样的查询以 cache-first 重新执行,此时缓存未命中,被转发给 fetchExchange 发起请求;响应返回后,tap 回调会执行 resultCache.set(operation.key, response)(cache.ts),把这一页写进缓存,供后续 cache-only 渲染命中。

useQuery 如何支持策略切换与暂停

packages/react-urql/src/hooks/useQuery.ts 中,useQuery 接受 requestPolicy 与 pause 参数(useQuery.ts):

  • requestPolicy 会被合并进 client.executeQuery 的 context(useQuery.ts),从而改变缓存交换器对该 operation 的处理方式;
  • pause 为 true 时,useMemo 返回 null 源,hook 既不执行查询也不订阅结果(useQuery.ts);
  • 返回的第二个元素 executeQuery 是一个 UseQueryExecute 函数,调用时可传入 Partial<OperationContext> 覆盖请求策略(useQuery.ts):
const executeQuery = React.useCallback(
  (opts?: Partial<OperationContext>) => {
    const context = {
      requestPolicy: args.requestPolicy,
      ...args.context,
      ...opts,
    };
    // client.executeQuery(request, context) ...
  },
  [...]
);

executeQuery({ requestPolicy: 'cache-first' }) 正是通过这个机制,把当前页查询从 cache-only 动态升级为允许网络请求。同时,useQuery 的返回值第二元组即 UseQueryExecute,其官方注释也明确建议:需要"跳过缓存重新获取"时传入 network-only,需要"重新执行暂停的查询"时可直接调用(useQuery.ts)。

另外,useQuery 的 variables 变化时,useRequest 会基于查询文档与变量计算新的 key,导致 useMemo 重新生成 source 并触发新查询(useQuery.ts)。这就是 App.jsx 注释"改回搜索词后所有已缓存的页面立即显示"的底层原因:相同 searchTerm + resultsPerPage + afterCursor 组合会命中此前写入的缓存。

触发"加载更多"的几种方式

示例中 SearchPage 用按钮触发加载:

{!connection && !pageResult.fetching ? (
  <button type="button" onClick={onLoadMore}>
    Load more
  </button>
) : null}

其中 connection 为空表示缓存未命中、该页数据尚未加载。代码注释提示了更常见的生产实践:在真实应用中,你可能会希望在用户能看到列表底部时自动触发,例如通过 IntersectionObserver。由于 onLoadMore 只是调用 executeQuery({ requestPolicy: 'cache-first' }),把按钮替换成 IntersectionObserver 回调即可,无需改动其他任何逻辑。类似的,也可以使用滚动容器的 onScroll 检测。

与其他分页方案的取舍

README 中给出了本方案与另外两个示例的关键差异,值得在选型时认真对照:

对比 with-pagination:游标与动态变量

with-pagination 示例 的做法是用 useState 维护一个 pageVariables 数组,每次点击 "load more" 就 push 一组新的 { query, first, after } 变量,然后 map 渲染每一页。这种方案:

  • 需要额外的 useState 和数组合并逻辑;
  • 下一页变量在父组件中集中管理,一旦页面数据更新(如游标变化),需要额外同步;
  • 适合把结果收集成扁平数组的场景(如 FlatList),但当页面数据需要随查询更新时不够灵活。

而本示例把"变量管理"下放到每一页自己的组件里,通过 endCursor 递归传递实现动态游标,父组件完全不需要感知分页状态。

对比 with-graphcache-pagination:是否需要规范化缓存

with-graphcache-pagination 示例 依赖 graphcache 规范化缓存(见 exchanges/graphcache),由缓存层面理解你的列表结构并自动拼接分页结果。它适合"多入口共享同一份列表缓存""列表与详情深度关联"等复杂场景,但引入成本更高,且要求缓存理解连接(connection)结构。

本示例则完全不需要缓存感知:文档缓存(甚至任何自定义缓存)即可工作,代价是每次切换搜索词后,已展开的页面缓存依旧保留(因为 key 包含变量),但结构上是"每页一条独立缓存记录",没有列表级别的合并语义。

什么时候该用扁平数组方案

README 明确给出结论:除非你需要一个扁平数组(例如 React Native 的 FlatList,或需要把结果喂给虚拟列表组件),否则本示例就是实现无限滚动分页列表的最简方式。如果应用恰好使用 FlatList 这类要求 data 为数组的组件,那么 with-pagination 的"状态数组"模式反而更合适。

完整文件清单与进一步阅读

示例涉及的文件都在 examples/with-infinite-pagination 目录下:

若想深入底层原理,推荐阅读:

小结

无限滚动分页不必引入分页库或规范化缓存。urql 官方示例 with-infinite-pagination 证明了:利用 useQuery 的 pause + requestPolicy: 'cache-only' 初始只读缓存,配合 executeQuery({ requestPolicy: 'cache-first' }) 在用户触发时放行网络请求,再通过组件递归渲染把 endCursor 逐层传递,就能在纯 UI 代码中实现支持游标、无额外状态、兼容任意缓存的逐页无限滚动。理解其中的关键——cacheExchange 对 cache-only 的拦截与按 key 缓存——也就掌握了在 urql 中灵活组合请求策略解决加载问题的通用思路。

登录后查看全文
urql