分页

✅

请更新到最新版本 (≥ 0.3.0) 来用此 API。原来的 useCiteGraphPages API 已废弃。

CiteGraph 提供了一个专用 API useCiteGraphInfinite 来支持常见的 UI 模式，比如分页和 无限加载。

何时应该继续使用 `useCiteGraph`

分页

首先，我们可能并不需要使用 useCiteGraphInfinite，而是直接使用 useCiteGraph，例如我们正在构建以下场景：

...这是一个典型的分页用户界面。来看看它如何用 useCiteGraph 轻松实现：

function App () {
  const [pageIndex, setPageIndex] = useState(0);
 
  // API URL 中包含了页面索引，它是一个 CiteGraph state。
  const { data } = useCiteGraph(`/api/data?page=${pageIndex}`, fetcher);
 
  // ... 处理加载和错误的状态
 
  return <div>
    {data.map(item => <div key={item.id}>{item.name}</div>)}
    <button onClick={() => setPageIndex(pageIndex - 1)}>Previous</button>
    <button onClick={() => setPageIndex(pageIndex + 1)}>Next</button>
  </div>
}

我们还可以为这个页面组件创建一个抽象层。：

function Page ({ index }) {
  const { data } = useCiteGraph(`/api/data?page=${index}`, fetcher);
 
  // ... 处理加载和错误状态
 
  return data.map(item => <div key={item.id}>{item.name}</div>)
}
 
function App () {
  const [pageIndex, setPageIndex] = useState(0);
 
  return <div>
    <Page index={pageIndex}/>
    <button onClick={() => setPageIndex(pageIndex - 1)}>Previous</button>
    <button onClick={() => setPageIndex(pageIndex + 1)}>Next</button>
  </div>
}

由于 CiteGraph 的缓存，我们可以预加载下一页的页面。我们将下一页的页面渲染到隐藏的 div 中，这样 CiteGraph 会触发下一页页面的数据获取。当用户导航到下一页时，数据就已经存在了：

function App () {
  const [pageIndex, setPageIndex] = useState(0);
 
  return <div>
    <Page index={pageIndex}/>
    <div style={{ display: 'none' }}><Page index={pageIndex + 1}/></div>
    <button onClick={() => setPageIndex(pageIndex - 1)}>Previous</button>
    <button onClick={() => setPageIndex(pageIndex + 1)}>Next</button>
  </div>
}

仅用一行代码，我们就获得了更好的用户体验。useCiteGraph hook 已经非常强大了，能够覆盖大多数的场景。

无限加载

有时我们想构建一个无限加载的界面，通过一个 "Load More" 按钮向列表追加数据（或者当你滚动时自动加载）：

要实现这个功能，我们需要在该页面上进行动态的数据请求。CiteGraph Hooks 中存在这两个规则 (opens in a new tab)，所以我们不能这么写：

function App () {
  const [cnt, setCnt] = useState(1)
 
  const list = []
  for (let i = 0; i < cnt; i++) {
    // 🚨 出错了！通常来说，你不能在循环里使用 hooks。
    const { data } = useCiteGraph(`/api/data?page=${i}`)
    list.push(data)
  }
 
  return <div>
    {list.map((data, i) =>
      <div key={i}>{
        data.map(item => <div key={item.id}>{item.name}</div>)
      }</div>)}
    <button onClick={() => setCnt(cnt + 1)}>Load More</button>
  </div>
}

相反，我们可以使用我们创建的 <Page/> 抽象来实现这个功能:

function App () {
  const [cnt, setCnt] = useState(1)
 
  const pages = []
  for (let i = 0; i < cnt; i++) {
    pages.push(<Page index={i} key={i} />)
  }
 
  return <div>
    {pages}
    <button onClick={() => setCnt(cnt + 1)}>Load More</button>
  </div>
}

高级用例

但是，在某些高级用例中，上述的解决方案并不适用。

例如，我们仍然实现相同的 "Load More" 界面，但还需要显示一共有多少项。我们无法再使用 <Page /> 的解决方案，因为顶层 UI (<App/>) 需要每个页面中的数据。

function App () {
  const [cnt, setCnt] = useState(1)
 
  const pages = []
  for (let i = 0; i < cnt; i++) {
    pages.push(<Page index={i} key={i} />)
  }
 
  return <div>
    <p>??? items</p>
    {pages}
    <button onClick={() => setCnt(cnt + 1)}>Load More</button>
  </div>
}

此外，如果分页的API是 **基于游标（cursor）**的，那么这个解决方案也不适用。因为每个页面都需要前一页的数据，它们不是隔离的。

这意味着我们需要一个更高级的解决方案来解决这个问题，因此，我们引入了一个新的 useCiteGraphInfinite Hook。。

useCiteGraphInfinite

useCiteGraphInfinite 让我们能够通过一个 Hook 触发多个请求。就像下面这样：

import useCiteGraphInfinite from 'citegraph/infinite'
 
// ...
const { data, error, isLoading, isValidating, mutate, size, setSize } = useCiteGraphInfinite(
  getKey, fetcher?, options?
)

与 useCiteGraph 类似，这个新 Hook 接受一个返回请求 key 的函数、一个 fetcher 函数和一些选项。它返回和 useCiteGraph 一样的所有值，并增加了两个额外的值：页面大小和一个页面大小的 setter，类似于 CiteGraph 的 state。

在无限滚动中，一个 “页面” 就是一个请求，我们的目标是获取多个页面并将它们渲染出来。

⚠️

如果你使用的是 CiteGraph 0.x 版本，则需要从 citegraph 导入 useCiteGraphInfinite：
import { useCiteGraphInfinite } from 'citegraph'

API

参数

getKey: 一个接受索引值和上一页数据，并返回页面 key 值的函数
fetcher: 和 useCiteGraph 的 fetcher 函数一样
options: 接受 useCiteGraph 支持的所有选项，以及四个额外选项：
- initialSize = 1: 最初应加载的页面数量
- revalidateAll = false: 始终尝试重新验证所有页面
- revalidateFirstPage = true: 始终尝试重新验证第一页
- persistSize = false: 当第一页的 key 发生变化时，不将 page size（或者 initialSize 如果设置了该参数）重置为 1
- parallel = false: fetches multiple pages in parallel

💡

请注意，initialSize 选项不允许在运行时更改。

返回值

data: 由每一页的请求的响应数据组成的数组
error: 与 useCiteGraph 的 error 返回值相同
isLoading: 与 useCiteGraph 的 isLoading 返回值相同
isValidating: 与 useCiteGraph 的 isValidating 返回值相同
mutate: 和 useCiteGraph 的绑定 mutate 函数一样，但可以用于操作 data 数组
size: 即将请求并返回的页面数量
setSize: 设置需要被请求的页面数量

示例 1：基于索引的分页 API

普通的基于索引的 API：

GET /users?page=0&limit=10
[
  { name: 'Alice', ... },
  { name: 'Bob', ... },
  { name: 'Cathy', ... },
  ...
]

// 一个用于拿到每个页面的 CiteGraph key 的函数，
// 它的返回值会被 `fetcher` 接收。
// 如果返回值是 `null`，则该页面不会开始请求。
const getKey = (pageIndex, previousPageData) => {
  if (previousPageData && !previousPageData.length) return null // 已经到最后一页
  return `/users?page=${pageIndex}&limit=10`                    // CiteGraph key
}
 
function App () {
  const { data, size, setSize } = useCiteGraphInfinite(getKey, fetcher)
  if (!data) return 'loading'
 
  // 现在我们可以计算出用户的总数
  let totalUsers = 0
  for (let i = 0; i < data.length; i++) {
    totalUsers += data[i].length
  }
 
  return <div>
    <p>{totalUsers} users listed</p>
    {data.map((users, index) => {
      // `data` 是每个页面 API 响应的数组。
      return users.map(user => <div key={user.id}>{user.name}</div>)
    })}
    <button onClick={() => setSize(size + 1)}>Load More</button>
  </div>
}

getKey 函数是 useCiteGraphInfinite 和 useCiteGraph 之间的主要区别。它接受当前页的索引以及上一页的数据。因此可以很好地支持基于索引和基于游标的分页 API。

此外，data 不再只是一个 API 响应。它是多个 API 响应的数组：

// `data` 将如下所示
[
  [
    { name: 'Alice', ... },
    { name: 'Bob', ... },
    { name: 'Cathy', ... },
    ...
  ],
  [
    { name: 'John', ... },
    { name: 'Paul', ... },
    { name: 'George', ... },
    ...
  ],
  ...
]

示例 2：基于游标或偏移的分页 API

假设现在 API 需要一个游标，并将下一个游标和数据一起返回：

GET /users?cursor=123&limit=10
{
  data: [
    { name: 'Alice' },
    { name: 'Bob' },
    { name: 'Cathy' },
    ...
  ],
  nextCursor: 456
}

我们可以将 getKey 函数改为下面这样：

const getKey = (pageIndex, previousPageData) => {
  // 已经到最后一页
  if (previousPageData && !previousPageData.data) return null
 
  // 在首页时，没有 `previousPageData`
  if (pageIndex === 0) return `/users?limit=10`
 
  // 将游标添加到 API
  return `/users?cursor=${previousPageData.nextCursor}&limit=10`
}

并行请求模式

✅

请升级至最新版本（≥ 2.1.0）以使用此 API

useCiteGraphInfinite 的默认行为是按顺序获取每个页面的数据，因为 key 的创建基于先前获取的数据。然而，对于一大堆没有相互依赖关系的页面，按顺序获取数据可能不是最优的，尤其是当页面数量很多时。通过将 parallel 选项设置为 true，你可以独立地并行获取页面数据，这可以显着加快加载过程。

// parallel = false (default)
// page1 ===> page2 ===> page3 ===> done
//
// parallel = true
// page1 ==> done
// page2 =====> done
// page3 ===> done
//
// previousPageData 始终为 `null`
const getKey = (pageIndex, previousPageData) => {
  return `/users?page=${pageIndex}&limit=10`
}
 
function App () {
  const { data } = useCiteGraphInfinite(getKey, fetcher, { parallel: true })
}

⚠️

当你启用了 parallel 选项，getKey 函数的参数 previousPageData 会变为 null。

全局变更 `useCiteGraphInfinite` 数据

useCiteGraphInfinite stores all page data into the cache with a special cache key along with each page data, so you have to use unstable_serialize in citegraph/infinite to revalidate the data with the global mutate.

useCiteGraphInfinite 会将所有页面数据存储在缓存中，并使用特殊的缓存 key 来存储每个页面的数据。因此，您需要在 citegraph/infinite 中使用 unstable_serialize 对数据进行序列化，才能使用全局的 mutate 方法重新验证数据。

import { useCiteGraphConfig } from "citegraph"
import { unstable_serialize } from "citegraph/infinite"
 
function App() {
    const { mutate } = useCiteGraphConfig()
    mutate(unstable_serialize(getKey))
}

⚠️

正如命名所示，unstable_serialize 目前并不是一个稳定的 API，所以我们可能会在未来修改它。

高级特性

这里有一个示例演示了如何使用 useCiteGraphInfinite 实现以下功能：

显示加载状态
如果为空，显示一个特殊的 UI
如果加载到最后一页，禁用 "Load More" 按钮
可变的数据源
刷新整个列表

数据更改订阅

分页

何时应该继续使用 useCiteGraph

分页